EFF-809: Add platform Crypto service

.changeset/green-rings-prove.md

@@ -0,0 +1,5 @@
+---
+"effect": patch
+---
+
+update Model uuid helpers

.changeset/platform-crypto-service.md

@@ -0,0 +1,9 @@
+---
+"effect": patch
+"@effect/platform-node": patch
+"@effect/platform-node-shared": patch
+"@effect/platform-bun": patch
+"@effect/platform-browser": patch
+---
+
+Add a platform-agnostic `Crypto` service for cryptographic random bytes, secure random generators, UUIDv4 / UUIDv7 generation, and digest operations. UUID generation should now use the `Crypto` service's `randomUUIDv4` or `randomUUIDv7`, which format bytes from the platform `Crypto` service; UUIDv7 also uses the `Clock` service timestamp. `Random.nextUUIDv4` has been removed because the base `Random` service is not cryptographically secure.

.specs/README.md

@@ -1,3 +1,4 @@
 # Specifications
 
 - [Effect SQL UniqueViolation SqlError Reason](./effect-sql-unique-violation.md) — Adds a `UniqueViolation` SQL error reason with a `constraint` property and updates driver classification for UNIQUE constraint violations.
+- [Effect Platform Crypto Service](./effect-platform-crypto.md) — Adds a platform-agnostic `Crypto` service for cryptographic random bytes, native UUIDv4 generation, and digest operations.

packages/ai/anthropic/src/index.ts

@@ -15,6 +15,24 @@
 export * as AnthropicClient from "./AnthropicClient.ts"
 
 /**
+ * The `AnthropicConfig` module provides contextual configuration for the
+ * Anthropic AI provider integration. It is used to customize the generated
+ * Anthropic HTTP client without changing individual request code.
+ *
+ * **Common tasks**
+ *
+ * - Provide a shared `HttpClient` transformation for Anthropic requests
+ * - Add provider-specific concerns such as request instrumentation, proxying,
+ *   retries, or header manipulation
+ * - Scope a client transformation to a single effect with {@link withClientTransform}
+ *
+ * **Gotchas**
+ *
+ * - Configuration is read from the Effect context, so overrides only apply to
+ *   effects run inside the configured scope
+ * - `withClientTransform` replaces the current `transformClient` value while
+ *   preserving any other Anthropic configuration fields
+ *
  * @since 4.0.0
  */
 export * as AnthropicConfig from "./AnthropicConfig.ts"
@@ -30,6 +48,32 @@ export * as AnthropicConfig from "./AnthropicConfig.ts"
 export * as AnthropicError from "./AnthropicError.ts"
 
 /**
+ * The `AnthropicLanguageModel` module provides the Anthropic implementation of
+ * Effect AI's `LanguageModel` service. It turns Effect AI prompts, tools, files,
+ * reasoning parts, and provider options into Anthropic Messages API requests,
+ * and converts Anthropic responses and streams back into Effect AI response
+ * parts with Anthropic-specific metadata.
+ *
+ * **Common tasks**
+ *
+ * - Create an Anthropic-backed model with {@link model}
+ * - Build or provide a `LanguageModel.LanguageModel` layer with {@link layer}
+ *   or {@link make}
+ * - Supply default request options through {@link Config}
+ * - Override configuration for a scoped operation with {@link withConfigOverride}
+ * - Attach Anthropic provider options for prompt caching, document citations,
+ *   reasoning signatures, MCP metadata, and server-side tools
+ *
+ * **Gotchas**
+ *
+ * - Prompt files are translated to Anthropic image or document blocks; only the
+ *   supported media types can be sent to the provider.
+ * - Structured output support depends on the selected Claude model, so this
+ *   module may use Anthropic's native structured output or fall back to a JSON
+ *   response tool.
+ * - Some features require Anthropic beta headers, which are added
+ *   automatically from the selected tools, files, and model capabilities.
+ *
  * @since 4.0.0
  */
 export * as AnthropicLanguageModel from "./AnthropicLanguageModel.ts"

packages/ai/openai-compat/src/index.ts

@@ -5,11 +5,54 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
+ * The `OpenAiClient` module provides an Effect service for calling
+ * OpenAI-compatible chat completions and embeddings APIs. It builds on the
+ * Effect HTTP client, adds authentication and OpenAI header handling, and
+ * exposes typed helpers for regular responses, server-sent event streaming, and
+ * embedding requests.
+ *
+ * **Common tasks**
+ *
+ * - Create a client service directly with {@link make}
+ * - Provide the service as a layer with {@link layer} or {@link layerConfig}
+ * - Send non-streaming chat completion requests with `createResponse`
+ * - Send streaming chat completion requests with `createResponseStream`
+ * - Generate embeddings with `createEmbedding`
+ * - Reuse the exported request and response types when integrating compatible providers
+ *
+ * **Gotchas**
+ *
+ * - The default base URL is `https://api.openai.com/v1`; set `apiUrl` for other
+ *   OpenAI-compatible providers.
+ * - `createResponseStream` forces `stream: true` and requests usage events with
+ *   `stream_options.include_usage`.
+ * - HTTP and schema decoding failures are mapped into `AiError`.
+ *
  * @since 4.0.0
  */
 export * as OpenAiClient from "./OpenAiClient.ts"
 
 /**
+ * The `OpenAiConfig` module provides shared configuration for clients that
+ * talk to OpenAI-compatible APIs. It is used to customize the HTTP client
+ * wiring around a provider without changing the higher-level model,
+ * embeddings, or tool-calling APIs that consume the client.
+ *
+ * **Common tasks**
+ *
+ * - Install a client transform with {@link withClientTransform}
+ * - Add provider-specific HTTP behavior, such as headers, retries, proxies, or
+ *   instrumentation
+ * - Read the active configuration from the Effect context when implementing
+ *   OpenAI-compatible integrations
+ *
+ * **Gotchas**
+ *
+ * - The transform receives and returns an `HttpClient`, so it should preserve
+ *   the existing client behavior unless it intentionally replaces it
+ * - Configuration is provided through Effect context and is scoped to the
+ *   effect that receives the service
+ *
  * @since 4.0.0
  */
 export * as OpenAiConfig from "./OpenAiConfig.ts"
@@ -24,6 +67,19 @@ export * as OpenAiConfig from "./OpenAiConfig.ts"
 export * as OpenAiEmbeddingModel from "./OpenAiEmbeddingModel.ts"
 
 /**
+ * The `OpenAiError` module defines OpenAI-specific metadata that can be
+ * attached to the shared `AiError` error types used by the AI packages. It is
+ * primarily used by OpenAI-compatible clients to preserve provider details
+ * such as error codes, error types, request IDs, and rate limit headers while
+ * still exposing errors through the provider-neutral Effect AI error model.
+ *
+ * Use this module when mapping OpenAI API failures into `AiError` values and
+ * when consumers need enough structured metadata to debug failed requests,
+ * inspect quota or rate limit responses, or correlate an error with OpenAI
+ * support. The exported types are metadata shapes only; the module augmentation
+ * makes those shapes available on the corresponding shared AI error metadata
+ * interfaces without defining new runtime error classes.
+ *
  * @since 4.0.0
  */
 export * as OpenAiError from "./OpenAiError.ts"

packages/ai/openai/src/index.ts

@@ -25,6 +25,22 @@ export * as OpenAiClient from "./OpenAiClient.ts"
 export * as OpenAiClientGenerated from "./OpenAiClientGenerated.ts"
 
 /**
+ * The `OpenAiConfig` module provides contextual configuration for the
+ * `@effect/ai-openai` integration. It is used to customize how OpenAI clients
+ * are built and interpreted without threading configuration through every API
+ * call manually.
+ *
+ * The primary use case is installing an HTTP client transform with
+ * {@link withClientTransform}. This lets applications adapt the underlying
+ * OpenAI HTTP client for cross-cutting concerns such as custom middleware,
+ * instrumentation, proxying, or request policy changes while keeping the
+ * OpenAI service APIs unchanged.
+ *
+ * Configuration is scoped through Effect's context, so transforms only apply to
+ * the effect they are provided to and anything evaluated inside that scope.
+ * When multiple transforms are needed, compose them into a single
+ * `HttpClient => HttpClient` function before providing the configuration.
+ *
  * @since 4.0.0
  */
 export * as OpenAiConfig from "./OpenAiConfig.ts"

packages/ai/openrouter/src/index.ts

@@ -10,11 +10,51 @@
 export * as Generated from "./Generated.ts"
 
 /**
+ * The `OpenRouterClient` module provides an Effect service for calling
+ * OpenRouter's chat completions API. It wraps the generated OpenRouter HTTP
+ * client with Effect-native constructors, layers, typed errors, and streaming
+ * support.
+ *
+ * **Common tasks**
+ *
+ * - Build a client from explicit options with {@link make}
+ * - Provide the client to an application with {@link layer} or {@link layerConfig}
+ * - Create non-streaming chat completions with {@link Service.createChatCompletion}
+ * - Create server-sent event chat completion streams with
+ *   {@link Service.createChatCompletionStream}
+ * - Customize authentication, base URL, OpenRouter ranking headers, or the
+ *   underlying HTTP client through {@link Options}
+ *
+ * **Gotchas**
+ *
+ * - Streaming requests are sent directly to `/chat/completions` with `stream`
+ *   and `stream_options.include_usage` enabled by this module.
+ * - OpenRouter API failures, HTTP client failures, and schema decoding failures
+ *   are mapped into `AiError` values for the exported service methods.
+ *
  * @since 4.0.0
  */
 export * as OpenRouterClient from "./OpenRouterClient.ts"
 
 /**
+ * The `OpenRouterConfig` module provides contextual configuration for the
+ * OpenRouter provider integration. It is used to customize the HTTP client that
+ * backs OpenRouter requests without rebuilding the provider layer itself.
+ *
+ * Use {@link withClientTransform} when a single effect, workflow, or scoped
+ * portion of an application needs to add cross-cutting HTTP client behavior
+ * such as request logging, retries, proxy routing, additional headers, or test
+ * doubles. The configuration is read from the current Effect context, so the
+ * transform only applies where the returned effect is run with that context.
+ *
+ * **Gotchas**
+ *
+ * - Each call to {@link withClientTransform} replaces the current client
+ *   transform for the provided effect; compose transforms manually when both
+ *   behaviors should apply.
+ * - The transform receives and returns an `HttpClient`, so it should preserve
+ *   the OpenRouter client contract while adding behavior around it.
+ *
  * @since 4.0.0
  */
 export * as OpenRouterConfig from "./OpenRouterConfig.ts"
@@ -30,6 +70,26 @@ export * as OpenRouterConfig from "./OpenRouterConfig.ts"
 export * as OpenRouterError from "./OpenRouterError.ts"
 
 /**
+ * The `OpenRouterLanguageModel` module provides constructors for using
+ * OpenRouter chat completion models through the Effect AI `LanguageModel`
+ * interface. It adapts Effect prompts, tools, structured output schemas, file
+ * parts, reasoning details, cache-control hints, and telemetry annotations into
+ * the OpenRouter request and response formats.
+ *
+ * Use this module when an application wants to select an OpenRouter model by
+ * name while keeping the rest of its AI workflow provider-agnostic. The
+ * exported layer and model constructors install a `LanguageModel` service backed
+ * by `OpenRouterClient`, and `withConfigOverride` can scope per-request
+ * OpenRouter options such as sampling, routing, tool use, or JSON schema
+ * behavior.
+ *
+ * OpenRouter routes requests to many underlying providers, so model support for
+ * images, files, tools, structured outputs, caching, and reasoning metadata can
+ * vary. Provider-specific prompt and response metadata is preserved under the
+ * `openrouter` option namespace so multi-turn conversations can round-trip
+ * details such as reasoning blocks and file annotations when the selected model
+ * supports them.
+ *
  * @since 4.0.0
  */
 export * as OpenRouterLanguageModel from "./OpenRouterLanguageModel.ts"