@chatman-media/kb 1.3.0

package/dist/ingest.d.ts

@@ -0,0 +1,49 @@
+import { type ChunkOptions } from "./chunk.ts";
+import type { EmbeddingClient } from "@chatman-media/llm-router";
+import type { IKbStore } from "./types.ts";
+export interface IngestDeps {
+    kb: IKbStore;
+    embedder: EmbeddingClient;
+    chunk?: Partial<ChunkOptions>;
+    topic?: string | null;
+    /** Overrides the default `file://<abs>` document source. Callers that
+     *  ingest from a throwaway temp path (e.g. an admin upload route) pass a
+     *  stable, content-addressed source here so re-uploads dedupe. */
+    source?: string;
+    /** Overrides the default `basename(abs)` document title — useful when the
+     *  on-disk filename is a temp name rather than something operator-facing. */
+    title?: string;
+}
+export interface IngestFileResult {
+    source: string;
+    documentId: number;
+    chunks: number;
+    created: boolean;
+}
+export declare function ingestFile(path: string, deps: IngestDeps): Promise<IngestFileResult>;
+/**
+ * Ingest a raw text document directly (no filesystem). Used by admin-UI
+ * paste path. Source is synthesised as `inline:<sha256[:12]>` so subsequent
+ * uploads of identical content dedupe via the `source` UNIQUE lookup.
+ */
+export declare function ingestText(input: {
+    title: string;
+    body: string;
+}, deps: IngestDeps): Promise<IngestFileResult>;
+export interface IngestDirectorySummary {
+    documents: number;
+    chunks: number;
+    skipped: number;
+}
+export declare function ingestDirectory(dir: string, deps: IngestDeps): Promise<IngestDirectorySummary>;
+/**
+ * Returns the immediate sub-directory name of `file` relative to `root`,
+ * or null when the file sits directly under `root`. Exported for unit tests.
+ */
+export declare function deriveTopicFromPath(file: string, root: string): string | null;
+/**
+ * Removes YAML frontmatter and HTML comments from Markdown — noise that
+ * pollutes embeddings. The visible body is preserved as-is.
+ */
+export declare function stripNonContent(raw: string): string;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../src/ingest.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,QAAQ,CAAC;IACb,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;sEAEkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+C1F;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,gBAAgB,CAAC,CA4C3B;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,sBAAsB,CAAC,CAejC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK7E;AAaD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/dist/multi-query.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Multi-query expansion for RAG retrieval.
+ *
+ * Instead of searching with a single query, generate N semantically-equivalent
+ * rephrases in parallel using a fast LLM call, then search with each and merge
+ * the results via RRF (Reciprocal Rank Fusion). This covers synonym gaps and
+ * different formulations that a single embedding vector misses.
+ *
+ * Example — query "сколько стоит квартира в ЖК Марина":
+ *   → "цена апартаментов в Marina Gate"
+ *   → "стоимость юнитов Marina Dubai"
+ *
+ * Falls back gracefully to the original query on any LLM error.
+ */
+import type { ChatClient, ChatMessage } from "@chatman-media/llm-router";
+export interface ExpandQueriesInput {
+    question: string;
+    history?: ChatMessage[];
+    chat: ChatClient;
+    /** Number of ADDITIONAL variants to generate (not counting the original). Default: 2. */
+    count?: number;
+}
+/**
+ * Generate N alternative search queries for the given question.
+ * Always includes the original question as the first element.
+ * Returns `[question]` (single item) on any error.
+ */
+export declare function expandQueries(input: ExpandQueriesInput): Promise<string[]>;
+//# sourceMappingURL=multi-query.d.ts.map

package/dist/multi-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-query.d.ts","sourceRoot":"","sources":["../src/multi-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGzE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAuBD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0BhF"}

package/dist/parse-pdf.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extract plain text from a PDF file. Pages are joined with double newlines
+ * so paragraph boundaries survive. Throws on corrupt/encrypted files.
+ */
+export declare function parsePdf(filePath: string): Promise<string>;
+/**
+ * Extract plain text directly from a PDF buffer (Uint8Array). Use this when
+ * the PDF is already in memory (e.g. HTTP multipart upload) to avoid writing
+ * a temporary file.
+ *
+ * Throws on corrupt or encrypted PDFs.
+ */
+export declare function parsePdfBuffer(buffer: Uint8Array): Promise<string>;
+//# sourceMappingURL=parse-pdf.d.ts.map

package/dist/parse-pdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-pdf.d.ts","sourceRoot":"","sources":["../src/parse-pdf.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxE"}

package/dist/persona-shortcuts.d.ts

@@ -0,0 +1,51 @@
+import type { Persona } from "./answer-types.ts";
+/**
+ * True when the message is asking about the persona's nature (bot vs human
+ * vs AI). Detected separately from the name/identity smalltalk because the
+ * answer depends on `persona.role`, not just on `persona.name`. Returns a
+ * single deterministic reply via `botPresenceReply` — bypassing RAG.
+ *
+ * Why this guard exists: the RAG system prompt contains an example reply
+ * ("конечно нет, я ${name}, чем помочь?") meant for "ты бот?". Without this
+ * shortcut, the LLM parrots that template literally — including for
+ * "ты человек?", inverting the answer ("конечно нет" = "I'm not human").
+ */
+export declare function isBotPresenceQuestion(question: string): boolean;
+/**
+ * Deterministic reply for `isBotPresenceQuestion`. For role=human the bot
+ * always asserts being human regardless of the question form ("ты бот?" /
+ * "ты человек?" both → same human reply). For role=assistant it admits
+ * being an AI helper.
+ */
+export declare function botPresenceReply(persona: Persona): string;
+/**
+ * True when the message is only smalltalk about identity (name / who are you).
+ * Catches the common bare forms candidates actually type — "как зовут?",
+ * "имя?", "представься" — not just the textbook "как тебя зовут".
+ *
+ * Returns false when the message also has any work/offer intent — even
+ * "как тебя зовут есть работа в китае?" should land in RAG, not the
+ * smalltalk shortcut, because the candidate is asking about a job.
+ */
+export declare function isPersonaSmalltalkQuestion(question: string): boolean;
+/**
+ * Returns a fact key ("city" | "age" | "status" | "experience") when the
+ * question is ONLY about that personal attribute of the persona, or `null`
+ * when it also contains job/offer intent (route to RAG in that case).
+ *
+ * Mirrors the `isPersonaSmalltalkQuestion` guard: same job-intent block list,
+ * same design — pure function, no side effects, safe to call unconditionally.
+ */
+export declare function isPersonalFactQuestion(question: string): string | null;
+/**
+ * Builds a short deterministic reply from `persona.facts[key]`.
+ * Returns `null` when the fact is not configured (caller falls through to RAG).
+ *
+ * "city" / "age" values are wrapped in natural templates; "status" /
+ * "experience" values are returned verbatim — the operator writes the full
+ * natural reply for these (e.g. "Не замужем, работа всё время занимает").
+ */
+export declare function personaFactReply(persona: Persona, key: string): string | null;
+/** Short reply derived from persona - no KB required. */
+export declare function personaSmalltalkReply(persona: Persona): string;
+//# sourceMappingURL=persona-shortcuts.d.ts.map

package/dist/persona-shortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona-shortcuts.d.ts","sourceRoot":"","sources":["../src/persona-shortcuts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAwB/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAQzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CA+CpE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA2DtE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB7E;AAgCD,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAe9D"}

package/dist/prompt.d.ts

@@ -0,0 +1,9 @@
+import type { ComposeOptions, FunnelStage, Style } from "./styles.ts";
+/**
+ * Builds the system prompt for one turn of conversation in the given style
+ * and stage. Up to 8 sections: persona, voice, framework, hooks, stage,
+ * KB-grounding reminder (conditional), guardrails, few-shot (conditional),
+ * and KB context (conditional).
+ */
+export declare function composeSystemPrompt(style: Style, stage: FunnelStage, preFetchedKbContext?: string | null, options?: ComposeOptions): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAQ,KAAK,EAAE,MAAM,aAAa,CAAC;AA6C5E;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,WAAW,EAClB,mBAAmB,GAAE,MAAM,GAAG,IAAW,EACzC,OAAO,GAAE,cAAmB,GAC3B,MAAM,CAqIR"}

package/dist/reflect.d.ts

@@ -0,0 +1,29 @@
+import type { ChatClient } from "@chatman-media/llm-router";
+/**
+ * Verifies that all factual claims in `answer` are grounded in `context`
+ * (the KB chunks retrieved for this turn). Used as a post-generation
+ * hallucination guard — if the LLM invented a number/city/condition, this
+ * catches it before the message reaches the candidate.
+ *
+ * Returns `{ grounded: true }` when the answer is fully supported by the
+ * context, or `{ grounded: false, reason }` when it isn't. The webhook
+ * caller is responsible for deciding what to do with `grounded:false` —
+ * typically: drop the reply (silent → mode stays "ai") or escalate.
+ */
+export interface ReflectInput {
+    question: string;
+    answer: string;
+    /** The same KB CONTEXT that was passed to the generator. */
+    context: string;
+    chat: ChatClient;
+}
+export interface ReflectResult {
+    grounded: boolean;
+    reason?: string;
+}
+export declare function verifyAnswer(input: ReflectInput): Promise<ReflectResult>;
+/** Parses the verifier's JSON output. Defaults to `grounded:true` on parse
+ *  failure — false negatives are cheap (one wasted reply), but false positives
+ *  here would silently drop legitimate answers. Exported for unit tests. */
+export declare function parseReflection(raw: string): ReflectResult;
+//# sourceMappingURL=reflect.d.ts.map

package/dist/reflect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.d.ts","sourceRoot":"","sources":["../src/reflect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,2BAA2B,CAAC;AAGzE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmBD,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CA6B9E;AAED;;4EAE4E;AAC5E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAoB1D"}

package/dist/reranker.d.ts

@@ -0,0 +1,71 @@
+import type { KbSearchHit } from "./types.ts";
+/**
+ * Cross-encoder reranker interface. Called after initial retrieval (vector /
+ * hybrid) to re-score and re-order hits using a more expensive but accurate
+ * relevance model. Optional third stage in the retrieval pipeline.
+ */
+export interface Reranker {
+    rerank(query: string, hits: KbSearchHit[], topK?: number): Promise<KbSearchHit[]>;
+}
+export interface CohereRerankerOptions {
+    apiKey: string;
+    /** Default: "rerank-v3.5" */
+    model?: string;
+    /** Base URL. Default: "https://api.cohere.com/v2" */
+    baseUrl?: string;
+    /** Per-request timeout ms. Default: 30_000. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * Reranker backed by the Cohere Rerank API.
+ *
+ * @example
+ * ```ts
+ * import { CohereReranker } from "@chatman-media/kb";
+ *
+ * const reranker = new CohereReranker({ apiKey: process.env.COHERE_API_KEY! });
+ * const reranked = await reranker.rerank(question, hits, 5);
+ * ```
+ */
+export declare class CohereReranker implements Reranker {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: CohereRerankerOptions);
+    rerank(query: string, hits: KbSearchHit[], topK?: number): Promise<KbSearchHit[]>;
+}
+export interface JinaRerankerOptions {
+    apiKey: string;
+    /** Default: "jina-reranker-v2-base-multilingual" */
+    model?: string;
+    /** Base URL. Default: "https://api.jina.ai/v1" */
+    baseUrl?: string;
+    /** Per-request timeout ms. Default: 30_000. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * Reranker backed by the Jina Reranker API.
+ * The default model is multilingual — works well for Russian and Chinese KB.
+ *
+ * @example
+ * ```ts
+ * import { JinaReranker } from "@chatman-media/kb";
+ *
+ * const reranker = new JinaReranker({ apiKey: process.env.JINA_API_KEY! });
+ * const reranked = await reranker.rerank(question, hits, 5);
+ * ```
+ */
+export declare class JinaReranker implements Reranker {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: JinaRerankerOptions);
+    rerank(query: string, hits: KbSearchHit[], topK?: number): Promise<KbSearchHit[]>;
+}
+//# sourceMappingURL=reranker.d.ts.map

package/dist/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../src/reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CACnF;AAID,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAOD;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,EAAE,qBAAqB;IASjC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CA+BxF;AAID,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAOD;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,EAAE,mBAAmB;IAS/B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CA8BxF"}

package/dist/retrieval-utils.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Post-retrieval utilities for the RAG pipeline.
+ *
+ * Three independent transforms, applied in order:
+ *
+ * 0. **`rrfMerge`** — merge multiple hit-lists (from multi-query expansion) via
+ *    Reciprocal Rank Fusion. Deduplicates by chunk_id, boosts chunks that rank
+ *    high across multiple queries.
+ *
+ * 1. **`applyDynamicThreshold`** — trim hits that are "too far" from the query.
+ *    Prevents hallucination-inducing weak matches from polluting the context.
+ *
+ * 2. **`mmrDiversify`** — re-rank via Maximal Marginal Relevance so that the
+ *    final context window covers diverse sub-topics rather than repeating the
+ *    same dense cluster of near-duplicate chunks.
+ *
+ * All functions are pure (no I/O) and operate on the {@link KbSearchHit} array
+ * that comes back from `IKbStore.search` / `IKbStore.hybridSearch`.
+ */
+import type { KbSearchHit } from "./types.ts";
+export interface RrfMergeOpts {
+    /**
+     * RRF smoothing constant. Higher = more weight to lower-ranked items.
+     * Standard value: 60.
+     */
+    k?: number;
+    /**
+     * Maximum number of hits to return. Defaults to all unique hits.
+     */
+    topN?: number;
+}
+/**
+ * Reciprocal Rank Fusion — merge multiple retrieval result lists into one.
+ *
+ * Each hit's score is the sum of `1 / (k + rank)` across all lists where it
+ * appears (1-based rank). Hits that appear in multiple lists get boosted.
+ * Deduplication is by `chunk_id`.
+ *
+ * The output uses the distance convention (lower = better):
+ * `distance = 1 / (1 + rrf_score)` so values stay in (0, 1].
+ *
+ * @param hitLists  One list per query, each sorted best-first.
+ */
+export declare function rrfMerge(hitLists: KbSearchHit[][], opts?: RrfMergeOpts): KbSearchHit[];
+export interface DynamicThresholdOpts {
+    /**
+     * Drop hits whose `distance` exceeds this value.
+     * Cosine distance is in [0, 2]; typical "useful" range is ≤ 0.4.
+     * Default: 0.45.
+     */
+    threshold?: number;
+    /**
+     * Always keep at least this many hits even if they all exceed the threshold.
+     * Prevents the context from going completely empty.
+     * Default: 1.
+     */
+    minHits?: number;
+}
+/**
+ * Trim hits that exceed a distance threshold, keeping at least `minHits`.
+ *
+ * When the best match is already weak (high distance), the whole batch is
+ * likely unhelpful — cap it so the model isn't given noise.
+ */
+export declare function applyDynamicThreshold(hits: KbSearchHit[], opts?: DynamicThresholdOpts): KbSearchHit[];
+export interface MmrOpts {
+    /**
+     * Trade-off between relevance and diversity.
+     * - 1.0 → pure relevance (same as original ranking)
+     * - 0.0 → pure diversity (greedy maximum coverage)
+     * Default: 0.6.
+     */
+    lambda?: number;
+    /**
+     * Maximum number of hits to return after diversification.
+     * Defaults to the full input length.
+     */
+    topK?: number;
+}
+/**
+ * Maximal Marginal Relevance re-ranking.
+ *
+ * Iteratively selects the next chunk that maximises:
+ *   `score = λ * relevance - (1 - λ) * max_similarity_to_already_selected`
+ *
+ * Relevance is derived from the search distance (lower distance = higher
+ * relevance). Inter-chunk similarity is approximated with **Jaccard overlap on
+ * trigrams** — cheap, no extra embedder call required, and surprisingly
+ * effective at detecting paraphrase duplicates.
+ *
+ * @param hits  Sorted by relevance (best first), as returned by the store.
+ */
+export declare function mmrDiversify(hits: KbSearchHit[], opts?: MmrOpts): KbSearchHit[];
+//# sourceMappingURL=retrieval-utils.d.ts.map

package/dist/retrieval-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-utils.d.ts","sourceRoot":"","sources":["../src/retrieval-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,GAAE,YAAiB,GAAG,WAAW,EAAE,CA8B1F;AAID,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EAAE,EACnB,IAAI,GAAE,oBAAyB,GAC9B,WAAW,EAAE,CAMf;AAID,MAAM,WAAW,OAAO;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,IAAI,GAAE,OAAY,GAAG,WAAW,EAAE,CAwCnF"}

package/dist/retry.d.ts

@@ -0,0 +1,53 @@
+import { type ChatClient } from "@chatman-media/llm-router";
+import { type EmbeddingClient } from "@chatman-media/llm-router";
+export interface RetryOptions {
+    /**
+     * Maximum number of attempts (including the first). Default: 3.
+     */
+    maxAttempts?: number;
+    /**
+     * Initial backoff in ms before the second attempt. Doubles on each retry.
+     * Default: 500.
+     */
+    initialDelayMs?: number;
+    /**
+     * Cap on backoff delay in ms. Default: 30_000.
+     */
+    maxDelayMs?: number;
+    /**
+     * HTTP status codes that should trigger a retry.
+     * Default: [429, 500, 502, 503, 504].
+     */
+    retryOn?: number[];
+}
+/**
+ * Wraps any `ChatClient` with automatic retry + exponential backoff.
+ *
+ * Retries on transient HTTP errors (429, 5xx) with jittered exponential
+ * backoff. Non-retryable errors (4xx other than 429) propagate immediately.
+ *
+ * @example
+ * ```ts
+ * import { withRetryChatClient, OpenAIChatClient } from "@chatman-media/kb";
+ *
+ * const chat = withRetryChatClient(
+ *   new OpenAIChatClient({ apiKey, baseUrl, model }),
+ *   { maxAttempts: 4, initialDelayMs: 1000 },
+ * );
+ * ```
+ */
+export declare function withRetryChatClient(client: ChatClient, opts?: RetryOptions): ChatClient;
+/**
+ * Wraps any `EmbeddingClient` with automatic retry + exponential backoff.
+ *
+ * @example
+ * ```ts
+ * import { withRetryEmbeddingClient, OpenAIEmbeddingClient } from "@chatman-media/kb";
+ *
+ * const embedder = withRetryEmbeddingClient(
+ *   new OpenAIEmbeddingClient({ apiKey, baseUrl, model, dim: 1536 }),
+ * );
+ * ```
+ */
+export declare function withRetryEmbeddingClient(client: EmbeddingClient, opts?: RetryOptions): EmbeddingClient;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,UAAU,EAGhB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEpF,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAwCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,YAAiB,GAAG,UAAU,CA4B3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE,YAAiB,GACtB,eAAe,CAUjB"}

package/dist/rewrite-query.d.ts

@@ -0,0 +1,30 @@
+import type { ChatClient, ChatMessage } from "@chatman-media/llm-router";
+/**
+ * Rewrites a user question into a search-friendly query using recent
+ * conversation history. Resolves pronouns ("это", "там", "то"), expands
+ * elliptical follow-ups ("а сколько платят?" → "сколько платят моделям в
+ * Дубае"), and folds in named entities from prior turns.
+ *
+ * Why this matters: vector search on the raw user message misses precision
+ * on follow-ups because embeddings of "а в дубае?" sit nowhere near the
+ * actual KB chunks about Dubai contracts. Rewriting bridges that gap.
+ */
+export interface RewriteQueryInput {
+    question: string;
+    /** Recent dialog (oldest first), excluding the current question. */
+    history?: ChatMessage[];
+    chat: ChatClient;
+    /** Cap output length to avoid the model writing essays. Default 200 chars. */
+    maxLength?: number;
+}
+/**
+ * Heuristic: skip rewriting when the question is already self-contained.
+ * Saves an LLM call (and thus latency + $) on the majority of inbound
+ * messages which are full standalone questions, not follow-ups.
+ */
+export declare function questionNeedsRewrite(question: string, history?: ChatMessage[]): boolean;
+export declare function rewriteQuery(input: RewriteQueryInput): Promise<string>;
+/** Strips think-tags, "ответ:" prefixes, markdown, line breaks. Falls back
+ *  to original on empty/garbage output. Exported for unit tests. */
+export declare function sanitizeRewritten(raw: string, fallback: string, maxLength: number): string;
+//# sourceMappingURL=rewrite-query.d.ts.map

package/dist/rewrite-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite-query.d.ts","sourceRoot":"","sources":["../src/rewrite-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGzE;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAwBvF;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgC5E;AAED;oEACoE;AACpE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAY1F"}

package/dist/sanitize.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Strip `<think>…</think>` reasoning blocks some chat models emit despite
+ * system instructions (qwen3, deepseek-r1 style). Both well-formed
+ * paired and an unclosed leading block are handled.
+ */
+export declare function stripThinkBlocks(raw: string): string;
+/** Strip markdown code fences (` ``` ` and ` ```json `). Useful when an LLM
+ *  wraps its JSON answer in a fenced block despite "only JSON" instructions. */
+export declare function stripCodeFences(raw: string): string;
+/**
+ * Strip artifacts some chat models emit despite system instructions:
+ * - `<think>…</think>` reasoning blocks (qwen3, deepseek-r1 style).
+ * - leading "Answer:" / "Ответ:" / "Согласно контексту" prefixes.
+ * - surrounding whitespace.
+ * - "AI tells" — em-/en-dashes, unicode ellipsis, "Конечно!" lead-ins
+ *   (see `text-style-rules.ts` for the full list).
+ *
+ * Exported for unit tests.
+ */
+export declare function sanitizeLlmOutput(raw: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;gFACgF;AAChF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/semantic-cache.d.ts

@@ -0,0 +1,70 @@
+import type { AnswerResult } from "./answer-types.ts";
+import type { EmbeddingClient } from "@chatman-media/llm-router";
+export interface SemanticCacheOptions {
+    /**
+     * Cosine similarity threshold for a cache hit (0–1). Higher = stricter.
+     * Default: 0.92 — catches paraphrases and minor reformulations.
+     */
+    threshold?: number;
+    /**
+     * Maximum number of entries to keep in memory. Oldest entries are evicted
+     * when the limit is reached. Default: 500.
+     */
+    maxEntries?: number;
+    /**
+     * TTL in milliseconds. Entries older than this are ignored. Default: 1 hour.
+     * Set to `Infinity` to disable expiry.
+     */
+    ttlMs?: number;
+}
+/**
+ * In-memory semantic cache for `answerWithRag` results.
+ *
+ * Stores (question embedding → AnswerResult) pairs. On lookup, computes
+ * cosine similarity between the incoming question embedding and all cached
+ * embeddings, returning the best match above `threshold`.
+ *
+ * Use `SemanticCache.wrap()` to get a drop-in cached version of any async
+ * function that accepts an `EmbeddingClient` and a question string.
+ *
+ * @example
+ * ```ts
+ * import { SemanticCache, answerWithRag } from "@chatman-media/kb";
+ *
+ * const cache = new SemanticCache(embedder, { threshold: 0.93, ttlMs: 30 * 60_000 });
+ *
+ * const result = await cache.getOrSet(
+ *   input.question,
+ *   () => answerWithRag(input),
+ * );
+ * ```
+ */
+export declare class SemanticCache {
+    private readonly embedder;
+    private readonly threshold;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private entries;
+    /** Total cache hits since creation. */
+    hits: number;
+    /** Total cache misses since creation. */
+    misses: number;
+    constructor(embedder: EmbeddingClient, opts?: SemanticCacheOptions);
+    /**
+     * Look up `question` in the cache. If a similar question was cached and is
+     * still fresh, returns the cached `AnswerResult` with `telemetry.path`
+     * overridden to `"cache_hit"`. Otherwise calls `fn()`, stores the result,
+     * and returns it.
+     */
+    getOrSet(question: string, fn: () => Promise<AnswerResult>): Promise<AnswerResult>;
+    /** Manually insert a question→result pair (e.g. from a warm-up script). */
+    prime(question: string, result: AnswerResult): Promise<void>;
+    /** Remove all entries. */
+    clear(): void;
+    /** Number of live (non-expired) entries. */
+    get size(): number;
+    private findBestMatch;
+    private store;
+    private evictExpired;
+}
+//# sourceMappingURL=semantic-cache.d.ts.map

package/dist/semantic-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-cache.d.ts","sourceRoot":"","sources":["../src/semantic-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,OAAO,CAAoB;IAEnC,uCAAuC;IACvC,IAAI,SAAK;IACT,yCAAyC;IACzC,MAAM,SAAK;gBAEC,QAAQ,EAAE,eAAe,EAAE,IAAI,GAAE,oBAAyB;IAOtE;;;;;OAKG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;IAqBxF,2EAA2E;IACrE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlE,0BAA0B;IAC1B,KAAK,IAAI,IAAI;IAIb,4CAA4C;IAC5C,IAAI,IAAI,IAAI,MAAM,CAGjB;IAID,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,YAAY;CAKrB"}