@chatman-media/kb 1.3.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,169 @@
+# @chatman-media/kb
+
+[![npm version](https://img.shields.io/npm/v/@chatman-media/kb?logo=npm&color=22c55e)](https://www.npmjs.com/package/@chatman-media/kb)
+[![CI](https://github.com/chatman-media/lead-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/chatman-media/lead-engine/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-compatible-fbf0df?logo=bun&logoColor=black)](https://bun.sh/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Tenant-scoped Knowledge Base for the Lead Engine platform. Provides a full
+retrieval-augmented generation (RAG) pipeline: hybrid search (pgvector cosine +
+BM25 with RRF fusion), multi-query expansion, cross-encoder reranking, MMR
+diversification, dynamic distance threshold, semantic caching, persona/skill
+composition, photo classification and passport OCR.
+
+LLM I/O lives in `@chatman-media/llm-router`.
+
+## Key modules
+
+| Module | What it does |
+|---|---|
+| `answer.ts` | Full RAG answer pipeline: retrieve → filter → diversify → rerank → generate |
+| `ingest.ts` | Document ingest: parse → chunk → embed → upsert |
+| `hybrid-search.ts` | pgvector cosine + BM25 keyword fusion via RRF |
+| `retrieval-utils.ts` | `rrfMerge`, `applyDynamicThreshold`, `mmrDiversify` — post-retrieval transforms |
+| `multi-query.ts` | `expandQueries` — LLM-generated query variants for parallel search |
+| `reranker.ts` | `JinaReranker`, `CohereReranker` — cross-encoder second-pass reranking |
+| `rewrite-query.ts` | Context-aware query rewriting (resolves pronouns / ellipsis via history) |
+| `semantic-cache.ts` | Vector-similarity cache for identical/near-identical questions |
+| `vision.ts` | `classifyPhoto()` + `extractPassportIdentity()` — passport OCR via vision LLM |
+| `ab-router.ts` | A/B experiment allocation for styles/personas |
+| `grade-skills.ts` | ELO-based skill grading via judge LLM |
+| `prompt.ts` | `composeSystemPrompt()` — assemble sales persona + KB context + style |
+
+## RAG pipeline
+
+Each call to `answerWithRag` / `answerWithRagStream` goes through these stages:
+
+```
+1. [opt] Query rewrite     — resolves pronouns, expands ellipsis (rewriteQueryBeforeRetrieval)
+2. [opt] Multi-query       — generate N variants → embed all in parallel (multiQuery)
+3. Vector / hybrid search  — pgvector cosine or RRF(vector+BM25)
+4. [opt] RRF merge         — fuse N result lists if multi-query was used (rrfMerge)
+5. [opt] Distance filter   — drop hits > threshold (autoTrimDistance)
+6. [opt] MMR diversify     — reduce duplicate chunks (mmr)
+7. [opt] Cross-encoder     — reranker.rerank(query, candidates, topK) (reranker)
+8. Prompt composition      — style + persona + context + skills + hooks
+9. LLM generation          — stream or single response
+10.[opt] Fact-checker      — hallucination guard (reflect)
+```
+
+All stages are optional and controlled per-request via `AnswerInput` fields.
+
+## API
+
+### `answerWithRag(input: AnswerInput): Promise<AnswerResult>`
+
+```ts
+import { answerWithRag, JinaReranker } from "@chatman-media/kb";
+
+const result = await answerWithRag({
+  question: "сколько стоит квартира в ЖК Марина?",
+  kb,           // IKbStore implementation
+  embedder,     // EmbeddingClient
+  chat,         // ChatClient
+
+  // ── Retrieval tuning ──────────────────────────────
+  topK: 5,                        // final chunks to pass to the LLM
+  hybridSearch: true,             // vector + BM25 fusion
+  rewriteQueryBeforeRetrieval: true, // resolve "там" / "он" via history
+
+  // Multi-query expansion (generate 2 rephrases, search 3 in parallel)
+  multiQuery: true,
+  multiQueryCount: 2,
+
+  // Drop chunks with cosine distance > 0.45 (reduce hallucinations)
+  autoTrimDistance: true,
+  autoTrimThreshold: 0.45,
+
+  // Maximal Marginal Relevance — diversify results
+  mmr: true,
+  mmrLambda: 0.6,               // 1.0 = pure relevance, 0.0 = pure diversity
+
+  // Cross-encoder reranker (retrieves topK×3 candidates, returns topK)
+  reranker: new JinaReranker({ apiKey: process.env.JINA_API_KEY! }),
+
+  // ── Generation ────────────────────────────────────
+  history,        // ChatMessage[] — conversation context
+  persona,        // Persona — bot identity
+  style,          // Style — sales methodology (SPIN / NEPQ / AIDA)
+  stage,          // FunnelStage — current funnel stage
+  skills,         // SkillForPrompt[] — active persuasion skills
+  reflect: true,  // hallucination guard (LLM judge)
+
+  onTelemetry: (t) => console.log(t), // retrieval_ms, top_distances, path, ...
+});
+
+console.log(result.text);         // generated reply
+console.log(result.hits);         // KbSearchHit[] — chunks used
+console.log(result.usedChunkIds); // chunk IDs referenced in the reply
+```
+
+### Rerankers
+
+```ts
+import { JinaReranker, CohereReranker } from "@chatman-media/kb";
+
+// Jina — multilingual, good for Russian (jina-reranker-v2-base-multilingual)
+const reranker = new JinaReranker({
+  apiKey: process.env.JINA_API_KEY!,
+  model: "jina-reranker-v2-base-multilingual", // default
+});
+
+// Cohere — also multilingual (rerank-v3.5)
+const reranker = new CohereReranker({
+  apiKey: process.env.COHERE_API_KEY!,
+  model: "rerank-v3.5", // default
+});
+```
+
+### Post-retrieval utilities
+
+```ts
+import { rrfMerge, applyDynamicThreshold, mmrDiversify } from "@chatman-media/kb";
+
+// Merge results from multiple queries via Reciprocal Rank Fusion
+const merged = rrfMerge([hitsFromQuery1, hitsFromQuery2, hitsFromQuery3], { topN: 15 });
+
+// Drop hits with cosine distance > 0.4 (keep at least 1)
+const trimmed = applyDynamicThreshold(hits, { threshold: 0.4, minHits: 1 });
+
+// Maximal Marginal Relevance — diversify, reduce duplicates
+const diverse = mmrDiversify(hits, { lambda: 0.6, topK: 5 });
+```
+
+### Vision
+
+```ts
+import { classifyPhoto, extractPassportIdentity } from "@chatman-media/kb";
+
+const cls = await classifyPhoto({
+  bytes: await res.arrayBuffer(),
+  model: "gpt-4o",
+  apiKey: "sk-...",
+  provider: "openai",
+});
+// cls → "passport" | "full_body" | "portrait" | "other"
+
+if (cls === "passport") {
+  const identity = await extractPassportIdentity({ bytes, model, apiKey, provider });
+  // identity → { family_name?, given_name?, passport_number?, passport_expiry? }
+}
+```
+
+In `apps/api`, photo classification is wired automatically via `photo-processor.ts`:
+when a tenant has a `vision` LLM config, every incoming photo is classified
+and passport data is merged into `contact.attributes_json`.
+
+## Install
+
+```bash
+bun add @chatman-media/kb     # Bun
+npm install @chatman-media/kb # npm / pnpm / yarn
+```
+
+Part of the [**lead-engine**](https://github.com/chatman-media/lead-engine) monorepo — a multi-tenant SaaS platform for AI sales bots on Telegram / WhatsApp.
+
+## License
+
+[MIT](LICENSE) — Alexander Kireev / [chatman-media](https://github.com/chatman-media)

package/dist/ab-router.d.ts

@@ -0,0 +1,66 @@
+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 declare class ABRouter {
+    private readonly variants;
+    private readonly totalWeight;
+    private readonly onResult;
+    private readonly salt;
+    constructor(opts: ABRouterOptions);
+    /**
+     * 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;
+    };
+    /** Distribution map — slug → fraction of users assigned. */
+    get distribution(): Record<string, number>;
+    private pickVariant;
+}
+//# sourceMappingURL=ab-router.d.ts.map

package/dist/ab-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ab-router.d.ts","sourceRoot":"","sources":["../src/ab-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;IACrE;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,eAAe;IAQjC;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG;QACtB,KAAK,EAAE,KAAK,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;KAC3C;IAcD,4DAA4D;IAC5D,IAAI,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMzC;IAID,OAAO,CAAC,WAAW;CAWpB"}

package/dist/answer-types.d.ts

@@ -0,0 +1,194 @@
+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 declare 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;
+}
+//# sourceMappingURL=answer-types.d.ts.map

package/dist/answer-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-types.d.ts","sourceRoot":"","sources":["../src/answer-types.ts"],"names":[],"mappings":"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"}

package/dist/answer.d.ts

@@ -0,0 +1,59 @@
+import type { z } from "zod";
+import { type AnswerInput, type AnswerResult, type Persona } from "./answer-types.ts";
+import type { ChatClient, ChatMessage } from "@chatman-media/llm-router";
+import type { KbSearchHit } from "./types.ts";
+export { type AnswerInput, type AnswerResult, type AnswerTelemetry, NO_CONTEXT_MARKER, type Persona, } from "./answer-types.ts";
+export { botPresenceReply, isBotPresenceQuestion, isPersonalFactQuestion, isPersonaSmalltalkQuestion, personaFactReply, personaSmalltalkReply, } from "./persona-shortcuts.ts";
+export { sanitizeLlmOutput } from "./sanitize.ts";
+export { buildSystemPrompt, legacyRagSamplingTemperature, renderSummaryBlock, renderUserFactsBlock, } from "./system-prompt.ts";
+export interface RetrievalResult {
+    hits: KbSearchHit[];
+    retrievalMs: number;
+    searchQuery: string;
+    queries: string[];
+    /** null when topicRouting is off or booksPriority path was used. */
+    usedTopic: string | null;
+}
+/**
+ * Shared retrieval logic for both `answerWithRag` and `answerWithRagStream`.
+ *
+ * Steps:
+ *  1. Optional query rewrite (LLM resolves pronouns/ellipsis via history).
+ *  2. Optional multi-query expansion (LLM generates N variants).
+ *  3. Embed all queries in one batch.
+ *  4. booksPriority path OR normal path (multi-query → RRF | single → topic fallback).
+ *  5. maxDistance filter → applyDynamicThreshold → mmrDiversify → reranker.
+ *  6. Slice to topK.
+ */
+export declare function retrieveHits(input: AnswerInput): Promise<RetrievalResult>;
+/**
+ * Streaming variant of `answerWithRag`. Yields raw text tokens as they arrive
+ * from the LLM. The final telemetry is delivered via `input.onTelemetry` (if
+ * set). Falls back to `complete()` when the chat client has no `stream()`.
+ *
+ * Note: hallucination guard (`reflect`, `vacancyGuard`) is not applied during
+ * streaming — fact-checking requires the full answer. Use `answerWithRag()` when
+ * fact-checking is required.
+ */
+export declare function answerWithRagStream(input: AnswerInput): AsyncIterable<string>;
+export declare function answerWithRag<T extends z.ZodTypeAny>(input: AnswerInput & {
+    outputSchema: T;
+}): Promise<AnswerResult<z.infer<T>>>;
+export declare function answerWithRag(input: AnswerInput): Promise<AnswerResult>;
+/**
+ * Soft fallback reply for turns where RAG produced nothing groundable — no KB
+ * hit, or the fact-checker dropped the draft as ungrounded. Instead of going
+ * silent, the bot answers in its own persona voice, but is hard-constrained
+ * NOT to invent any specifics (salaries, dates, visa terms, cities, prices).
+ *
+ * Concrete questions get an honest "I'll clarify and come back"; general
+ * questions get a normal conversational answer. The caller is still expected
+ * to log the unanswered question (kb_suggestions) for a later precise reply.
+ */
+export declare function generateSoftFallback(input: {
+    question: string;
+    chat: ChatClient;
+    persona: Persona;
+    history?: ChatMessage[];
+}): Promise<string>;
+//# sourceMappingURL=answer.d.ts.map

package/dist/answer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../src/answer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EAGjB,KAAK,OAAO,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AA8BzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,iBAAiB,EACjB,KAAK,OAAO,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAgG/E;AA2OD;;;;;;;;GAQG;AACH,wBAAuB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,CA0HpF;AAED,wBAAsB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACxD,KAAK,EAAE,WAAW,GAAG;IAAE,YAAY,EAAE,CAAC,CAAA;CAAE,GACvC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,wBAAsB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAiG/E;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BlB"}

package/dist/built-in-tools/calendly.d.ts

@@ -0,0 +1,19 @@
+import type { AnyRagTool } from "../tools.ts";
+/**
+ * Встроенный tool: "offer_booking_link".
+ *
+ * Когда лид/кандидат хочет записаться на звонок, демо или встречу — LLM
+ * вызывает этот tool, получает ссылку и вставляет её в ответ.
+ * Работает с любой платформой бронирования: Calendly, Cal.com, Tidycal, и т.д.
+ *
+ * @param schedulingUrl — публичная ссылка на страницу бронирования тенанта
+ *   Пример: "https://calendly.com/your-agency/30min"
+ *
+ * @example
+ * ```ts
+ * const tool = makeBookingLinkTool("https://calendly.com/my-agency/demo");
+ * const result = await answerWithRag({ ..., tools: [tool] });
+ * ```
+ */
+export declare function makeBookingLinkTool(schedulingUrl: string): AnyRagTool;
+//# sourceMappingURL=calendly.d.ts.map

package/dist/built-in-tools/calendly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendly.d.ts","sourceRoot":"","sources":["../../src/built-in-tools/calendly.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAYrE"}

package/dist/chunk.d.ts

@@ -0,0 +1,48 @@
+export interface ChunkOptions {
+    maxChars: number;
+    overlapChars: number;
+}
+export interface Chunk {
+    index: number;
+    text: string;
+    /** Rough token estimate: ~4 chars per token. */
+    tokenCount: number;
+}
+/** Approximate token count for English/mixed text: ~4 chars per token. */
+export declare function estimateTokens(text: string): number;
+/**
+ * Splits `text` into overlapping chunks bounded by `maxChars`. Tries to break
+ * on paragraph boundaries (\n\n) first, then on whitespace, before slicing
+ * mid-word. Empty/whitespace-only input yields an empty array.
+ */
+export declare function chunkText(text: string, opts?: Partial<ChunkOptions>): Chunk[];
+export interface SectionChunk extends Chunk {
+    /** Heading that introduces this section, or null for the document preamble. */
+    heading: string | null;
+    /** Heading level (1–6) derived from the number of `#` characters, or null. */
+    headingLevel: number | null;
+}
+/**
+ * Semantic chunker that splits Markdown/plain-text documents by headings
+ * (`#`, `##`, …) and paragraph breaks, keeping each heading with its content.
+ *
+ * Compared to `chunkText()`:
+ * - Never breaks a heading away from its first paragraph
+ * - Each chunk carries the heading context, so retrieval results are
+ *   self-contained even without surrounding text
+ * - Falls back to `chunkText()` for sections that exceed `maxChars`
+ *
+ * Use this for structured knowledge-base documents (FAQs, wikis, product
+ * pages). Use `chunkText()` for unstructured long-form prose.
+ *
+ * @example
+ * ```ts
+ * import { chunkBySections } from "@chatman-media/kb";
+ *
+ * const chunks = chunkBySections(markdownString, { maxChars: 1200 });
+ * // chunks[0].heading → "Installation"
+ * // chunks[0].text    → "## Installation\n\nRun `bun add …`"
+ * ```
+ */
+export declare function chunkBySections(text: string, opts?: Partial<ChunkOptions>): SectionChunk[];
+//# sourceMappingURL=chunk.d.ts.map

package/dist/chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../src/chunk.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AAOD,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,KAAK,EAAE,CAqDjF;AAED,MAAM,WAAW,YAAa,SAAQ,KAAK;IACzC,+EAA+E;IAC/E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,YAAY,EAAE,CA2E9F"}