@chatman-media/kb 1.3.0

package/src/multi-query.ts

@@ -0,0 +1,89 @@
+/**
+ * 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";
+import { stripThinkBlocks } from "./sanitize.ts";
+
+export interface ExpandQueriesInput {
+  question: string;
+  history?: ChatMessage[];
+  chat: ChatClient;
+  /** Number of ADDITIONAL variants to generate (not counting the original). Default: 2. */
+  count?: number;
+}
+
+const SYSTEM_PROMPT = `Ты генерируешь альтернативные формулировки поискового запроса для базы знаний.
+
+Правила:
+1. Сохраняй смысл — только меняй слова/порядок/стиль, не искажай суть
+2. Используй синонимы, профессиональную лексику, другой порядок слов
+3. Каждая формулировка на ОТДЕЛЬНОЙ СТРОКЕ, без нумерации, без кавычек, без пояснений
+4. Не повторяй оригинальный запрос
+5. Если запрос слишком короткий или это смолток — верни одну строку с оригиналом
+
+Пример:
+запрос: сколько стоит квартира в ЖК Марина
+ответ:
+цена апартаментов в Marina Gate Dubai
+стоимость юнитов в Marsa Al Arab
+
+Пример:
+запрос: условия контракта для моделей
+ответ:
+требования к договору для моделей агентства
+правила трудового соглашения модельного бизнеса`;
+
+/**
+ * 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 async function expandQueries(input: ExpandQueriesInput): Promise<string[]> {
+  const { question, chat, count = 2 } = input;
+  const original = question.trim();
+  if (!original) return [original];
+
+  const tail = (input.history ?? []).slice(-4);
+  const historySnippet = tail.length > 0 ? tail.map((m) => `${m.role}: ${m.content}`).join("\n") + "\n\n" : "";
+  const userPrompt = `${historySnippet}запрос: ${original}\nответ (${count} строки):`;
+
+  let raw: string;
+  try {
+    raw = await chat.complete(
+      [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: userPrompt },
+      ],
+      { temperature: 0.3 },
+    );
+  } catch (err) {
+    console.warn("[multi-query] LLM call failed, using original only:", err);
+    return [original];
+  }
+
+  const variants = parseVariants(raw, count);
+  // Original always first so that its RRF rank is counted separately from variants.
+  return [original, ...variants];
+}
+
+/** Parse LLM output into a list of clean query strings. */
+function parseVariants(raw: string, maxCount: number): string[] {
+  const cleaned = stripThinkBlocks(raw);
+  return cleaned
+    .split("\n")
+    .map((l) => l.trim().replace(/^[-•*\d.]+\s*/, "")) // strip list markers
+    .filter((l) => l.length > 3)
+    .slice(0, maxCount);
+}

package/src/parse-pdf.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { extractText, getDocumentProxy } from "unpdf";
+
+/**
+ * Extract plain text from a PDF file. Pages are joined with double newlines
+ * so paragraph boundaries survive. Throws on corrupt/encrypted files.
+ */
+export async function parsePdf(filePath: string): Promise<string> {
+  const buffer = readFileSync(filePath);
+  return parsePdfBuffer(new Uint8Array(buffer));
+}
+
+/**
+ * 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 async function parsePdfBuffer(buffer: Uint8Array): Promise<string> {
+  const pdf = await getDocumentProxy(buffer);
+  const { text } = await extractText(pdf, { mergePages: false });
+  return (Array.isArray(text) ? text : [text]).join("\n\n").trim();
+}

package/src/persona-shortcuts.ts

@@ -0,0 +1,255 @@
+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 function isBotPresenceQuestion(question: string): boolean {
+  const trimmed = question.trim();
+  if (!trimmed) return false;
+  const q = trimmed.toLowerCase().replace(/\s+/g, " ");
+
+  // Job/offer intent → not smalltalk; let RAG handle.
+  const hasJobOrOfferIntent =
+    /(работ|ваканс|зарплат|виза|оффер|переезд|агентств|услов|\bофис\b|график|смен|жилье|жильё|рейс|кита|китай|коре|англ\b)/i.test(
+      question,
+    );
+  if (hasJobOrOfferIntent) return false;
+
+  // One regex covering all forms: bare ("бот?", "человек?") and "ты <noun>"
+  // ("ты бот", "ты chatgpt"). The leading "ты " is optional. Unicode-property
+  // lookarounds replace `\b` because JS `\b` is ASCII-only and silently fails
+  // on Cyrillic word ends — same trick as `isPersonaSmalltalkQuestion`.
+  const presenceNouns =
+    "бот|человек|робот|ии|нейросет(?:ь|ка)|нейронка|чат\\s*бот|chat\\s*bot|chat\\s*gpt|chatgpt|gpt|llm|ai";
+  const ruRe = new RegExp(
+    `(?<![\\p{L}\\p{N}])(?:ты\\s+)?(?:${presenceNouns})(?![\\p{L}\\p{N}])`,
+    "iu",
+  );
+  if (ruRe.test(q)) return true;
+  return /(?<![a-z])are\s+you\s+(?:a\s+)?(?:bot|human|ai|robot)(?![a-z])/i.test(q);
+}
+
+/**
+ * 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 function botPresenceReply(persona: Persona): string {
+  const name = persona.name?.trim() || "Менеджер";
+  if (persona.role === "human") {
+    const company = persona.company?.trim();
+    const tail = company ? `, в ${company}` : "";
+    return `Я живой человек, ${name}${tail}. Чем помочь?`;
+  }
+  return `Я ${name}, ИИ-ассистент. Чем помочь?`;
+}
+
+/**
+ * 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 function isPersonaSmalltalkQuestion(question: string): boolean {
+  const trimmed = question.trim();
+  if (!trimmed) return false;
+  const q = trimmed.toLowerCase().replace(/\s+/g, " ");
+
+  const hasJobOrOfferIntent =
+    /(работ|ваканс|зарплат|виза|оффер|переезд|агентств|услов|\bофис\b|график|смен|жилье|жильё|рейс|кита|китай|коре|англ\b)/i.test(
+      question,
+    );
+  if (hasJobOrOfferIntent) return false;
+
+  // Various phrasings of "what's your name". The bare forms ("как зовут?",
+  // "имя?", "ваше имя") are the ones that USED TO LEAK into RAG and produce
+  // an off-topic stall — the regression we just fixed.
+  const nameCue =
+    q.includes("как тебя зовут") ||
+    q.includes("как вас зовут") ||
+    q.includes("тебя как зовут") ||
+    q.includes("вас как зовут") ||
+    /^как\s+зовут\??$/.test(q) ||
+    /как\s+(твоё|твое|ваше)\s+имя/i.test(question) ||
+    /^(твоё|твое|ваше)\s+имя\??$/i.test(trimmed) ||
+    /^имя\??$/.test(q) ||
+    /как\s+звать/i.test(question) ||
+    /как\s+(тебя|вас)\s+называть/i.test(question);
+
+  // "представься" / "представься" / "представьтесь" — imperative forms of
+  // "introduce yourself". Matches both the -ся and -сь endings (singular/plural).
+  // Note: JS `\b` is ASCII-only and silently fails on Cyrillic word ends —
+  // we use a Unicode-property lookahead instead. Same trick as stage-router.ts.
+  const introCue =
+    /^представ(ь|ьте)?(ся|сь)(?!\p{L})/iu.test(trimmed) ||
+    /^представь(те)?\s+себя(?!\p{L})/iu.test(trimmed);
+
+  const whoCue =
+    /^кто\s+ты\??$/i.test(trimmed) ||
+    /^ты\s+кто\??$/i.test(trimmed) ||
+    /^кто\s+вы\??$/i.test(trimmed) ||
+    /^с\s+кем\s+(я\s+)?(общаюсь|разговариваю|переписываюсь)\??$/i.test(trimmed);
+
+  // English: "what's your name" / "what is your name" / "whats your name".
+  // The earlier `what\s+('?s\s+)?your\s+name` required whitespace BEFORE 's,
+  // which `what's` doesn't have — silent miss on the most common form.
+  const enName = /\bwhat(?:'?s|\s+is)?\s+your\s+name\b/i.test(question);
+  const enWho = /\bwho\s+are\s+you\b/i.test(question);
+
+  return !!(nameCue || introCue || whoCue || enName || enWho);
+}
+
+/**
+ * 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 function isPersonalFactQuestion(question: string): string | null {
+  const trimmed = question.trim();
+  if (!trimmed) return null;
+
+  const hasJobOrOfferIntent =
+    /(работ|ваканс|зарплат|виза|оффер|переезд|агентств|услов|\bофис\b|график|смен|жилье|жильё|рейс|кита|китай|коре|англ\b)/i.test(
+      question,
+    );
+  if (hasJobOrOfferIntent) return null;
+
+  const q = trimmed.toLowerCase().replace(/\s+/g, " ");
+
+  const cityCue =
+    /где\s+(ты\s+)?(живёшь|живешь)/i.test(q) ||
+    /откуда\s+ты/i.test(q) ||
+    /из\s+какого\s+города/i.test(q) ||
+    /в\s+каком\s+городе/i.test(q) ||
+    /где\s+(ты\s+)?сейчас/i.test(q) ||
+    /где\s+(ты\s+)?находишься/i.test(q) ||
+    /в\s+каком\s+месте/i.test(q);
+
+  if (cityCue) return "city";
+
+  const ageCue =
+    /сколько\s+(тебе\s+)?лет/i.test(q) ||
+    /тебе\s+сколько\s+лет/i.test(q) ||
+    /какой\s+(у\s+тебя\s+)?возраст/i.test(q) ||
+    /твой\s+возраст/i.test(q) ||
+    /тебе\s+сколько/i.test(q) ||
+    /^возраст\??$/.test(q);
+
+  if (ageCue) return "age";
+
+  const statusCue =
+    /ты\s+замужем/i.test(q) ||
+    /замужем\s+ты/i.test(q) ||
+    /^замужем\??$/.test(q) ||
+    /есть\s+(парень|муж|молодой\s+человек)/i.test(q) ||
+    /в\s+отношениях/i.test(q) ||
+    /одна\s+(живёшь|живешь)/i.test(q) ||
+    /^ты\s+одна\??$/.test(q) ||
+    /^отношения(\s+есть)?\??$/.test(q);
+
+  if (statusCue) return "status";
+
+  // Phone / contact requests. Common phrasings: "твой номер", "номер
+  // телефона", "дай номер", "whatsapp есть?". Also catches the "+1 …"
+  // / "+7 …" style request where a candidate asks where to message.
+  const phoneCue =
+    /(?<![\p{L}\p{N}])(номер\s+(твой|телефона|тел))/iu.test(q) ||
+    /(?<![\p{L}\p{N}])(твой|какой|есть)\s+(номер|телефон|whatsapp|вотсап|whatsap)/iu.test(q) ||
+    /(?<![\p{L}\p{N}])(дай|скинь|пришли)\s+(номер|телефон|whatsapp)/iu.test(q) ||
+    /^номер\??$/.test(q) ||
+    /^телефон\??$/.test(q) ||
+    /^whatsapp\??$/i.test(q);
+
+  if (phoneCue) return "phone";
+
+  return 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 function personaFactReply(persona: Persona, key: string): string | null {
+  const val = persona.facts?.[key]?.trim();
+  if (!val) return null;
+
+  if (key === "city") return `Живу в ${val}.`;
+  if (key === "age") {
+    // If value already contains letters (e.g. "26 лет") return as-is, else append " лет"
+    return /\d/.test(val) && !/[а-яё]/i.test(val) ? `${val} лет.` : `${val}.`;
+  }
+  if (key === "phone") {
+    // The configured value is the raw number. Wrap with a natural
+    // sentence so the bot doesn't sound like a database row.
+    return `Мой номер: ${val}. Можно писать в WhatsApp / Telegram.`;
+  }
+  // "status" / "experience" / other — operator writes the full reply
+  return val;
+}
+
+/**
+ * Short tail phrases tacked onto the smalltalk introduction. Picked at
+ * random per call so a candidate asking "как тебя зовут?" twice in a row
+ * doesn't get a verbatim repeat — the giveaway "I'm a script" pattern.
+ *
+ * All entries use ASCII hyphens (not em-dashes); the smalltalk path
+ * bypasses `sanitizeLlmOutput`, so anything here ends up in the wire
+ * message exactly as written.
+ */
+const HUMAN_SMALLTALK_TAILS_WITH_COMPANY: readonly string[] = [
+  "Что хотел узнать?",
+  "По чему интересно?",
+  "Чем помочь?",
+  "Что подсказать?",
+  "По работе что-то?",
+  "", // sometimes just the introduction, no tail at all
+];
+
+const HUMAN_SMALLTALK_TAILS_NO_COMPANY: readonly string[] = [
+  "Чем помочь?",
+  "Что хотел узнать?",
+  "Если что по вакансиям - просто напиши.",
+  "",
+];
+
+function pickTail(pool: readonly string[]): string {
+  const idx = Math.floor(Math.random() * pool.length);
+  return pool[idx] ?? "";
+}
+
+/** Short reply derived from persona - no KB required. */
+export function personaSmalltalkReply(persona: Persona): string {
+  const name = persona.name?.trim() || "Менеджер";
+  const company = persona.company?.trim();
+  if (persona.role === "human") {
+    if (company) {
+      const tail = pickTail(HUMAN_SMALLTALK_TAILS_WITH_COMPANY);
+      const head = `Меня зовут ${name}, я в ${company}.`;
+      return tail ? `${head} ${tail}` : head;
+    }
+    const tail = pickTail(HUMAN_SMALLTALK_TAILS_NO_COMPANY);
+    const head = `Меня зовут ${name}.`;
+    return tail ? `${head} ${tail}` : head;
+  }
+  if (company) return `Я ${name}, помощник агентства ${company}.`;
+  return `Я ${name}.`;
+}

package/src/prompt.ts

@@ -0,0 +1,190 @@
+import type { ComposeOptions, FunnelStage, Hook, Style } from "./styles.ts";
+import { renderSummaryBlock, renderUserFactsBlock } from "./system-prompt.ts";
+
+const HOOK_LABELS: Record<Hook["kind"], string> = {
+  social_proof: "СОЦ. ДОКАЗАТЕЛЬСТВО",
+  scarcity: "ДЕФИЦИТ",
+  authority: "АВТОРИТЕТ",
+  liking: "СИМПАТИЯ",
+  reciprocity: "ВЗАИМНОСТЬ",
+  commitment: "ОБЯЗАТЕЛЬСТВО",
+};
+
+const FRAMEWORK_BLURB: Record<Style["framework"], string> = {
+  AIDA: "Двигай разговор по AIDA: Attention → Interest → Desire → Action.",
+  PAS: "Используй PAS: Problem → Agitate → Solve. Кратко, без воды.",
+  SPIN: "Веди по SPIN: Situation → Problem → Implication → Need-payoff.",
+  NEPQ: "NEPQ: задавай нейро-эмоциональные вопросы. Пусть prospect сам убедит себя.",
+  straight_line:
+    "Belfort Straight Line: веди prospect к 10/10 уверенности по продукту, продавцу и компании. Тон уверенный и заразительный.",
+};
+
+function kbGroundingReminder(personaRole: Style["persona"]["role"]): string {
+  const base = "Никогда не выдумывай цифры, суммы, сроки, условия. Если фактов нет в KB CONTEXT — ";
+  return personaRole === "human"
+    ? base +
+        "напиши по-человечески, что сейчас уточнишь детали (без официоза вроде «обращусь к руководству»), если этих фактов нет в контексте."
+    : `${base}скажи prospect, что уточнишь у руководства.`;
+}
+
+/** Calm FAQ-support guidance used in place of the sales blocks when the
+ *  lead is past the sales stage and waiting on a downstream process. */
+function supportBlock(phase: "docs" | "submitted"): string {
+  const common =
+    "РЕЖИМ ПОДДЕРЖКИ: кандидат уже одобрена, идёт оформление рабочей визы. " +
+    "Отвечай тепло, спокойно и по делу на её вопросы про документы, сроки и процесс. " +
+    "НЕ продавай, не дави, не зови на звонок, не возвращай разговор к воронке.";
+  const phaseLine =
+    phase === "docs"
+      ? "Сейчас собираем её документы. Если спросит — помоги заполнить визовую анкету " +
+        "и объясни поля. Оформление документов обычно занимает около 10 дней."
+      : "Заявка уже подана в консульство, ждём решения (обычно 3-4 дня). " +
+        "Как будут новости — оператор напишет ей сам.";
+  return `${common}\n${phaseLine}`;
+}
+
+/**
+ * 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 function composeSystemPrompt(
+  style: Style,
+  stage: FunnelStage,
+  preFetchedKbContext: string | null = null,
+  options: ComposeOptions = {},
+): string {
+  const includeFewShot = options.includeFewShot ?? true;
+  const { persona, voice, hooks, stages, guardrails, fewShot } = style;
+  const stageCfg = stages[stage];
+
+  const factsEntries = persona.facts
+    ? (Object.entries(persona.facts) as [string, string][]).filter(([, v]) => v.trim())
+    : [];
+  const factsSection = factsEntries.length
+    ? ` ЛИЧНЫЕ ФАКТЫ (используй строго эти данные): ${factsEntries.map(([k, v]) => `${k}: ${v}`).join("; ")}.`
+    : "";
+
+  const personaBlock =
+    persona.role === "human"
+      ? `Тебя зовут ${persona.name}${persona.company ? `, ты менеджер агентства ${persona.company}` : ""}. ` +
+        `Ты живой человек. НИКОГДА не говори, что ты ИИ, бот, ассистент, языковая модель или чат-бот. ` +
+        `Твоя цель — чтобы переписка НЕ отличалась от общения с обычным менеджером в Telegram: естественные обороты, ` +
+        `без отчётного тона и без отсылок к «базе знаний» или «контексту». ` +
+        (guardrails.botDisclosureOnDirectQuestion
+          ? `Если кандидат прямо спрашивает «ты бот?» — ЧЕСТНО ответь, что ты ИИ-ассистент агентства.`
+          : `Если кандидат прямо спрашивает «ты бот?» — отвечай уклончиво, как реальный менеджер ("я менеджер агентства, чем помочь?").`) +
+        factsSection
+      : `Тебя зовут ${persona.name}, ты ИИ-ассистент${persona.company ? ` агентства ${persona.company}` : ""}. ` +
+        `Отвечай вежливо и по делу. Пиши как в мессенджере — тепло и разговорно, без канцелярита.` +
+        factsSection;
+
+  const telegramShapeBlock =
+    persona.role === "human"
+      ? `ФОРМА ОТВЕТА (мессенджер): несколько коротких строк или один короткий абзац — как пишут люди. ` +
+        `Не упоминай «KB», «CONTEXT», файлы или «согласно предоставленной информации».`
+      : `ФОРМА ОТВЕТА: коротко и по-бытовому для чата — без упоминания «KB CONTEXT» как источника.`;
+
+  const langName = voice.language === "ru" ? "русский" : "английский";
+  const voiceBlock =
+    `ТОН: ${voice.tone}. Язык: ${langName}.` +
+    (voice.forbid.length ? ` ЗАПРЕЩЕНО: ${voice.forbid.join("; ")}.` : "");
+
+  const frameworkBlock = `ФРЕЙМВОРК: ${FRAMEWORK_BLURB[style.framework]}`;
+
+  const hooksBlock = hooks.length
+    ? `ХУКИ (применяй когда уместно — не все сразу):\n` +
+      hooks.map((h) => `- ${HOOK_LABELS[h.kind]}: ${h.text}`).join("\n")
+    : "";
+
+  // Director hooks: tenant-specific scripted persuasion techniques. Always
+  // injected when present — not filtered by stage. Appear BEFORE universal
+  // skills so they take priority in LLM attention.
+  const directorHooksBlock =
+    options.directorHooks && options.directorHooks.length > 0
+      ? `ХУКИ УБЕЖДЕНИЯ (применяй когда уместно — не все сразу):\n` +
+        options.directorHooks
+          .map((h) => {
+            const triggerLine = h.triggerHint ? `Когда: ${h.triggerHint}\n` : "";
+            return `━━ ${h.name} ━━\n${triggerLine}${h.body}`;
+          })
+          .join("\n\n")
+      : "";
+
+  const skillsForStage =
+    options.skills?.filter(
+      (s) => s.applicableStages.length === 0 || s.applicableStages.includes(stage),
+    ) ?? [];
+  const skillsBlock = skillsForStage.length
+    ? `ПРИЁМЫ (используй уместные, не все сразу — выбирай по контексту):\n` +
+      skillsForStage.map((s) => `- ${s.displayName} — ${s.promptFragment}`).join("\n")
+    : "";
+
+  const stageBlock = stageCfg
+    ? `ТЕКУЩИЙ ЭТАП: ${stage.toUpperCase()}.\n` +
+      `ЦЕЛЬ ЭТАПА: ${stageCfg.goal}.` +
+      (stageCfg.guidance ? `\nКАК: ${stageCfg.guidance}` : "") +
+      (stageCfg.groundingRequired
+        ? `\nGROUNDING: на этом этапе все конкретные факты (цифры, суммы, сроки) бери ТОЛЬКО из секции KB CONTEXT ниже. Если её нет или нужного факта в ней нет — не выдумывай, скажи что уточнишь.`
+        : "")
+    : `ТЕКУЩИЙ ЭТАП: ${stage}. (Специфических правил для этапа нет — используй общий стиль.)`;
+
+  const minorRule = guardrails.noMinors ? "- Если prospect <18 лет — вежливо заверши диалог." : "";
+  const topicsRule = guardrails.forbiddenTopics.length
+    ? `- Запрещённые темы: ${guardrails.forbiddenTopics.join(", ")}.`
+    : "";
+  const brevityRule =
+    persona.role === "human"
+      ? `- Пиши как в живом чате: 2–6 коротких фраз можно, если нужно передать условия. Без markdown-заголовков. ` +
+        `Списком с номерами — только если человек сам просит структуру.`
+      : `- Пиши коротко: 1-3 предложения. Без markdown-заголовков и нумерованных списков.`;
+  const guardrailBlock = `ЖЁСТКИЕ ПРАВИЛА:\n${[minorRule, topicsRule, brevityRule].filter(Boolean).join("\n")}`;
+
+  const fewShotBlock =
+    includeFewShot && fewShot.length
+      ? `ПРИМЕРЫ ДИАЛОГА (стиль и регистр):\n` +
+        fewShot
+          .map(
+            (ex, i) =>
+              `[${i + 1}]${ex.stage ? ` (этап: ${ex.stage})` : ""}\n` +
+              `  prospect: ${ex.user}\n` +
+              `  ты: ${ex.assistant}`,
+          )
+          .join("\n")
+      : "";
+
+  const kbBlock = preFetchedKbContext
+    ? `KB CONTEXT (актуальные факты агентства):\n${preFetchedKbContext}`
+    : "";
+
+  const userFactsBlock = renderUserFactsBlock(options.userFacts);
+  const summaryBlock = renderSummaryBlock(options.conversationSummary);
+
+  const needsGroundingReminder = stageCfg?.groundingRequired === true && !preFetchedKbContext;
+
+  // Support mode: the lead is past the sales stage and waiting on a
+  // downstream process. Drop every sales block (framework / hooks / skills /
+  // funnel stage / few-shot) and replace them with a calm FAQ-support block.
+  // Persona, voice, guardrails, KB grounding + context stay intact.
+  const support = options.supportPhase ? supportBlock(options.supportPhase) : "";
+
+  return [
+    personaBlock,
+    telegramShapeBlock,
+    voiceBlock,
+    support ? "" : frameworkBlock,
+    support ? "" : hooksBlock,
+    support ? "" : directorHooksBlock,
+    support ? "" : skillsBlock,
+    support || stageBlock,
+    summaryBlock,
+    userFactsBlock,
+    needsGroundingReminder ? kbGroundingReminder(persona.role) : "",
+    guardrailBlock,
+    support ? "" : fewShotBlock,
+    kbBlock,
+  ]
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+}

package/src/reflect.ts

@@ -0,0 +1,99 @@
+import type { ChatClient, ChatMessage } from "@chatman-media/llm-router";
+import { stripCodeFences, stripThinkBlocks } from "./sanitize.ts";
+
+/**
+ * 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;
+}
+
+const SYSTEM_PROMPT = `Ты проверяешь ответ бота на галлюцинации.
+Тебе дают: ВОПРОС кандидата, КОНТЕКСТ (выдержки из базы знаний), ОТВЕТ бота.
+
+Задача: проверить, что КАЖДЫЙ конкретный факт из ОТВЕТА (цифры, страны, города, валюты, сроки, названия услуг, условия) встречается в КОНТЕКСТЕ.
+
+Правила:
+- Общие фразы ("у нас хорошие условия", "напишу подробности"), приветствия, эмоции — НЕ требуют проверки
+- Конкретные числа, страны, города, валюты, сроки, % — ДОЛЖНЫ быть в контексте
+- Если ответ говорит "уточню у руководства" / "сейчас уточню" — это ОК, не требует проверки
+- Личные факты бота (имя, возраст, город, статус) — НЕ требуют проверки в контексте
+
+Верни СТРОГО JSON одной строкой, без markdown, без \`\`\`:
+{"grounded": true} — если все факты подтверждены или ответ общий
+{"grounded": false, "reason": "<какой именно факт не из контекста>"} — если есть выдуманное
+
+Только JSON, ничего больше.`;
+
+export async function verifyAnswer(input: ReflectInput): Promise<ReflectResult> {
+  // Trivial / empty answers don't need a verifier — they cannot hallucinate.
+  // This guards against pointless LLM calls on the NO_CONTEXT path and on
+  // the smalltalk/persona-fact short-circuits (those return without context).
+  const trimmed = input.answer.trim();
+  if (trimmed.length === 0) return { grounded: true };
+  if (input.context.trim().length === 0) {
+    // If the generator had no KB context but produced a non-empty answer,
+    // we can't verify anything — let it through. The KB-grounding rules in
+    // the system prompt already force NO_CONTEXT_MARKER on missing data.
+    return { grounded: true };
+  }
+
+  const userPrompt = `ВОПРОС: ${input.question}\n\nКОНТЕКСТ:\n${input.context}\n\nОТВЕТ: ${trimmed}\n\nJSON:`;
+
+  const messages: ChatMessage[] = [
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: userPrompt },
+  ];
+
+  let raw: string;
+  try {
+    raw = await input.chat.complete(messages, { temperature: 0.0 });
+  } catch (err) {
+    console.error("[reflect] LLM call failed; treating as grounded:", err);
+    return { grounded: true };
+  }
+
+  return parseReflection(raw);
+}
+
+/** 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 function parseReflection(raw: string): ReflectResult {
+  const s = stripCodeFences(stripThinkBlocks(raw)).trim();
+  const start = s.indexOf("{");
+  const end = s.lastIndexOf("}");
+  if (start === -1 || end === -1 || end < start) return { grounded: true };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(s.slice(start, end + 1));
+  } catch {
+    return { grounded: true };
+  }
+
+  if (typeof parsed !== "object" || parsed === null) return { grounded: true };
+  const obj = parsed as Record<string, unknown>;
+  const grounded = obj.grounded;
+  if (typeof grounded !== "boolean") return { grounded: true };
+  if (grounded) return { grounded: true };
+  const reason = typeof obj.reason === "string" ? obj.reason : "unknown";
+  return { grounded: false, reason };
+}