@lunora/ai 1.0.0-alpha.16 → 1.0.0-alpha.18

package/dist/index.d.mts

@@ -1,6 +1,28 @@
-import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-C6dA8LCy.mjs";
-export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-C6dA8LCy.mjs";
+import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-BXCiRv1x.mjs";
+export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-BXCiRv1x.mjs";
 export { type EmbeddingModel, type LanguageModel, embed, embedMany, generateObject, generateText, hasToolCall, jsonSchema, streamObject, streamText, tool } from 'ai';
 export { createWorkersAI } from 'workers-ai-provider';
+/**
+ * Create the `ctx.ai` helper over a Workers `AI` binding.
+ *
+ * Workers AI is the zero-config default, but `@lunora/ai` is provider-agnostic:
+ * every helper takes either a model id string (resolved against the Workers AI
+ * provider) or any AI SDK {@link LanguageModel}/{@link EmbeddingModel} object
+ * (`@ai-sdk/openai`, `@ai-sdk/anthropic`, OpenRouter, …), so apps are never
+ * locked to Workers AI. Pair `embed` with `@lunora/bindings/vectors` for RAG.
+ *
+ * Combine with the re-exported `generateText`/`streamText`/`generateObject`/
+ * `embed`/`tool` from this package:
+ *
+ * ```ts
+ * import { streamText } from "@lunora/ai";
+ *
+ * const result = streamText({
+ *   model: ctx.ai.model("@cf/meta/llama-3.3-70b-instruct-fp8-fast"),
+ *   messages,
+ * });
+ * ```
+ * @experimental
+ */
 declare const createAi: (options: LunoraAiOptions) => LunoraAi;
 export { type LunoraAi, type LunoraAiOptions, createAi };

package/dist/index.d.ts

@@ -1,6 +1,28 @@
-import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-C6dA8LCy.js";
-export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-C6dA8LCy.js";
+import { L as LunoraAiOptions, a as LunoraAi } from "./packem_shared/types.d-BXCiRv1x.js";
+export type { A as AiBindingLike, b as AiGatewayOptions, E as EmbeddingModelInput, M as ModelInput, W as WorkersAiProviderLike } from "./packem_shared/types.d-BXCiRv1x.js";
 export { type EmbeddingModel, type LanguageModel, embed, embedMany, generateObject, generateText, hasToolCall, jsonSchema, streamObject, streamText, tool } from 'ai';
 export { createWorkersAI } from 'workers-ai-provider';
+/**
+ * Create the `ctx.ai` helper over a Workers `AI` binding.
+ *
+ * Workers AI is the zero-config default, but `@lunora/ai` is provider-agnostic:
+ * every helper takes either a model id string (resolved against the Workers AI
+ * provider) or any AI SDK {@link LanguageModel}/{@link EmbeddingModel} object
+ * (`@ai-sdk/openai`, `@ai-sdk/anthropic`, OpenRouter, …), so apps are never
+ * locked to Workers AI. Pair `embed` with `@lunora/bindings/vectors` for RAG.
+ *
+ * Combine with the re-exported `generateText`/`streamText`/`generateObject`/
+ * `embed`/`tool` from this package:
+ *
+ * ```ts
+ * import { streamText } from "@lunora/ai";
+ *
+ * const result = streamText({
+ *   model: ctx.ai.model("@cf/meta/llama-3.3-70b-instruct-fp8-fast"),
+ *   messages,
+ * });
+ * ```
+ * @experimental
+ */
 declare const createAi: (options: LunoraAiOptions) => LunoraAi;
 export { type LunoraAi, type LunoraAiOptions, createAi };

package/dist/packem_shared/{defineRag-CH8wZ0d5.mjs → defineRag-CGGLJ5ax.mjs}

@@ -109,6 +109,10 @@ const resolveEmbeddingModel = (input, ai) => {
   }
   return ai.embeddingModel(input);
 };
+const modelIdOf = (model) => {
+  const id = model.modelId;
+  return typeof id === "string" && id.length > 0 ? id : 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");
@@ -143,10 +147,21 @@ const defineRag = (config) => {
   };
   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 { embedding } = await embed({ model, value: text });
-      return embedding;
+      const resolvedModel = model ??= resolveEmbeddingModel(config.embeddingModel, context.ai);
+      const run = async () => {
+        const { embedding } = await embed({ model: resolvedModel, value: text });
+        return embedding;
+      };
+      if (tracer === void 0) {
+        return run();
+      }
+      const modelId = modelIdOf(resolvedModel);
+      return tracer("ai.embed", run, {
+        "gen_ai.operation.name": "embeddings",
+        ...modelId === void 0 ? {} : { "gen_ai.request.model": modelId }
+      });
     };
     const checkNamespace = (namespace) => {
       if (namespace !== void 0) {

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 };

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

@@ -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 };