secondbrain-py 0.2.1__py3-none-any.whl

brain/enrichment.py

@@ -0,0 +1,808 @@
+"""Local-Ollama enrichment: per-document summary + tag proposals.
+
+One module, two consumers: the post-ingest auto-summary hook in
+``brain.ingest.__init__`` and the interactive ``brain tag --auto`` flow in
+``brain.cli``. Both go through :class:`OllamaEnricher` so HTTP transport,
+JSON-mode handling, timeouts, and retry policy live in one place.
+
+Ollama is the only backend in Wave Q1-D — no Claude Haiku / OpenAI / Voyage
+surface. Model is configurable via ``BRAIN_ENRICH_MODEL`` (default
+``llama3.1:8b``). The class reuses the ``httpx.Client`` transport pattern
+from :class:`brain.embeddings._OllamaEmbedderBase` but does NOT subclass it:
+the embedder hits ``/api/embed`` for vectors and the enricher hits
+``/api/chat`` for JSON completions, so a shared parent would carry no
+shared logic.
+
+Model upgrade semantics
+-----------------------
+``documents.summary_model`` records the model fingerprint of every persisted
+summary. The post-ingest hook and ``brain enrich --backfill`` both treat
+"existing summary AND ``summary_model == cfg.enrich_model``" as up-to-date;
+when the user upgrades ``BRAIN_ENRICH_MODEL`` (e.g. ``llama3.1:8b`` →
+``llama3.2:8b``), every doc whose stored summary was generated by the OLD
+model is automatically re-enriched on next ingest / next backfill run. The
+behavior is keyed on ``OllamaEnricher.model`` (the property), so callers
+that pass a fake enricher in tests can control the comparison without
+monkey-patching the production module.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import tiktoken
+
+from .chat import ChatMessage, chat_json_with_client
+from .config import Config
+from .errors import EnrichmentError
+from .tags import normalize_tags
+
+_logger = logging.getLogger(__name__)
+
+# Module-level keep_alive fallback — matches embeddings.py convention. Tests
+# that construct OllamaEnricher without an explicit ``keep_alive`` kwarg get
+# this default; production always threads ``Config.ollama_keep_alive``.
+_DEFAULT_KEEP_ALIVE = "30m"
+
+# D20 — banned auto-tag formats. These are ``documents.content_type`` values
+# (or close synonyms) that the LLM should never propose as semantic tags.
+# Belt-and-braces with the prompt: a prompt-injection / model drift case that
+# slipped one past the prompt is still filtered at the Python layer. Stored
+# casefold-lower-hyphen-normalized so the post-``normalize_tags`` comparison
+# is a direct membership check.
+_BANNED_AUTO_TAGS = frozenset(
+    {
+        "pdf",
+        "transcript",
+        "email",
+        "email-thread",
+        "note",
+        "docx",
+        "markdown",
+        "text",
+        "krisp-action-items",
+    }
+)
+
+
+_SUMMARY_SYSTEM_PROMPT = (
+    "You write 2-3 sentence summaries of personal-knowledge-base documents.\n"
+    "\n"
+    "The user gives you a TITLE and a BODY. Return ONLY valid JSON:\n"
+    '{"summary": "..."}\n'
+    "\n"
+    "The summary must:\n"
+    "- be 2-3 sentences, factual, written in plain past tense\n"
+    "- name specific people / projects / dates if they appear in the body\n"
+    "- never invent facts, never include \"this document discusses\" filler\n"
+    "- never exceed 60 words"
+)
+
+
+_TAG_SYSTEM_PROMPT = (
+    "You propose tags for a personal-knowledge-base document.\n"
+    "\n"
+    "Inputs: TITLE, SUMMARY, EXISTING_VOCAB (tags already used in the corpus),\n"
+    "CURRENT_TAGS (tags already on this doc).\n"
+    "\n"
+    "Return ONLY valid JSON:\n"
+    '{"tags": ["tag1", "tag2", "tag3"]}\n'
+    "\n"
+    "Rules:\n"
+    "- propose 3 to 5 tags\n"
+    "- prefer tags from EXISTING_VOCAB; only propose new tags when no existing tag fits\n"
+    "- lowercase, hyphen-separated (e.g. \"interview-prep\", \"company-acme\")\n"
+    "- never propose tags already in CURRENT_TAGS\n"
+    "- never propose more than 5 tags\n"
+    "- never propose tags about file format (pdf, docx, transcript) — those are tracked elsewhere\n"
+    "- never propose tags about timing (recent, old, last-week)"
+)
+
+
+# Wave G2-b — concept entity extraction (spec §3 D3 / §8). The extractor
+# *backend* lives here (transport, JSON-mode, retry) so it shares one place with
+# ``summarize`` / ``propose_tags``; the concept-extraction *logic* (chunking,
+# canonicalization, position-finding, per-doc cap, never-raise) lives in
+# :mod:`brain.graph_rag.extract`. ``type`` is constrained to the four concept
+# entity types — people are derived for free from the participants pipeline and
+# are deliberately NOT extracted here (spec §17b decision 2: "people excluded").
+_EXTRACT_SYSTEM_PROMPT = (
+    "You extract the salient non-person CONCEPT entities from a "
+    "personal-knowledge-base document.\n"
+    "\n"
+    "Return ONLY valid JSON:\n"
+    '{"entities": [{"name": "...", "type": "topic"}]}\n'
+    "\n"
+    "type MUST be exactly one of: org, project, tool, topic.\n"
+    "Use the entity's surface form exactly as it appears in the text for name.\n"
+    "\n"
+    "Type rules:\n"
+    "- org: a company or provider whose hosted service or platform you consume "
+    "or integrate with — e.g. a payments, identity, data-warehouse, or cloud "
+    "provider. Use the company name.\n"
+    "- tool: software you run, deploy, operate, import, or build with — a "
+    "framework, library, language, database, monitoring agent, or server.\n"
+    "- project: a named initiative or effort. Keep the FULL name including a "
+    'leading word like "Project" (return the whole "Project <name>" form, never '
+    "just the bare name).\n"
+    "- topic: a central, durable theme or subject area the document is about, "
+    "usually one or two words.\n"
+    "\n"
+    "Topic guidance:\n"
+    "- Capture the few themes the text frames as central. Look for "
+    "importance-signaling language — examples (not an exhaustive list) include "
+    '"the main topic", "the recurring theme", "the headline", "dominated the '
+    'discussion", "a major focus was", "central to the conversation", "we kept '
+    'coming back to", or "came up repeatedly" — and any similar phrasing that '
+    "marks something as important, as well as the core subject the document "
+    "centers on.\n"
+    "- Also capture the core subject word that a named effort or platform is "
+    'about — the domain word inside phrases like a "<X> effort", "<X> '
+    'initiative", "<X> platform", or "<X> stack" (extract <X> as the topic).\n'
+    "- Return roughly 1-3 topics, and prefer the short theme word over a long "
+    "phrase (the one- or two-word theme, not a verbose feature description).\n"
+    "\n"
+    "Never extract:\n"
+    "- people or person names (they are tracked separately)\n"
+    "- dates, times, or file formats\n"
+    "- document-structure references (PDF, chapter, section, page, table, "
+    "figure, appendix, heading)\n"
+    "- generic activities or events (meetings, reviews, sprints, workshops)\n"
+    "- incidental UI or implementation nouns, or one-off mentions that are not a "
+    "central theme\n"
+    "- vague container words (platform, service, system, dashboard) on their own\n"
+    "\n"
+    "CRITICAL: Extract ONLY entities that appear LITERALLY in THIS text. Copy the "
+    "name exactly as written. Never invent a name, never add a name that is not "
+    "in the text, and never copy a name from these instructions or from a "
+    "previous document.\n"
+    "\n"
+    "The bracketed words in the FORMAT example below are PLACEHOLDERS showing the "
+    "JSON shape only. They are NOT real entities — never output them.\n"
+    "FORMAT (schematic — replace each placeholder with a real name from the "
+    "text, or omit it):\n"
+    'JSON: {"entities": [{"name": "<the hosted provider named in the text>", '
+    '"type": "org"}, {"name": "Project <the effort named in the text>", '
+    '"type": "project"}, {"name": "<the software tool named in the text>", '
+    '"type": "tool"}, {"name": "<the central theme of the text>", '
+    '"type": "topic"}]}\n'
+    "\n"
+    "When THIS text contains no org, project, tool, or topic entities, return an "
+    "empty list. Do NOT fill it with examples or guesses:\n"
+    'JSON: {"entities": []}'
+)
+
+
+# Wave G2-f — on-demand theme synthesis (spec §6b step 4 / §17b decision 7).
+# Opt-in (``--synthesize``); best-effort and never required for retrieval.
+
+# Wave elicit — articulate tacit rules the user follows but has never written
+# down.  The enricher holds the LLM transport; the elicit drafter owns the
+# orchestration logic.
+_ELICIT_SYSTEM_PROMPT = (
+    "You are articulating a tacit rule the user follows in their work but has "
+    "never written down. You are given a subject and evidence excerpts drawn from "
+    "their meetings, messages, and notes. State the single most likely underlying "
+    "rule as a confident, first-person assertion the user can quickly confirm or "
+    "correct. Be specific and concrete; do not hedge. Respond with JSON: "
+    '{"title": "<short imperative title>", "rule": "<1-3 sentence rule in first person>"}.'
+)
+
+_GROUP_SUMMARY_SYSTEM_PROMPT = (
+    "You write a one-to-two sentence synthesis of a cluster of related topics "
+    "from a personal knowledge base.\n"
+    "\n"
+    "Inputs: PERSON/SCOPE (the person the themes are about, if any), TOPICS "
+    "(the cluster's key entities), and REPRESENTATIVE DOCUMENTS (their titles).\n"
+    "\n"
+    "Return ONLY valid JSON:\n"
+    '{"summary": "..."}\n'
+    "\n"
+    "Rules:\n"
+    "- 1-2 sentences, factual, plain past tense\n"
+    "- name the specific topics that tie the cluster together\n"
+    "- never invent facts, never exceed 50 words"
+)
+
+# Plan 05 — `brain timeline --synthesize`. Per-time-bucket narrative synthesis
+# GROUNDED in the period's document SUMMARIES (not just titles): write a concrete
+# "what happened this period" line naming the actual decisions / deliverables /
+# problems. When a PREVIOUS period is supplied the model states what CHANGED.
+# Best-effort + never-raises, same discipline as :data:`_GROUP_SUMMARY_SYSTEM_PROMPT`.
+_BUCKET_SUMMARY_SYSTEM_PROMPT = (
+    "You write a 1-3 sentence synthesis of what concretely happened in one time "
+    "period for a recurring theme in a personal knowledge base. You are graded on "
+    "SPECIFICITY: a reader must learn something they could not guess from the "
+    "topic name alone.\n"
+    "\n"
+    "Inputs: PERIOD (the time-bucket label), ENTITY (the theme tracked over "
+    "time), CO-TOPICS (entities that co-occurred this period), DOCUMENT SUMMARIES "
+    "(the period's source-document summaries — your PRIMARY evidence), DOCUMENT "
+    "TITLES, and optionally PREVIOUS PERIOD (the prior bucket's label, co-topics, "
+    "and synthesis) for contrast.\n"
+    "\n"
+    "Return ONLY valid JSON:\n"
+    '{"summary": "..."}\n'
+    "\n"
+    "Rules:\n"
+    "- Ground EVERY claim in the DOCUMENT SUMMARIES. Name the concrete specifics "
+    "they contain: decisions made, deliverables or artifacts produced, problems "
+    "or blockers hit, and named systems / tools / documents.\n"
+    "- If a PREVIOUS PERIOD is given, state what CHANGED versus it (a new focus, a "
+    "decision reversed, a problem resolved) — but ONLY when the summaries support "
+    "it; never fabricate a change.\n"
+    "- FORBIDDEN — these phrasings are an automatic failure: 'discussions about', "
+    "'discussions on', 'conversations around', 'connecting to', 'topics related "
+    "to', 'focused on various', 'a range of', 'integration, reports, and "
+    "planning', or any vacuous paraphrase of the topic / co-topic names.\n"
+    "- 1-3 sentences, factual, plain past tense. Never invent facts. Never exceed "
+    "60 words. If the summaries are too thin to say anything concrete, write a "
+    "single short factual sentence rather than padding with generic filler."
+)
+
+# Wave elicit Wave 4 — contradiction detection between document summaries.
+# The model is given a subject entity and several summary excerpts from
+# different documents and must decide whether they express CONTRADICTORY
+# positions or decisions about that entity (a reversed decision, opposing
+# stance, or conflicting fact).
+_CONTRADICTION_SYSTEM_PROMPT = (
+    "You are given an entity subject and several summary excerpts drawn from "
+    "different documents in a personal knowledge base. Your task is to decide "
+    "whether the excerpts express CONTRADICTORY positions, decisions, or facts "
+    "about that entity — for example a reversed decision, an opposing stance, "
+    "or a directly conflicting statement of fact. Minor differences in emphasis "
+    "or level of detail are NOT contradictions. Return ONLY valid JSON:\n"
+    '{"contradicts": <true|false>, "rationale": "<one sentence>"}\n'
+    "\n"
+    "Rules:\n"
+    '- "contradicts" MUST be a JSON boolean (true or false, no quotes)\n'
+    "- \"rationale\" must be a single sentence explaining the contradiction (or lack thereof)\n"
+    "- never invent facts not present in the excerpts\n"
+    "- when in doubt, return false"
+)
+
+# Token budget for the concept-extraction completion. Larger than the
+# summary/tag budget (256) because a document can yield a long entity list.
+_EXTRACT_NUM_PREDICT = 1024
+
+# Recognized string forms for a boolean ``contradicts`` verdict. The model is
+# instructed to return a JSON boolean, but small local models occasionally
+# stringify it; we tolerate ONLY these exact (stripped, lowercased) forms and
+# raise on anything else rather than silently coercing arbitrary truthiness.
+_CONTRADICTS_TRUE_STRINGS = frozenset({"true", "yes", "1"})
+_CONTRADICTS_FALSE_STRINGS = frozenset({"false", "no", "0"})
+
+
+@dataclass(frozen=True)
+class SummaryResult:
+    """One enrichment summary. Stored byte-for-byte on ``documents.summary``.
+
+    ``model`` is the model fingerprint (e.g. ``"llama3.1:8b"``) so the
+    post-ingest hook can persist it onto ``documents.summary_model`` and
+    ``brain enrich --backfill --remodel`` can detect drift after a model
+    swap (without ``--remodel``, backfill is NULL-only and ignores
+    fingerprint mismatches).
+    """
+
+    summary: str
+    model: str
+
+
+@dataclass(frozen=True)
+class RuleDraft:
+    """A drafted tacit rule for the user to confirm or correct.
+
+    ``title`` is a short imperative phrase; ``rule_text`` is the 1-3 sentence
+    first-person assertion.  ``model`` is the Ollama model fingerprint so
+    callers can persist provenance alongside the draft.
+    """
+
+    title: str
+    rule_text: str
+    model: str
+
+
+@dataclass(frozen=True)
+class ContradictionVerdict:
+    """Assessment of whether document summaries express conflicting positions.
+
+    ``contradicts`` is True when the LLM detected a genuine contradiction
+    (reversed decision, opposing stance, conflicting fact) in the evidence
+    summaries for a given subject entity.  ``rationale`` is a one-sentence
+    explanation suitable for display in ``brain elicit``.
+    """
+
+    contradicts: bool
+    rationale: str
+
+
+@dataclass(frozen=True)
+class TagProposal:
+    """The LLM's proposed tag set for one document, partitioned by novelty.
+
+    ``existing`` are tags already used somewhere in the corpus; ``new`` are
+    tags the LLM proposed that aren't in the vocabulary yet (already
+    rate-limited to ≤``max_new`` entries — default 1 — by
+    :meth:`OllamaEnricher.propose_tags`).
+    """
+
+    existing: list[str]
+    new: list[str]
+
+
+class OllamaEnricher:
+    """Thin wrapper over Ollama's ``/api/chat`` endpoint with JSON mode.
+
+    One instance, one model. Callers (post-ingest hook, ``brain enrich``,
+    ``brain tag --auto``) instantiate via :func:`make_enricher` and reuse
+    the same instance for the lifetime of a CLI invocation.
+
+    Public surface:
+        - ``summarize(title, content)`` → :class:`SummaryResult`
+        - ``propose_tags(title, summary, existing_vocab, current_tags, max_new=1)``
+            → :class:`TagProposal`
+        - ``extract_entities(text)`` → ``list[Any]`` (raw concept-entity
+            candidates; the concept-extraction *logic* lives in
+            :mod:`brain.graph_rag.extract`)
+        - ``summarize_group(person, entity_names, doc_titles)`` → ``str | None``
+            (best-effort theme synthesis; never raises)
+        - ``summarize_bucket(bucket_label, entity_name, doc_titles, cotopics)``
+            → ``str | None`` (best-effort timeline-bucket synthesis; never raises)
+        - ``count_tokens(text)`` → int (tiktoken ``cl100k_base``)
+        - ``model`` (read-only attribute) → the model fingerprint
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str,
+        model: str,
+        client: httpx.Client | None = None,
+        timeout: float = 60.0,
+        max_input_tokens: int = 4000,
+        keep_alive: str = _DEFAULT_KEEP_ALIVE,
+    ) -> None:
+        self._host = host
+        self._model = model
+        self._max_input_tokens = max_input_tokens
+        self._keep_alive = keep_alive
+        self._tokenizer = tiktoken.get_encoding("cl100k_base")
+        if client is not None:
+            self._client = client
+        else:
+            self._client = httpx.Client(
+                base_url=host, timeout=httpx.Timeout(timeout)
+            )
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    def count_tokens(self, text: str) -> int:
+        """Return the number of tokens in ``text`` per ``cl100k_base``."""
+        return len(self._tokenizer.encode(text))
+
+    def truncate_to_tokens(self, text: str, max_tokens: int) -> str:
+        """Return the head of ``text`` truncated to its first ``max_tokens`` tokens.
+
+        Head-only truncation using the SAME ``cl100k_base`` tokenizer as
+        :meth:`count_tokens`, so a caller's truncation boundary is consistent with
+        the chunk budgeting that also goes through ``count_tokens`` — the concept
+        extractor's input head cap (perf Fix C, 2026-05-24) reuses this so its cap
+        and its per-chunk token sizing agree. The full text is returned unchanged
+        when it already fits. ``max_tokens`` must be positive. Cheap: one encode +
+        one decode.
+        """
+        if max_tokens < 1:
+            raise ValueError(
+                f"max_tokens must be a positive integer (got {max_tokens})"
+            )
+        ids = self._tokenizer.encode(text)
+        if len(ids) <= max_tokens:
+            return text
+        return self._tokenizer.decode(ids[:max_tokens])
+
+    def _truncate_to_budget(self, text: str) -> str:
+        """Truncate ``text`` to this enricher's summary input budget (head-only).
+
+        Delegates to :meth:`truncate_to_tokens` with ``self._max_input_tokens``
+        (the per-instance summary cap, default 4000): the opening of a doc is the
+        highest-signal portion for transcripts, emails, and notes alike.
+        """
+        return self.truncate_to_tokens(text, self._max_input_tokens)
+
+    def summarize(self, title: str, content: str) -> SummaryResult:
+        """Return a 2-3 sentence summary of ``content``.
+
+        Calls ``/api/chat`` with ``format='json'`` and a system prompt that
+        constrains the model to emit ``{"summary": "..."}``. On JSON parse
+        failure or missing key, retries ONCE with the same prompt. Second
+        failure raises :class:`EnrichmentError`. Connection / 5xx errors
+        raise :class:`OllamaUnavailable` immediately (no retry — Ollama-down
+        is the common case and we want to fail fast so the post-ingest hook
+        can skip).
+        """
+        truncated = self._truncate_to_budget(content)
+        user_message = f"TITLE: {title}\n\nBODY:\n{truncated}"
+        body = self._chat_with_retry(
+            system=_SUMMARY_SYSTEM_PROMPT,
+            user=user_message,
+            schema_keys=("summary",),
+        )
+        summary = body["summary"]
+        if not isinstance(summary, str) or not summary.strip():
+            raise EnrichmentError(
+                f"summarize: model returned non-string / empty summary: {body!r}"
+            )
+        return SummaryResult(summary=summary.strip(), model=self._model)
+
+    def propose_tags(
+        self,
+        *,
+        title: str,
+        summary: str,
+        existing_vocab: list[str],
+        current_tags: list[str],
+        max_new: int = 1,
+    ) -> TagProposal:
+        """Return 3-5 proposed tags partitioned into existing-vocab + new.
+
+        Returned tags are normalized via :func:`brain.tags.normalize_tags`,
+        de-duplicated against ``current_tags`` (we never re-propose tags
+        already on the doc), banned-format tags are dropped at the Python
+        layer (D20 belt-and-braces), and the ``new`` partition is truncated
+        to the first ``max_new`` entries (default 1) per the R2 mitigation
+        in the wave plan.
+        """
+        if max_new < 0:
+            raise ValueError(f"max_new must be non-negative (got {max_new})")
+        # Normalize the vocab + current-tags so the LLM sees canonical forms
+        # and the post-call partitioning compares normalized to normalized.
+        vocab_normalized = normalize_tags(existing_vocab)
+        current_normalized = set(normalize_tags(current_tags))
+        user_message = (
+            f"TITLE: {title}\n\n"
+            f"SUMMARY: {summary}\n\n"
+            f"EXISTING_VOCAB: {json.dumps(vocab_normalized)}\n"
+            f"CURRENT_TAGS: {json.dumps(sorted(current_normalized))}"
+        )
+        body = self._chat_with_retry(
+            system=_TAG_SYSTEM_PROMPT,
+            user=user_message,
+            schema_keys=("tags",),
+        )
+        raw_tags = body["tags"]
+        if not isinstance(raw_tags, list) or not all(
+            isinstance(t, str) for t in raw_tags
+        ):
+            raise EnrichmentError(
+                f"propose_tags: model returned non-list-of-str tags: {body!r}"
+            )
+        normalized = normalize_tags(raw_tags)
+        # Drop banned formats (D20) BEFORE partitioning so they can't sneak
+        # into either bucket.
+        normalized = [t for t in normalized if t not in _BANNED_AUTO_TAGS]
+        # Drop anything already on the doc — no point proposing what's there.
+        normalized = [t for t in normalized if t not in current_normalized]
+        vocab_set = set(vocab_normalized)
+        existing: list[str] = []
+        new: list[str] = []
+        for tag in normalized:
+            if tag in vocab_set:
+                existing.append(tag)
+            else:
+                new.append(tag)
+        return TagProposal(existing=existing, new=new[:max_new])
+
+    def extract_entities(self, text: str) -> list[Any]:
+        """Return the model's raw concept-entity candidates for one text block.
+
+        One ``/api/chat`` JSON-mode round-trip with the concept-extraction
+        system prompt. Returns the model's ``entities`` array verbatim — a list
+        whose individual elements the caller (:class:`brain.graph_rag.extract.
+        OllamaExtractor`) validates, canonicalizes, positions, dedups, and caps.
+        This method does NOT chunk: the extractor sizes each ``text`` block to
+        the model context and calls once per chunk.
+
+        Raises :class:`OllamaUnavailable` / :class:`EnrichmentError` on transport
+        / malformed-response failures exactly like :meth:`summarize`. The
+        never-raise boundary is the :class:`~brain.graph_rag.extract.
+        OllamaExtractor`, which catches these so a gated ingest never breaks
+        (spec §17b decision 7 / §7 never-raise discipline).
+        """
+        body = self._chat_with_retry(
+            system=_EXTRACT_SYSTEM_PROMPT,
+            user=f"TEXT:\n{text}",
+            schema_keys=("entities",),
+            num_predict=_EXTRACT_NUM_PREDICT,
+        )
+        entities = body["entities"]
+        if not isinstance(entities, list):
+            raise EnrichmentError(
+                f"extract_entities: model returned non-list entities: {body!r}"
+            )
+        return entities
+
+    def summarize_group(
+        self,
+        *,
+        person: str | None,
+        entity_names: list[str],
+        doc_titles: list[str],
+    ) -> str | None:
+        """Best-effort one-to-two sentence synthesis of a theme group.
+
+        Used by the G2-f ``--synthesize`` path (spec §6b step 4 / §17b decision
+        7): opt-in, default-off, and **never required for retrieval**. Returns
+        the synthesized text, or ``None`` (logging a WARN) when Ollama is
+        unavailable / times out / returns invalid JSON / yields an empty
+        summary. NEVER raises — mirroring the GraphSyncer + enrich never-raise
+        discipline so a retrieval path never becomes a hard live-Ollama
+        dependency.
+        """
+        scope = f" {person}" if person else " (none)"
+        user_message = (
+            f"PERSON/SCOPE:{scope}\n"
+            f"TOPICS: {json.dumps(entity_names)}\n"
+            f"REPRESENTATIVE DOCUMENTS: {json.dumps(doc_titles)}"
+        )
+        try:
+            body = self._chat_with_retry(
+                system=_GROUP_SUMMARY_SYSTEM_PROMPT,
+                user=user_message,
+                schema_keys=("summary",),
+            )
+        except EnrichmentError as exc:
+            # OllamaUnavailable is an EnrichmentError subclass, so this single
+            # clause covers transport failure AND malformed-JSON-twice.
+            _logger.warning(
+                "summarize_group: synthesis failed (%s); returning summary=None",
+                exc,
+            )
+            return None
+        summary = body["summary"]
+        if not isinstance(summary, str) or not summary.strip():
+            _logger.warning(
+                "summarize_group: model returned empty / non-string summary; "
+                "returning summary=None"
+            )
+            return None
+        return summary.strip()
+
+    def summarize_bucket(
+        self,
+        *,
+        bucket_label: str,
+        entity_name: str,
+        doc_titles: list[str],
+        cotopics: list[str],
+        doc_summaries: list[str] | None = None,
+        prev_bucket_label: str | None = None,
+        prev_cotopics: list[str] | None = None,
+        prev_synthesis: str | None = None,
+    ) -> str | None:
+        """Best-effort 1-3 sentence, content-grounded synthesis of one timeline bucket.
+
+        Used by the Plan 05 ``brain timeline --synthesize`` path: opt-in,
+        default-off, and **never required** for the timeline to render.
+
+        ``doc_summaries`` is the period's source-document summaries (the caller
+        token-budgets the bundle and falls back to titles where a summary is
+        NULL). They are the model's PRIMARY evidence — passing them is what makes
+        the synthesis concrete instead of a paraphrase of the titles. The
+        ``prev_*`` parameters carry the chronologically PREVIOUS bucket's label /
+        co-topics / already-generated synthesis so the model can state what
+        CHANGED (the caller synthesizes oldest→newest so a prior synthesis is
+        available). All four new params are optional and default-absent so older
+        callers keep working.
+
+        Returns the synthesized text, or ``None`` (logging a WARN) when Ollama is
+        unavailable / times out / returns invalid JSON / yields an empty summary.
+        NEVER raises — mirroring :meth:`summarize_group`'s never-raise discipline
+        so the display command never becomes a hard live-Ollama dependency.
+        """
+        parts = [
+            f"PERIOD: {bucket_label}",
+            f"ENTITY: {entity_name}",
+            f"CO-TOPICS: {json.dumps(cotopics)}",
+            f"DOCUMENT SUMMARIES: {json.dumps(doc_summaries or [])}",
+            f"DOCUMENT TITLES: {json.dumps(doc_titles)}",
+        ]
+        if prev_bucket_label:
+            prev_lines = [f"PREVIOUS PERIOD: {prev_bucket_label}"]
+            prev_lines.append(f"PREVIOUS CO-TOPICS: {json.dumps(prev_cotopics or [])}")
+            if prev_synthesis:
+                prev_lines.append(f"PREVIOUS SYNTHESIS: {prev_synthesis}")
+            parts.append("\n".join(prev_lines))
+        user_message = "\n".join(parts)
+        try:
+            body = self._chat_with_retry(
+                system=_BUCKET_SUMMARY_SYSTEM_PROMPT,
+                user=user_message,
+                schema_keys=("summary",),
+            )
+        except EnrichmentError as exc:
+            # OllamaUnavailable is an EnrichmentError subclass, so this single
+            # clause covers transport failure AND malformed-JSON-twice.
+            _logger.warning(
+                "summarize_bucket: synthesis failed (%s); returning summary=None",
+                exc,
+            )
+            return None
+        summary = body["summary"]
+        if not isinstance(summary, str) or not summary.strip():
+            _logger.warning(
+                "summarize_bucket: model returned empty / non-string summary; "
+                "returning summary=None"
+            )
+            return None
+        return summary.strip()
+
+    def draft_rule(self, *, subject: str, evidence_texts: list[str]) -> RuleDraft:
+        """Articulate the tacit rule implied by ``subject`` and ``evidence_texts``.
+
+        Calls ``/api/chat`` with :data:`_ELICIT_SYSTEM_PROMPT` and a numbered
+        excerpt prompt built by :meth:`_build_elicit_user_prompt`.  The caller
+        (``GapDrafter``) is responsible for pre-truncating ``evidence_texts``
+        to a reasonable token budget; this method joins them as-is.
+
+        Raises :class:`OllamaUnavailable` on transport failure and
+        :class:`EnrichmentError` on two consecutive bad responses — the same
+        contract as :meth:`summarize`.
+        """
+        user = self._build_elicit_user_prompt(subject, evidence_texts)
+        data = self._chat_with_retry(
+            system=_ELICIT_SYSTEM_PROMPT,
+            user=user,
+            schema_keys=("title", "rule"),
+            num_predict=256,
+        )
+        title = data["title"]
+        if not isinstance(title, str) or not title.strip():
+            raise EnrichmentError(
+                f"draft_rule: model returned non-string / empty title: {data!r}"
+            )
+        rule_text = data["rule"]
+        if not isinstance(rule_text, str) or not rule_text.strip():
+            raise EnrichmentError(
+                f"draft_rule: model returned non-string / empty rule: {data!r}"
+            )
+        return RuleDraft(
+            title=title.strip(),
+            rule_text=rule_text.strip(),
+            model=self._model,
+        )
+
+    def _build_elicit_user_prompt(
+        self, subject: str, evidence_texts: list[str]
+    ) -> str:
+        """Compose the user-turn prompt for :meth:`draft_rule`.
+
+        Joins ``subject`` and numbered evidence excerpts into a clear prompt.
+        Evidence texts are assumed pre-truncated by the caller; this method
+        only formats them.
+        """
+        parts = [f"SUBJECT: {subject}", ""]
+        for i, text in enumerate(evidence_texts, 1):
+            parts.append(f"EXCERPT {i}:\n{text}")
+        return "\n".join(parts)
+
+    def assess_contradiction(
+        self, *, subject: str, summaries: list[str]
+    ) -> ContradictionVerdict:
+        """Decide whether ``summaries`` express contradictory positions about ``subject``.
+
+        Calls ``/api/chat`` with :data:`_CONTRADICTION_SYSTEM_PROMPT` and a
+        numbered-excerpt prompt.  Returns a :class:`ContradictionVerdict` with
+        ``contradicts=True`` when a genuine conflict is detected.
+
+        Raises :class:`OllamaUnavailable` on transport failure and
+        :class:`EnrichmentError` on two consecutive bad responses — the same
+        contract as :meth:`draft_rule`.
+        """
+        user = self._build_contradiction_user_prompt(subject, summaries)
+        data = self._chat_with_retry(
+            system=_CONTRADICTION_SYSTEM_PROMPT,
+            user=user,
+            schema_keys=("contradicts", "rationale"),
+            num_predict=200,
+        )
+        contradicts = self._coerce_contradicts(data)
+        rationale = data["rationale"]
+        if not isinstance(rationale, str) or not rationale.strip():
+            raise EnrichmentError(
+                "assess_contradiction: model returned non-string / empty "
+                f"rationale: {data!r}"
+            )
+        return ContradictionVerdict(
+            contradicts=contradicts, rationale=rationale.strip()
+        )
+
+    @staticmethod
+    def _coerce_contradicts(data: dict[str, Any]) -> bool:
+        """Validate + coerce the ``contradicts`` field into a real bool.
+
+        Accepts a JSON boolean directly. Tolerates the common stringified
+        forms ("true"/"false"/"yes"/"no"/"1"/"0", case-insensitive) some local
+        models emit. Anything else — a number, a dict, an unrecognized string —
+        raises :class:`EnrichmentError` (parity with :meth:`draft_rule`, which
+        refuses to coerce malformed output) rather than silently treating
+        arbitrary truthiness as a verdict.
+        """
+        value = data["contradicts"]
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            token = value.strip().lower()
+            if token in _CONTRADICTS_TRUE_STRINGS:
+                return True
+            if token in _CONTRADICTS_FALSE_STRINGS:
+                return False
+        raise EnrichmentError(
+            f"assess_contradiction: non-boolean contradicts verdict: {data!r}"
+        )
+
+    def _build_contradiction_user_prompt(
+        self, subject: str, summaries: list[str]
+    ) -> str:
+        """Compose the user-turn prompt for :meth:`assess_contradiction`.
+
+        Joins ``subject`` and numbered summary excerpts into a clear prompt.
+        """
+        parts = [f"SUBJECT: {subject}", ""]
+        for i, summary in enumerate(summaries, 1):
+            parts.append(f"SUMMARY {i}:\n{summary}")
+        return "\n".join(parts)
+
+    def _chat_with_retry(
+        self,
+        *,
+        system: str,
+        user: str,
+        schema_keys: tuple[str, ...],
+        num_predict: int = 256,
+    ) -> dict[str, Any]:
+        """Issue an ``/api/chat`` JSON-mode call with one retry on parse failure.
+
+        Thin adapter over the shared transport + retry core in
+        :func:`brain.chat.chat_json_with_client`. Preserves the enricher's
+        exact two-message (system + user) wire shape and its persistent
+        injected ``httpx.Client`` (the retry / truncation-bump / transport
+        error policy lives once, in ``chat``). Returns the parsed JSON object;
+        raises :class:`~brain.errors.OllamaUnavailable` on transport failure
+        (no retry) and :class:`EnrichmentError` on two consecutive bad
+        responses — the unchanged contract every caller depends on.
+        """
+        messages: list[ChatMessage] = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+        return chat_json_with_client(
+            self._client,
+            model=self._model,
+            messages=messages,
+            required_keys=schema_keys,
+            keep_alive=self._keep_alive,
+            num_predict=num_predict,
+        )
+
+
+def make_enricher(cfg: Config) -> OllamaEnricher:
+    """Factory — same shape as :func:`brain.embeddings.make_embedder`.
+
+    Reads ``cfg.enrich_model`` / ``cfg.ollama_host`` /
+    ``cfg.enrich_max_input_tokens`` / ``cfg.enrich_timeout_seconds`` and
+    always returns an :class:`OllamaEnricher` (single-backend wave). Tests
+    pass a fake via direct construction or by substituting at the call site;
+    production code goes through this factory.
+    """
+    return OllamaEnricher(
+        host=cfg.ollama_host,
+        model=cfg.enrich_model,
+        timeout=cfg.enrich_timeout_seconds,
+        max_input_tokens=cfg.enrich_max_input_tokens,
+        keep_alive=cfg.ollama_keep_alive,
+    )