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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions