@zerotal/ai 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog — @zerotal/ai
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `experimental`**
+
+## [Unreleased]
+
+## [1.5.0] — 2026-08-15
+
+### Added
+
+- **The package.** `Ai.text()`, `Ai.stream()`, `Ai.object()`, `Ai.agent()`, and
+  `Ai.embed()` behind one facade, with the provider chosen in `config/ai.ts`
+  rather than at each call site. Three drivers ship: Anthropic (via the optional
+  `@anthropic-ai/sdk` peer), OpenAI, and Ollama (both over plain `fetch`).
+
+- **One agent loop, shared by every driver.** `AiDriver.agent()` is optional and
+  none of the three implement it — they all run the same loop over `text()`. An
+  abstraction whose second implementation reuses none of the first is not an
+  abstraction, and the shared suite in `drivers.test.ts` runs the same
+  assertions against all three so that stays true.
+
+- **`pause_turn` is resumed, not mistaken for an answer.** A provider running a
+  long server-side tool can end a turn with `stop_reason: "pause_turn"`, meaning
+  "ask me again". It is neither an error nor a completion, so an unhandled one
+  reads as a finished answer and the user sees a silently truncated response
+  with no warning anywhere. The loop pushes the paused turn back and re-requests,
+  capped by `agent.maxResumes`.
+
+- **Refusals are typed, and checked before the content is read.** A declined
+  request arrives as a **successful HTTP 200** with empty or partial content, so
+  code that reads `content[0]` first crashes on a response the API considers
+  fine. `AiRefusedError` carries the provider's category and, for a mid-stream
+  decline, the partial text — so a caller can discard a truncated answer
+  knowingly. Anthropic's server-side `fallbacks: "default"` is on by default.
+
+- **Schema translation that decides, rather than hoping.** Structured output
+  accepts a narrow JSON Schema subset — `additionalProperties: false` required on
+  every object, no length or numeric bounds, no recursion — and rejects anything
+  else at _request_ time. So `translateSchema()` strips what it cannot express
+  and `recheckAgainstSchema()` re-applies it with the validator we already own;
+  a recursive schema, which has no client-side rescue, is refused at definition
+  time instead. `schema.test.ts` pins the exact output for every supported rule.
+
+- **A refreshable lock on named agent runs.** `Ai.agent({ lock: "refund:4821" })`
+  is exclusive for that name, refreshes for as long as the loop runs, and aborts
+  the loop's signal if the lock is ever lost. Opt-in and named on purpose: a
+  shared key would serialize every agent run in the app.
+
+- **Spend ceilings, prompt redaction, and a monitor section.**
+  `limits.perRequestUsd` is checked before the request is sent, from a real token
+  count via the provider's own tokenizer — never `tiktoken`, which undercounts
+  Claude by 15–20%. Prompts are redacted in logs and the monitor by default,
+  because a prompt is user data and observability is where it would otherwise be
+  durably kept. The monitor's **AI** section shows spend against the ceiling,
+  tokens, latency percentiles per model, and the refusal rate.
+
+- **`AiFake`** — `respondWith()`, `respondWithObject()`, `refuse()`, and
+  `assertPrompted()` / `assertPromptCount()` / `assertSystemPrompted()`. The
+  assertions are about what the application asked for, which is the part that can
+  be wrong. The suite passes with no API key set.
+
+- **Commands.** `zt ai:test [driver]` reaches the provider once and prints the
+  resolved model; `zt ai:spend` reports this process's token spend by model.
+
+### Notes
+
+- `temperature` is accepted on the request surface but **dropped** by the
+  Anthropic driver, because current Claude models reject it with a 400 and a
+  parameter forwarded blindly would fail every request. `validateAiConfig()`
+  warns when a configured model rejects it. Use `effort` instead.
+- The daily spend ceiling is in-process: N workers hold N ceilings, and the
+  figures are estimated from public list prices. It is a guard against a runaway
+  loop, not a billing system.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @zerotal/ai
+
+> Text, streaming, structured output, typed tools, and an agent loop — behind one provider-agnostic facade.
+
+One way to talk to a language model: `Ai.text()` for a completion, `Ai.stream()` for tokens as they arrive, `Ai.object()` for a value that satisfies a validator schema, and `Ai.agent()` for a loop that calls your tools until the model is done. The provider is chosen in `config/ai.ts`, not at each call site.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+**Maturity: `experimental`** — the API may change in a minor release.
+
+## Installation
+
+```bash
+bun add @zerotal/ai
+```
+
+Provider SDKs are optional peers, imported lazily. Install only the one you use:
+
+```bash
+bun add @anthropic-ai/sdk    # only for the anthropic driver
+```
+
+The OpenAI and Ollama drivers use `fetch` directly and need nothing extra.
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { AiProvider } from "@zerotal/ai";
+```
+
+Then configure it:
+
+```ts
+// config/ai.ts
+import { AiConfig } from "@zerotal/ai";
+
+export default AiConfig({
+  default: "anthropic",
+  drivers: {
+    anthropic: { apiKey: Bun.env["ANTHROPIC_API_KEY"] ?? "" },
+  },
+  limits: { perRequestUsd: 0.5, perDayUsd: 25 },
+});
+```
+
+## Usage
+
+```ts
+import { Ai, tool } from "@zerotal/ai";
+
+// A completion.
+const summary = await Ai.text(`Summarize in one sentence:\n\n${article}`);
+
+// Tokens as they arrive, cancellable.
+for await (const chunk of Ai.stream({ prompt, signal })) {
+  if (chunk.type === "text") process.stdout.write(chunk.text);
+}
+
+// A value that satisfies a validator schema — the same schema you use for forms.
+const review = await Ai.object({ prompt }, (rule) => ({
+  sentiment: rule.string().in(["positive", "neutral", "negative"]),
+  score: rule.number().min(1).max(5),
+}));
+
+// A tool-calling loop, exclusive for the work it names.
+const lookupOrder = tool({
+  name: "lookup_order",
+  description: "Fetch one order by id. Call this whenever the user mentions an order number.",
+  input: (rule) => ({ id: rule.string() }),
+  handle: async ({ id }) => await Order.find(id),
+});
+
+const result = await Ai.agent({
+  prompt: "Where is order 4821?",
+  tools: [lookupOrder],
+  lock: "order:4821",
+});
+```
+
+## Testing
+
+```ts
+import { AiFake } from "@zerotal/ai";
+
+const ai = AiFake.install();
+ai.respondWith("A one-sentence summary.");
+
+await service.summarize(article);
+
+ai.assertPrompted(/Summarize/);
+ai.restore();
+```
+
+No API key, no network. The suite for this package passes with neither.
+
+## Commands
+
+| Command               | What it does                                             |
+| --------------------- | -------------------------------------------------------- |
+| `zt ai:test [driver]` | Reach the provider once and print the **resolved model** |
+| `zt ai:spend`         | This process's token spend today, by model               |
+
+## Documentation
+
+Full documentation: [zerotal.dev/docs/ai](https://zerotal.dev/docs/ai).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@zerotal/ai",
+  "version": "1.5.0",
+  "license": "MIT",
+  "maturity": "experimental",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.5.0",
+    "@zerotal/validator": "1.5.0",
+    "@zerotal/queue": "1.5.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.70.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Provider-agnostic AI generation for Zerotal — text, streaming, structured output, typed tools, and an agent loop.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "ai",
+    "llm",
+    "anthropic",
+    "claude",
+    "openai",
+    "ollama"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/ai"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/ai#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/AiFake.ts

@@ -0,0 +1,351 @@
+import { Application, currentApp } from "@zerotal/core";
+import { AiRefusedError } from "./errors.ts";
+import { normalizeMessages, promptText, type DriverStatus } from "./drivers/AiDriver.ts";
+import type { AiAgentRequest, AiQueueHandler, AiQueueOptions } from "./AiManager.ts";
+import type {
+  AiAgentResult,
+  AiEmbedRequest,
+  AiEmbedResponse,
+  AiRequest,
+  AiResponse,
+  AiStreamChunk,
+  AiUsage,
+} from "./types.ts";
+
+type Binding = unknown;
+
+/** One recorded call. */
+export interface CapturedGeneration {
+  /** `"text" | "stream" | "object" | "agent" | "embed" | "queue"`. */
+  operation: string;
+  /** The last user turn, unredacted — this is a test, and it is in memory. */
+  prompt: string;
+  system: string | undefined;
+  request: AiRequest;
+}
+
+/** What the fake returns when nothing more specific was queued. */
+const DEFAULT_TEXT = "This is a fake AI response.";
+
+const NO_USAGE: AiUsage = {
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+};
+
+/**
+ * Drop-in replacement for {@link AiManager} that records prompts and answers
+ * from a script, instead of calling a provider.
+ *
+ * This is the piece that makes an AI feature testable at all: the assertions are
+ * about *what your application asked for*, which is the part you wrote and the
+ * part that can be wrong. Whether the model's prose is good is not a unit test.
+ *
+ * @example
+ * const ai = AiFake.install();
+ * ai.respondWith("A one-sentence summary.");
+ *
+ * await service.summarize(article);
+ *
+ * ai.assertPrompted(/Summarize/);
+ * ai.assertPromptCount(1);
+ * ai.restore();     // in afterEach
+ */
+export class AiFake {
+  private readonly _calls: CapturedGeneration[] = [];
+  private readonly _texts: string[] = [];
+  private readonly _objects: unknown[] = [];
+  private readonly _handlers = new Map<string, AiQueueHandler>();
+  private _refuseWith: { category: string | null; explanation: string | null } | undefined;
+
+  private constructor(
+    private readonly _app: Application,
+    private readonly _original: Binding,
+  ) {}
+
+  /** Replace the `ai` container binding with this fake. */
+  static install(): AiFake {
+    const app = currentApp();
+    const original = app.container.registry.get("ai");
+    const fake = new AiFake(app, original);
+    app.container.value("ai", fake);
+    return fake;
+  }
+
+  /** Restore the original `ai` binding. Call in `afterEach`. */
+  restore(): void {
+    if (this._original !== undefined) {
+      this._app.container.registry.set("ai", this._original as never);
+    } else {
+      this._app.container.registry.delete("ai");
+    }
+  }
+
+  // ── Scripting ────────────────────────────────────────────────────────────
+
+  /**
+   * Queue one or more text answers, returned in order. The last one repeats
+   * once the queue is exhausted, so a test that does not care how many calls
+   * happen does not have to count them.
+   */
+  respondWith(...texts: string[]): this {
+    this._texts.push(...texts);
+    return this;
+  }
+
+  /** Queue one or more answers for `object()`, returned in order. */
+  respondWithObject(...objects: unknown[]): this {
+    this._objects.push(...objects);
+    return this;
+  }
+
+  /**
+   * Make the next call refuse, as the provider's safety classifiers would.
+   *
+   * Worth testing deliberately: a refusal is an HTTP 200 with no content, so the
+   * handling path is the one most likely to have never run.
+   */
+  refuse(category: string | null = "cyber", explanation: string | null = null): this {
+    this._refuseWith = { category, explanation };
+    return this;
+  }
+
+  // ── The AiManager surface ────────────────────────────────────────────────
+
+  async text(request: AiRequest | string): Promise<string> {
+    return (await this.generate(request)).text;
+  }
+
+  async generate(request: AiRequest | string): Promise<AiResponse> {
+    const normalized = capture(request);
+    this._record("text", normalized);
+    this._maybeRefuse();
+
+    const text = this._nextText();
+    return {
+      text,
+      model: "fake",
+      usage: NO_USAGE,
+      stopReason: "end_turn",
+      toolCalls: [],
+      assistantTurn: { role: "assistant", content: text },
+    };
+  }
+
+  async *stream(request: AiRequest | string): AsyncIterable<AiStreamChunk> {
+    const normalized = capture(request);
+    this._record("stream", normalized);
+    this._maybeRefuse();
+
+    const text = this._nextText();
+    // Word by word, because a caller that only ever sees one chunk is not
+    // actually exercising its accumulation.
+    for (const word of text.split(/(\s+)/)) {
+      if (word) yield { type: "text", text: word };
+    }
+
+    yield {
+      type: "done",
+      response: {
+        text,
+        model: "fake",
+        usage: NO_USAGE,
+        stopReason: "end_turn",
+        toolCalls: [],
+        assistantTurn: { role: "assistant", content: text },
+      },
+    };
+  }
+
+  async object<T = Record<string, unknown>>(request: AiRequest | string): Promise<T> {
+    const normalized = capture(request);
+    this._record("object", normalized);
+    this._maybeRefuse();
+
+    if (this._objects.length === 0) {
+      throw new Error(
+        "[Zerotal/ai] AiFake had no scripted object to return. Call " +
+          "ai.respondWithObject({ … }) before the code under test runs.",
+      );
+    }
+    return (this._objects.length > 1 ? this._objects.shift() : this._objects[0]) as T;
+  }
+
+  async agent(request: AiAgentRequest): Promise<AiAgentResult> {
+    this._record("agent", request);
+    this._maybeRefuse();
+
+    return {
+      text: this._nextText(),
+      model: "fake",
+      usage: NO_USAGE,
+      steps: [],
+      stopReason: "end_turn",
+    };
+  }
+
+  async embed(
+    input: string | string[],
+    _options: Omit<AiEmbedRequest, "input"> = {},
+  ): Promise<AiEmbedResponse> {
+    const inputs = Array.isArray(input) ? input : [input];
+    this._record("embed", { prompt: inputs.join("\n") });
+
+    // A deterministic, non-zero vector: a test asserting "these two differ"
+    // should pass, and one asserting a specific value should not.
+    return {
+      embeddings: inputs.map((value) => [value.length, value.charCodeAt(0) || 0, 0]),
+      model: "fake",
+      usage: { inputTokens: 0 },
+    };
+  }
+
+  async countTokens(request: AiRequest | string): Promise<number> {
+    const normalized = capture(request);
+    return Math.ceil(promptText(normalized).length / 4);
+  }
+
+  async verify(): Promise<DriverStatus> {
+    return { ok: true, model: "fake", detail: "AiFake is installed — no provider was contacted." };
+  }
+
+  onGenerated(name: string, handler: AiQueueHandler): this {
+    this._handlers.set(name, handler);
+    return this;
+  }
+
+  handlerFor(name: string): AiQueueHandler | undefined {
+    return this._handlers.get(name);
+  }
+
+  /** Records the call and runs the handler inline — no worker, no queue driver. */
+  async queue(request: AiRequest, options: AiQueueOptions): Promise<void> {
+    this._record("queue", request);
+    const handler = this._handlers.get(options.handler);
+    if (handler) await handler(await this.generate(request), options.meta ?? {});
+  }
+
+  drivers(): string[] {
+    return ["fake"];
+  }
+
+  // ── Assertions ───────────────────────────────────────────────────────────
+
+  /** Every recorded call, in order. */
+  get calls(): CapturedGeneration[] {
+    return [...this._calls];
+  }
+
+  /** Just the prompts, in order. */
+  get prompts(): string[] {
+    return this._calls.map((call) => call.prompt);
+  }
+
+  /**
+   * Assert some prompt matched.
+   *
+   * @param expected - A substring, a regular expression, or a predicate.
+   */
+  assertPrompted(expected: string | RegExp | ((prompt: string) => boolean)): void {
+    const matches = this._calls.some((call) => matchPrompt(call.prompt, expected));
+    if (matches) return;
+
+    throw new Error(
+      `[Zerotal/ai] Expected a prompt matching ${describe(expected)}, but ` +
+        (this._calls.length === 0
+          ? "nothing was prompted."
+          : `the ${this._calls.length} prompt(s) were:\n` +
+            this.prompts.map((p) => `  - ${truncate(p)}`).join("\n")),
+    );
+  }
+
+  /** Assert no prompt matched. */
+  assertNotPrompted(expected: string | RegExp | ((prompt: string) => boolean)): void {
+    const match = this._calls.find((call) => matchPrompt(call.prompt, expected));
+    if (!match) return;
+    throw new Error(
+      `[Zerotal/ai] Expected no prompt matching ${describe(expected)}, but found: ${truncate(match.prompt)}`,
+    );
+  }
+
+  /** Assert the system prompt of some call matched. */
+  assertSystemPrompted(expected: string | RegExp | ((prompt: string) => boolean)): void {
+    const matches = this._calls.some(
+      (call) => call.system !== undefined && matchPrompt(call.system, expected),
+    );
+    if (matches) return;
+    throw new Error(
+      `[Zerotal/ai] Expected a system prompt matching ${describe(expected)}, but ` +
+        `none of the ${this._calls.length} call(s) had one that did.`,
+    );
+  }
+
+  /** Assert exactly `count` generations happened. */
+  assertPromptCount(count: number): void {
+    if (this._calls.length === count) return;
+    throw new Error(
+      `[Zerotal/ai] Expected ${count} generation(s), got ${this._calls.length}.` +
+        (this._calls.length > 0
+          ? `\n${this._calls.map((c) => `  - ${c.operation}: ${truncate(c.prompt)}`).join("\n")}`
+          : ""),
+    );
+  }
+
+  /** Assert nothing was generated. */
+  assertNothingPrompted(): void {
+    this.assertPromptCount(0);
+  }
+
+  // ── Internals ────────────────────────────────────────────────────────────
+
+  private _record(operation: string, request: Partial<AiRequest> & { prompt?: string }): void {
+    const full = request as AiRequest;
+    this._calls.push({
+      operation,
+      prompt: promptText(full) || (request.prompt ?? ""),
+      system: full.system,
+      request: full,
+    });
+  }
+
+  private _nextText(): string {
+    if (this._texts.length === 0) return DEFAULT_TEXT;
+    return this._texts.length > 1 ? this._texts.shift()! : this._texts[0]!;
+  }
+
+  private _maybeRefuse(): void {
+    if (!this._refuseWith) return;
+    const { category, explanation } = this._refuseWith;
+    this._refuseWith = undefined;
+    throw new AiRefusedError(category, explanation);
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function capture(request: AiRequest | string): AiRequest {
+  return typeof request === "string" ? { prompt: request } : request;
+}
+
+function matchPrompt(
+  prompt: string,
+  expected: string | RegExp | ((prompt: string) => boolean),
+): boolean {
+  if (typeof expected === "function") return expected(prompt);
+  if (expected instanceof RegExp) return expected.test(prompt);
+  return prompt.includes(expected);
+}
+
+function describe(expected: string | RegExp | ((prompt: string) => boolean)): string {
+  if (typeof expected === "function") return "the given predicate";
+  if (expected instanceof RegExp) return String(expected);
+  return `"${expected}"`;
+}
+
+function truncate(text: string, limit = 120): string {
+  return text.length > limit ? `${text.slice(0, limit)}…` : text;
+}
+
+/** Re-exported so a fake's caller can normalise messages the same way. @internal */
+export { normalizeMessages };