alchemy 2.0.0-beta.46 → 2.0.0-beta.48

package/src/Cloudflare/AiGateway/AiGateway.ts

@@ -231,7 +231,11 @@ export const isAiGateway = (value: unknown): value is AiGateway =>
  * governance across AI provider requests.
  *
  * AI Gateway gives your application a stable gateway ID and account-scoped
- * endpoint that can route model requests through Cloudflare.
+ * endpoint that can route model requests through Cloudflare. Once bound to a
+ * Worker, `aiGateway.model({...})` returns an `effect/unstable/ai`
+ * `LanguageModel` Layer so you use the standard `generateText` / `streamText`
+ * APIs — provider-agnostic, with caching, rate limiting, retries, and a
+ * unified request log handled by the gateway.
  *
  * @section Creating a Gateway
  * @example Basic gateway
@@ -260,6 +264,113 @@ export const isAiGateway = (value: unknown): value is AiGateway =>
  *   logManagementStrategy: "STOP_INSERTING",
  * });
  * ```
+ *
+ * @section Binding into a Worker
+ * @example Bind the gateway and provide the runtime layer
+ * `AiGateway.bind(gateway)` returns a typed, Effect-native client during the
+ * Worker's Init phase. Provide `Cloudflare.AiGatewayBindingLive` once at the
+ * bottom of the Init layer chain so every `bind(...)` resolves at runtime.
+ * ```typescript
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ * import { Gateway } from "./AiGateway.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.path },
+ *   Effect.gen(function* () {
+ *     const aiGateway = yield* Cloudflare.AiGateway.bind(Gateway);
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         // …routes
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.AiGatewayBindingLive)),
+ * ) {}
+ * ```
+ *
+ * @section Building a LanguageModel
+ * @example `aiGateway.model(...)` -> Effect AI `LanguageModel`
+ * Call `aiGateway.model({...})` with a Workers AI model id. It returns a
+ * `Layer<LanguageModel, never, RuntimeContext>` directly — no API key and no
+ * `Layer.unwrap`, since the binding handles auth and the gateway URL. Build it
+ * in the Init phase; construction is pure.
+ * ```typescript
+ * const aiGateway = yield* Cloudflare.AiGateway.bind(Gateway);
+ *
+ * const languageModel = aiGateway.model({
+ *   client: aiGateway,
+ *   model: "@cf/meta/llama-3.1-8b-instruct",
+ *   parameters: { temperature: 0.7, maxTokens: 1024 },
+ * });
+ * ```
+ *
+ * @section Generating Text
+ * @example Generate text on a route
+ * Provide the `languageModel` layer to the handler and call
+ * `LanguageModel.generateText` like any other Effect. `Effect.orDie` collapses
+ * `AiError` to a defect (a 500); use `Effect.catchTag("AiError", …)` for typed
+ * handling instead.
+ * ```typescript
+ * import { LanguageModel } from "effect/unstable/ai";
+ * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+ *
+ * fetch: Effect.gen(function* () {
+ *   const response = yield* LanguageModel.generateText({
+ *     prompt: "Say hello.",
+ *   }).pipe(Effect.orDie);
+ *   return yield* HttpServerResponse.json({
+ *     text: response.text,
+ *     usage: {
+ *       inputTokens: response.usage.inputTokens.total,
+ *       outputTokens: response.usage.outputTokens.total,
+ *     },
+ *   });
+ * }).pipe(Effect.provide(languageModel));
+ * ```
+ *
+ * @section Streaming Text
+ * @example Stream tokens as Server-Sent Events
+ * `LanguageModel.streamText` returns a `Stream` of typed response parts.
+ * `Stream.provide(languageModel)` keeps the model available for the whole
+ * stream lifetime; pipe through `Sse.encode` for an SSE response.
+ * ```typescript
+ * import { LanguageModel } from "effect/unstable/ai";
+ * import * as Stream from "effect/Stream";
+ * import * as Sse from "effect/unstable/encoding/Sse";
+ * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+ *
+ * const stream = LanguageModel.streamText({ prompt }).pipe(
+ *   Stream.provide(languageModel),
+ *   Sse.encode,
+ * );
+ * return HttpServerResponse.stream(stream, {
+ *   headers: {
+ *     "content-type": "text/event-stream",
+ *     "cache-control": "no-cache",
+ *     "x-accel-buffering": "no",
+ *   },
+ * });
+ * ```
+ *
+ * @section Tuning the Gateway
+ * @example Production-grade caching, rate limits, and DLP
+ * Every prop maps to an in-place update — no replacement, no downtime.
+ * ```typescript
+ * export const Gateway = Cloudflare.AiGateway("Gateway", {
+ *   id: "prod-gateway",
+ *   cacheTtl: 300,
+ *   cacheInvalidateOnUpdate: true,
+ *   rateLimitingInterval: 60,
+ *   rateLimitingLimit: 100,
+ *   rateLimitingTechnique: "sliding",
+ *   collectLogs: true,
+ *   logManagement: 100_000,
+ *   logManagementStrategy: "DELETE_OLDEST",
+ *   authentication: true,
+ * });
+ * ```
  */
 export const AiGateway = Resource<AiGateway>("Cloudflare.AiGateway")({
   /**
@@ -337,7 +448,8 @@ export const AiGatewayProvider = () =>
         rateLimitingLimit: nullIfZero(gateway.rateLimitingLimit),
         rateLimitingTechnique: gateway.rateLimitingTechnique ?? "fixed",
         authentication: gateway.authentication ?? false,
-        dlp: gateway.dlp ?? undefined,
+        // Distilled widened generated string enums to open unions (`string & {}`).
+        dlp: (gateway.dlp ?? undefined) as AiGatewayDlp | undefined,
         isDefault: gateway.isDefault ?? false,
         logManagement: gateway.logManagement ?? 100_000,
         logManagementStrategy:

package/src/Cloudflare/AiGateway/AiGatewayBinding.ts

@@ -3,15 +3,18 @@
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import type { LanguageModel } from "effect/unstable/ai/LanguageModel";
 import * as Binding from "../../Binding.ts";
 import type { ResourceLike } from "../../Resource.ts";
 import type { RuntimeContext } from "../../RuntimeContext.ts";
 import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
 import type { AiGateway as AiGatewayResource } from "./AiGateway.ts";
+import {
+  makeLanguageModelLayer,
+  type LanguageModelOptions,
+} from "./LanguageModel.ts";
 
-/**
- * Error raised by AI Gateway runtime operations.
- */
+// Error raised by AI Gateway runtime operations.
 export class AiGatewayError extends Data.TaggedError("AiGatewayError")<{
   /**
    * Human-readable runtime error message.
@@ -39,6 +42,12 @@ export interface AiGatewayClient {
    * Effect resolving to the raw AI Gateway runtime binding.
    */
   gateway: Effect.Effect<AiGateway, never, RuntimeContext>;
+  /**
+   * Effect resolving to the gateway id (the resource attribute, captured at
+   * bind time). Useful when calling `ai.run(model, inputs, { gateway: { id } })`
+   * — the in-account path for first-party services like Workers AI.
+   */
+  id: Effect.Effect<string, never, RuntimeContext>;
   /**
    * Update metadata on an existing AI Gateway log entry.
    */
@@ -65,17 +74,27 @@ export interface AiGatewayClient {
     data: Parameters<AiGateway["run"]>[0],
     options?: Parameters<AiGateway["run"]>[1],
   ): Effect.Effect<Response, AiGatewayError, RuntimeContext>;
+
+  model(
+    options: LanguageModelOptions,
+  ): Layer.Layer<LanguageModel, never, RuntimeContext>;
 }
 
 /**
- * Binding service that turns an {@link AiGatewayResource} resource into a typed
- * {@link AiGatewayClient} for Worker runtime code.
+ * Binding service that turns an {@link AiGatewayResource} resource
+ * into a typed {@link AiGatewayClient} for Worker runtime code. Wraps
+ * the Cloudflare AI Gateway runtime binding so each operation returns
+ * an Effect tagged with {@link AiGatewayError}, exposes the raw
+ * Workers AI handle for `ai.run(...)`, and provides a `model(options)`
+ * factory that produces an `effect/unstable/ai` `LanguageModel`
+ * `Layer`.
  *
- * @section Calling AI Gateway
- * Bind the gateway during the Worker's init phase, then use `run` or `getUrl`
- * from request handlers.
+ * @binding
  *
+ * @section Calling AI Gateway
  * @example Run through a gateway
+ * Bind the gateway during the Worker's init phase, then use `run` or
+ * `getUrl` from request handlers.
  * ```typescript
  * const aiGateway = yield* Cloudflare.AiGatewayBinding.bind(gateway);
  *
@@ -91,8 +110,29 @@ export interface AiGatewayClient {
  * };
  * ```
  *
- * Provide {@link AiGatewayBindingLive} in the worker's runtime layer to
- * resolve the underlying Cloudflare AI binding at request time.
+ * @section Driving Effect AI through the gateway
+ * @example `aiGateway.model(...)` -> Effect AI `LanguageModel`
+ * `model(options)` produces a `Layer<LanguageModel, never,
+ * RuntimeContext>` that translates `LanguageModel.generateText` /
+ * `streamText` calls (including tool calls and structured outputs)
+ * into `ai.run(...)` against the bound Workers AI model, routed
+ * through the gateway.
+ * ```typescript
+ * const aiGateway = yield* Cloudflare.AiGatewayBinding.bind(gateway);
+ *
+ * const languageModel = aiGateway.model({
+ *   client: aiGateway,
+ *   model: "@cf/meta/llama-3.1-8b-instruct",
+ *   parameters: { temperature: 0.7, maxTokens: 1024 },
+ * });
+ *
+ * const response = yield* AiLanguageModel.generateText({ prompt }).pipe(
+ *   Effect.provide(languageModel),
+ * );
+ * ```
+ *
+ * Provide {@link AiGatewayBindingLive} in the worker's runtime layer
+ * to resolve the underlying Cloudflare AI binding at request time.
  */
 export class AiGatewayBinding extends Binding.Service<
   AiGatewayBinding,
@@ -129,11 +169,13 @@ export const AiGatewayBindingLive = Layer.effect(
       return {
         raw: ai,
         gateway: runtimeGateway,
+        id: gatewayIdAccessor,
         patchLog: (logId, data) =>
           use((gateway) => gateway.patchLog(logId, data)),
         getLog: (logId) => use((gateway) => gateway.getLog(logId)),
         getUrl: (provider) => use((gateway) => gateway.getUrl(provider)),
         run: (data, options) => use((gateway) => gateway.run(data, options)),
+        model: (options) => makeLanguageModelLayer(options),
       } satisfies AiGatewayClient;
     });
   }),