@zerotal/ai 1.5.0

package/src/drivers/anthropic-sdk.ts

@@ -0,0 +1,126 @@
+/**
+ * The slice of `@anthropic-ai/sdk` this package uses, declared structurally.
+ *
+ * The SDK is an **optional** peer dependency: an app that only talks to Ollama
+ * should install nothing. That rules out importing its types, because a missing
+ * package is a `tsc` failure for every consumer, not just the ones using it. So
+ * the shape lives here instead, and the module is loaded through a non-literal
+ * specifier so the compiler never tries to resolve it.
+ *
+ * The cost is that this file, alone in the package, is only as correct as the
+ * SDK's documented wire format. Everything it touches is exercised by
+ * `AnthropicDriver.test.ts` against an injected stub built to these same types —
+ * which pins our *use* of the shapes, not the shapes themselves. Keep it small.
+ */
+
+/** A content block in a response. Unknown block types keep their raw fields. */
+export type AnthropicBlock =
+  | { type: "text"; text: string }
+  | { type: "thinking"; thinking: string }
+  | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
+  | { type: string; [key: string]: unknown };
+
+/** Token accounting, as the API reports it. */
+export interface AnthropicUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens?: number | null;
+  cache_creation_input_tokens?: number | null;
+}
+
+/** Populated only when `stop_reason` is `refusal`; `null` otherwise. */
+export interface AnthropicStopDetails {
+  type?: string;
+  category?: string | null;
+  explanation?: string | null;
+}
+
+/** One finished message. */
+export interface AnthropicMessage {
+  id?: string;
+  model: string;
+  content: AnthropicBlock[];
+  stop_reason: string | null;
+  stop_details?: AnthropicStopDetails | null;
+  usage: AnthropicUsage;
+}
+
+/** The stream events this package reads. Others are ignored. */
+export type AnthropicStreamEvent =
+  | {
+      type: "content_block_delta";
+      delta:
+        | { type: "text_delta"; text: string }
+        | { type: "thinking_delta"; thinking: string }
+        | { type: string; [key: string]: unknown };
+    }
+  | { type: string; [key: string]: unknown };
+
+/** What `messages.stream()` returns. */
+export interface AnthropicMessageStream extends AsyncIterable<AnthropicStreamEvent> {
+  finalMessage(): Promise<AnthropicMessage>;
+  abort?(): void;
+}
+
+/** Per-request options. Note the SDK's timeout is in **milliseconds**. */
+export interface AnthropicRequestOptions {
+  signal?: AbortSignal;
+  timeout?: number;
+}
+
+/** One `messages` namespace — the shape is identical on `client` and `client.beta`. */
+export interface AnthropicMessagesApi {
+  create(
+    params: Record<string, unknown>,
+    options?: AnthropicRequestOptions,
+  ): Promise<AnthropicMessage>;
+  stream(
+    params: Record<string, unknown>,
+    options?: AnthropicRequestOptions,
+  ): AnthropicMessageStream;
+  countTokens?(
+    params: Record<string, unknown>,
+    options?: AnthropicRequestOptions,
+  ): Promise<{ input_tokens: number }>;
+}
+
+/** The client surface this driver drives. */
+export interface AnthropicClient {
+  messages: AnthropicMessagesApi;
+  beta: { messages: AnthropicMessagesApi };
+}
+
+/** Anything `instanceof` can be tested against. */
+export type ErrorClass = new (...args: never[]) => Error;
+
+/**
+ * The SDK's default export: a constructor that also carries the typed error
+ * classes. Mapping errors **by class** rather than by matching message text is
+ * the difference between a rate limit staying a rate limit and it becoming
+ * whatever the provider decides to call it next quarter.
+ */
+export interface AnthropicConstructor {
+  new (options: {
+    apiKey: string;
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+  }): AnthropicClient;
+  RateLimitError: ErrorClass;
+  APIConnectionError: ErrorClass;
+  AuthenticationError: ErrorClass;
+  NotFoundError: ErrorClass;
+  BadRequestError: ErrorClass;
+  APIError: ErrorClass;
+}
+
+/** The module namespace. */
+export interface AnthropicModule {
+  default: AnthropicConstructor;
+}
+
+/** Both halves of a loaded SDK: the class (for `instanceof`) and a client. */
+export interface LoadedAnthropic {
+  ctor: AnthropicConstructor;
+  client: AnthropicClient;
+}

package/src/drivers/embeddings/EmbeddingsDriver.ts

@@ -0,0 +1,20 @@
+import type { AiEmbedRequest, AiEmbedResponse } from "../../types.ts";
+
+/**
+ * What an embeddings provider implements.
+ *
+ * Separate from {@link AiDriver} on purpose, and separately configured: Anthropic
+ * has no embeddings endpoint at all, so a design that hangs `embed()` off the
+ * generation driver makes the normal pairing — Claude for generation, something
+ * cheaper for vectors — impossible to express.
+ */
+export interface EmbeddingsDriver {
+  readonly name: string;
+  readonly model: string;
+  embed(request: AiEmbedRequest): Promise<AiEmbedResponse>;
+}
+
+/** Normalise `string | string[]` to the list every provider actually wants. */
+export function toInputs(input: string | string[]): string[] {
+  return Array.isArray(input) ? input : [input];
+}

package/src/drivers/embeddings/OllamaEmbeddingsDriver.ts

@@ -0,0 +1,60 @@
+import { AiCancelledError, AiRequestError } from "../../errors.ts";
+import type { AiEmbedRequest, AiEmbedResponse } from "../../types.ts";
+import { toInputs, type EmbeddingsDriver } from "./EmbeddingsDriver.ts";
+
+interface OllamaEmbedResponse {
+  model?: string;
+  embeddings: number[][];
+  prompt_eval_count?: number;
+}
+
+/** Ollama embeddings — a local server, so no key and no per-token cost. */
+export class OllamaEmbeddingsDriver implements EmbeddingsDriver {
+  readonly name = "ollama";
+
+  constructor(
+    private readonly config: { model: string; baseUrl: string; timeout: number },
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  get model(): string {
+    return this.config.model;
+  }
+
+  async embed(request: AiEmbedRequest): Promise<AiEmbedResponse> {
+    const model = request.model ?? this.config.model;
+    const inputs = toInputs(request.input);
+
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.config.baseUrl}/api/embed`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model, input: inputs }),
+        signal: request.signal ?? AbortSignal.timeout(this.config.timeout),
+      });
+    } catch (error) {
+      if (request.signal?.aborted) throw new AiCancelledError();
+      throw new AiRequestError(
+        `Could not reach Ollama at ${this.config.baseUrl}: ` +
+          `${error instanceof Error ? error.message : String(error)}. Is \`ollama serve\` running?`,
+        0,
+      );
+    }
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new AiRequestError(
+        `Ollama embeddings error ${response.status}: ${detail || response.statusText}`,
+        response.status,
+      );
+    }
+
+    const body = (await response.json()) as OllamaEmbedResponse;
+    return {
+      embeddings: body.embeddings,
+      model: body.model ?? model,
+      usage: { inputTokens: body.prompt_eval_count ?? 0 },
+    };
+  }
+}

package/src/drivers/embeddings/OpenAiEmbeddingsDriver.ts

@@ -0,0 +1,69 @@
+import { AiCancelledError, AiRateLimitError, AiRequestError } from "../../errors.ts";
+import type { AiEmbedRequest, AiEmbedResponse } from "../../types.ts";
+import { toInputs, type EmbeddingsDriver } from "./EmbeddingsDriver.ts";
+
+interface OpenAiEmbeddingResponse {
+  model: string;
+  data: Array<{ index: number; embedding: number[] }>;
+  usage?: { prompt_tokens?: number };
+}
+
+/** OpenAI embeddings over `fetch`. No SDK, no dependency. */
+export class OpenAiEmbeddingsDriver implements EmbeddingsDriver {
+  readonly name = "openai";
+
+  constructor(
+    private readonly config: { apiKey: string; model: string; baseUrl: string; timeout: number },
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  get model(): string {
+    return this.config.model;
+  }
+
+  async embed(request: AiEmbedRequest): Promise<AiEmbedResponse> {
+    const inputs = toInputs(request.input);
+
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.config.baseUrl}/embeddings`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ model: request.model ?? this.config.model, input: inputs }),
+        signal: request.signal ?? AbortSignal.timeout(this.config.timeout),
+      });
+    } catch (error) {
+      if (request.signal?.aborted) throw new AiCancelledError();
+      throw new AiRequestError(
+        `Could not reach the OpenAI API: ${error instanceof Error ? error.message : String(error)}`,
+        0,
+      );
+    }
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      if (response.status === 429) {
+        throw new AiRateLimitError(`OpenAI rate limit: ${detail || response.statusText}`);
+      }
+      throw new AiRequestError(
+        `OpenAI embeddings error ${response.status}: ${detail || response.statusText}`,
+        response.status,
+      );
+    }
+
+    const body = (await response.json()) as OpenAiEmbeddingResponse;
+
+    // The API does not promise input order, and a mis-ordered batch silently
+    // attaches every vector to the wrong document.
+    const ordered = [...body.data].sort((a, b) => a.index - b.index);
+
+    return {
+      embeddings: ordered.map((entry) => entry.embedding),
+      model: body.model,
+      usage: { inputTokens: body.usage?.prompt_tokens ?? 0 },
+    };
+  }
+}

package/src/drivers/sse.ts

@@ -0,0 +1,107 @@
+import { AiCancelledError, AiRequestError } from "../errors.ts";
+
+/**
+ * Read a `text/event-stream` body, yielding each event's `data:` payload.
+ *
+ * Frames do not align with chunks — a single `read()` can hand back half an
+ * event, or three of them — so the buffer is split on the blank-line terminator
+ * rather than per chunk. Getting that wrong produces a stream that works on a
+ * fast localhost and drops tokens over a real network.
+ *
+ * @internal
+ */
+export async function* readSse(response: Response, signal?: AbortSignal): AsyncGenerator<string> {
+  const body = response.body;
+  if (!body)
+    throw new AiRequestError("The provider returned a streaming response with no body.", 0);
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    for (;;) {
+      if (signal?.aborted) throw new AiCancelledError();
+
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+
+        const data = dataOf(frame);
+        if (data !== undefined) yield data;
+
+        boundary = buffer.indexOf("\n\n");
+      }
+    }
+
+    // A final frame with no trailing blank line still carries an event.
+    const tail = dataOf(buffer);
+    if (tail !== undefined) yield tail;
+  } finally {
+    // Releasing matters on the abort path: the response body stays open until
+    // the reader lets go, and an abandoned stream holds the socket.
+    reader.releaseLock();
+    if (!response.bodyUsed) await body.cancel().catch(() => undefined);
+  }
+}
+
+/** The concatenated `data:` lines of one frame, or `undefined` for a comment. */
+function dataOf(frame: string): string | undefined {
+  const lines = frame.split("\n");
+  const data: string[] = [];
+
+  for (const line of lines) {
+    if (line.startsWith("data:")) data.push(line.slice(5).trimStart());
+  }
+
+  return data.length > 0 ? data.join("\n") : undefined;
+}
+
+/**
+ * Read a newline-delimited JSON body, yielding each line. Ollama's stream format.
+ *
+ * @internal
+ */
+export async function* readNdjson(
+  response: Response,
+  signal?: AbortSignal,
+): AsyncGenerator<string> {
+  const body = response.body;
+  if (!body)
+    throw new AiRequestError("The provider returned a streaming response with no body.", 0);
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  try {
+    for (;;) {
+      if (signal?.aborted) throw new AiCancelledError();
+
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+
+      let newline = buffer.indexOf("\n");
+      while (newline !== -1) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) yield line;
+        newline = buffer.indexOf("\n");
+      }
+    }
+
+    const tail = buffer.trim();
+    if (tail) yield tail;
+  } finally {
+    reader.releaseLock();
+    if (!response.bodyUsed) await body.cancel().catch(() => undefined);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,129 @@
+import { ZerotalError } from "@zerotal/core";
+
+/** Base class for all `@zerotal/ai` errors. */
+export class AiError extends ZerotalError {
+  constructor(message: string, code = "E_AI", status = 500, context?: Record<string, unknown>) {
+    super(message, code, status, context);
+  }
+}
+
+/** Thrown for a driver name the manager does not know. */
+export class UnknownAiDriverError extends AiError {
+  constructor(driver: string, known: string[] = []) {
+    super(
+      `Unknown AI driver: '${driver}'.` +
+        (known.length > 0
+          ? ` Configured: ${known.join(", ")}. Add your own with Ai.extend("${driver}", () => …).`
+          : " Configure one under drivers in config/ai.ts."),
+      "E_AI_UNKNOWN_DRIVER",
+      500,
+      { driver, known },
+    );
+  }
+}
+
+/** Thrown at boot, or on first use, for a config combination that cannot work. */
+export class AiConfigError extends AiError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(`[Zerotal/ai] ${message}`, "E_AI_CONFIG", 500, context);
+  }
+}
+
+/**
+ * Thrown when a driver's optional peer package is not installed.
+ *
+ * The SDKs are optional peers so an app that only talks to Ollama installs
+ * nothing; the cost is that the failure has to name the missing package.
+ */
+export class AiDriverUnavailableError extends AiError {
+  constructor(driver: string, packageName: string) {
+    super(
+      `[Zerotal/ai] The '${driver}' driver needs ${packageName}, which is not installed. ` +
+        `Run: bun add ${packageName}`,
+      "E_AI_DRIVER_UNAVAILABLE",
+      500,
+      { driver, packageName },
+    );
+  }
+}
+
+/**
+ * Thrown when the provider's safety classifiers declined the request.
+ *
+ * This arrives as a **successful** HTTP 200 with an empty or partial body, so a
+ * caller that reads `content[0]` without checking the stop reason crashes on a
+ * response the API considers fine. Raising a typed error is the whole point.
+ */
+export class AiRefusedError extends AiError {
+  constructor(
+    /** The provider's refusal category, when it gave one — `cyber`, `bio`, … */
+    readonly category: string | null,
+    /** The provider's own explanation, when it gave one. */
+    readonly explanation: string | null,
+    /** Whatever text arrived before the refusal, for a mid-stream decline. */
+    readonly partialText = "",
+  ) {
+    super(
+      `[Zerotal/ai] The model declined the request` +
+        (category ? ` (${category})` : "") +
+        (explanation ? `: ${explanation}` : "."),
+      "E_AI_REFUSED",
+      // Not a server fault and not the caller's malformed input — it is a
+      // policy decision about the content, which is what 422 says.
+      422,
+      { category, explanation },
+    );
+  }
+}
+
+/** Thrown when the provider rate-limits. The SDKs already retried. */
+export class AiRateLimitError extends AiError {
+  constructor(
+    message: string,
+    readonly retryAfterSeconds?: number,
+  ) {
+    super(`[Zerotal/ai] ${message}`, "E_AI_RATE_LIMIT", 429, { retryAfterSeconds });
+  }
+}
+
+/** Thrown for any other non-2xx from the provider, carrying its status. */
+export class AiRequestError extends AiError {
+  constructor(
+    message: string,
+    readonly providerStatus: number,
+    context?: Record<string, unknown>,
+  ) {
+    super(`[Zerotal/ai] ${message}`, "E_AI_REQUEST", providerStatus >= 500 ? 502 : 400, {
+      providerStatus,
+      ...context,
+    });
+  }
+}
+
+/** Thrown when a request would breach a configured spend ceiling. */
+export class AiSpendLimitError extends AiError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(`[Zerotal/ai] ${message}`, "E_AI_SPEND_LIMIT", 429, context);
+  }
+}
+
+/** Thrown when a validator schema uses a constraint structured output cannot express. */
+export class AiSchemaError extends AiError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(`[Zerotal/ai] ${message}`, "E_AI_SCHEMA", 500, context);
+  }
+}
+
+/** Thrown when the agent loop hits its step or resume ceiling. */
+export class AiAgentLimitError extends AiError {
+  constructor(message: string, context?: Record<string, unknown>) {
+    super(`[Zerotal/ai] ${message}`, "E_AI_AGENT_LIMIT", 500, context);
+  }
+}
+
+/** Thrown when the caller's `AbortSignal` fired before the call finished. */
+export class AiCancelledError extends AiError {
+  constructor(message = "The generation was cancelled.") {
+    super(`[Zerotal/ai] ${message}`, "E_AI_CANCELLED", 499);
+  }
+}

package/src/events.ts

@@ -0,0 +1,51 @@
+/**
+ * The AI package's framework events, emitted on core's `FrameworkEvents` bus.
+ * Observability packages subscribe to them by class; nothing here imports them.
+ *
+ * Prompt text on these events has already been through {@link redactPrompt} —
+ * a prompt is user data, and the observability path is the one place it would
+ * otherwise be durably kept.
+ */
+
+/** Emitted after a generation finishes, whether it succeeded or not. */
+export class AiGenerated {
+  constructor(
+    /** The driver that served it: "anthropic" | "openai" | "ollama" | custom. */
+    readonly driver: string,
+    readonly model: string,
+    /** "text" | "stream" | "object" | "agent" | "embed". */
+    readonly operation: string,
+    readonly inputTokens: number,
+    readonly outputTokens: number,
+    readonly cacheReadTokens: number,
+    readonly durationMs: number,
+    /** Estimated cost in USD, from the driver's price table. 0 when unpriced. */
+    readonly costUsd: number,
+    readonly ok: boolean,
+    /** Redacted prompt preview — never the raw prompt. */
+    readonly preview: string,
+    readonly error?: string,
+  ) {}
+}
+
+/** Emitted when the provider's safety classifiers declined a request. */
+export class AiRefused {
+  constructor(
+    readonly driver: string,
+    readonly model: string,
+    readonly category: string | null,
+    readonly preview: string,
+  ) {}
+}
+
+/** Emitted once per tool call inside an agent run. */
+export class AiToolCalled {
+  constructor(
+    readonly driver: string,
+    readonly tool: string,
+    readonly step: number,
+    readonly durationMs: number,
+    readonly ok: boolean,
+    readonly error?: string,
+  ) {}
+}

package/src/facades/Ai.ts

@@ -0,0 +1,3 @@
+import { createFacade } from "@zerotal/core";
+
+export const Ai = createFacade("ai");

package/src/global.d.ts

@@ -0,0 +1,8 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+// ── Bun globals ───────────────────────────────────────────────────────────
+interface Request {
+  readonly params?: Record<string, string>;
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+/**
+ * Provider-agnostic AI generation for Zerotal.
+ *
+ * Text, streaming, structured output, typed tools, and an agent loop, behind one
+ * facade — with the provider chosen in config rather than in every call site.
+ *
+ * @example
+ * ```ts
+ * import { Ai, tool } from "@zerotal/ai";
+ *
+ * const summary = await Ai.text(`Summarize in one sentence:\n\n${article}`);
+ *
+ * for await (const chunk of Ai.stream({ prompt, signal: this.signal })) {
+ *   if (chunk.type === "text") this.answer += chunk.text;
+ * }
+ *
+ * const review = await Ai.object({ prompt }, (rule) => ({
+ *   sentiment: rule.string().in(["positive", "neutral", "negative"]),
+ *   score:     rule.number().min(1).max(5),
+ * }));
+ *
+ * const result = await Ai.agent({ prompt, tools: [lookupOrder], lock: "order:4821" });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { AiManager } from "./AiManager.ts";
+export type { AiAgentRequest, AiQueueHandler, AiQueueOptions } from "./AiManager.ts";
+export { Ai } from "./facades/Ai.ts";
+export { AiProvider } from "./provider/AiProvider.ts";
+export { AiConfig, AiConfigFromEnv, validateAiConfig } from "./config.ts";
+export type { AiConfigInput } from "./config.ts";
+export { AiFake } from "./AiFake.ts";
+export type { CapturedGeneration } from "./AiFake.ts";
+
+// Tools
+export { tool } from "./tool.ts";
+
+// Schema translation — exported so a test can pin the exact JSON Schema a
+// validator schema produces, which is the only way that stays honest.
+export { translateSchema, strippedConstraints, toSchema } from "./schema.ts";
+export type { SchemaInput } from "./schema.ts";
+
+// Drivers — implement the interface to add a provider, or instantiate directly.
+export { AnthropicDriver } from "./drivers/AnthropicDriver.ts";
+export { OpenAiDriver } from "./drivers/OpenAiDriver.ts";
+export { OllamaDriver } from "./drivers/OllamaDriver.ts";
+export type { AiDriver, AgentOptions, DriverStatus } from "./drivers/AiDriver.ts";
+
+// Embeddings — their own driver, because Anthropic has no embeddings endpoint.
+export { OpenAiEmbeddingsDriver } from "./drivers/embeddings/OpenAiEmbeddingsDriver.ts";
+export { OllamaEmbeddingsDriver } from "./drivers/embeddings/OllamaEmbeddingsDriver.ts";
+export type { EmbeddingsDriver } from "./drivers/embeddings/EmbeddingsDriver.ts";
+
+// Background generation
+export { AiGenerationJob } from "./AiGenerationJob.ts";
+
+// Cost estimation — extend the table for a model this package does not price.
+export { estimateCost, modelPrice, registerModelPrice, modelRejectsSampling } from "./pricing.ts";
+export type { ModelPrice } from "./pricing.ts";
+
+// Spend ledger
+export { spentToday, resetSpend } from "./spend.ts";
+
+// Counters backing the monitor section
+export { modelStats, recentGenerations, refusalRate, resetStats } from "./stats.ts";
+export type { AiDelivery, ModelStat } from "./stats.ts";
+
+// Console commands
+export { AiTestCommand, AiSpendCommand } from "./commands/index.ts";
+
+// Typed error vocabulary
+export * from "./errors.ts";
+
+// Framework instrumentation events (emitted on the core FrameworkEvents bus)
+export { AiGenerated, AiRefused, AiToolCalled } from "./events.ts";
+
+export type {
+  AiAgentResult,
+  AiAgentStep,
+  AiConfigShape,
+  AiEffort,
+  AiEmbedRequest,
+  AiEmbedResponse,
+  AiLimitsConfigShape,
+  AiAgentConfigShape,
+  AiMessage,
+  AiObjectResponse,
+  AiProviderOptions,
+  AiRequest,
+  AiResponse,
+  AiRole,
+  AiStopReason,
+  AiStreamChunk,
+  AiTool,
+  AiToolCall,
+  AiToolContext,
+  AiToolResult,
+  AiUsage,
+  AnthropicConfigShape,
+  EmbeddingsConfigShape,
+  JsonSchema,
+  OllamaConfigShape,
+  OpenAiConfigShape,
+} from "./types.ts";