@warlock.js/ai 4.5.0 → 4.6.0

package/esm/rag/store/pg-vector-store.mjs

@@ -0,0 +1,328 @@
+//#region ../@warlock.js/ai/src/rag/store/pg-vector-store.ts
+/**
+* Default backing table — provisions the store with no extra config when
+* the dev runs {@link VectorStore.schema | ensureSchema} through their
+* migration tool.
+*/
+const DEFAULT_TABLE = "warlock_ai_rag_vectors";
+/** Default embedding width baked into the DDL (OpenAI `text-embedding-3-small`). */
+const DEFAULT_DIMENSIONS = 1536;
+/** Default `ivfflat` list count when that index strategy is chosen. */
+const DEFAULT_IVFFLAT_LISTS = 100;
+/**
+* Allowed characters in a Postgres identifier (table name). The table name
+* is interpolated into DDL/DML, so anything outside this conservative
+* ASCII subset is rejected — interpolating an arbitrary string would be a
+* SQL-injection footgun (mirrors the snapshot / human-interrupt pg stores
+* and `@warlock.js/cache`'s `PgCacheDriver`).
+*/
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Module specifier for the optional `pg` driver. Held in a `string`
+* variable so the dynamic `import()` is not statically resolved at compile
+* time — `pg` is an optional peer that need not be installed for this
+* package to type-check or for a cache-only consumer to run.
+*/
+const PG_MODULE = "pg";
+/**
+* Curated install string surfaced (at use time) when a `connectionString`
+* is configured but the optional `pg` driver is absent. Never thrown at
+* import — a cache-only consumer must be able to load this module.
+*/
+const PG_INSTALL_INSTRUCTIONS = `
+The @warlock.js/ai Postgres vector store requires the pg package and a
+Postgres database with the pgvector extension. Install the driver with:
+
+  npm install pg
+
+Or with your preferred package manager:
+
+  pnpm add pg
+  yarn add pg
+`.trim();
+/**
+* Lazily import `pg` and return a `Pool` built from `connectionString`. A
+* bare `catch` rethrows the curated install string — a missing optional
+* peer surfaces as actionable guidance, never a raw resolution error.
+*/
+async function buildPgClient(connectionString) {
+	let sdk;
+	try {
+		sdk = await import(PG_MODULE);
+	} catch {
+		throw new Error(PG_INSTALL_INSTRUCTIONS);
+	}
+	return new sdk.Pool({ connectionString });
+}
+/**
+* Serialize a JS `number[]` to the pgvector text literal: `[1,2,3]`.
+* pgvector accepts a vector either as this bracketed literal or via a
+* typed parameter; passing the literal string + an explicit `::vector`
+* cast keeps the store driver-agnostic (no dependency on a registered
+* `pg` type parser).
+*
+* Non-finite components (`NaN` / `±Infinity`) are rejected — pgvector
+* stores only finite floats, and silently coercing them would corrupt the
+* index. The check is cheap relative to the embed call that produced the
+* vector.
+*
+* @example
+* vectorLiteral([1, 0.5, -2]); // "[1,0.5,-2]"
+*/
+function vectorLiteral(vector) {
+	let literal = "[";
+	for (let index = 0; index < vector.length; index++) {
+		const component = vector[index];
+		if (!Number.isFinite(component)) throw new TypeError(`pgVectorStore: embedding component at index ${index} is not finite (${component}); pgvector stores only finite floats.`);
+		if (index > 0) literal += ",";
+		literal += String(component);
+	}
+	return literal + "]";
+}
+/**
+* Coerce a `value` JSONB column back into the stored payload. node-postgres
+* parses `JSONB` into a JS value already, but some pool wrappers hand back
+* the raw string — be defensive across both (mirrors the snapshot store's
+* `parsePayload`).
+*/
+function parseValue(value) {
+	if (typeof value === "string") return JSON.parse(value);
+	return value;
+}
+/**
+* Coerce a pgvector cosine **distance** (`<=>`, in `[0, 2]`, 0 = identical)
+* into the cosine **similarity** score the {@link VectorStore} contract
+* declares (`[0, 1]`, 1 = identical). `pg` returns the computed distance
+* column as a string for `double precision`; parse then map `1 - distance`,
+* clamped to `[0, 1]` so a tiny floating-point overshoot never yields a
+* score just outside the contract's range.
+*/
+function distanceToScore(distance) {
+	const score = 1 - (typeof distance === "string" ? Number(distance) : distance);
+	if (score < 0) return 0;
+	if (score > 1) return 1;
+	return score;
+}
+/**
+* Postgres + pgvector-backed {@link VectorStore} — one durable row per
+* indexed chunk, keyed by the RAG pipeline's dotted `key`
+* (`ai.rag.<name>.<sourceId>.<chunkIndex>`), with the chunk payload in a
+* `value` JSONB column and the embedding in a `vector` column.
+*
+* Owns: the three RAG vector operations against a pgvector index —
+* `upsert` (INSERT … ON CONFLICT DO UPDATE), `query` (cosine
+* `ORDER BY embedding <=> $vec` with a `threshold` floor + optional `tags`
+* overlap filter, capped at `topK`), and `removeNamespace` (prefix DELETE).
+* Also emits the reference DDL via {@link PgVectorStore.schema} (alias
+* {@link PgVectorStore.ensureSchema}).
+*
+* Does NOT own: the connection lifecycle (a dev-supplied `client` is never
+* closed; a store-built `Pool` from a `connectionString` is also left open
+* for the process to reuse) or schema migration — the dev runs the DDL
+* through their own tool; the framework never auto-migrates.
+*
+* Front it with the {@link pgVectorStore} factory — callers never `new` it.
+*/
+var PgVectorStore = class {
+	constructor(options) {
+		const table = options.table ?? DEFAULT_TABLE;
+		if (!SAFE_IDENTIFIER.test(table)) throw new TypeError(`pgVectorStore: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
+		this.table = table;
+		this.dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;
+		this.index = options.index ?? "hnsw";
+		this.ivfflatLists = options.ivfflatLists ?? DEFAULT_IVFFLAT_LISTS;
+		if (options.client) {
+			if (typeof options.client.query !== "function") throw new TypeError("pgVectorStore requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.");
+			this.clientPromise = Promise.resolve(options.client);
+			return;
+		}
+		if (options.connectionString) {
+			this.clientPromise = buildPgClient(options.connectionString);
+			return;
+		}
+		throw new TypeError("pgVectorStore requires either a 'client' or a 'connectionString' option.");
+	}
+	/**
+	* Resolve the backing client, surfacing the lazy `pg` import's curated
+	* install string on the first call that needs it.
+	*/
+	client() {
+		return this.clientPromise;
+	}
+	/**
+	* Index `value` under `key` with its embedding `vector`. Upserts on the
+	* `key` primary key — re-indexing the same chunk overwrites its payload,
+	* embedding, and tags rather than appending a duplicate row. Optional
+	* `tags` ride a `text[]` column so {@link query} can restrict the
+	* candidate set with an array-overlap filter.
+	*
+	* The embedding is sent as a pgvector text literal (`$3`) cast to
+	* `::vector`, so the store needs no registered `pg` type parser. `tags`
+	* defaults to an empty array (never `NULL`) to keep the overlap filter's
+	* `&&` semantics simple.
+	*/
+	async upsert(key, value, vector, tags) {
+		await (await this.client()).query(`INSERT INTO ${this.table} (key, value, embedding, tags)
+       VALUES ($1, $2::jsonb, $3::vector, $4::text[])
+       ON CONFLICT (key) DO UPDATE
+         SET value = EXCLUDED.value,
+             embedding = EXCLUDED.embedding,
+             tags = EXCLUDED.tags`, [
+			key,
+			JSON.stringify(value),
+			vectorLiteral(vector),
+			tags ?? []
+		]);
+	}
+	/**
+	* Return the cosine-nearest rows to `vector`, mapped to the contract's
+	* `{ key, value, score }` shape. The SQL:
+	*
+	* - computes `embedding <=> $1::vector` (cosine **distance**) once, aliased
+	*   `distance`, and `ORDER BY` it ascending (nearest first);
+	* - applies the `threshold` floor as `distance <= 1 - threshold`
+	*   (similarity `>=` threshold), so the default `0.5` floor maps to a
+	*   `<= 0.5` distance bound — the filter runs in SQL, not in JS, so a
+	*   below-floor row never crosses the wire;
+	* - when `tags` are given, restricts to rows whose `tags` array overlaps
+	*   the requested set via `tags && $tags::text[]` (one-of semantics,
+	*   matching the cache store);
+	* - caps the result at `topK` with `LIMIT`.
+	*
+	* The returned `score` is `1 - distance`, clamped to `[0, 1]`, so callers
+	* see the same cosine-similarity scale the cache store emits.
+	*/
+	async query(vector, options) {
+		const client = await this.client();
+		const params = [vectorLiteral(vector), options.topK];
+		const conditions = [];
+		if (options.threshold !== void 0) {
+			params.push(1 - options.threshold);
+			conditions.push(`(embedding <=> $1::vector) <= $${params.length}`);
+		}
+		if (options.tags !== void 0 && options.tags.length > 0) {
+			params.push(options.tags);
+			conditions.push(`tags && $${params.length}::text[]`);
+		}
+		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+		const { rows } = await client.query(`SELECT key, value, (embedding <=> $1::vector) AS distance
+       FROM ${this.table}
+       ${where}
+       ORDER BY embedding <=> $1::vector
+       LIMIT $2`, params);
+		return rows.map((row) => ({
+			key: row.key,
+			value: parseValue(row.value),
+			score: distanceToScore(row.distance)
+		}));
+	}
+	/**
+	* Drop every entry written under `namespace`. The RAG pipeline keys
+	* chunks as `<namespace>.<sourceId>.<chunkIndex>`, so a row belongs to
+	* the namespace when its `key` equals it OR begins with `<namespace>.`
+	* — deleting `ai.rag.docs` must not also catch `ai.rag.docs2`. The `_`
+	* and `%` LIKE wildcards in the namespace are escaped so a namespace
+	* that happens to contain them is matched literally.
+	*/
+	async removeNamespace(namespace) {
+		const client = await this.client();
+		const escaped = namespace.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
+		await client.query(`DELETE FROM ${this.table}
+       WHERE key = $1 OR key LIKE $2 ESCAPE '\\'`, [namespace, `${escaped}.%`]);
+	}
+	/**
+	* Return the reference migration DDL for this store's backing table,
+	* interpolating the configured table name, embedding width, and ANN
+	* index strategy. The dev runs it once through their migration tool —
+	* the framework never auto-migrates.
+	*
+	* The emitted statements:
+	* 1. `CREATE EXTENSION IF NOT EXISTS vector;` — enables pgvector (needs
+	*    a superuser or a role with `CREATE` on the database the first time).
+	* 2. `CREATE TABLE IF NOT EXISTS <table> (key TEXT PRIMARY KEY, value
+	*    JSONB NOT NULL, embedding vector(<dimensions>) NOT NULL, tags
+	*    text[] NOT NULL DEFAULT '{}');`
+	* 3. A GIN index on `tags` so the array-overlap filter stays sargable.
+	* 4. The chosen ANN index over `embedding` using `vector_cosine_ops`:
+	*    - `"hnsw"` → `USING hnsw (embedding vector_cosine_ops)`;
+	*    - `"ivfflat"` → `USING ivfflat (embedding vector_cosine_ops)
+	*      WITH (lists = <ivfflatLists>)`;
+	*    - `"none"` → emitted as a comment (exact scan, no ANN index).
+	*
+	* @example
+	* const store = pgVectorStore({ client: pool, dimensions: 1536 });
+	* await pool.query(store.ensureSchema());
+	*/
+	schema() {
+		const lines = [
+			`CREATE EXTENSION IF NOT EXISTS vector;`,
+			`CREATE TABLE IF NOT EXISTS ${this.table} (`,
+			`  key        TEXT PRIMARY KEY,`,
+			`  value      JSONB NOT NULL,`,
+			`  embedding  vector(${this.dimensions}) NOT NULL,`,
+			`  tags       TEXT[] NOT NULL DEFAULT '{}'`,
+			`);`,
+			`CREATE INDEX IF NOT EXISTS idx_${this.table}_tags`,
+			`  ON ${this.table} USING gin (tags);`
+		];
+		if (this.index === "hnsw") lines.push(`CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`, `  ON ${this.table} USING hnsw (embedding vector_cosine_ops);`);
+		else if (this.index === "ivfflat") lines.push(`CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`, `  ON ${this.table} USING ivfflat (embedding vector_cosine_ops)`, `  WITH (lists = ${this.ivfflatLists});`);
+		else lines.push(`-- No ANN index requested (index: "none"): cosine queries fall back`, `-- to an exact sequential scan, which is correct but linear in rows.`);
+		return lines.join("\n");
+	}
+	/**
+	* Alias for {@link PgVectorStore.schema} — reads more naturally in a
+	* migration script (`await pool.query(store.ensureSchema())`). Returns
+	* the identical DDL string; it does NOT execute anything against the
+	* database (the store never auto-migrates).
+	*/
+	ensureSchema() {
+		return this.schema();
+	}
+};
+/**
+* Create a Postgres + pgvector-backed {@link VectorStore} for the RAG
+* pipeline. Either pass a live `pg.Pool` / `pg.Client` (`{ client }`) —
+* `@warlock.js/ai` never imports `pg` in that case — or a
+* `{ connectionString }` and let the store lazily `import("pg")` to build
+* its own pool. When `pg` is not installed, a curated install string
+* surfaces on first use, never at import.
+*
+* Run {@link PgVectorStoreInstance.ensureSchema} through your migration
+* tool once before use (it enables the `vector` extension, creates the
+* table, and builds the tag + ANN indexes); the store never auto-migrates.
+*
+* Index and query MUST use the same embedding model — the `vector(N)`
+* column width is fixed at table-creation time from `dimensions`.
+*
+* @example
+* import { Pool } from "pg";
+* import { ai } from "@warlock.js/ai";
+*
+* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+* const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });
+*
+* // Once, via your migration tooling:
+* // await pool.query(store.ensureSchema());
+*
+* const kb = ai.rag({
+*   name: "docs",
+*   embedder: openai.embedder({ name: "text-embedding-3-small" }),
+*   store,
+* });
+*
+* @example
+* // Let the store build its own pool from a connection string:
+* const store = ai.rag.pgVectorStore({
+*   connectionString: process.env.DATABASE_URL,
+*   index: "ivfflat",
+*   ivfflatLists: 200,
+* });
+*/
+function pgVectorStore(options) {
+	return new PgVectorStore(options);
+}
+
+//#endregion
+export { pgVectorStore, vectorLiteral };
+//# sourceMappingURL=pg-vector-store.mjs.map

package/esm/rag/store/pg-vector-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-vector-store.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/store/pg-vector-store.ts"],"sourcesContent":["import type { VectorStore } from \"./vector-store.contract\";\n\n/**\n * Minimal `pg`-compatible client surface the Postgres {@link VectorStore}\n * depends on. Both `pg.Pool` and `pg.Client` satisfy it — the store only\n * ever calls `query`.\n *\n * `@warlock.js/ai` takes **no** hard dependency on `pg`; the dev installs\n * it (an optional peer) and passes the client in. Structurally identical\n * to the snapshot / human-interrupt stores' `PgClientLike`, so a single\n * pool can back the orchestrator checkpoint/snapshot tables, the\n * interrupt table, and this vectors table alike.\n */\nexport interface PgClientLike {\n  query(text: string, params?: unknown[]): Promise<{ rows: unknown[] }>;\n}\n\n/**\n * Options for the Postgres {@link VectorStore}.\n *\n * Two mutually-supportive ways to supply the connection (mirroring\n * `ai.human.interrupt.pg`):\n * - **`client`** — pass an already-built `pg.Pool` / `pg.Client` (anything\n *   satisfying {@link PgClientLike}). The store only ever calls `query`\n *   and never opens or closes it; one pool can back several stores.\n * - **`connectionString`** — let the store lazily `import(\"pg\")` and build\n *   its own `Pool`. `@warlock.js/ai` takes **no** hard dependency on\n *   `pg` (an optional peer); when it is absent the store throws a curated\n *   install string at first use, never a raw module-resolution stack trace\n *   at import.\n *\n * Exactly one of the two must be present.\n */\nexport interface PgVectorStoreOptions {\n  /** An already-built `pg.Pool` / `pg.Client` — anything matching {@link PgClientLike}. */\n  client?: PgClientLike;\n\n  /** Connection string the store passes to a lazily-imported `pg.Pool`. */\n  connectionString?: string;\n\n  /**\n   * Backing table name. Defaults to `warlock_ai_rag_vectors`. Must be a\n   * safe SQL identifier — it is interpolated into DDL/DML.\n   */\n  table?: string;\n\n  /**\n   * Embedding dimensionality used in the `CREATE TABLE` DDL emitted by\n   * {@link VectorStore.schema | ensureSchema}. Defaults to `1536`\n   * (OpenAI `text-embedding-3-small`). The column is declared\n   * `vector(N)`; queries and upserts never re-state it, so an existing\n   * table provisioned at a different size is unaffected — only the DDL\n   * helper reads this.\n   */\n  dimensions?: number;\n\n  /**\n   * Approximate-nearest-neighbour index strategy baked into the DDL\n   * emitted by {@link VectorStore.schema | ensureSchema}. Defaults to\n   * `\"hnsw\"` (better recall/latency on modern pgvector). Use `\"ivfflat\"`\n   * for the classic list-partitioned index, or `\"none\"` to emit no ANN\n   * index (exact scan — correct, but linear in row count).\n   */\n  index?: \"hnsw\" | \"ivfflat\" | \"none\";\n\n  /**\n   * `lists` parameter for an `ivfflat` index (ignored for `hnsw` / `none`).\n   * Defaults to `100`. Tune toward `rows / 1000` for large tables.\n   */\n  ivfflatLists?: number;\n}\n\n/**\n * Default backing table — provisions the store with no extra config when\n * the dev runs {@link VectorStore.schema | ensureSchema} through their\n * migration tool.\n */\nconst DEFAULT_TABLE = \"warlock_ai_rag_vectors\";\n\n/** Default embedding width baked into the DDL (OpenAI `text-embedding-3-small`). */\nconst DEFAULT_DIMENSIONS = 1536;\n\n/** Default `ivfflat` list count when that index strategy is chosen. */\nconst DEFAULT_IVFFLAT_LISTS = 100;\n\n/**\n * Allowed characters in a Postgres identifier (table name). The table name\n * is interpolated into DDL/DML, so anything outside this conservative\n * ASCII subset is rejected — interpolating an arbitrary string would be a\n * SQL-injection footgun (mirrors the snapshot / human-interrupt pg stores\n * and `@warlock.js/cache`'s `PgCacheDriver`).\n */\nconst SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Module specifier for the optional `pg` driver. Held in a `string`\n * variable so the dynamic `import()` is not statically resolved at compile\n * time — `pg` is an optional peer that need not be installed for this\n * package to type-check or for a cache-only consumer to run.\n */\nconst PG_MODULE = \"pg\";\n\n/**\n * Curated install string surfaced (at use time) when a `connectionString`\n * is configured but the optional `pg` driver is absent. Never thrown at\n * import — a cache-only consumer must be able to load this module.\n */\nconst PG_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai Postgres vector store requires the pg package and a\nPostgres database with the pgvector extension. Install the driver with:\n\n  npm install pg\n\nOr with your preferred package manager:\n\n  pnpm add pg\n  yarn add pg\n`.trim();\n\n/**\n * Minimal structural view of a `pg.Pool` constructor — just enough of the\n * `pg` module surface for the store to build a client when handed a\n * `connectionString`. Declared locally (rather than `typeof import(\"pg\")`)\n * so this module type-checks even when `pg` is not installed.\n */\ninterface PgModuleLike {\n  Pool: new (config: { connectionString: string }) => PgClientLike;\n}\n\n/**\n * Lazily import `pg` and return a `Pool` built from `connectionString`. A\n * bare `catch` rethrows the curated install string — a missing optional\n * peer surfaces as actionable guidance, never a raw resolution error.\n */\nasync function buildPgClient(connectionString: string): Promise<PgClientLike> {\n  let sdk: PgModuleLike;\n\n  try {\n    sdk = (await import(PG_MODULE)) as unknown as PgModuleLike;\n  } catch {\n    throw new Error(PG_INSTALL_INSTRUCTIONS);\n  }\n\n  return new sdk.Pool({ connectionString });\n}\n\n/**\n * Serialize a JS `number[]` to the pgvector text literal: `[1,2,3]`.\n * pgvector accepts a vector either as this bracketed literal or via a\n * typed parameter; passing the literal string + an explicit `::vector`\n * cast keeps the store driver-agnostic (no dependency on a registered\n * `pg` type parser).\n *\n * Non-finite components (`NaN` / `±Infinity`) are rejected — pgvector\n * stores only finite floats, and silently coercing them would corrupt the\n * index. The check is cheap relative to the embed call that produced the\n * vector.\n *\n * @example\n * vectorLiteral([1, 0.5, -2]); // \"[1,0.5,-2]\"\n */\nexport function vectorLiteral(vector: number[]): string {\n  let literal = \"[\";\n\n  for (let index = 0; index < vector.length; index++) {\n    const component = vector[index];\n\n    if (!Number.isFinite(component)) {\n      throw new TypeError(\n        `pgVectorStore: embedding component at index ${index} is not finite (${component}); pgvector stores only finite floats.`,\n      );\n    }\n\n    if (index > 0) {\n      literal += \",\";\n    }\n\n    literal += String(component);\n  }\n\n  return literal + \"]\";\n}\n\n/**\n * Coerce a `value` JSONB column back into the stored payload. node-postgres\n * parses `JSONB` into a JS value already, but some pool wrappers hand back\n * the raw string — be defensive across both (mirrors the snapshot store's\n * `parsePayload`).\n */\nfunction parseValue<T>(value: unknown): T {\n  if (typeof value === \"string\") {\n    return JSON.parse(value) as T;\n  }\n\n  return value as T;\n}\n\n/**\n * Coerce a pgvector cosine **distance** (`<=>`, in `[0, 2]`, 0 = identical)\n * into the cosine **similarity** score the {@link VectorStore} contract\n * declares (`[0, 1]`, 1 = identical). `pg` returns the computed distance\n * column as a string for `double precision`; parse then map `1 - distance`,\n * clamped to `[0, 1]` so a tiny floating-point overshoot never yields a\n * score just outside the contract's range.\n */\nfunction distanceToScore(distance: unknown): number {\n  const value = typeof distance === \"string\" ? Number(distance) : (distance as number);\n  const score = 1 - value;\n\n  if (score < 0) {\n    return 0;\n  }\n\n  if (score > 1) {\n    return 1;\n  }\n\n  return score;\n}\n\n/**\n * Postgres + pgvector-backed {@link VectorStore} — one durable row per\n * indexed chunk, keyed by the RAG pipeline's dotted `key`\n * (`ai.rag.<name>.<sourceId>.<chunkIndex>`), with the chunk payload in a\n * `value` JSONB column and the embedding in a `vector` column.\n *\n * Owns: the three RAG vector operations against a pgvector index —\n * `upsert` (INSERT … ON CONFLICT DO UPDATE), `query` (cosine\n * `ORDER BY embedding <=> $vec` with a `threshold` floor + optional `tags`\n * overlap filter, capped at `topK`), and `removeNamespace` (prefix DELETE).\n * Also emits the reference DDL via {@link PgVectorStore.schema} (alias\n * {@link PgVectorStore.ensureSchema}).\n *\n * Does NOT own: the connection lifecycle (a dev-supplied `client` is never\n * closed; a store-built `Pool` from a `connectionString` is also left open\n * for the process to reuse) or schema migration — the dev runs the DDL\n * through their own tool; the framework never auto-migrates.\n *\n * Front it with the {@link pgVectorStore} factory — callers never `new` it.\n */\nclass PgVectorStore implements VectorStore {\n  /** Validated backing table name, safe to interpolate into SQL. */\n  private readonly table: string;\n\n  /** Embedding width baked into the DDL. */\n  private readonly dimensions: number;\n\n  /** ANN index strategy baked into the DDL. */\n  private readonly index: \"hnsw\" | \"ivfflat\" | \"none\";\n\n  /** `lists` parameter for an `ivfflat` index. */\n  private readonly ivfflatLists: number;\n\n  /**\n   * A ready client, or a promise resolving to one the store builds lazily\n   * from a `connectionString`. Resolved once and memoized so the optional\n   * `pg` import happens at most once.\n   */\n  private readonly clientPromise: Promise<PgClientLike>;\n\n  public constructor(options: PgVectorStoreOptions) {\n    const table = options.table ?? DEFAULT_TABLE;\n\n    if (!SAFE_IDENTIFIER.test(table)) {\n      throw new TypeError(\n        `pgVectorStore: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n      );\n    }\n\n    this.table = table;\n    this.dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;\n    this.index = options.index ?? \"hnsw\";\n    this.ivfflatLists = options.ivfflatLists ?? DEFAULT_IVFFLAT_LISTS;\n\n    if (options.client) {\n      if (typeof options.client.query !== \"function\") {\n        throw new TypeError(\n          \"pgVectorStore requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.\",\n        );\n      }\n\n      this.clientPromise = Promise.resolve(options.client);\n\n      return;\n    }\n\n    if (options.connectionString) {\n      // Defer the optional `pg` import to first use — a curated install\n      // string surfaces from `buildPgClient`, not at construction.\n      this.clientPromise = buildPgClient(options.connectionString);\n\n      return;\n    }\n\n    throw new TypeError(\n      \"pgVectorStore requires either a 'client' or a 'connectionString' option.\",\n    );\n  }\n\n  /**\n   * Resolve the backing client, surfacing the lazy `pg` import's curated\n   * install string on the first call that needs it.\n   */\n  private client(): Promise<PgClientLike> {\n    return this.clientPromise;\n  }\n\n  /**\n   * Index `value` under `key` with its embedding `vector`. Upserts on the\n   * `key` primary key — re-indexing the same chunk overwrites its payload,\n   * embedding, and tags rather than appending a duplicate row. Optional\n   * `tags` ride a `text[]` column so {@link query} can restrict the\n   * candidate set with an array-overlap filter.\n   *\n   * The embedding is sent as a pgvector text literal (`$3`) cast to\n   * `::vector`, so the store needs no registered `pg` type parser. `tags`\n   * defaults to an empty array (never `NULL`) to keep the overlap filter's\n   * `&&` semantics simple.\n   */\n  public async upsert(\n    key: string,\n    value: unknown,\n    vector: number[],\n    tags?: string[],\n  ): Promise<void> {\n    const client = await this.client();\n\n    await client.query(\n      `INSERT INTO ${this.table} (key, value, embedding, tags)\n       VALUES ($1, $2::jsonb, $3::vector, $4::text[])\n       ON CONFLICT (key) DO UPDATE\n         SET value = EXCLUDED.value,\n             embedding = EXCLUDED.embedding,\n             tags = EXCLUDED.tags`,\n      [key, JSON.stringify(value), vectorLiteral(vector), tags ?? []],\n    );\n  }\n\n  /**\n   * Return the cosine-nearest rows to `vector`, mapped to the contract's\n   * `{ key, value, score }` shape. The SQL:\n   *\n   * - computes `embedding <=> $1::vector` (cosine **distance**) once, aliased\n   *   `distance`, and `ORDER BY` it ascending (nearest first);\n   * - applies the `threshold` floor as `distance <= 1 - threshold`\n   *   (similarity `>=` threshold), so the default `0.5` floor maps to a\n   *   `<= 0.5` distance bound — the filter runs in SQL, not in JS, so a\n   *   below-floor row never crosses the wire;\n   * - when `tags` are given, restricts to rows whose `tags` array overlaps\n   *   the requested set via `tags && $tags::text[]` (one-of semantics,\n   *   matching the cache store);\n   * - caps the result at `topK` with `LIMIT`.\n   *\n   * The returned `score` is `1 - distance`, clamped to `[0, 1]`, so callers\n   * see the same cosine-similarity scale the cache store emits.\n   */\n  public async query<T>(\n    vector: number[],\n    options: { topK: number; threshold?: number; tags?: string[] },\n  ): Promise<{ key: string; value: T; score: number }[]> {\n    const client = await this.client();\n    const queryVector = vectorLiteral(vector);\n\n    // $1 = query vector, $2 = topK. Optional threshold + tags are appended\n    // as $3 / $4 only when present, so the prepared statement carries no\n    // unused placeholders.\n    const params: unknown[] = [queryVector, options.topK];\n    const conditions: string[] = [];\n\n    if (options.threshold !== undefined) {\n      params.push(1 - options.threshold);\n      conditions.push(`(embedding <=> $1::vector) <= $${params.length}`);\n    }\n\n    if (options.tags !== undefined && options.tags.length > 0) {\n      params.push(options.tags);\n      conditions.push(`tags && $${params.length}::text[]`);\n    }\n\n    const where = conditions.length > 0 ? `WHERE ${conditions.join(\" AND \")}` : \"\";\n\n    const { rows } = await client.query(\n      `SELECT key, value, (embedding <=> $1::vector) AS distance\n       FROM ${this.table}\n       ${where}\n       ORDER BY embedding <=> $1::vector\n       LIMIT $2`,\n      params,\n    );\n\n    return (rows as Record<string, unknown>[]).map((row) => ({\n      key: row.key as string,\n      value: parseValue<T>(row.value),\n      score: distanceToScore(row.distance),\n    }));\n  }\n\n  /**\n   * Drop every entry written under `namespace`. The RAG pipeline keys\n   * chunks as `<namespace>.<sourceId>.<chunkIndex>`, so a row belongs to\n   * the namespace when its `key` equals it OR begins with `<namespace>.`\n   * — deleting `ai.rag.docs` must not also catch `ai.rag.docs2`. The `_`\n   * and `%` LIKE wildcards in the namespace are escaped so a namespace\n   * that happens to contain them is matched literally.\n   */\n  public async removeNamespace(namespace: string): Promise<void> {\n    const client = await this.client();\n\n    const escaped = namespace\n      .replace(/\\\\/g, \"\\\\\\\\\")\n      .replace(/_/g, \"\\\\_\")\n      .replace(/%/g, \"\\\\%\");\n\n    await client.query(\n      `DELETE FROM ${this.table}\n       WHERE key = $1 OR key LIKE $2 ESCAPE '\\\\'`,\n      [namespace, `${escaped}.%`],\n    );\n  }\n\n  /**\n   * Return the reference migration DDL for this store's backing table,\n   * interpolating the configured table name, embedding width, and ANN\n   * index strategy. The dev runs it once through their migration tool —\n   * the framework never auto-migrates.\n   *\n   * The emitted statements:\n   * 1. `CREATE EXTENSION IF NOT EXISTS vector;` — enables pgvector (needs\n   *    a superuser or a role with `CREATE` on the database the first time).\n   * 2. `CREATE TABLE IF NOT EXISTS <table> (key TEXT PRIMARY KEY, value\n   *    JSONB NOT NULL, embedding vector(<dimensions>) NOT NULL, tags\n   *    text[] NOT NULL DEFAULT '{}');`\n   * 3. A GIN index on `tags` so the array-overlap filter stays sargable.\n   * 4. The chosen ANN index over `embedding` using `vector_cosine_ops`:\n   *    - `\"hnsw\"` → `USING hnsw (embedding vector_cosine_ops)`;\n   *    - `\"ivfflat\"` → `USING ivfflat (embedding vector_cosine_ops)\n   *      WITH (lists = <ivfflatLists>)`;\n   *    - `\"none\"` → emitted as a comment (exact scan, no ANN index).\n   *\n   * @example\n   * const store = pgVectorStore({ client: pool, dimensions: 1536 });\n   * await pool.query(store.ensureSchema());\n   */\n  public schema(): string {\n    const lines = [\n      `CREATE EXTENSION IF NOT EXISTS vector;`,\n      `CREATE TABLE IF NOT EXISTS ${this.table} (`,\n      `  key        TEXT PRIMARY KEY,`,\n      `  value      JSONB NOT NULL,`,\n      `  embedding  vector(${this.dimensions}) NOT NULL,`,\n      `  tags       TEXT[] NOT NULL DEFAULT '{}'`,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${this.table}_tags`,\n      `  ON ${this.table} USING gin (tags);`,\n    ];\n\n    if (this.index === \"hnsw\") {\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`,\n        `  ON ${this.table} USING hnsw (embedding vector_cosine_ops);`,\n      );\n    } else if (this.index === \"ivfflat\") {\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`,\n        `  ON ${this.table} USING ivfflat (embedding vector_cosine_ops)`,\n        `  WITH (lists = ${this.ivfflatLists});`,\n      );\n    } else {\n      lines.push(\n        `-- No ANN index requested (index: \"none\"): cosine queries fall back`,\n        `-- to an exact sequential scan, which is correct but linear in rows.`,\n      );\n    }\n\n    return lines.join(\"\\n\");\n  }\n\n  /**\n   * Alias for {@link PgVectorStore.schema} — reads more naturally in a\n   * migration script (`await pool.query(store.ensureSchema())`). Returns\n   * the identical DDL string; it does NOT execute anything against the\n   * database (the store never auto-migrates).\n   */\n  public ensureSchema(): string {\n    return this.schema();\n  }\n}\n\n/**\n * The {@link VectorStore} surface plus the pg store's extra DDL helpers.\n * `schema()` / `ensureSchema()` are not part of the base contract (the\n * cache store has no backing table), so the factory's return type widens\n * it for callers that want the migration SQL.\n */\nexport interface PgVectorStoreInstance extends VectorStore {\n  /** Reference migration DDL (extension + table + indexes). Never executed. */\n  schema(): string;\n  /** Alias for {@link PgVectorStoreInstance.schema} — reads better in a migration script. */\n  ensureSchema(): string;\n}\n\n/**\n * Create a Postgres + pgvector-backed {@link VectorStore} for the RAG\n * pipeline. Either pass a live `pg.Pool` / `pg.Client` (`{ client }`) —\n * `@warlock.js/ai` never imports `pg` in that case — or a\n * `{ connectionString }` and let the store lazily `import(\"pg\")` to build\n * its own pool. When `pg` is not installed, a curated install string\n * surfaces on first use, never at import.\n *\n * Run {@link PgVectorStoreInstance.ensureSchema} through your migration\n * tool once before use (it enables the `vector` extension, creates the\n * table, and builds the tag + ANN indexes); the store never auto-migrates.\n *\n * Index and query MUST use the same embedding model — the `vector(N)`\n * column width is fixed at table-creation time from `dimensions`.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n * const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });\n *\n * // Once, via your migration tooling:\n * // await pool.query(store.ensureSchema());\n *\n * const kb = ai.rag({\n *   name: \"docs\",\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store,\n * });\n *\n * @example\n * // Let the store build its own pool from a connection string:\n * const store = ai.rag.pgVectorStore({\n *   connectionString: process.env.DATABASE_URL,\n *   index: \"ivfflat\",\n *   ivfflatLists: 200,\n * });\n */\nexport function pgVectorStore(options: PgVectorStoreOptions): PgVectorStoreInstance {\n  return new PgVectorStore(options);\n}\n"],"mappings":"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"}

package/esm/speech/index.mjs

@@ -0,0 +1,3 @@
+import { speech } from "./speech.mjs";
+
+export {  };

package/esm/speech/speech.d.mts

@@ -0,0 +1,65 @@
+import { BaseReport } from "../contracts/result/base-report.type.mjs";
+import { ExecuteResult } from "../contracts/result/execute-result.type.mjs";
+import { FlowObserveOption } from "../observe/resolve-observers.mjs";
+import { GeneratedAudio, SpeechModelContract } from "../contracts/speech-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/speech/speech.d.ts
+/** Parameters for {@link speech}. `model` comes from `sdk.speech({ name })`. */
+type SpeechParams = {
+  /** The TTS model to synthesize with. */model: SpeechModelContract; /** The text to speak. */
+  text: string; /** Voice id/name; overrides the model's default voice. */
+  voice?: string; /** Output container (`"mp3"` / `"opus"` / `"aac"` / `"flac"` / `"wav"` / `"pcm"`). */
+  format?: string; /** Playback speed multiplier. */
+  speed?: number; /** Extra tone/delivery steering (model-dependent). */
+  instructions?: string; /** Cancellation handle. */
+  signal?: AbortSignal; /** Observability routing — same `observe` seam as agents. */
+  observe?: FlowObserveOption; /** Groups this call into a session for flat cost/trace queries. */
+  sessionId?: string; /** Report node name (defaults to `"speech"`). */
+  name?: string; /** Provider-specific options forwarded verbatim to the adapter. */
+  options?: Record<string, unknown>;
+};
+/** Success payload of a {@link speech} run. */
+type SpeechData = {
+  /** The synthesized audio, normalized to the discriminated shape. */audio: GeneratedAudio;
+};
+/** The report node a {@link speech} run produces (`type: "speech"`). */
+type SpeechReport = BaseReport & {
+  type: "speech"; /** Identity of the TTS model this run used. */
+  model: {
+    name: string;
+    provider: string;
+  }; /** Number of input characters synthesized (0 on failure). */
+  characters: number;
+};
+/** Result envelope of {@link speech} — the uniform `{ data, error, usage, report }`. */
+type SpeechResult = ExecuteResult<SpeechData> & {
+  type: "speech";
+  report: SpeechReport;
+};
+/**
+ * Synthesize speech from text — the text-to-speech verb of the
+ * output-modality track (Theme I), sibling to `ai.image()`. Wraps a
+ * {@link SpeechModelContract} (from `openai.speech(...)`) in the
+ * framework's uniform result contract:
+ *
+ * - **Never throws.** Provider failures surface as a typed `AIError` on
+ *   `result.error`; `result.data` is then `undefined`.
+ * - **Cost-truth.** `result.usage.cost` is filled per-character
+ *   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same
+ *   `Usage.cost` rollup as text.
+ * - **Observable.** The completed {@link SpeechReport} routes to any
+ *   registered `Observer` (panoptic, OTel, …) via the `observe` seam.
+ *
+ * @example
+ * const openai = new OpenAISDK({ apiKey });
+ * const { data, error } = await ai.speech({
+ *   model: openai.speech({ name: "tts-1", voice: "alloy" }),
+ *   text: "Your order has shipped.",
+ *   format: "mp3",
+ * });
+ * if (!error) await fs.writeFile("ship.mp3", Buffer.from(data.audio.base64, "base64"));
+ */
+declare function speech(params: SpeechParams): Promise<SpeechResult>;
+//#endregion
+export { SpeechData, SpeechParams, SpeechReport, SpeechResult, speech };
+//# sourceMappingURL=speech.d.mts.map

package/esm/speech/speech.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/speech/speech.ts"],"mappings":";;;;;;;KAmBY,YAAA;EAAA,wCAEV,KAAA,EAAO,mBAAA;EAEP,IAAA,UAUS;EART,KAAA,WAgBU;EAdV,MAAA,WAcgB;EAZhB,KAAA,WARO;EAUP,YAAA,WANA;EAQA,MAAA,GAAS,WAAA,EAJT;EAMA,OAAA,GAAU,iBAAA,EAFV;EAIA,SAAA,WAFA;EAIA,IAAA,WAFA;EAIA,OAAA,GAAU,MAAA;AAAA;;KAIA,UAAA;EAJM,oEAMhB,KAAA,EAAO,cAAc;AAAA;;KAIX,YAAA,GAAe,UAAU;EACnC,IAAA,YADU;EAGV,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA,GAFvB;EAIA,UAAA;AAAA;;KAIU,YAAA,GAAe,aAAA,CAAc,UAAA;EACvC,IAAA;EACA,MAAA,EAAQ,YAAA;AAAA;;;;;;;;;;;;;;AAAY;AA0BtB;;;;;;;;;iBAAsB,MAAA,CAAO,MAAA,EAAQ,YAAA,GAAe,OAAA,CAAQ,YAAA"}

package/esm/speech/speech.mjs

@@ -0,0 +1,123 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { ProviderError } from "../errors/provider-error.mjs";
+import { computeCost } from "../utils/compute-cost.mjs";
+import { generateRunId } from "../utils/generate-run-id.mjs";
+import { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
+import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import { notifyObservers } from "../observe/resolve-observers.mjs";
+
+//#region ../@warlock.js/ai/src/speech/speech.ts
+/**
+* Synthesize speech from text — the text-to-speech verb of the
+* output-modality track (Theme I), sibling to `ai.image()`. Wraps a
+* {@link SpeechModelContract} (from `openai.speech(...)`) in the
+* framework's uniform result contract:
+*
+* - **Never throws.** Provider failures surface as a typed `AIError` on
+*   `result.error`; `result.data` is then `undefined`.
+* - **Cost-truth.** `result.usage.cost` is filled per-character
+*   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same
+*   `Usage.cost` rollup as text.
+* - **Observable.** The completed {@link SpeechReport} routes to any
+*   registered `Observer` (panoptic, OTel, …) via the `observe` seam.
+*
+* @example
+* const openai = new OpenAISDK({ apiKey });
+* const { data, error } = await ai.speech({
+*   model: openai.speech({ name: "tts-1", voice: "alloy" }),
+*   text: "Your order has shipped.",
+*   format: "mp3",
+* });
+* if (!error) await fs.writeFile("ship.mp3", Buffer.from(data.audio.base64, "base64"));
+*/
+async function speech(params) {
+	const { model, text } = params;
+	const runId = generateRunId("speech");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let characters = 0;
+	try {
+		const response = await model.generate(text, {
+			voice: params.voice,
+			format: params.format,
+			speed: params.speed,
+			instructions: params.instructions,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		characters = response.characters;
+		if (usage.cost === void 0) {
+			const cost = computeSpeechCost(usage, characters, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
+		}
+		data = { audio: response.audio };
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
+	}
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "speech",
+		type: "speech",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		characters,
+		reportSchemaVersion: 1
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	await notifyObservers(params.observe, report);
+	return {
+		type: "speech",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/**
+* Price a TTS run: `perMillionCharacters × characters` (per-character
+* metering, attributed to `cost.input`) wins when configured, otherwise
+* the standard token math. Returns `undefined` when no usable pricing
+* is present.
+*/
+function computeSpeechCost(usage, characters, pricing) {
+	if (!pricing) return;
+	if (pricing.perMillionCharacters !== void 0) return {
+		input: characters * pricing.perMillionCharacters / 1e6,
+		output: 0
+	};
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+export { speech };
+//# sourceMappingURL=speech.mjs.map

package/esm/speech/speech.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/speech/speech.ts"],"sourcesContent":["import type {\n  GeneratedAudio,\n  SpeechModelContract,\n  SpeechModelPricing,\n} from \"../contracts/speech-model.contract\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { computeCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\n\n/** Parameters for {@link speech}. `model` comes from `sdk.speech({ name })`. */\nexport type SpeechParams = {\n  /** The TTS model to synthesize with. */\n  model: SpeechModelContract;\n  /** The text to speak. */\n  text: string;\n  /** Voice id/name; overrides the model's default voice. */\n  voice?: string;\n  /** Output container (`\"mp3\"` / `\"opus\"` / `\"aac\"` / `\"flac\"` / `\"wav\"` / `\"pcm\"`). */\n  format?: string;\n  /** Playback speed multiplier. */\n  speed?: number;\n  /** Extra tone/delivery steering (model-dependent). */\n  instructions?: string;\n  /** Cancellation handle. */\n  signal?: AbortSignal;\n  /** Observability routing — same `observe` seam as agents. */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"speech\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of a {@link speech} run. */\nexport type SpeechData = {\n  /** The synthesized audio, normalized to the discriminated shape. */\n  audio: GeneratedAudio;\n};\n\n/** The report node a {@link speech} run produces (`type: \"speech\"`). */\nexport type SpeechReport = BaseReport & {\n  type: \"speech\";\n  /** Identity of the TTS model this run used. */\n  model: { name: string; provider: string };\n  /** Number of input characters synthesized (0 on failure). */\n  characters: number;\n};\n\n/** Result envelope of {@link speech} — the uniform `{ data, error, usage, report }`. */\nexport type SpeechResult = ExecuteResult<SpeechData> & {\n  type: \"speech\";\n  report: SpeechReport;\n};\n\n/**\n * Synthesize speech from text — the text-to-speech verb of the\n * output-modality track (Theme I), sibling to `ai.image()`. Wraps a\n * {@link SpeechModelContract} (from `openai.speech(...)`) in the\n * framework's uniform result contract:\n *\n * - **Never throws.** Provider failures surface as a typed `AIError` on\n *   `result.error`; `result.data` is then `undefined`.\n * - **Cost-truth.** `result.usage.cost` is filled per-character\n *   (`tts-1`) or per-token (`gpt-4o-mini-tts`), folding into the same\n *   `Usage.cost` rollup as text.\n * - **Observable.** The completed {@link SpeechReport} routes to any\n *   registered `Observer` (panoptic, OTel, …) via the `observe` seam.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error } = await ai.speech({\n *   model: openai.speech({ name: \"tts-1\", voice: \"alloy\" }),\n *   text: \"Your order has shipped.\",\n *   format: \"mp3\",\n * });\n * if (!error) await fs.writeFile(\"ship.mp3\", Buffer.from(data.audio.base64, \"base64\"));\n */\nexport async function speech(params: SpeechParams): Promise<SpeechResult> {\n  const { model, text } = params;\n\n  const runId = generateRunId(\"speech\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: SpeechData | undefined;\n  let error: AIError | undefined;\n  let status: SpeechReport[\"status\"] = \"completed\";\n  let characters = 0;\n\n  try {\n    const response = await model.generate(text, {\n      voice: params.voice,\n      format: params.format,\n      speed: params.speed,\n      instructions: params.instructions,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    Object.assign(usage, response.usage);\n    characters = response.characters;\n\n    if (usage.cost === undefined) {\n      const cost = computeSpeechCost(usage, characters, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { audio: response.audio };\n  } catch (thrown) {\n    error =\n      thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: SpeechReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"speech\",\n    type: \"speech\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    characters,\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"speech\", data, error, usage, report };\n}\n\n/**\n * Price a TTS run: `perMillionCharacters × characters` (per-character\n * metering, attributed to `cost.input`) wins when configured, otherwise\n * the standard token math. Returns `undefined` when no usable pricing\n * is present.\n */\nfunction computeSpeechCost(\n  usage: Usage,\n  characters: number,\n  pricing: SpeechModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  if (pricing.perMillionCharacters !== undefined) {\n    return { input: (characters * pricing.perMillionCharacters) / 1_000_000, output: 0 };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,eAAsB,OAAO,QAA6C;CACxE,MAAM,EAAE,OAAO,SAAS;CAExB,MAAM,QAAQ,cAAc,QAAQ;CACpC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAiC;CACrC,IAAI,aAAa;CAEjB,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,SAAS,MAAM;GAC1C,OAAO,OAAO;GACd,QAAQ,OAAO;GACf,OAAO,OAAO;GACd,cAAc,OAAO;GACrB,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,KAAK;EACnC,aAAa,SAAS;EAEtB,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,kBAAkB,OAAO,YAAY,MAAM,OAAO;GAC/D,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO,EAAE,OAAO,SAAS,MAAM;CACjC,SAAS,QAAQ;EACf,QACE,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAC7F,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAAuB;EAC3B;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD;EACA;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAU;EAAM;EAAO;EAAO;CAAO;AACtD;;;;;;;AAQA,SAAS,kBACP,OACA,YACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAGF,IAAI,QAAQ,yBAAyB,QACnC,OAAO;EAAE,OAAQ,aAAa,QAAQ,uBAAwB;EAAW,QAAQ;CAAE;CAGrF,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}

package/esm/supervisor/entries.mjs

@@ -178,8 +178,8 @@ function isDispatchableUnit(value) {
 	return typeof candidate.name === "string" && typeof candidate.execute === "function";
 }
 function detectType(unit) {
-	if (typeof unit.signature === "string") return "workflow";
-	return "agent";
+	if (typeof unit.stream === "function") return "agent";
+	return "workflow";
 }
 function resolveAgentLikeDescription(intent, entryForm, unit, supervisorName) {
 	const entryOverride = entryForm?.description;