@lunora/ai 1.0.0-alpha.13 → 1.0.0-alpha.131

package/dist/packem_shared/types.d-KCPinSfY.d.mts

@@ -0,0 +1,614 @@
+import { EmbeddingModel, LanguageModel } from 'ai';
+/**
+ * AI Gateway's hard limit on `cf-aig-metadata` keys. Exceeding it makes the
+ * gateway reject the metadata object entirely, so the builder trims to this
+ * rather than sending something that will be thrown away.
+ */
+declare const AI_GATEWAY_METADATA_MAX_KEYS = 5;
+/**
+ * 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;
+/**
+ * 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";
+/**
+ * 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;
+  /**
+   * App-supplied correlation tags — what the app slices its own AI spend by:
+   * feature, plan, tenant, a hashed user id. AI Gateway's cost filtering can
+   * only group by keys that were sent WITH the call, so a tag not set here is
+   * a question that cannot be asked later.
+   *
+   * Merged under the built-in fields, which win on a key collision, and
+   * trimmed to AI Gateway's {@link AI_GATEWAY_METADATA_MAX_KEYS}-key limit —
+   * over it, the gateway rejects the metadata outright and the correlation is
+   * lost rather than truncated.
+   *
+   * Values should stay low-cardinality for the same reason a route label
+   * does: a raw user id per call makes every call its own group. Hash it.
+   */
+  tags?: Record<string, 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 carrying the default Workers AI **language** model id, used by
+ * `ctx.ai.model()` when it is called with no argument.
+ *
+ * This exists because `env` is the only configuration seam `ctx.ai` has. The
+ * generated shard constructs the facade as `createAi({ binding, env, metadata })`
+ * with those three fields fixed, so `LunoraAiOptions.defaultModel` — the field
+ * `model()` reads — was unreachable from an app: `ctx.ai.model()` with no
+ * argument threw, always. Reading the default off `env` puts it back in the
+ * app's hands (a wrangler `vars` entry or `.dev.vars` line) without a new
+ * constructor argument codegen would have to learn to emit.
+ *
+ * An explicit `defaultModel` option still wins — the env var is
+ * the fallback, exactly as with the gateway vars above.
+ */
+declare const AI_DEFAULT_MODEL_ENV = "LUNORA_AI_DEFAULT_MODEL";
+/**
+ * Env var carrying the default Workers AI **embedding** model id, used by
+ * `ctx.ai.embeddingModel()` with no argument — and so by `defineRag`, whose
+ * `embeddingModel` is documented as optional and resolves through exactly that
+ * call. Separate from {@link AI_DEFAULT_MODEL_ENV} because a language-model id
+ * and an embedding-model id are never interchangeable.
+ */
+declare const AI_DEFAULT_EMBEDDING_MODEL_ENV = "LUNORA_AI_DEFAULT_EMBEDDING_MODEL";
+/** 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";
+/**
+ * Env var carrying deployment-scoped AI Gateway tags as a flat JSON object of
+ * string values, e.g. `{"app":"checkout","env":"prod"}`.
+ *
+ * Deployment-scoped because that is the dimension you cannot recover in code:
+ * AI Gateway can only filter cost by keys that were sent WITH the call, and
+ * "which environment / which app spent this" is fixed at deploy time. Per-call
+ * tags (feature, hashed user) go through {@link AiGatewayMetadata.tags}
+ * instead. A malformed value is ignored with a warning rather than failing the
+ * call — telemetry configuration must not take inference down.
+ */
+declare const AI_GATEWAY_TAGS_ENV = "LUNORA_AI_GATEWAY_TAGS";
+/**
+ * Env var carrying the base URL of a self-hosted OpenAI-compatible proxy
+ * (LiteLLM, OpenRouter, your own), e.g. `https://ai-proxy.internal/v1`.
+ *
+ * When set, `ctx.ai.model("<provider>/<model>")` sends the slug unchanged as the
+ * `model` of an OpenAI chat-completions request to this URL instead of routing
+ * it through Cloudflare AI Gateway — which needs no `AI` binding, so it is how
+ * `ctx.ai` works on hosts without Workers AI (celld). `@cf/…` ids still need
+ * the binding.
+ */
+declare const AI_PROXY_URL_ENV = "LUNORA_AI_PROXY_URL";
+/** Env var carrying the bearer token sent to {@link AI_PROXY_URL_ENV}, when the proxy requires one. */
+declare const AI_PROXY_TOKEN_ENV = "LUNORA_AI_PROXY_TOKEN";
+/**
+ * Parse {@link AI_GATEWAY_TAGS_ENV} into tag fields. Non-string values are
+ * dropped rather than coerced — a number silently becoming `"1"` is a worse
+ * outcome than the tag being absent and visibly so.
+ */
+declare const readAiGatewayEnvTags: (env: Record<string, unknown>) => Record<string, string> | undefined;
+/**
+ * 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>;
+  /**
+   * Markdown Conversion API (beta) — converts a document (PDF, Office file,
+   * HTML, image) to Markdown. Optional because runtimes and test doubles that
+   * predate it have no such method; `ctx.ai.toMarkdown` reports that instead
+   * of a bare `TypeError`. Mirrors `env.AI.toMarkdown(files, options)` at
+   * https://developers.cloudflare.com/workers-ai/features/markdown-conversion/.
+   */
+  toMarkdown?: (files: AiMarkdownDocument | AiMarkdownDocument[], options?: Record<string, unknown>) => Promise<AiMarkdownConversionResult | AiMarkdownConversionResult[]>;
+  /**
+   * Web Search API (beta). Optional because runtimes and test doubles that
+   * predate it have no such method; `ctx.ai.websearch` reports that instead of
+   * a bare `TypeError`.
+   */
+  websearch?: (input: Omit<AiWebSearchOptions, "gatewayId"> & {
+    gatewayId: string;
+    query: string;
+  }) => Promise<Response>;
+}
+/**
+ * One document handed to `ctx.ai.toMarkdown(...)`: the Workers AI
+ * `MarkdownDocument` shape (a name plus a Blob carrying the bytes).
+ * @experimental
+ */
+interface AiMarkdownDocument {
+  blob: Blob;
+  name: string;
+}
+/**
+ * One Workers AI `ConversionResult`. `data` and `tokens` are present only when
+ * `format` is `"markdown"` (or `"text"`); an `"error"` result carries `error`
+ * instead. `pages` is not in the current binding contract — carried here so a
+ * binding that starts reporting it passes through unchanged.
+ * @experimental
+ */
+interface AiMarkdownConversionResult {
+  data?: string;
+  error?: string;
+  format: "error" | "markdown" | "text";
+  id?: string;
+  /** The detected document mime type (spelled `mimetype` by the binding). */
+  mimetype?: string;
+  name?: string;
+  /** Page count, when the binding reports it. */
+  pages?: number;
+  tokens?: number;
+}
+/**
+ * What `ctx.ai.toMarkdown(...)` accepts: a `Blob`, raw bytes, or a `URL` that
+ * is fetched first.
+ * @experimental
+ */
+type AiToMarkdownInput = ArrayBuffer | Blob | Uint8Array | URL;
+/**
+ * Options for `ctx.ai.toMarkdown(...)`.
+ * @experimental
+ */
+interface AiToMarkdownOptions {
+  /** Conversion options forwarded verbatim to the binding's `toMarkdown(files, options)`. */
+  conversionOptions?: Record<string, unknown>;
+  /**
+   * Byte cap for a `URL`/raw-bytes input, guarding against an accidental huge
+   * download. Defaults to 20 MiB. A `Blob` is checked against the same cap.
+   */
+  maxBytes?: number;
+  /** MIME type for a raw `ArrayBuffer`/`Uint8Array` input (a `Blob`/`URL` carries its own). */
+  mimeType?: string;
+  /** Document name sent to the binding; defaults to the URL's last path segment, else `"document"`. */
+  name?: string;
+}
+/**
+ * What `ctx.ai.toMarkdown(...)` resolves to — the first (and only) converted
+ * document, normalised across the binding's single/array return.
+ * @experimental
+ */
+interface AiToMarkdownResult {
+  markdown: string;
+  /** The detected mime type of the source document, when the binding reports it. */
+  mimeType?: string;
+  /** Page count, when the binding reports it. */
+  pages?: number;
+  /** The binding's estimated token count for the converted Markdown, when reported. */
+  tokens?: number;
+}
+/**
+ * One generated image: base64 bytes (`base64`), a URL, or the provider's media
+ * type. Which fields are present depends on the provider.
+ * @experimental
+ */
+interface AiImage {
+  base64?: string;
+  mimeType?: string;
+  url?: string;
+}
+/**
+ * Input for `ctx.ai.images.generate(...)`.
+ * @experimental
+ */
+interface AiImageGenerateInput {
+  /** How many images to generate. Defaults to 1. */
+  count?: number;
+  /**
+   * A model id: a Workers AI image model (`@cf/black-forest-labs/flux-1-schnell`),
+   * or an `"openai/<model>"` / `"google/<model>"` slug routed through the AI
+   * Gateway. Any other slug throws `AI_UNKNOWN_IMAGE_MODEL`.
+   */
+  model: string;
+  prompt: string;
+  /**
+   * Seed for reproducible generation, for providers that support it. A Workers AI
+   * `count` batch uses `seed + i` for image `i`, so the images differ; provider
+   * models receive the seed as given.
+   */
+  seed?: number;
+  /** Image size as `"<width>x<height>"`, e.g. `"1024x1024"`. */
+  size?: `${number}x${number}`;
+}
+/**
+ * What `ctx.ai.images.generate(...)` resolves to.
+ * @experimental
+ */
+interface AiImageGenerateResult {
+  images: AiImage[];
+  /** The model id the caller asked for (the unmodified `input.model`). */
+  model: string;
+}
+/**
+ * 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. It is the shape of
+ * the lazy delegate `ctx.ai.workersai` exposes, so only the callable factory and
+ * `textEmbeddingModel` are part of it.
+ * @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>;
+}
+/**
+ * Options for the raw `ctx.ai.run(...)` passthrough — the Workers AI binding's
+ * third argument. Unlisted keys are forwarded to the binding unchanged.
+ * @experimental
+ */
+interface AiRunOptions {
+  [key: string]: unknown;
+  /** Route this call through a Cloudflare AI Gateway. Defaults to the gateway `createAi` resolved. */
+  gateway?: AiGatewayOptions;
+  /**
+   * Fail at once instead of waiting in the Workers AI capacity queue when no
+   * capacity is free. The rejection surfaces as a `LunoraError` with code
+   * `RATE_LIMITED` (Workers AI error `3040`, HTTP 429).
+   */
+  rejectIfBusy?: boolean;
+}
+/**
+ * Per-call settings for `ctx.ai.model(...)`. Applied to Workers AI model ids
+ * (`@cf/…`) only; a gateway slug or a bring-your-own model ignores them.
+ * @experimental
+ */
+interface AiModelOptions {
+  /**
+   * Fail at once instead of waiting in the Workers AI capacity queue. The
+   * provider reports the rejection as an AI SDK `APICallError` with
+   * `statusCode: 429`, which the AI SDK retries unless the call sets
+   * `maxRetries: 0`.
+   */
+  rejectIfBusy?: boolean;
+}
+/**
+ * Structural slice of the span handle `ctx.trace` hands its body — enough to
+ * attach a model call's usage once it is known. Declared here rather than
+ * imported so `@lunora/ai` takes no dependency on `@lunora/server`; the real
+ * handle is assignable to it.
+ * @experimental
+ */
+interface AiSpan {
+  setAttribute: (key: string, value: unknown) => void;
+  setAttributes: (fields: Record<string, unknown>) => void;
+}
+/**
+ * Structural slice of `ctx.trace` (the server `LunoraTracer`): runs `function_`
+ * inside a named span and hands it the span's {@link AiSpan}.
+ * @experimental
+ */
+type AiTracer = <T>(name: string, function_: (trace: AiTracer, span: AiSpan) => Promise<T> | T, attributes?: Record<string, unknown>) => Promise<T>;
+/**
+ * Structural slice of `ctx.metrics` (the server `LunoraMetrics`) — only the
+ * counter, which is what usage accounting needs.
+ * @experimental
+ */
+interface AiMetrics {
+  count: (name: string, value?: number, attributes?: Record<string, unknown>) => void;
+}
+/**
+ * Where `ctx.ai` reports model usage. The generated `ctx.ai` passes the
+ * function's own `ctx.trace` / `ctx.metrics`, so every call made through
+ * `ctx.ai.model(...)` gets an `ai.generate` / `ai.stream` span and
+ * `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` /
+ * `gen_ai.usage.cost` counters attributed to that function.
+ * @experimental
+ */
+interface AiTelemetry {
+  metrics?: AiMetrics;
+  trace?: AiTracer;
+}
+/**
+ * `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.
+   *
+   * Falls back to `LUNORA_AI_DEFAULT_EMBEDDING_MODEL` in {@link LunoraAiOptions.env}
+   * — which is how an app sets it, since the generated `ctx.ai` is constructed
+   * with a fixed `{ binding, env, metadata }`.
+   */
+  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.
+   *
+   * Falls back to `LUNORA_AI_DEFAULT_MODEL` in {@link LunoraAiOptions.env} — the
+   * seam a Lunora app actually has (see `defaultEmbeddingModel`).
+   */
+  defaultModel?: string;
+  /**
+   * The Worker `env`, read for opt-in Cloudflare AI Gateway routing (the
+   * `LUNORA_AI_GATEWAY_*` vars, via `resolveAiGateway`) and for the default
+   * model ids (`LUNORA_AI_DEFAULT_MODEL` / `LUNORA_AI_DEFAULT_EMBEDDING_MODEL`).
+   * 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;
+  /**
+   * Record every language-model call resolved by `model()` — a span plus
+   * token and cost counters (see {@link AiTelemetry}). Omitted, models are
+   * returned unwrapped.
+   */
+  telemetry?: AiTelemetry;
+}
+/**
+ * A search provider the Web Search API brokers. Each one runs under Cloudflare's
+ * Zero Data Retention terms. A search bills a provider key stored on the gateway
+ * when there is one (the `default` alias unless `byokAlias` names another),
+ * otherwise AI Gateway credits at list price.
+ * @experimental
+ */
+type AiWebSearchProvider = "ceramic" | "exa" | "linkup";
+/**
+ * Options for `ctx.ai.websearch(...)`.
+ * @experimental
+ */
+interface AiWebSearchOptions {
+  /** Alias of a provider key stored on the gateway to bill instead of the `default` alias. Without a stored key, gateway credits pay. */
+  byokAlias?: string;
+  /**
+   * The AI Gateway that brokers and bills the search. Defaults to the gateway
+   * `ctx.ai` routes inference through (`LUNORA_AI_GATEWAY_ID`), else the
+   * account's `default` gateway.
+   */
+  gatewayId?: string;
+  /** Maximum results, 1–10. Defaults to 10. */
+  limit?: number;
+  /** Defaults to `"ceramic"`. */
+  provider?: AiWebSearchProvider;
+}
+/**
+ * One result. Web search is discovery only: a result describes a page, and
+ * reading the page is a separate `fetch` of its `url`. The optional fields are
+ * present only when the provider returns them.
+ * @experimental
+ */
+interface AiWebSearchItem {
+  description?: string;
+  faviconUrl?: string;
+  imageUrl?: string;
+  /** Naive (no timezone) ISO-8601 datetime, e.g. `"2025-11-30T04:39:48"`. */
+  lastModifiedDate?: string;
+  title: string;
+  url: string;
+}
+/**
+ * What `ctx.ai.websearch(...)` resolves to.
+ * @experimental
+ */
+interface AiWebSearchResult {
+  items: AiWebSearchItem[];
+  metadata: {
+    latencyMs: number;
+    query: string;
+    requestId: string;
+  };
+}
+/**
+ * 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 resolved by `ctx.ai.model` — a Workers AI id (`@cf/…`), a
+ * `"<provider>/<model>"` slug (`anthropic/claude-sonnet-5`, `openai/gpt-5`, …)
+ * routed through Cloudflare AI Gateway, or a gateway dynamic route
+ * (`dynamic/<route>`); 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 lazy provider delegate for direct model access.
+ * @experimental
+ */
+interface LunoraAi {
+  /** Resolve an {@link EmbeddingModel}: a string → Workers AI, an object → passthrough. */
+  embeddingModel: (model?: EmbeddingModelInput) => EmbeddingModel;
+  /**
+   * Generate images. A Workers AI image model id (`@cf/…`) runs through the
+   * binding (and the AI Gateway when configured); an `"openai/<model>"` or
+   * `"google/<model>"` slug routes to that provider's image endpoint through
+   * the AI Gateway. Any other slug throws `AI_UNKNOWN_IMAGE_MODEL`; a
+   * Workers AI id without a binding throws the same directed error `run` does.
+   */
+  images: {
+    generate: (input: AiImageGenerateInput) => Promise<AiImageGenerateResult>;
+  };
+  /**
+   * Resolve a {@link LanguageModel}: a `@cf/…` id → Workers AI, a
+   * `"<provider>/<model>"` slug or `dynamic/<route>` → Cloudflare AI Gateway
+   * over the same binding (Unified Billing or the gateway's stored keys — no
+   * provider key in the app) or, with `LUNORA_AI_PROXY_URL` set, to that
+   * OpenAI-compatible proxy; an object → passthrough.
+   */
+  model: (model?: ModelInput, options?: AiModelOptions) => 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?: AiRunOptions) => Promise<unknown>;
+  /**
+   * Convert a document (PDF, Office file, HTML, image) to Markdown through the
+   * binding's Markdown Conversion API (beta). Accepts a `Blob`, raw bytes or a
+   * `URL` (fetched first). Throws if no binding was supplied, or if the
+   * runtime's binding has no `toMarkdown()`.
+   */
+  toMarkdown: (input: AiToMarkdownInput, options?: AiToMarkdownOptions) => Promise<AiToMarkdownResult>;
+  /**
+   * Search the web through the binding's Web Search API (beta) to ground a
+   * response in live information. Billed to a stored provider key or AI Gateway
+   * credits (see {@link AiWebSearchProvider}). Throws if no
+   * binding was supplied, or if the runtime's binding has no `websearch()`.
+   */
+  websearch: (query: string, options?: AiWebSearchOptions) => Promise<AiWebSearchResult>;
+  /**
+   * A lazy delegate to the Workers AI provider: call it as
+   * `ai.workersai("@cf/…")` for a raw language model, or use
+   * `ai.workersai.textEmbeddingModel("@cf/…")` for embeddings. The provider
+   * module loads on first use, so only the callable factory and
+   * `textEmbeddingModel` are exposed — the rest of the `createWorkersAI`
+   * factories (image, transcription, speech, …) are not part of this surface.
+   */
+  workersai: WorkersAiProviderLike;
+}
+export { AiBindingLike as A, AiTelemetry as B, AiTracer as C, AiWebSearchOptions as D, EmbeddingModelInput as E, AiWebSearchResult as F, buildAiGatewayMetadataFields as G, readAiGatewayEnvTags as H, resolveAiGateway as I, LunoraAi as L, ModelInput as M, ResolvedAiGateway as R, WorkersAiProviderLike as W, LunoraAiOptions as a, AiImage as b, AiImageGenerateInput as c, AiImageGenerateResult as d, AiToMarkdownInput as e, AiToMarkdownOptions as f, AiToMarkdownResult as g, AiWebSearchItem as h, AiWebSearchProvider as i, AI_DEFAULT_EMBEDDING_MODEL_ENV as j, AI_DEFAULT_MODEL_ENV as k, AI_GATEWAY_ACCOUNT_ID_ENV as l, AI_GATEWAY_ID_ENV as m, AI_GATEWAY_METADATA_MAX_KEYS as n, AI_GATEWAY_TAGS_ENV as o, AI_GATEWAY_TOKEN_ENV as p, AI_PROXY_TOKEN_ENV as q, AI_PROXY_URL_ENV as r, AiGatewayMetadata as s, AiGatewayOptions as t, AiMarkdownConversionResult as u, AiMarkdownDocument as v, AiMetrics as w, AiModelOptions as x, AiRunOptions as y, AiSpan as z };