HOW IT WORKS

REQUEST PIPELINE

Swipe chart → to read full pipeline

Blue steps route spend. Gold steps gate risk. Both paths end with an audit_id and structured policy reasons.

TWO DECISIONS (DO NOT CONFLATE)

SYNTHESIS CONTRACT

Retrieval governance is not enough if the agent layer free-formats answers. Every cleared response is wrapped in a synthesis contract (also returned as synthesis_contract JSON on POST /evidence):

Your agent should render synthesis_contract.body or map the structured fields directly — not paraphrase from raw retrieval snippets.

CONFLICT DETECTION & RESOLUTION

Detection: pairwise compare qualifying evidence items. When title-token overlap is high and snippet polarity diverges (positive vs negative framing), we record a Conflict with confidence (max of the two items) and authority gap.

When multiple rules fire, the strictest action wins (block > escalate > search_more). legal blocks on high-confidence conflicts; support escalates; research warns but still allows (unless confidence or source-count thresholds fail).

POLICY PRESETS

Start with a named preset. Override thresholds via YAML or API for your workload.

CHOOSING A PRESET (POST /policy/evaluate)

Partners bring their own retrieval (Tavily, Exa, internal RAG, etc.). Query Fanout scores each chunk’s URL for authority and applies the preset you pass. You do not set min_authority per request on the hosted API — pick the preset, optionally add authority_overrides for internal doc hosts.

• support (default on /policy/evaluate) — customer-facing agents, mixed external search. No authority bar; escalates when evidence is thin.
• research — internal drafting and cost routing. Permissive; conflicts warn instead of block.
• legal — compliance / legal workflows. Requires high-authority URLs (.gov, courts, firm filings via overrides). Open web at 55% authority will block often — that is expected.
• calibrated — always answer with confidence band + warnings; never hard-block.

Authority overrides: one-time domain patterns in your integration, e.g. {"internal://filing": 0.92}. Match how you label chunk URLs. Include a url on every source — empty URLs score 40%.

QUALIFYING SOURCES (WHY LEGAL BLOCKS)

Policy does not count raw search hits. It counts qualifying sources after our evidence pass:

• Item confidence — our score, not the provider’s alone. We blend provider relevance, query–snippet relevance (hash or embedding re-rank), domain authority heuristics, and cross-query consensus.
• Threshold — items below 40% item confidence are dropped before source counting.
• Dedup — remaining items deduped by URL/title so duplicate hits don’t inflate counts.

That is why legal can block at “2 qualifying sources; minimum is 3” even when the search API returned more raw results.

Legal block rates are from a controlled web-search benchmark with default policy thresholds — illustrative of gating behavior, not a compliance certification or production SLA.

SOURCE AUTHORITY (V0)

Each evidence item gets an authority score from the result URL’s domain — a fixed tier table, not PageRank or a legal citation graph. Scores are attached in the audit trail and returned on POST /evidence citations.

Bands: institutional (85%+) for courts, .gov, journals, and .edu; reference (78–84%) for Wikipedia and encyclopedias; official docs (72%) for vendor documentation your agents hit daily; everything else defaults to 55% (most blogs, forums, SEO).

How policy uses it: after qualifying-source filtering, we take the highest authority among remaining items and compare it to the preset’s min_authority (e.g. 75% on legal). Official docs at 72% improve research / support confidence but do not clear legal on a single source. Conflict detection can escalate when disagreeing sources sit in different authority tiers (gap ≥ 15–20%).

How confidence uses it: authority is 25% of per-item confidence (alongside cross-query consensus, query–snippet relevance, and provider score). A blog or vendor URL at 55% authority can still contribute to source count but may fail a legal gate on its own.

What you can tune today: raise or lower min_authority per preset, or add tenant-specific authority_overrides in policy YAML or on POST /evidence. Overrides use the same host/suffix matching as the table above and always win over built-in tiers (longest suffix wins among overrides).

policy:
  name: legal
  min_authority: 0.75
authority_overrides:
  docs.acme.com: 0.90
  help.acme.com: 0.82

Heuristic defaults for explainability, not a compliance certification. General web search results cluster at 55%; that is why live legal benchmarks block heavily on authority even when retrieval spend is low.

Example block response (legal preset):

{
  "allow_answer": false,
  "audit_id": "99c08409-28ec-4427-...",
  "policy": {
    "profile": "legal",
    "action": "block",
    "reasons": ["only 2 qualifying source(s); minimum is 3"]
  }
}

FAILURE MODES (UPFRONT)

CALIBRATION PATHS

You do not need to send production logs to start evaluating the architecture.

Published live benchmark: 125 production-style tasks, 625→173 searches (~72% reduction) on Tavily — see field study and landing stats. Numbers vary by corpus; treat as reference, not a SLA.

SEARCH PROVIDERS

Tavily is our reference benchmark preset. The control plane sits above your search API:

• mock — offline control plane: deterministic fake results for CI, local dev, and running probe/policy/audit without any search API key. Not just a test double; full pipeline works end-to-end.
• wikipedia — offline real retrieval for demos and benchmarks
• tavily — live paid search (reference benchmark)
• Generic http backend in YAML for Exa, Brave, Serper, or internal search

Policy, audit, and allow_answer are provider-agnostic. Swap the adapter; keep the governance layer.

CONFIGURATION & PRECEDENCE

Precedence: policy_file (YAML) > policy API param > preset defaults. Set one source of truth per environment to avoid surprises.

from query_fanout import RetrievalClient

client = RetrievalClient(preset="tavily", policy="legal", agent_id="support-bot")
report = await client.retrieve("How do refund policies work?")

if report.allow_answer:
    answer(report.synthesis)
else:
    escalate(report.audit_id, report.policy.reasons)

Need soft answers instead of hard blocks? Use calibrated for draft generation (confidence band + warnings, always allow_answer: true), default for permissive general use, or research to expand retrieval before failing.