@lunora/ai 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/packem_shared/types.d-BcLGTChd.d.ts

@@ -0,0 +1,239 @@
+import { EmbeddingModel, LanguageModel } from 'ai';
+/**
+ * Which surface resolved the gateway. The two paths handle the auth token
+ * differently: a bring-your-own AI SDK provider sends it as the
+ * `cf-aig-authorization` header (`ResolvedAiGateway.headers`), but the Workers AI
+ * **binding** routes through the gateway using the account's own credentials and
+ * its native `gateway` option (Cloudflare `GatewayOptions`) has **no** field to
+ * carry an authorization token — so a token set for the binding path cannot be
+ * delivered and is warned about instead of silently dropped.
+ * @experimental
+ */
+type AiGatewayConsumer = "byo-provider" | "workers-ai-binding";
+/**
+ * Project {@link AiGatewayMetadata} to a plain string-map of only its defined,
+ * non-empty fields, or `undefined` when nothing is set. This is the shared source
+ * of truth behind both gateway-correlation forms: the `cf-aig-metadata` HTTP
+ * header (bring-your-own providers) and the Workers AI binding's native
+ * `gateway.metadata` option — both encode the same `{ functionPath, traceId }`.
+ * @experimental
+ */
+declare const buildAiGatewayMetadataFields: (metadata: AiGatewayMetadata | undefined) => Record<string, string> | undefined;
+/**
+ * Correlation metadata folded into the `cf-aig-metadata` request header so a
+ * gateway log entry can be tied back to the Lunora function + trace that made
+ * the call. Every field is optional — only defined ones are sent.
+ * @experimental
+ */
+interface AiGatewayMetadata {
+  /** The Lunora function path that issued the model call (e.g. `messages:send`). */
+  functionPath?: string;
+  /** The 32-hex trace id the call belongs to, so the gateway log joins the trace. */
+  traceId?: string;
+}
+/**
+ * The resolved AI Gateway coordinates.
+ *
+ * `gatewayId`/`accountId` drive the Workers AI provider's native `gateway` option
+ * (Cloudflare routes the binding call internally). `baseURL` + `headers` are for
+ * bring-your-own AI SDK providers (`@ai-sdk/openai`, …): append the provider
+ * slug to `baseURL` and spread `headers` into the provider config, e.g.
+ *
+ * ```ts
+ * const gw = resolveAiGateway(env);
+ * const openai = createOpenAI(gw ? { baseURL: `${gw.baseURL}/openai`, headers: gw.headers } : {});
+ * ```
+ * @experimental
+ */
+interface ResolvedAiGateway {
+  /** The Cloudflare account id owning the gateway. */
+  accountId: string;
+  /**
+   * The universal gateway base URL:
+   * `https://gateway.ai.cloudflare.com/v1/{account}/{gateway}`. Append the
+   * provider slug (`/openai`, `/anthropic`, `/workers-ai`, …) per provider.
+   */
+  baseURL: string;
+  /** The gateway id (slug). */
+  gatewayId: string;
+  /**
+   * Request headers for a gateway-routed call: `cf-aig-authorization` when the
+   * gateway is authenticated, and `cf-aig-metadata` when correlation metadata
+   * was supplied. Empty object when neither applies.
+   */
+  headers: Record<string, string>;
+}
+/** Env var naming the Cloudflare account that owns the gateway. */
+declare const AI_GATEWAY_ACCOUNT_ID_ENV = "LUNORA_AI_GATEWAY_ACCOUNT_ID";
+/** Env var naming the AI Gateway id (the gateway's slug). */
+declare const AI_GATEWAY_ID_ENV = "LUNORA_AI_GATEWAY_ID";
+/**
+ * Env var carrying the gateway's authentication token (only for authenticated
+ * gateways).
+ *
+ * **Workers AI binding limitation.** This token is delivered only on the
+ * bring-your-own AI SDK provider path, as the `cf-aig-authorization` header (see
+ * {@link ResolvedAiGateway.headers}). The Workers AI **binding** (`ctx.ai` over
+ * `env.AI`) routes through the gateway with the account's own credentials and its
+ * native `gateway` option (Cloudflare's `GatewayOptions`: `id` / `cacheKey` /
+ * `metadata` / …) has no authorization field — so an *authenticated* gateway that
+ * requires a token cannot be reached on the binding path. Set this only for a BYO
+ * provider; for Workers AI, leave the gateway unauthenticated (or front it with a
+ * BYO provider). {@link resolveAiGateway} warns once per isolate if the token is
+ * set on the binding path.
+ */
+declare const AI_GATEWAY_TOKEN_ENV = "LUNORA_AI_GATEWAY_TOKEN";
+/**
+ * Resolve the Cloudflare AI Gateway coordinates from the Worker `env`, or
+ * `undefined` when the gateway is not configured (both `LUNORA_AI_GATEWAY_ACCOUNT_ID`
+ * and `LUNORA_AI_GATEWAY_ID` must be present). Opt-in and backward-compatible:
+ * an unconfigured app gets `undefined` and every caller keeps its direct-provider
+ * behavior.
+ *
+ * Pass optional {@link AiGatewayMetadata} to fold a `cf-aig-metadata` correlation
+ * header into `headers` — only its defined fields are sent.
+ *
+ * `consumer` names the surface resolving the gateway (default `"byo-provider"`).
+ * When it is `"workers-ai-binding"` and an {@link AI_GATEWAY_TOKEN_ENV} token is
+ * configured, this warns once per isolate: the binding path cannot carry the
+ * token (see {@link AI_GATEWAY_TOKEN_ENV}), so it would otherwise be dropped with
+ * no diagnostic and every `ctx.ai.model(...)` call would fail against an
+ * authenticated gateway while the token var reads as "configured".
+ * @experimental
+ */
+declare const resolveAiGateway: (env: Record<string, unknown>, metadata?: AiGatewayMetadata, consumer?: AiGatewayConsumer) => ResolvedAiGateway | undefined;
+/**
+ * Structural projection of the Cloudflare Workers `AI` binding (`env.AI`).
+ * Declared locally so unit tests can pass a plain-object double and the real
+ * binding satisfies the same shape without importing `@cloudflare/workers-types`
+ * into the public surface. Mirrors the `run` method documented at
+ * https://developers.cloudflare.com/workers-ai/.
+ * @experimental
+ */
+interface AiBindingLike {
+  run: (model: string, inputs: Record<string, unknown>, options?: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * A Workers AI provider instance — the value returned by `createWorkersAI(...)`.
+ * Calling it with a model id yields an AI SDK {@link LanguageModel}; the
+ * optional `textEmbeddingModel` factory yields an {@link EmbeddingModel}.
+ * Typed structurally so `@lunora/ai` neither re-declares the provider's full
+ * surface nor hard-pins its exact type across minor releases.
+ * @experimental
+ */
+interface WorkersAiProviderLike {
+  (modelId: string, settings?: Record<string, unknown>): LanguageModel;
+  textEmbeddingModel?: (modelId: string) => EmbeddingModel;
+}
+/**
+ * AI Gateway options forwarded to `createWorkersAI`. Lets inference route
+ * through a Cloudflare AI Gateway for caching, rate-limiting, and observability.
+ * @experimental
+ */
+interface AiGatewayOptions {
+  [key: string]: unknown;
+  id: string;
+  /**
+   * Custom correlation metadata surfaced in the AI Gateway logs (Cloudflare's
+   * native `gateway.metadata`). `@lunora/ai` folds `{ functionPath, traceId }`
+   * here from {@link LunoraAiOptions.metadata} when a gateway is configured.
+   */
+  metadata?: Record<string, string>;
+}
+/**
+ * `LunoraAiOptions` is part of the experimental `@lunora/ai` API and may change without a major version bump.
+ * @experimental
+ */
+interface LunoraAiOptions {
+  /**
+   * The Workers `AI` binding (`env.AI`). Required for the zero-config Workers
+   * AI default and for the raw `ai.run(...)` passthrough. May be omitted when
+   * a pre-built `provider` is supplied (e.g. in tests or a custom setup).
+   */
+  binding?: AiBindingLike;
+  /**
+   * Default Workers AI **embedding** model id used by `embeddingModel()` when no
+   * explicit model is passed (e.g. `@cf/baai/bge-base-en-v1.5`). Kept separate
+   * from `defaultModel` because a language-model id and an embedding-model
+   * id belong to different Workers AI families and are never interchangeable —
+   * reusing the language-model default here would defer a wrong-family error to
+   * inference time. Has no effect on bring-your-own providers.
+   */
+  defaultEmbeddingModel?: string;
+  /**
+   * Default Workers AI **language** model id used by `model()` when no explicit
+   * model is passed. For embeddings, set `defaultEmbeddingModel` instead.
+   * Has no effect on bring-your-own providers.
+   */
+  defaultModel?: string;
+  /**
+   * The Worker `env`, read for opt-in Cloudflare AI Gateway routing (the
+   * `LUNORA_AI_GATEWAY_*` vars, via `resolveAiGateway`). When it configures a
+   * gateway and no explicit {@link LunoraAiOptions.gateway} is given, the
+   * Workers AI provider is routed through that gateway so token + dollar-cost
+   * telemetry is computed on the app's behalf. Unset, or with no gateway vars,
+   * behavior is unchanged (calls go straight to Workers AI).
+   */
+  env?: Record<string, unknown>;
+  /**
+   * Route Workers AI inference through a Cloudflare AI Gateway. An explicit
+   * value wins over anything derived from {@link LunoraAiOptions.env}.
+   */
+  gateway?: AiGatewayOptions;
+  /**
+   * Correlation metadata folded into the active gateway call (the Workers AI
+   * binding's native `gateway.metadata`) so an AI Gateway log entry ties back
+   * to the Lunora function + trace that made it. Only applied when a gateway is
+   * actually configured (explicit or env-derived) and only its defined fields
+   * are sent — absent otherwise, so behavior is unchanged. The generated
+   * `ctx.ai` facade threads `{ functionPath, traceId }` here automatically.
+   */
+  metadata?: AiGatewayMetadata;
+  /**
+   * Pre-built Workers AI provider. When omitted, one is constructed from
+   * `binding` via `createWorkersAI`. Supplying it directly is the seam used by
+   * tests and advanced setups; it also lets callers configure the provider
+   * (e.g. `safePrompt`) before handing it to `@lunora/ai`.
+   */
+  provider?: WorkersAiProviderLike;
+}
+/**
+ * A model to run against. The AI SDK's {@link LanguageModel} already admits a
+ * bare `string`, so this alias covers both arms of the provider-agnostic seam:
+ * a string id is the Workers AI convenience path (resolved by `ctx.ai.model`),
+ * a built model object is bring-your-own (`@ai-sdk/openai`, `@ai-sdk/anthropic`,
+ * `@ai-sdk/google`, OpenRouter, …).
+ * @experimental
+ */
+type ModelInput = LanguageModel;
+/**
+ * Likewise for embeddings: a Workers AI embedding model id (e.g.
+ * `@cf/baai/bge-base-en-v1.5`) or any AI SDK {@link EmbeddingModel}.
+ * @experimental
+ */
+type EmbeddingModelInput = EmbeddingModel | string;
+/**
+ * The `ctx.ai` surface. `model`/`embeddingModel` resolve a Workers AI model from
+ * a string (the default provider) and pass any non-string model straight through,
+ * so both accept Workers AI and bring-your-own providers. Feed the resolved model
+ * to the AI SDK functions re-exported from `@lunora/ai` (`generateText`,
+ * `streamText`, `generateObject`, `embed`, …); `run` is the raw binding escape
+ * hatch, and `workersai` is the underlying provider for direct model access.
+ * @experimental
+ */
+interface LunoraAi {
+  /** Resolve an {@link EmbeddingModel}: a string → Workers AI, an object → passthrough. */
+  embeddingModel: (model?: EmbeddingModelInput) => EmbeddingModel;
+  /** Resolve a {@link LanguageModel}: a string → Workers AI, an object → passthrough. */
+  model: (model?: ModelInput) => LanguageModel;
+  /**
+   * Raw Workers AI binding passthrough (void-style `ai.run`). Bypasses the AI
+   * SDK entirely — useful for Workers-AI-only model families (image, ASR,
+   * translation) not surfaced through the provider. Throws if no binding was
+   * supplied.
+   */
+  run: (model: string, inputs: Record<string, unknown>, options?: Record<string, unknown>) => Promise<unknown>;
+  /** The underlying Workers AI provider — `ai.workersai("@cf/...")` for a raw model. */
+  workersai: WorkersAiProviderLike;
+}
+export { AI_GATEWAY_ACCOUNT_ID_ENV as A, EmbeddingModelInput as E, LunoraAiOptions as L, ModelInput as M, ResolvedAiGateway as R, WorkersAiProviderLike as W, LunoraAi as a, AI_GATEWAY_ID_ENV as b, AI_GATEWAY_TOKEN_ENV as c, AiBindingLike as d, AiGatewayMetadata as e, AiGatewayOptions as f, buildAiGatewayMetadataFields as g, resolveAiGateway as r };