@chatman-media/kb 1.3.0

package/dist/tools.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/**
+ * A tool the LLM can call during `answerWithRag`.
+ *
+ * Pass one or more tools via `AnswerInput.tools`. When the model decides to
+ * use a tool, the library executes `execute()` automatically and feeds the
+ * result back to the model for a final answer (single-cycle — one tool call
+ * per request).
+ *
+ * @example
+ * ```ts
+ * import { answerWithRag, type RagTool } from "@chatman-media/kb";
+ * import { z } from "zod";
+ *
+ * const slotsTool: RagTool = {
+ *   name: "getAvailableSlots",
+ *   description: "Returns available booking slots for a given date (YYYY-MM-DD).",
+ *   parameters: z.object({ date: z.string() }),
+ *   execute: async ({ date }) => fetchSlotsFromCRM(date),
+ * };
+ *
+ * const result = await answerWithRag({ question, kb, chat, embedder, tools: [slotsTool] });
+ * // result.telemetry.toolCall — name + result if a tool was invoked
+ * ```
+ */
+export interface RagTool<TParams extends z.ZodTypeAny = z.ZodTypeAny> {
+    name: string;
+    description: string;
+    /** Zod schema for the tool's input parameters. Used to build the JSON Schema sent to the model. */
+    parameters: TParams;
+    execute: (args: z.infer<TParams>) => Promise<unknown>;
+}
+export type AnyRagTool = RagTool<any>;
+/** Converts a `RagTool` to the OpenAI function-calling format. */
+export declare function toolToOpenAIFunction(tool: AnyRagTool): OpenAIToolDefinition;
+export interface OpenAIToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface ToolCallRequest {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolCallResult {
+    /** Tool call id returned by the model. */
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface CompleteWithToolsResult {
+    /** Model text when no tool was called. */
+    content: string | null;
+    /** Parsed tool calls when the model chose to call a tool. */
+    toolCalls: ToolCallResult[];
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,OAAO,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAGD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;AAEtC,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,oBAAoB,CAS3E;AAID,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6DAA6D;IAC7D,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B"}

package/dist/topic-classifier.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns a single topic slug when exactly ONE topic pattern matches, or
+ * `null` when zero or multiple match. Multi-match is treated as ambiguous —
+ * forcing one topic would silently drop docs from the other.
+ */
+export declare function classifyTopic(question: string): string | null;
+/** Exposed for tests + admin debugging — lets callers see ALL matches. */
+export declare function classifyTopicAll(question: string): string[];
+/** All defined topic slugs. Useful for ingest CLI validation and admin UI. */
+export declare const KNOWN_TOPICS: readonly string[];
+//# sourceMappingURL=topic-classifier.d.ts.map

package/dist/topic-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic-classifier.d.ts","sourceRoot":"","sources":["../src/topic-classifier.ts"],"names":[],"mappings":"AAqFA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7D;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAO3D;AAED,8EAA8E;AAC9E,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAuC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Storage interfaces for the RAG engine.
+ *
+ * The package defines these interfaces; consumers provide implementations.
+ * The reference implementation (`PgKbStore`) ships with the lead-engine platform
+ * project and wraps the PostgreSQL + pgvector repos.
+ */
+export interface KbSearchHit {
+    chunk_id: number;
+    /** Cosine distance (vector search) or negated BM25 rank (FTS). Lower = closer. */
+    distance: number;
+    text: string;
+    document_id: number;
+    source: string;
+    title: string;
+}
+/**
+ * Minimal contract the RAG engine needs from whatever storage backend you
+ * plug in. Split into two logical groups:
+ *
+ * - **Search** — called by `answerWithRag` at query time (read-only).
+ * - **Ingest** — called by `ingestFile` / `ingestText` / `ingestDirectory`
+ *   when indexing documents (read+write).
+ */
+export interface IKbStore {
+    /**
+     * Pure vector search (cosine distance via pgvector or equivalent).
+     * Returns up to `k` hits, optionally filtered by `topic`.
+     */
+    search(embedding: number[], k: number, topic?: string | null): Promise<KbSearchHit[]>;
+    /**
+     * Hybrid retrieval: fuse vector + BM25 results via Reciprocal Rank Fusion.
+     * Falls back to vector-only when the FTS index returns nothing.
+     */
+    hybridSearch(input: {
+        embedding: number[];
+        query: string;
+        k?: number;
+        topic?: string | null;
+    }): Promise<KbSearchHit[]>;
+    /**
+     * Books-priority search: tries the "books" topic first, falls back to
+     * global search when no books-tagged chunks match. Used when `booksPriority`
+     * is set on `AnswerInput`.
+     */
+    prioritySearch(input: {
+        embedding: number[];
+        query: string;
+        k?: number;
+        vectorOnly?: boolean;
+    }): Promise<KbSearchHit[]>;
+    /** Look up an existing document by its source URI. */
+    getDocumentBySource(source: string): Promise<{
+        id: number;
+        content_hash: string;
+    } | null>;
+    /** Count indexed chunks for a document (used for dedup short-circuit). */
+    countChunksForDocument(documentId: number): Promise<number>;
+    /** Delete a document and all its chunks (called before re-indexing). */
+    deleteDocument(id: number): Promise<boolean>;
+    /** Upsert a document record; returns the canonical row id. */
+    upsertDocument(input: {
+        source: string;
+        title: string;
+        contentHash: string;
+        topic?: string | null;
+    }): Promise<{
+        id: number;
+    }>;
+    /** Insert one chunk with its embedding vector. */
+    insertChunkWithEmbedding(input: {
+        documentId: number;
+        chunkIndex: number;
+        text: string;
+        tokenCount: number;
+        embedding: number[];
+    }): Promise<void>;
+}
+/** Optional write-only interface for logging unanswered questions. */
+export interface IKbSuggestionsStore {
+    log(question: string, conversationId: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IAGvB;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEtF;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE;QAClB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,CAAC,CAAC,EAAE,MAAM,CAAC;QACX,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE3B;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE;QACpB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,CAAC,CAAC,EAAE,MAAM,CAAC;QACX,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAI3B,sDAAsD;IACtD,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAE1F,0EAA0E;IAC1E,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5D,wEAAwE;IACxE,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7C,8DAA8D;IAC9D,cAAc,CAAC,KAAK,EAAE;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE5B,kDAAkD;IAClD,wBAAwB,CAAC,KAAK,EAAE;QAC9B,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D"}

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+import type { KbSearchHit } from "./types.ts";
+/**
+ * Reciprocal Rank Fusion — fuses two ranked result lists into one.
+ *
+ * Standard formula: score(d) = Σ 1/(k + rank(d))
+ * where k=60 is the smoothing constant (Cormack et al., 2009).
+ *
+ * Returns hits sorted by descending fused score. The `distance` field is
+ * remapped to `1 - score` so callers get a consistent "lower = better"
+ * interpretation regardless of whether the underlying search was vector or BM25.
+ *
+ * @param vectorHits  Results from vector (cosine) search, ranked by ascending distance.
+ * @param bm25Hits    Results from BM25 search, ranked by descending BM25 score.
+ * @param k           Number of top results to return.
+ * @param rrfK        RRF smoothing constant (default 60).
+ */
+export declare function reciprocalRankFusion(vectorHits: KbSearchHit[], bm25Hits: KbSearchHit[], k: number, rrfK?: number): KbSearchHit[];
+export declare function sanitizeFtsQuery(raw: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,WAAW,EAAE,EACzB,QAAQ,EAAE,WAAW,EAAE,EACvB,CAAC,EAAE,MAAM,EACT,IAAI,SAAK,GACR,WAAW,EAAE,CA0Bf;AAuBD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASpD"}

package/dist/vision.d.ts

@@ -0,0 +1,72 @@
+import type { FetchLike } from "@chatman-media/llm-router";
+/** AI provider for the vision model — both expose an OpenAI-compatible API. */
+export type VisionProvider = "openrouter" | "openai";
+/**
+ * Photo classification via a vision-capable model.
+ *
+ * The recruiting funnel collects two distinct kinds of photo from a
+ * candidate — full-body shots and a photo of her international passport
+ * (загранпаспорт) — plus assorted regular photos. The bot needs to tell
+ * them apart so the lead intake counters are accurate (see
+ * `src/leads/intake.ts`), instead of the old "total photos >= 7" guess.
+ *
+ * Works with either OpenRouter or OpenAI (set via `provider`). Both expose
+ * an OpenAI-compatible `/chat/completions` endpoint; vision input is the
+ * standard `image_url` content part with a data URL. The OpenRouter-only
+ * `reasoning` request param is sent only for that provider.
+ */
+export declare const PHOTO_CLASSES: readonly ["passport", "full_body", "portrait", "other"];
+export type PhotoClass = (typeof PHOTO_CLASSES)[number];
+export interface ClassifyPhotoOptions {
+    /** Raw image bytes (as downloaded from Telegram). */
+    bytes: ArrayBuffer;
+    /** MIME type, e.g. "image/jpeg". Falls back to image/jpeg when empty. */
+    mimeType?: string;
+    /** Vision-capable model id (OpenRouter slug or OpenAI model name). */
+    model: string;
+    apiKey: string;
+    /** AI provider. Default: "openrouter". */
+    provider?: VisionProvider;
+    /** Default: https://openrouter.ai/api/v1 */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default 30_000. */
+    timeoutMs?: number;
+    fetch?: FetchLike;
+}
+/** Maps a free-form model reply onto a `PhotoClass`, defaulting to `other`. */
+export declare function parsePhotoClass(raw: string): PhotoClass;
+/**
+ * Downloads nothing — caller passes raw bytes. Returns the classified
+ * category. Throws on transport / API errors so the caller can decide
+ * to leave the photo unclassified and retry on the next turn.
+ */
+export declare function classifyPhoto(opts: ClassifyPhotoOptions): Promise<PhotoClass>;
+/**
+ * Identity fields read off a candidate's international passport
+ * (загранпаспорт). Latin spelling — the form is what the visa anketa
+ * needs and what the MRZ carries unambiguously. Every field optional:
+ * a blurry scan may yield only some, or none.
+ */
+export interface PassportIdentity {
+    /** Surname, Latin, as printed in the passport / MRZ. */
+    family_name?: string;
+    /** Given name(s), Latin. */
+    given_name?: string;
+    passport_number?: string;
+    /** Expiration date, formatted dd.mm.yyyy to match the intake field. */
+    passport_expiry?: string;
+}
+/**
+ * Strips markdown / think-tags and parses the model's passport JSON.
+ * Validates value types and length. Exported for unit tests.
+ */
+export declare function parsePassportJson(raw: string): PassportIdentity;
+/**
+ * Reads identity fields off a passport photo via the same vision model
+ * used for classification. Caller should only invoke this for photos
+ * already classified as `passport`. Throws on transport / API errors so
+ * the caller can leave the photo for retry; a successful-but-empty model
+ * reply returns `{}` (a valid "nothing readable" result).
+ */
+export declare function extractPassportIdentity(opts: ClassifyPhotoOptions): Promise<PassportIdentity>;
+//# sourceMappingURL=vision.d.ts.map

package/dist/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../src/vision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,CAAC;AAErD;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,aAAa,yDAA0D,CAAC;AACrF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAcxD,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,KAAK,EAAE,WAAW,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAUD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAIvD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CA4DnF;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAqBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAwB/D;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAwD3B"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@chatman-media/kb",
+  "version": "1.3.0",
+  "description": "Tenant-scoped Knowledge Base: hybrid retrieval (pgvector + BM25), ingest, answer pipeline, persona/skill composition. LLM I/O живёт в @chatman-media/llm-router.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --format esm && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check ./src ./test",
+    "format": "biome format --write ./src ./test",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "keywords": [
+    "rag",
+    "retrieval-augmented-generation",
+    "pgvector",
+    "bm25",
+    "hybrid-search",
+    "llm",
+    "chatbot",
+    "sales-bot",
+    "telegram-bot",
+    "ollama",
+    "openai",
+    "openrouter"
+  ],
+  "author": "Alexander Kireev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatman-media/lead-engine.git",
+    "directory": "packages/kb"
+  },
+  "homepage": "https://github.com/chatman-media/lead-engine/tree/main/packages/kb#readme",
+  "bugs": {
+    "url": "https://github.com/chatman-media/lead-engine/issues"
+  },
+  "dependencies": {
+    "@chatman-media/llm-router": "1.0.0",
+    "unpdf": "^1.6.2",
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.8",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/bun": "latest",
+    "semantic-release": "^25.0.3",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/ab-router.ts

@@ -0,0 +1,118 @@
+import type { AnswerTelemetry } from "./answer-types.ts";
+import type { Style } from "./styles.ts";
+
+export interface ABVariant {
+  /** Weight relative to other variants. Default 1. */
+  weight?: number;
+  style: Style;
+}
+
+export interface ABRouterOptions {
+  variants: ABVariant[];
+  /**
+   * Called after every answer with the assigned variant slug and telemetry.
+   * Use this to log impressions, latency, and conversion signals to your DB.
+   */
+  onResult?: (variantSlug: string, telemetry: AnswerTelemetry) => void;
+  /**
+   * Salt added to the userId before hashing. Change it to re-randomise
+   * assignments without changing user ids.
+   */
+  salt?: string;
+}
+
+/**
+ * Deterministic A/B style router.
+ *
+ * Assigns each user to a variant by hashing `userId + salt` — the same user
+ * always gets the same variant within an experiment. Weights are respected:
+ * a variant with weight 2 gets twice as many users as one with weight 1.
+ *
+ * Pass the returned `style` directly to `answerWithRag`. Log results via
+ * `onResult` to measure conversion by variant.
+ *
+ * @example
+ * ```ts
+ * import { ABRouter, answerWithRag } from "@chatman-media/kb";
+ *
+ * const router = new ABRouter({
+ *   variants: [
+ *     { style: nepqStyle,         weight: 1 },
+ *     { style: straightLineStyle, weight: 1 },
+ *   ],
+ *   onResult: (slug, telemetry) => db.logImpression(slug, telemetry),
+ * });
+ *
+ * const { style, onTelemetry } = router.assign(userId);
+ * const result = await answerWithRag({ question, kb, chat, embedder, style, onTelemetry });
+ * ```
+ */
+export class ABRouter {
+  private readonly variants: Required<ABVariant>[];
+  private readonly totalWeight: number;
+  private readonly onResult: ABRouterOptions["onResult"];
+  private readonly salt: string;
+
+  constructor(opts: ABRouterOptions) {
+    if (opts.variants.length === 0) throw new Error("ABRouter: at least one variant required");
+    this.variants = opts.variants.map((v) => ({ weight: v.weight ?? 1, style: v.style }));
+    this.totalWeight = this.variants.reduce((s, v) => s + v.weight, 0);
+    this.onResult = opts.onResult;
+    this.salt = opts.salt ?? "";
+  }
+
+  /**
+   * Assign a user to a variant. Returns the `style` to pass to `answerWithRag`
+   * and an `onTelemetry` callback that forwards results to `opts.onResult`.
+   */
+  assign(userId: string): {
+    style: Style;
+    variantSlug: string;
+    onTelemetry: (t: AnswerTelemetry) => void;
+  } {
+    const style = this.pickVariant(userId);
+    const variantSlug = style.slug;
+    const onResult = this.onResult;
+
+    return {
+      style,
+      variantSlug,
+      onTelemetry: (telemetry: AnswerTelemetry) => {
+        onResult?.(variantSlug, telemetry);
+      },
+    };
+  }
+
+  /** Distribution map — slug → fraction of users assigned. */
+  get distribution(): Record<string, number> {
+    const out: Record<string, number> = {};
+    for (const v of this.variants) {
+      out[v.style.slug] = v.weight / this.totalWeight;
+    }
+    return out;
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private pickVariant(userId: string): Style {
+    const hash = simpleHash(userId + this.salt);
+    const bucket = ((hash % this.totalWeight) + this.totalWeight) % this.totalWeight;
+    let cumulative = 0;
+    for (const v of this.variants) {
+      cumulative += v.weight;
+      if (bucket < cumulative) return v.style;
+    }
+    // Fallback — should never be reached
+    return (this.variants[this.variants.length - 1] as Required<ABVariant>).style;
+  }
+}
+
+/** Fast non-cryptographic integer hash (FNV-1a 32-bit). */
+function simpleHash(s: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = (h * 16777619) >>> 0;
+  }
+  return h;
+}

package/src/answer-types.ts

@@ -0,0 +1,191 @@
+import type { z } from "zod";
+import type { ChatClient, ChatMessage } from "@chatman-media/llm-router";
+import type { EmbeddingClient } from "@chatman-media/llm-router";
+import type { DirectorHookForPrompt, FunnelStage, SkillForPrompt, Style } from "./styles.ts";
+import type { Reranker } from "./reranker.ts";
+import type { AnyRagTool } from "./tools.ts";
+import type { IKbStore, KbSearchHit } from "./types.ts";
+
+export const NO_CONTEXT_MARKER = "__NO_CONTEXT__";
+
+export interface Persona {
+  name: string;
+  role: "human" | "assistant";
+  company?: string;
+  /**
+   * Fixed personal facts about the persona — bypasses RAG for direct personal
+   * questions and injects into the system prompt as inviolable grounding.
+   * Known keys: "city", "age", "status", "experience", "phone".
+   */
+  facts?: Record<string, string>;
+}
+
+export interface AnswerInput {
+  question: string;
+  kb: IKbStore;
+  embedder: EmbeddingClient;
+  chat: ChatClient;
+  history?: ChatMessage[];
+  topK?: number;
+  maxDistance?: number;
+  persona?: Persona;
+  style?: Style;
+  stage?: FunnelStage;
+  includeFewShot?: boolean;
+  numPredict?: number;
+  userFacts?: Record<string, string>;
+  rewriteQueryBeforeRetrieval?: boolean;
+  reflect?: boolean;
+  hybridSearch?: boolean;
+  conversationSummary?: string;
+  topicRouting?: boolean;
+  vacanciesBlock?: string;
+  vacancyGuard?: boolean;
+  skills?: readonly SkillForPrompt[];
+  /**
+   * Tenant-specific director hooks to inject into the system prompt.
+   * Loaded from `director_hooks` table filtered by `is_active = true`.
+   * Always injected (not stage-filtered) — the LLM decides when to apply.
+   */
+  directorHooks?: readonly DirectorHookForPrompt[];
+  booksPriority?: boolean;
+  /**
+   * Support mode — set when the lead is past the sales stage and waiting on a
+   * downstream process (`docs` = collecting their documents, `submitted` =
+   * filed). When set AND a `style` is active, the composed system prompt drops
+   * the sales framework / hooks / skills / few-shot / funnel-stage guidance and
+   * uses a calm FAQ-support block instead — answering questions without selling.
+   */
+  supportPhase?: "docs" | "submitted";
+  /**
+   * Called after every `answerWithRag` or `answerWithRagStream` call with the
+   * final telemetry. Useful for logging, metrics, or A/B experiment recording
+   * without having to unwrap the return value.
+   */
+  onTelemetry?: (telemetry: AnswerTelemetry) => void;
+  /**
+   * Optional tools the LLM can call during answer generation (single-cycle).
+   * When the model decides to call a tool, `execute()` is called automatically
+   * and the result is fed back for a final answer.
+   * Requires `chat` to implement `completeWithTools` (e.g. `OpenAIChatClient`),
+   * otherwise falls back to prompt-based tool injection.
+   */
+  tools?: AnyRagTool[];
+  /**
+   * Maximum number of agentic tool-calling cycles. Each cycle is one LLM call
+   * that may request tools, followed by execution of those tools. When the
+   * limit is reached, a final answer is forced WITHOUT tools. Only relevant
+   * when `tools` is set. Default: 4 (caps at 5 LLM calls including the final
+   * answer — note the latency and cost of a long tool chain).
+   */
+  maxToolCycles?: number;
+  /**
+   * Enable Maximal Marginal Relevance re-ranking after retrieval.
+   * Selects a diverse set of chunks so that repeated near-duplicate passages
+   * do not crowd out different sub-topics. Default: false.
+   */
+  mmr?: boolean;
+  /**
+   * λ (lambda) for MMR: trade-off between relevance and diversity.
+   * 1.0 = pure relevance, 0.0 = pure diversity. Default: 0.6.
+   * Only has effect when `mmr` is true.
+   */
+  mmrLambda?: number;
+  /**
+   * Trim retrieved hits that exceed a cosine-distance threshold before passing
+   * them to the LLM. Reduces hallucinations caused by weak/unrelated matches.
+   * Default: false (no trimming).
+   */
+  autoTrimDistance?: boolean;
+  /**
+   * Distance threshold used when `autoTrimDistance` is true.
+   * Cosine distance in [0, 2]; typical useful range is ≤ 0.4.
+   * Default: 0.45.
+   */
+  autoTrimThreshold?: number;
+  /**
+   * Enable multi-query expansion: generate `multiQueryCount` rephrased variants
+   * of the question with a fast LLM call, search with each in parallel, and
+   * merge all result lists via Reciprocal Rank Fusion (RRF). Improves recall
+   * for synonym gaps and differently-phrased concepts.
+   * Default: false.
+   */
+  multiQuery?: boolean;
+  /**
+   * Number of ADDITIONAL query variants to generate (not counting the original).
+   * Only has effect when `multiQuery` is true. Default: 2.
+   */
+  multiQueryCount?: number;
+  /**
+   * Optional cross-encoder reranker applied after vector/hybrid retrieval.
+   * Retrieves `topK * 3` candidates, passes them to the reranker, then keeps
+   * the top `topK`. Use `JinaReranker` or `CohereReranker` from this package.
+   *
+   * @example
+   * ```ts
+   * import { JinaReranker } from "@chatman-media/kb";
+   * await answerWithRag({ ..., reranker: new JinaReranker({ apiKey: process.env.JINA_API_KEY! }) });
+   * ```
+   */
+  reranker?: Reranker;
+  /**
+   * When provided, the LLM is instructed to return a JSON object matching this
+   * Zod schema. The parsed and validated value is available as `result.output`.
+   * Uses OpenAI's native `response_format` when available; falls back to prompt
+   * injection for other providers (Ollama, OpenRouter, etc.).
+   *
+   * @example
+   * ```ts
+   * const result = await answerWithRag({
+   *   question: "Classify this lead",
+   *   kb, chat, embedder,
+   *   outputSchema: z.object({
+   *     intent: z.enum(["buy", "info", "not_interested"]),
+   *     budget: z.number().optional(),
+   *     nextAction: z.string(),
+   *   }),
+   * });
+   * console.log(result.output.intent); // "buy" | "info" | "not_interested"
+   * ```
+   */
+  outputSchema?: z.ZodTypeAny;
+}
+
+export interface AnswerTelemetry {
+  path: "smalltalk" | "persona_fact" | "no_context" | "ungrounded" | "ok" | "cache_hit";
+  total_ms?: number;
+  retrieval_ms?: number;
+  generation_ms?: number;
+  top_distances?: number[];
+  hybrid?: boolean;
+  topic?: string | null;
+  original_query?: string;
+  rewritten_query?: string;
+  factCheck?: { grounded: boolean; vacancyOk: boolean; reason?: string };
+  /**
+   * @deprecated Use `toolCalls`. Retained for backward compatibility — set to
+   * the first tool call when any tools ran during answer generation.
+   */
+  toolCall?: { name: string; result: unknown };
+  /**
+   * Every tool call executed across all agentic cycles, in order. Note that
+   * `args` may contain user-derived input — treat as sensitive if your tools
+   * receive PII.
+   */
+  toolCalls?: Array<{
+    name: string;
+    args: Record<string, unknown>;
+    result: unknown;
+    error?: boolean;
+    cycle: number;
+  }>;
+}
+
+export interface AnswerResult<TOutput = unknown> {
+  text: string;
+  usedChunkIds: number[];
+  hits: KbSearchHit[];
+  telemetry: AnswerTelemetry;
+  /** Parsed and validated output when `outputSchema` was passed to `answerWithRag`. */
+  output?: TOutput;
+}