Skip to content

feat: kb.synthesize — answer-mode retrieval over the review-gated KB #222

Description

@plind-junior

What you're trying to do

gbrain's headline pitch is "search gives you raw pages; gbrain gives you the answer." Today kb.context returns a ranked list of approved claims with citations — useful, but the calling agent still has to synthesise. The natural vouch shape, distinct from gbrain's, is review-gated synthesis: answer only from approved claims, surface explicit gaps ("the KB doesn't know X"), and never hallucinate around a missing citation.

This is the single biggest functional differentiator vouch lacks. Done right, it turns the review gate from a constraint into a feature: every word in the synthesis traces to a claim a human approved.

Suggested shape

vouch synthesize "what's our auth model?" [--depth 3] [--max-chars 4000]
# CLI; same surface available as kb.synthesize over MCP + JSONL
  • New src/vouch/synthesize.py builds an answer by walking the existing kb.context ranking, then composing a paragraph per relevant cluster with inline [<claim_id>] citations.
  • Refuses to synthesise across uncited spans; every sentence carries at least one citation.
  • A trailing gaps: block lists topics the query implies but no approved claim covers (gaps: ["mfa", "session-rotation"]).
  • Configurable backend: deterministic (template-driven) by default; --llm opts into an LLM-mediated rewrite that still must cite each sentence — the deterministic path is the audit-friendly default.
  • _meta.synthesis_confidence field on the response: high (every sentence cited from a stable claim), medium (some working-status claims), low (contested claims present).

Acceptance

  • A KB with 3 approved claims about auth produces a 1-paragraph synthesis citing all 3 by id.
  • A query the KB doesn't cover produces an empty body + a populated gaps: block.
  • Synthesis never includes text not traceable to an approved claim (a fuzz test asserts this).
  • kb.synthesize is reachable over MCP stdio, JSONL, HTTP (chore(deps): bump actions/setup-python from 5 to 6 #1), and kb.capabilities lists it.

Out of scope

  • Multi-turn dialogue.
  • Cross-KB synthesis (federation territory).
  • LLM-mediated synthesis as the default — opt-in only.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions