@lunora/ai 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/packem_shared/defineRag-CQ3pnKUh.mjs

@@ -0,0 +1,471 @@
+import { LunoraError } from '@lunora/errors';
+import { tool, jsonSchema, embed } from 'ai';
+import fixedWindowChunks from './fixedWindowChunks-J-WfQDw9.mjs';
+import hybridRank from './hybridRank-DPC9c2ON.mjs';
+
+const INDEX_CONCURRENCY = 8;
+const concurrentMap = async (items, limit, function_) => {
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new RangeError("concurrentMap: `limit` must be a positive integer");
+  }
+  if (items.length === 0) {
+    return [];
+  }
+  const effectiveLimit = Math.max(1, Math.min(limit, items.length));
+  const results = Array.from({ length: items.length });
+  let cursor = 0;
+  let failed = false;
+  let firstError;
+  const worker = async () => {
+    for (; ; ) {
+      if (failed) {
+        return;
+      }
+      const index = cursor;
+      cursor += 1;
+      if (index >= items.length) {
+        return;
+      }
+      try {
+        results[index] = await function_(items[index], index);
+      } catch (error) {
+        if (!failed) {
+          failed = true;
+          firstError = error;
+        }
+        return;
+      }
+    }
+  };
+  const workers = Array.from({ length: effectiveLimit }, () => worker());
+  await Promise.all(workers);
+  if (failed) {
+    throw firstError;
+  }
+  return results;
+};
+
+const DEFAULT_CHUNK_SIZE = 1e3;
+const DEFAULT_CHUNK_OVERLAP = 200;
+const DEFAULT_TOP_K = 5;
+const MAX_TOP_K_FULL_METADATA = 20;
+const MAX_TOP_K = 100;
+const CHUNK_INDEX_KEY = "__ragChunk";
+const SOURCE_KEY = "__ragSource";
+const TEXT_KEY = "__ragText";
+const HASH_KEY = "__ragHash";
+const COUNT_KEY = "__ragChunks";
+const IMPORTANCE_KEY = "__ragImportance";
+const MODEL_KEY = "__ragModel";
+const INTERNAL_KEYS = /* @__PURE__ */ new Set([CHUNK_INDEX_KEY, COUNT_KEY, HASH_KEY, IMPORTANCE_KEY, MODEL_KEY, SOURCE_KEY, TEXT_KEY]);
+const MODEL_VERSION_PATTERN = /^[\w.-]{1,40}$/;
+const namespacePrefix = (namespace) => namespace === void 0 ? "" : `${encodeURIComponent(namespace)}#`;
+const chunkVectorId = (namespace, sourceId, chunkIndex) => `${namespacePrefix(namespace)}${sourceId}#${String(chunkIndex)}`;
+const parseChunkVectorId = (id, namespace) => {
+  const prefix = namespacePrefix(namespace);
+  const body = prefix !== "" && id.startsWith(prefix) ? id.slice(prefix.length) : id;
+  const separator = body.lastIndexOf("#");
+  const chunkIndex = separator === -1 ? Number.NaN : Number(body.slice(separator + 1));
+  if (separator === -1 || !Number.isInteger(chunkIndex) || chunkIndex < 0) {
+    return { chunkIndex: 0, sourceId: body };
+  }
+  return { chunkIndex, sourceId: body.slice(0, separator) };
+};
+const sha256Hex = async (text) => {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+const userMetadataOf = (metadata) => {
+  if (!metadata) {
+    return void 0;
+  }
+  const entries = Object.entries(metadata).filter(([key]) => !INTERNAL_KEYS.has(key));
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+};
+const sharedNamespaceWarned = /* @__PURE__ */ new Set();
+const warnSharedNamespace = (indexName) => {
+  if (sharedNamespaceWarned.has(indexName)) {
+    return;
+  }
+  sharedNamespaceWarned.add(indexName);
+  console.warn(
+    `[@lunora/ai/rag] index "${indexName}" is used without a namespace — in a multi-tenant/sharded
+app this shares one tenant's chunks (text included) with every other tenant, since
+Vectorize indexes are account-global. Pass \`namespace\` (the shard/tenant key) on both
+index() and retrieve(). Single-tenant apps suppress this via { allowSharedNamespace: true }.`
+  );
+};
+const assembleContext = (chunks) => chunks.map((chunk) => `[source:${chunk.sourceId}#${String(chunk.chunkIndex)}]
+${chunk.text}`).join("\n\n");
+const resolveEmbeddingModel = (input, ai) => {
+  if (typeof input === "object") {
+    return input;
+  }
+  if (ai === void 0) {
+    throw new LunoraError(
+      "INTERNAL",
+      "@lunora/ai/rag: `embeddingModel` is a Workers AI model id (or omitted) but the bound context has no `ai` (env.AI). Pass an AI SDK EmbeddingModel object to embed without Workers AI, or bind a context whose `ctx.ai` is wired."
+    );
+  }
+  return ai.embeddingModel(input);
+};
+const modelIdOf = (model) => {
+  const id = model.modelId;
+  return typeof id === "string" && id.length > 0 ? id : void 0;
+};
+const embedCostOf = (providerMetadata) => {
+  if (typeof providerMetadata !== "object" || providerMetadata === null) {
+    return void 0;
+  }
+  for (const bag of Object.values(providerMetadata)) {
+    if (typeof bag === "object" && bag !== null) {
+      const { cost } = bag;
+      if (typeof cost === "number" && Number.isFinite(cost)) {
+        return cost;
+      }
+    }
+  }
+  return void 0;
+};
+const defineRag = (config) => {
+  if (typeof config.index !== "string" || config.index.length === 0) {
+    throw new LunoraError("BAD_REQUEST", "@lunora/ai/rag: `index` must be a non-empty Vectorize index name");
+  }
+  const chunkSize = config.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  const chunkOverlap = config.chunkOverlap ?? DEFAULT_CHUNK_OVERLAP;
+  if (!Number.isInteger(chunkSize) || chunkSize < 1) {
+    throw new LunoraError("BAD_REQUEST", "@lunora/ai/rag: `chunkSize` must be a positive integer");
+  }
+  if (!Number.isInteger(chunkOverlap) || chunkOverlap < 0 || chunkOverlap >= chunkSize) {
+    throw new LunoraError("BAD_REQUEST", "@lunora/ai/rag: `chunkOverlap` must be a non-negative integer smaller than `chunkSize`");
+  }
+  const defaultTopK = config.topK ?? DEFAULT_TOP_K;
+  if (!Number.isInteger(defaultTopK) || defaultTopK < 1) {
+    throw new LunoraError("BAD_REQUEST", "@lunora/ai/rag: `topK` must be a positive integer");
+  }
+  if (config.embeddingModelVersion !== void 0 && !MODEL_VERSION_PATTERN.test(config.embeddingModelVersion)) {
+    throw new LunoraError(
+      "BAD_REQUEST",
+      '@lunora/ai/rag: `embeddingModelVersion` must match /^[A-Za-z0-9._-]{1,40}$/ (a short, stable tag like "bge-v1.5")'
+    );
+  }
+  const splitter = config.chunk ?? ((text) => fixedWindowChunks(text, chunkSize, chunkOverlap));
+  const { textStore } = config;
+  const topKCeiling = textStore ? MAX_TOP_K : MAX_TOP_K_FULL_METADATA;
+  const modelTag = config.embeddingModelVersion;
+  const withModelTag = (namespace) => {
+    if (modelTag === void 0) {
+      return namespace;
+    }
+    return namespace === void 0 ? modelTag : `${modelTag}::${namespace}`;
+  };
+  return (context) => {
+    let model;
+    const tracer = typeof context.trace === "function" ? context.trace : void 0;
+    const embedText = async (text) => {
+      model ??= resolveEmbeddingModel(config.embeddingModel, context.ai);
+      const resolvedModel = model;
+      const run = async (span) => {
+        const { embedding, providerMetadata, usage } = await embed({ model: resolvedModel, value: text });
+        if (span !== void 0) {
+          const inputTokens = usage.tokens;
+          if (typeof inputTokens === "number" && Number.isFinite(inputTokens)) {
+            span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
+          }
+          const cost = embedCostOf(providerMetadata);
+          if (cost !== void 0) {
+            span.setAttribute("gen_ai.usage.cost", cost);
+          }
+        }
+        return embedding;
+      };
+      if (tracer === void 0) {
+        return run();
+      }
+      const modelId = modelIdOf(resolvedModel);
+      return tracer("ai.embed", (_trace, span) => run(span), {
+        "gen_ai.operation.name": "embeddings",
+        ...modelId === void 0 ? {} : { "gen_ai.request.model": modelId }
+      });
+    };
+    const checkNamespace = (namespace) => {
+      if (namespace !== void 0) {
+        return;
+      }
+      if (config.requireNamespace) {
+        throw new LunoraError(
+          "BAD_REQUEST",
+          `@lunora/ai/rag: index "${config.index}" requires a namespace (requireNamespace is set) — pass the tenant/shard key on index()/retrieve()/remove()`
+        );
+      }
+      if (!config.allowSharedNamespace) {
+        warnSharedNamespace(config.index);
+      }
+    };
+    const readHead = async (sourceId, namespace) => {
+      const [head] = await context.vectors.getByIds(config.index, [chunkVectorId(namespace, sourceId, 0)], namespace);
+      const hash = head?.metadata?.[HASH_KEY];
+      const chunks = head?.metadata?.[COUNT_KEY];
+      return {
+        chunks: typeof chunks === "number" && Number.isInteger(chunks) && chunks > 0 ? chunks : void 0,
+        hash: typeof hash === "string" ? hash : void 0
+      };
+    };
+    const deleteChunkRange = async (sourceId, from, to, namespace) => {
+      const ids = Array.from({ length: to - from }, (_, offset) => chunkVectorId(namespace, sourceId, from + offset));
+      if (ids.length === 0) {
+        return;
+      }
+      await context.vectors.deleteByIds(config.index, ids, namespace);
+      await textStore?.remove?.(ids, { namespace });
+      await config.lexicalStore?.remove?.(ids, { namespace });
+    };
+    const index = async (input) => {
+      checkNamespace(input.namespace);
+      if (input.importance !== void 0 && (typeof input.importance !== "number" || input.importance < 0 || input.importance > 1)) {
+        throw new LunoraError("BAD_REQUEST", "@lunora/ai/rag: `importance` must be a number in [0, 1]");
+      }
+      const effectiveNamespace = withModelTag(input.namespace);
+      const hash = await sha256Hex(input.text);
+      const previous = await readHead(input.id, effectiveNamespace);
+      if (previous.hash === hash && previous.chunks !== void 0) {
+        return {
+          chunks: previous.chunks,
+          ids: Array.from({ length: previous.chunks }, (_, chunkIndex) => chunkVectorId(effectiveNamespace, input.id, chunkIndex)),
+          unchanged: true
+        };
+      }
+      const pieces = splitter(input.text);
+      const ids = pieces.map((_, chunkIndex) => chunkVectorId(effectiveNamespace, input.id, chunkIndex));
+      if (pieces.length === 0 && input.allowEmptySources === false) {
+        throw new LunoraError("BAD_REQUEST", `@lunora/ai/rag: source "${input.id}" produced zero chunks — set allowEmptySources: true to allow this`);
+      }
+      if (pieces.length > 0) {
+        const storedChunks = pieces.map((text, chunkIndex) => {
+          return { chunkIndex, id: ids[chunkIndex], sourceId: input.id, text };
+        });
+        if (textStore) {
+          await textStore.put(storedChunks, { namespace: effectiveNamespace });
+        }
+        if (config.lexicalStore) {
+          await config.lexicalStore.index(storedChunks, { namespace: effectiveNamespace });
+        }
+      }
+      await concurrentMap(pieces, INDEX_CONCURRENCY, async (piece, chunkIndex) => {
+        const id = ids[chunkIndex];
+        const metadata = {
+          ...input.metadata,
+          [CHUNK_INDEX_KEY]: chunkIndex,
+          [SOURCE_KEY]: input.id
+        };
+        if (!textStore) {
+          metadata[TEXT_KEY] = piece;
+        }
+        if (input.importance !== void 0) {
+          metadata[IMPORTANCE_KEY] = input.importance;
+        }
+        if (chunkIndex === 0) {
+          metadata[HASH_KEY] = hash;
+          metadata[COUNT_KEY] = pieces.length;
+          if (modelTag !== void 0) {
+            metadata[MODEL_KEY] = modelTag;
+          }
+        }
+        await context.vectors.upsert(config.index, {
+          embed: embedText,
+          id,
+          input: piece,
+          metadata,
+          namespace: effectiveNamespace
+        });
+        input.onChunk?.({ chunkIndex, id, text: piece, total: pieces.length });
+      });
+      if (previous.chunks !== void 0 && previous.chunks > pieces.length) {
+        await deleteChunkRange(input.id, pieces.length, previous.chunks, effectiveNamespace);
+      }
+      return { chunks: pieces.length, ids, unchanged: false };
+    };
+    const remove = async (input) => {
+      checkNamespace(input.namespace);
+      const effectiveNamespace = withModelTag(input.namespace);
+      const previous = await readHead(input.id, effectiveNamespace);
+      const totalChunks = previous.chunks ?? 1;
+      await deleteChunkRange(input.id, 0, totalChunks, effectiveNamespace);
+    };
+    const textsByIds = async (ids, namespace) => {
+      const texts = /* @__PURE__ */ new Map();
+      if (ids.length === 0) {
+        return texts;
+      }
+      if (textStore) {
+        const stored = await textStore.getMany(ids, { namespace });
+        for (const [position, id] of ids.entries()) {
+          const text = stored[position];
+          if (typeof text === "string") {
+            texts.set(id, text);
+          }
+        }
+        return texts;
+      }
+      const records = await context.vectors.getByIds(config.index, ids, namespace);
+      for (const record of records) {
+        const text = record.metadata?.[TEXT_KEY];
+        if (typeof text === "string") {
+          texts.set(record.id, text);
+        }
+      }
+      return texts;
+    };
+    const expandChunks = async (chunks, options, effectiveNamespace) => {
+      const before = options?.chunkContext?.before ?? 0;
+      const after = options?.chunkContext?.after ?? 0;
+      if (before === 0 && after === 0) {
+        return chunks;
+      }
+      if (!Number.isInteger(before) || before < 0 || !Number.isInteger(after) || after < 0) {
+        throw new LunoraError("BAD_REQUEST", "@lunora/ai/rag: `chunkContext.before`/`chunkContext.after` must be non-negative integers");
+      }
+      const known = new Map(chunks.map((chunk) => [chunk.id, chunk.text]));
+      const neighbourIds = /* @__PURE__ */ new Set();
+      for (const chunk of chunks) {
+        for (let offset = -before; offset <= after; offset += 1) {
+          const neighbourIndex = chunk.chunkIndex + offset;
+          const id = chunkVectorId(effectiveNamespace, chunk.sourceId, neighbourIndex);
+          if (offset !== 0 && neighbourIndex >= 0 && !known.has(id)) {
+            neighbourIds.add(id);
+          }
+        }
+      }
+      const neighbourTexts = await textsByIds([...neighbourIds], effectiveNamespace);
+      const textOf = (sourceId, chunkIndex) => {
+        const id = chunkVectorId(effectiveNamespace, sourceId, chunkIndex);
+        return known.get(id) ?? neighbourTexts.get(id);
+      };
+      return chunks.map((chunk) => {
+        const parts = [];
+        for (let offset = -before; offset <= after; offset += 1) {
+          const text = offset === 0 ? chunk.text : textOf(chunk.sourceId, chunk.chunkIndex + offset);
+          if (text !== void 0) {
+            parts.push(text);
+          }
+        }
+        return { ...chunk, text: parts.join("\n") };
+      });
+    };
+    const resolveFilter = (filter) => {
+      if (typeof filter === "string") {
+        const resolved = config.filters?.[filter];
+        if (!resolved) {
+          throw new LunoraError(
+            "NOT_FOUND",
+            `@lunora/ai/rag: unknown named filter "${filter}" — must be one of the keys declared in RagConfig.filters`
+          );
+        }
+        return resolved.filter;
+      }
+      return filter;
+    };
+    const parseMatches = (result, namespace) => result.matches.map((match) => {
+      const metadata = match.metadata ?? {};
+      const parsed = parseChunkVectorId(match.id, namespace);
+      const rawText = metadata[TEXT_KEY];
+      const rawImportance = metadata[IMPORTANCE_KEY];
+      const importance = typeof rawImportance === "number" && rawImportance >= 0 && rawImportance <= 1 ? rawImportance : 1;
+      return {
+        chunkIndex: parsed.chunkIndex,
+        id: match.id,
+        importance,
+        metadata: userMetadataOf(metadata),
+        score: match.score * importance,
+        sourceId: parsed.sourceId,
+        text: typeof rawText === "string" ? rawText : ""
+      };
+    });
+    const hydrateFromStore = async (chunks, namespace) => {
+      if (!textStore) {
+        return chunks;
+      }
+      const ids = chunks.map((chunk) => chunk.id);
+      const [texts, records] = await Promise.all([textsByIds(ids, namespace), context.vectors.getByIds(config.index, ids, namespace)]);
+      const fullMetadataById = new Map(records.map((record) => [record.id, record.metadata]));
+      return chunks.flatMap((chunk) => {
+        const text = texts.get(chunk.id);
+        if (text === void 0) {
+          return [];
+        }
+        const fullMetadata = fullMetadataById.get(chunk.id);
+        const rawImportance = fullMetadata?.[IMPORTANCE_KEY];
+        const importance = typeof rawImportance === "number" && rawImportance >= 0 && rawImportance <= 1 ? rawImportance : chunk.importance;
+        const score = chunk.score / chunk.importance * importance;
+        return [{ ...chunk, importance, metadata: userMetadataOf(fullMetadata) ?? chunk.metadata, score, text }];
+      });
+    };
+    const retrieve = async (query, options) => {
+      checkNamespace(options?.namespace);
+      const effectiveNamespace = withModelTag(options?.namespace);
+      const resolvedFilter = resolveFilter(options?.filter);
+      const rlsFilter = config.rlsFilter ? await config.rlsFilter(context.auth) : void 0;
+      const effectiveFilter = rlsFilter ? { ...resolvedFilter, ...rlsFilter } : resolvedFilter;
+      const topK = Math.min(options?.topK ?? defaultTopK, topKCeiling);
+      const vectorResult = await context.vectors.query(config.index, {
+        embed: embedText,
+        filter: effectiveFilter,
+        input: query,
+        namespace: effectiveNamespace,
+        returnMetadata: textStore ? "indexed" : "all",
+        topK
+      });
+      let chunks = await hydrateFromStore(parseMatches(vectorResult, effectiveNamespace), effectiveNamespace);
+      const minScore = options?.minScore;
+      if (minScore !== void 0) {
+        chunks = chunks.filter((chunk) => chunk.score >= minScore);
+      }
+      if (config.lexicalStore) {
+        const lexicalMatches = await config.lexicalStore.search(query, {
+          filter: effectiveFilter,
+          namespace: effectiveNamespace,
+          topK: config.lexicalTopK ?? topK
+        });
+        const lexicalChunks = lexicalMatches.map((match) => {
+          const parsed = parseChunkVectorId(match.id, effectiveNamespace);
+          return {
+            chunkIndex: parsed.chunkIndex,
+            id: match.id,
+            importance: 1,
+            metadata: void 0,
+            score: match.score,
+            sourceId: parsed.sourceId,
+            text: match.text
+          };
+        });
+        chunks = [...hybridRank(chunks, lexicalChunks)];
+      }
+      chunks.sort((a, b) => b.score - a.score);
+      chunks = [...await expandChunks(chunks, options, effectiveNamespace)];
+      const sources = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const chunk of chunks) {
+        if (!seen.has(chunk.sourceId)) {
+          seen.add(chunk.sourceId);
+          sources.push({ id: chunk.sourceId, metadata: chunk.metadata, weight: chunk.importance });
+        }
+      }
+      options?.onRetrieve?.({ matches: chunks.length, query });
+      return { chunks, context: assembleContext(chunks), sources };
+    };
+    const asTool = (options) => tool({
+      description: options?.description ?? `Search the "${config.index}" knowledge base for passages relevant to a natural-language query.`,
+      execute: async ({ query }) => retrieve(query, { namespace: options?.namespace, topK: options?.topK }),
+      inputSchema: jsonSchema({
+        properties: {
+          query: { description: "The natural-language search query.", type: "string" }
+        },
+        required: ["query"],
+        type: "object"
+      })
+    });
+    return { asTool, index, remove, retrieve };
+  };
+};
+
+export { defineRag as default };

package/dist/packem_shared/fixedWindowChunks-J-WfQDw9.mjs

@@ -0,0 +1,26 @@
+const fixedWindowChunks = (text, size, overlap) => {
+  if (!Number.isInteger(size) || size < 1) {
+    throw new RangeError("fixedWindowChunks: `size` must be a positive integer");
+  }
+  if (!Number.isInteger(overlap) || overlap < 0 || overlap >= size) {
+    throw new RangeError("fixedWindowChunks: `overlap` must be a non-negative integer smaller than `size`");
+  }
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return [];
+  }
+  if (trimmed.length <= size) {
+    return [trimmed];
+  }
+  const step = Math.max(1, size - overlap);
+  const chunks = [];
+  for (let start = 0; start < trimmed.length; start += step) {
+    chunks.push(trimmed.slice(start, start + size));
+    if (start + size >= trimmed.length) {
+      break;
+    }
+  }
+  return chunks;
+};
+
+export { fixedWindowChunks as default };

package/dist/packem_shared/hybridRank-DPC9c2ON.mjs

@@ -0,0 +1,20 @@
+const hybridRank = (vectorResults, textResults, k = 60) => {
+  const fused = /* @__PURE__ */ new Map();
+  for (const [rank, chunk] of vectorResults.entries()) {
+    fused.set(chunk.id, { chunk, score: 1 / (k + rank), vectorRank: rank });
+  }
+  for (const [rank, chunk] of textResults.entries()) {
+    const existing = fused.get(chunk.id);
+    if (existing) {
+      existing.score += 1 / (k + rank);
+    } else {
+      fused.set(chunk.id, { chunk, score: 1 / (k + rank), vectorRank: Number.POSITIVE_INFINITY });
+    }
+  }
+  return [...fused.values()].toSorted((a, b) => {
+    const delta = b.score - a.score;
+    return delta === 0 ? a.vectorRank - b.vectorRank : delta;
+  }).map((entry) => entry.chunk);
+};
+
+export { hybridRank as default };

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

@@ -0,0 +1,109 @@
+import { EmbeddingModel, LanguageModel } from 'ai';
+/**
+ * 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;
+}
+/**
+ * `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;
+  /** Route Workers AI inference through a Cloudflare AI Gateway. */
+  gateway?: AiGatewayOptions;
+  /**
+   * 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 { AiBindingLike as A, EmbeddingModelInput as E, LunoraAiOptions as L, ModelInput as M, WorkersAiProviderLike as W, LunoraAi as a, AiGatewayOptions as b };