@chatman-media/kb 1.3.0

package/src/built-in-tools/calendly.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+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 function makeBookingLinkTool(schedulingUrl: string): AnyRagTool {
+  return {
+    name: "offer_booking_link",
+    description: [
+      "Use this tool when the lead or candidate explicitly wants to book a call,",
+      "schedule a demo, arrange a meeting, or talk to a human.",
+      "Returns the booking page URL so you can share it in your reply.",
+      "Do NOT use it proactively — only when the person asks to book/schedule.",
+    ].join(" "),
+    parameters: z.object({}),
+    execute: async () => ({ url: schedulingUrl }),
+  };
+}

package/src/chunk.ts

@@ -0,0 +1,198 @@
+export interface ChunkOptions {
+  maxChars: number;
+  overlapChars: number;
+}
+
+export interface Chunk {
+  index: number;
+  text: string;
+  /** Rough token estimate: ~4 chars per token. */
+  tokenCount: number;
+}
+
+const DEFAULT_OPTIONS: ChunkOptions = {
+  maxChars: 1500,
+  overlapChars: 150,
+};
+
+/** Approximate token count for English/mixed text: ~4 chars per token. */
+export function estimateTokens(text: string): number {
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+/**
+ * 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 function chunkText(text: string, opts: Partial<ChunkOptions> = {}): Chunk[] {
+  const { maxChars, overlapChars } = { ...DEFAULT_OPTIONS, ...opts };
+  if (overlapChars < 0 || overlapChars >= maxChars) {
+    throw new Error("overlapChars must be in [0, maxChars)");
+  }
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+
+  const paragraphs = trimmed
+    .split(/\n{2,}/)
+    .map((p) => p.trim())
+    .filter(Boolean);
+
+  const segments: string[] = [];
+  let buf = "";
+  for (const p of paragraphs) {
+    if (p.length > maxChars) {
+      if (buf) {
+        segments.push(buf);
+        buf = "";
+      }
+      for (const part of splitLong(p, maxChars, overlapChars)) {
+        segments.push(part);
+      }
+      continue;
+    }
+    if (!buf) {
+      buf = p;
+    } else if (buf.length + 2 + p.length <= maxChars) {
+      buf = `${buf}\n\n${p}`;
+    } else {
+      segments.push(buf);
+      buf = p;
+    }
+  }
+  if (buf) segments.push(buf);
+
+  if (overlapChars > 0 && segments.length > 1) {
+    for (let i = 1; i < segments.length; i++) {
+      const prevTail = (segments[i - 1] ?? "").slice(-overlapChars);
+      let current = `${prevTail}${segments[i] ?? ""}`;
+      if (current.length > maxChars) {
+        current = current.slice(0, maxChars);
+      }
+      segments[i] = current;
+    }
+  }
+
+  return segments.map((text, index) => ({
+    index,
+    text,
+    tokenCount: estimateTokens(text),
+  }));
+}
+
+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 function chunkBySections(text: string, opts: Partial<ChunkOptions> = {}): SectionChunk[] {
+  const { maxChars, overlapChars } = { ...DEFAULT_OPTIONS, ...opts };
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+
+  // Split on Markdown headings — keep the heading line with its section body.
+  const lines = trimmed.split("\n");
+
+  interface RawSection {
+    heading: string | null;
+    headingLevel: number | null;
+    body: string;
+  }
+
+  const sections: RawSection[] = [];
+  let currentHeading: string | null = null;
+  let currentLevel: number | null = null;
+  let bodyLines: string[] = [];
+
+  const flush = () => {
+    const body = bodyLines.join("\n").trim();
+    if (body || currentHeading) {
+      sections.push({ heading: currentHeading, headingLevel: currentLevel, body });
+    }
+    bodyLines = [];
+  };
+
+  for (const line of lines) {
+    const m = line.match(/^(#{1,6})\s+(.+)$/);
+    if (m) {
+      flush();
+      currentHeading = m[2] ?? null;
+      currentLevel = (m[1] ?? "").length;
+      bodyLines = [];
+    } else {
+      bodyLines.push(line);
+    }
+  }
+  flush();
+
+  const result: SectionChunk[] = [];
+  let globalIndex = 0;
+
+  for (const section of sections) {
+    // Build full section text: prepend heading if present
+    const headingPrefix =
+      section.heading && section.headingLevel
+        ? `${"#".repeat(section.headingLevel)} ${section.heading}\n\n`
+        : "";
+    const full = `${headingPrefix}${section.body}`.trim();
+    if (!full) continue;
+
+    if (full.length <= maxChars) {
+      result.push({
+        index: globalIndex++,
+        text: full,
+        tokenCount: estimateTokens(full),
+        heading: section.heading,
+        headingLevel: section.headingLevel,
+      });
+    } else {
+      // Section is too large — fall back to chunkText, preserve heading context
+      const subChunks = chunkText(full, { maxChars, overlapChars });
+      for (const sub of subChunks) {
+        result.push({
+          ...sub,
+          index: globalIndex++,
+          heading: section.heading,
+          headingLevel: section.headingLevel,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
+function splitLong(text: string, maxChars: number, overlapChars: number): string[] {
+  const out: string[] = [];
+  const step = Math.max(1, maxChars - overlapChars);
+  for (let i = 0; i < text.length; i += step) {
+    const slice = text.slice(i, i + maxChars);
+    out.push(slice);
+    if (i + maxChars >= text.length) break;
+  }
+  return out;
+}

package/src/conversation-store.ts

@@ -0,0 +1,138 @@
+import type { ChatMessage } from "@chatman-media/llm-router";
+
+/**
+ * Unified interface for persisting conversation history and summaries.
+ *
+ * Implement this for your storage backend (PostgreSQL, Redis, SQLite, …).
+ * An in-memory reference implementation is exported as `InMemoryConversationStore`.
+ */
+export interface IConversationStore {
+  /** Append one message to the conversation history. */
+  addMessage(conversationId: string, message: ChatMessage): Promise<void>;
+
+  /** Return messages in chronological order. Returns [] for unknown ids. */
+  getHistory(conversationId: string): Promise<ChatMessage[]>;
+
+  /**
+   * Replace the stored history with a shorter version (e.g. after summarisation).
+   * Typically called with the last N messages after older turns are compressed.
+   */
+  setHistory(conversationId: string, messages: ChatMessage[]): Promise<void>;
+
+  /** Store or update the running summary for the conversation. */
+  setSummary(conversationId: string, summary: string): Promise<void>;
+
+  /** Retrieve the current summary, or null if none exists. */
+  getSummary(conversationId: string): Promise<string | null>;
+
+  /** Remove all data for a conversation (GDPR deletion, session reset, …). */
+  deleteConversation(conversationId: string): Promise<void>;
+}
+
+interface ConversationData {
+  history: ChatMessage[];
+  summary: string | null;
+  updatedAt: number;
+}
+
+/**
+ * Zero-dependency in-memory `IConversationStore`.
+ *
+ * Suitable for tests, prototypes, and single-process deployments.
+ * Data is lost on process restart — use a database-backed implementation
+ * for production.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   InMemoryConversationStore,
+ *   summarizeConversation,
+ *   answerWithRag,
+ * } from "@chatman-media/kb";
+ *
+ * const store = new InMemoryConversationStore({ maxHistoryLength: 20, ttlMs: 2 * 60 * 60_000 });
+ *
+ * // Each turn:
+ * const history = await store.getHistory(userId);
+ * const summary = await store.getSummary(userId);
+ * const result = await answerWithRag({ question, kb, chat, embedder, history, conversationSummary: summary ?? undefined });
+ * await store.addMessage(userId, { role: "user", content: question });
+ * await store.addMessage(userId, { role: "assistant", content: result.text });
+ *
+ * // Compress when history grows long:
+ * if (history.length > 30) {
+ *   const newSummary = await summarizeConversation({ history, chat });
+ *   await store.setSummary(userId, newSummary);
+ *   await store.setHistory(userId, history.slice(-10));
+ * }
+ * ```
+ */
+export class InMemoryConversationStore implements IConversationStore {
+  private readonly data = new Map<string, ConversationData>();
+  private readonly maxHistoryLength: number;
+  private readonly ttlMs: number;
+
+  constructor(opts: { maxHistoryLength?: number; ttlMs?: number } = {}) {
+    this.maxHistoryLength = opts.maxHistoryLength ?? 100;
+    this.ttlMs = opts.ttlMs ?? Infinity;
+  }
+
+  async addMessage(conversationId: string, message: ChatMessage): Promise<void> {
+    const conv = this.getOrCreate(conversationId);
+    conv.history.push(message);
+    if (conv.history.length > this.maxHistoryLength) {
+      conv.history = conv.history.slice(-this.maxHistoryLength);
+    }
+    conv.updatedAt = Date.now();
+  }
+
+  async getHistory(conversationId: string): Promise<ChatMessage[]> {
+    const conv = this.data.get(conversationId);
+    if (!conv || this.isExpired(conv)) return [];
+    return [...conv.history];
+  }
+
+  async setHistory(conversationId: string, messages: ChatMessage[]): Promise<void> {
+    const conv = this.getOrCreate(conversationId);
+    conv.history = [...messages];
+    conv.updatedAt = Date.now();
+  }
+
+  async setSummary(conversationId: string, summary: string): Promise<void> {
+    const conv = this.getOrCreate(conversationId);
+    conv.summary = summary;
+    conv.updatedAt = Date.now();
+  }
+
+  async getSummary(conversationId: string): Promise<string | null> {
+    const conv = this.data.get(conversationId);
+    if (!conv || this.isExpired(conv)) return null;
+    return conv.summary;
+  }
+
+  async deleteConversation(conversationId: string): Promise<void> {
+    this.data.delete(conversationId);
+  }
+
+  /** Number of active (non-expired) conversations. */
+  get size(): number {
+    let n = 0;
+    for (const conv of this.data.values()) {
+      if (!this.isExpired(conv)) n++;
+    }
+    return n;
+  }
+
+  private getOrCreate(id: string): ConversationData {
+    let conv = this.data.get(id);
+    if (!conv || this.isExpired(conv)) {
+      conv = { history: [], summary: null, updatedAt: Date.now() };
+      this.data.set(id, conv);
+    }
+    return conv;
+  }
+
+  private isExpired(conv: ConversationData): boolean {
+    return this.ttlMs !== Infinity && Date.now() - conv.updatedAt > this.ttlMs;
+  }
+}

package/src/eval.ts

@@ -0,0 +1,127 @@
+import type { KbSearchHit } from "./types.ts";
+
+/**
+ * One labelled query for retrieval evaluation.
+ * `relevantChunkIds` are the ground-truth chunk ids that should be retrieved.
+ */
+export interface EvalQuery {
+  question: string;
+  relevantChunkIds: number[];
+}
+
+/** Per-query metrics returned by `evalRetrieval`. */
+export interface QueryMetrics {
+  question: string;
+  /** Fraction of relevant chunks found in the top-k results (0–1). */
+  recallAtK: number;
+  /** Mean Reciprocal Rank — position of the first relevant hit (0–1). */
+  mrr: number;
+  /** Normalised Discounted Cumulative Gain (0–1). */
+  ndcg: number;
+  /** Chunk ids that were retrieved. */
+  retrievedIds: number[];
+}
+
+/** Aggregated metrics over a full eval set. */
+export interface EvalResult {
+  /** Arithmetic mean of recall@k across all queries. */
+  meanRecallAtK: number;
+  /** Arithmetic mean of MRR across all queries. */
+  meanMrr: number;
+  /** Arithmetic mean of NDCG across all queries. */
+  meanNdcg: number;
+  /** Per-query breakdown. */
+  queries: QueryMetrics[];
+}
+
+/**
+ * Evaluate retrieval quality over a labelled query set.
+ *
+ * Runs `retrieve(query)` for each `EvalQuery`, compares the returned chunk ids
+ * against the ground-truth relevant ids, and reports recall@k, MRR, and NDCG.
+ *
+ * @param queries     Labelled queries with ground-truth chunk ids.
+ * @param retrieve    Function that takes a question and returns `KbSearchHit[]`.
+ *                    Wrap your `kb.search()` / `kb.hybridSearch()` call here.
+ *
+ * @example
+ * ```ts
+ * import { evalRetrieval } from "@chatman-media/kb";
+ *
+ * const result = await evalRetrieval(
+ *   [
+ *     { question: "Какая зарплата в Дубае?", relevantChunkIds: [12, 15] },
+ *     { question: "Нужна ли виза?",          relevantChunkIds: [7] },
+ *   ],
+ *   async (q) => {
+ *     const [vec] = await embedder.embed([q]);
+ *     return kb.hybridSearch({ embedding: vec!, query: q, k: 5 });
+ *   },
+ * );
+ *
+ * console.log(`recall@5: ${result.meanRecallAtK.toFixed(3)}`);
+ * console.log(`MRR:      ${result.meanMrr.toFixed(3)}`);
+ * console.log(`NDCG:     ${result.meanNdcg.toFixed(3)}`);
+ * ```
+ */
+export async function evalRetrieval(
+  queries: EvalQuery[],
+  retrieve: (question: string) => Promise<KbSearchHit[]>,
+): Promise<EvalResult> {
+  const queryMetrics: QueryMetrics[] = [];
+
+  for (const q of queries) {
+    const hits = await retrieve(q.question);
+    const retrievedIds = hits.map((h) => h.chunk_id);
+    const relevant = new Set(q.relevantChunkIds);
+
+    queryMetrics.push({
+      question: q.question,
+      recallAtK: recallAtK(retrievedIds, relevant),
+      mrr: mrr(retrievedIds, relevant),
+      ndcg: ndcg(retrievedIds, relevant),
+      retrievedIds,
+    });
+  }
+
+  const mean = (arr: number[]) =>
+    arr.length === 0 ? 0 : arr.reduce((a, b) => a + b, 0) / arr.length;
+
+  return {
+    meanRecallAtK: mean(queryMetrics.map((q) => q.recallAtK)),
+    meanMrr: mean(queryMetrics.map((q) => q.mrr)),
+    meanNdcg: mean(queryMetrics.map((q) => q.ndcg)),
+    queries: queryMetrics,
+  };
+}
+
+// ── Metric implementations ────────────────────────────────────────────────────
+
+function recallAtK(retrieved: number[], relevant: Set<number>): number {
+  if (relevant.size === 0) return 1;
+  const found = retrieved.filter((id) => relevant.has(id)).length;
+  return found / relevant.size;
+}
+
+function mrr(retrieved: number[], relevant: Set<number>): number {
+  for (let i = 0; i < retrieved.length; i++) {
+    if (relevant.has(retrieved[i] as number)) return 1 / (i + 1);
+  }
+  return 0;
+}
+
+function ndcg(retrieved: number[], relevant: Set<number>): number {
+  const dcg = retrieved.reduce((sum, id, i) => {
+    const gain = relevant.has(id) ? 1 : 0;
+    return sum + gain / Math.log2(i + 2);
+  }, 0);
+
+  // Ideal DCG: all relevant docs at the top
+  const idealLen = Math.min(relevant.size, retrieved.length);
+  const idcg = Array.from({ length: idealLen }, (_, i) => 1 / Math.log2(i + 2)).reduce(
+    (a, b) => a + b,
+    0,
+  );
+
+  return idcg === 0 ? 0 : dcg / idcg;
+}

package/src/extract-user-facts.ts

@@ -0,0 +1,120 @@
+import type { ChatClient, ChatMessage } from "@chatman-media/llm-router";
+import { stripCodeFences, stripThinkBlocks } from "./sanitize.ts";
+
+/**
+ * Extracts persistent facts ABOUT THE CANDIDATE (not the bot persona) from
+ * a slice of conversation. Used by the cross-session memory layer in
+ * webhook → after each turn the new messages are passed here and the result
+ * merged into `users.profile_json.memory.facts`.
+ *
+ * Facts schema is flexible — the prompt encourages the most common keys for
+ * the recruitment use-case but allows free-form keys when the candidate
+ * volunteers something unusual ("instagram", "previous_agency", …). Only
+ * volunteered facts are returned — no inference or guessing.
+ */
+export interface ExtractFactsInput {
+  /** Recent messages, oldest first. Should include both user and bot turns. */
+  messages: ChatMessage[];
+  chat: ChatClient;
+  /** Existing facts so the LLM doesn't re-emit already-known data. */
+  existingFacts?: Record<string, string>;
+}
+
+const SYSTEM_PROMPT = `Ты извлекаешь факты О КАНДИДАТЕ из переписки рекрутингового агентства.
+Анализируй ТОЛЬКО реплики кандидата (role=user). Реплики бота (role=assistant) — для контекста.
+
+Извлекай только факты, которые КАНДИДАТ САМ ЯВНО СООБЩИЛ. Никаких догадок и вывода.
+
+Типичные ключи (используй их когда подходит):
+- name: имя кандидата
+- city: город/страна где живёт сейчас
+- age: возраст (число)
+- experience: опыт работы (что уже делал)
+- language: какие языки знает
+- country_target: куда хочет поехать работать
+- intent: что ищет ("работа моделью", "поездка в Дубай", "разовый контракт")
+- contact: telegram/instagram/email если давал
+
+Можешь добавлять свои ключи (snake_case) если кандидат сообщил что-то ещё.
+
+ВЕРНИ СТРОГО JSON-ОБЪЕКТ, без markdown, без \`\`\`, без комментариев.
+Если фактов нет — верни {}.
+Если факт уже есть в "Существующие факты" и не изменился — не повторяй его.
+Только новые или ОБНОВЛЁННЫЕ факты.
+
+Пример:
+Сообщения:
+user: привет, я Аня из новосибирска, мне 23
+user: ищу работу в дубае, хочу заработать
+Существующие факты: {}
+Ответ:
+{"name":"Аня","city":"Новосибирск","age":"23","country_target":"Дубай","intent":"работа, заработок"}`;
+
+const MAX_RETURNED_KEYS = 20;
+const MAX_VALUE_LEN = 200;
+
+export async function extractUserFacts(input: ExtractFactsInput): Promise<Record<string, string>> {
+  // No new messages → nothing to extract. Skip LLM call entirely.
+  const userMessages = input.messages.filter((m) => m.role === "user");
+  if (userMessages.length === 0) return {};
+
+  const conversation = input.messages.map((m) => `${m.role}: ${m.content}`).join("\n");
+  const existingJson = JSON.stringify(input.existingFacts ?? {});
+
+  const userPrompt = `Сообщения:\n${conversation}\n\nСуществующие факты: ${existingJson}\n\nОтвет:`;
+
+  const messages: ChatMessage[] = [
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: userPrompt },
+  ];
+
+  let raw: string;
+  try {
+    raw = await input.chat.complete(messages, { temperature: 0.1 });
+  } catch (err) {
+    console.error("[extract-user-facts] LLM call failed:", err);
+    return {};
+  }
+
+  return parseFactsFromLlmOutput(raw);
+}
+
+/**
+ * Parses the LLM output — strips think-tags and markdown fences, finds the
+ * JSON object, validates that values are short strings, caps total keys.
+ * Exported for unit tests.
+ */
+export function parseFactsFromLlmOutput(raw: string): Record<string, string> {
+  const s = stripCodeFences(stripThinkBlocks(raw)).trim();
+
+  // Find the first {...} block. The model sometimes prefixes "Ответ:" or similar.
+  const start = s.indexOf("{");
+  const end = s.lastIndexOf("}");
+  if (start === -1 || end === -1 || end < start) return {};
+
+  const candidate = s.slice(start, end + 1);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch {
+    return {};
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return {};
+  }
+
+  const result: Record<string, string> = {};
+  let count = 0;
+  for (const [key, val] of Object.entries(parsed as Record<string, unknown>)) {
+    if (count >= MAX_RETURNED_KEYS) break;
+    if (typeof key !== "string" || key.length === 0 || key.length > 40) continue;
+    if (val === null || val === undefined) continue;
+    const str = typeof val === "string" ? val : String(val);
+    const trimmed = str.trim();
+    if (!trimmed || trimmed.length > MAX_VALUE_LEN) continue;
+    result[key] = trimmed;
+    count++;
+  }
+  return result;
+}