Sign in

v2

latestOpenAPI 3.1.02026-08-0382170235.8 KB
synthesis
synthesis

Answer a question with receipts (facts + scores + provenance)

Retrieve relevant facts from a POT and produce a synthesized natural-language answer with receipts: cited facts, POT Scores, source provenance, detected contradictions, and an optional epistemic briefing summarizing the system's confidence and coverage gaps.

Flow under the hood:

  1. The Hybrid Router classifies the query and selects an optimal retrieval strategy — CAG (cached, <5ms), RAG (semantic vector), GraphRAG (graph traversal following edges), or a combination.
  2. Top facts are retrieved and ranked using combined = (similarity × 0.7) + (pot_score × 0.3).
  3. Full provenance is fetched for each fact.
  4. Contradictions are detected among the retrieved set (flag-only, never auto-resolved).
  5. The LLM composes an answer with calibrated certainty (high-score facts spoken plainly; lower-score facts hedged or omitted).
  6. The response includes the answer, the facts used, contradictions, and an epistemic_briefing block describing what the system is confident about and where coverage is thin.

Production guidance: for any consequential agent, set include_epistemic_briefing=true and treat unresolved contradictions (contradictions_found) as a signal that may justify deferring to a human.

post/pots/{pot_id}/synthesize

Path parameters

pot_idstring required

POT identifier (UUID or slug)

POT identifier (UUID or slug)

Request body

querystring required

Question to answer from the knowledge base

max_factsinteger

Maximum facts to retrieve for synthesis

include_epistemic_briefingboolean

Include epistemic briefing in response (certainty guidance)

Example request

{
  "include_epistemic_briefing": true,
  "max_facts": 10,
  "query": "What is the POT Score system?"
}

Response

Synthesized answer with epistemic metadata + receipts

answerstring required

Synthesized answer from LLM

strategy_usedstring required

Retrieval strategy used

total_facts_retrievedinteger required
llm_modelstring required

LLM model used for synthesis

llm_cost_usdnumber required

Cost of LLM call

latency_msnumber required

Total latency including retrieval + synthesis

is_knowledge_gapboolean required

Convenience flag: true when the answer is likely a knowledge gap (gap_signal.confidence < threshold). The integrator decides whether to act on it.