Provenance

Provenance schema attached to every search result — bridge version, template, intent classifier, coverage.

Every search result carries a provenance dict answering two questions:

Why did the system return this? — Template used, coverage of query constraints, intent classifier version.
What artifacts produced it? — Bridge version, ANN snapshot size, timestamp.

Schema

{
  "provenance": {
    "bridge_version": "20260223T015855Z_hlq_reqs_v2",
    "bridge_format_version": "1.0.0",
    "ann_snapshot_items": 1806,
    "template": "composite_trader_screening_daily",
    "intent_classifier": "regex_v1",
    "coverage": {
      "applied": [...],
      "dropped": [...],
      "fully_covered": true
    },
    "timestamp_utc": "2026-02-26T14:30:00Z"
  }
}

Fields

Field	Type	Description
`bridge_version`	`str`	Bridge snapshot that produced this result
`bridge_format_version`	`str`	Bridge schema version
`ann_snapshot_items`	`int`	ANN index size at query time
`template`	`str \| null`	SQL template name used. Null for help responses and multi-coin top-level results
`intent_classifier`	`str`	Classifier version. Currently `regex_v1` (transitional)
`coverage`	`dict \| null`	Which query constraints reached the SQL. Null for help/error
`timestamp_utc`	`str`	ISO 8601 timestamp of when the query ran

Coverage

Coverage tracks which semantic constraints from the query were applied to the SQL template vs dropped:

{
  "applied": [
    {"field": "max_risk_score", "value": 3.5, "label": "maximum risk score"},
    {"field": "temporal_window", "value": {"window_days": 7}, "label": "date range override"}
  ],
  "dropped": [
    {"field": "min_consistency_score", "value": 0.8, "label": "minimum consistency score",
     "reason": "template 'risk_regime_stress_scoring_daily' does not use {min_consistency_score}"}
  ],
  "fully_covered": false
}

applied — Constraints that were injected into the SQL.
dropped — Constraints the user specified but the template doesn't support. Each includes a reason.
fully_covered — true if nothing was dropped. When false, the result may not fully match the query.

Where provenance appears

Provenance is injected at every return site in the pipeline:

Return site	`template`	`coverage`
Help response	`null`	`null`
Error (no template)	`null`	`null`
Single-coin dry-run	template name	coverage dict
Single-coin live	template name	coverage dict
Multi-coin dry-run	`null`	`{"per_coin": [...]}`
Multi-coin live	`null`	`{"per_coin": [...]}`

MCP tools

All 4 search-related MCP tools pass through provenance:

find_similar_traders → response.provenance
explain_trader → response.provenance
detect_copytrade → response.provenance
screen_risk → response.provenance

Why this matters

No one else in the AI crypto intelligence space provides traceable, auditable evidence chains. Provenance lets agents:

Audit results — Verify which bridge version and template produced a result.
Debug coverage gaps — See which constraints were dropped and why.
Track freshness — Timestamp shows when the query ran; bridge version shows data staleness.
Compare across versions — When the bridge updates, provenance shows exactly what changed.