feat: versioned JSON evidence schema for query APIs (#16)

[leo-aa88]

Closes #16

Summary

Versioned JSON evidence schema (schema_version: "1.0") and llm provenance (used, provider, model, fell_back) on every /v1/query/* response so consumers can store discrete fields instead of scraping prose.

Covered endpoints:

• POST /v1/query/explain (and deprecated /query/explain, same handler)
• POST /v1/query/timeline
• POST /v1/query/compare
• POST /v1/query/ask
• POST /v1/query/clusters

Contract

• Pydantic models in src/api/schemas/v1.py
• JSON Schema in clients/jsonschema/ (explain, timeline, compare, ask, clusters)
• OpenAPI response_model= plus re-exported clients/openapi.json
• Prose lives in rendered_text (text kept as an alias for timeline/compare; markdown path unchanged)
• Cached explain payloads are upgraded on the way out

Tests

Unit tests in tests/unit/test_query_schema.py plus API/OpenAPI contract coverage. python -m pytest tests/unit/ passed locally.

Deferred (out of G7 scope)

• G8 scope filtering (scope is reported only)
• G10 consumption of llm.fell_back
• CLI panel changes
• Database migration

  

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[cursor]

Review — PR #44 (G7 JSON evidence schema)

Issue #16 acceptance is met. Explain/timeline/compare (plus ask/clusters) return schema_version: "1.0" with an llm block (used, provider, model, fell_back). Canonical explain fields are present (scope, window.from/to, confidence.{label,score}, summary, trigger, primary_cluster / secondary_clusters, evidence[], rendered_text). Compare diffs carry + / - / ↑ / ↓ / +⚡ / -⚡. Prose is preserved on rendered_text (text alias when format: text). Published schemas live in clients/jsonschema/ and stay in lockstep with Pydantic. Cached explain payloads are upgraded on the way out. python -m pytest tests/unit/ — 616 passed. Ruff hits on touched files are pre-existing on main.

Must-fix

(None)

Should-fix

(None)

Nice-to-have

1. src/api/schemas/v1.py:99 (and the same default on timeline/compare/ask/clusters) — schema_version: str = SCHEMA_VERSION means the published JSON Schema omits it from required (clients/jsonschema/explain.v1.json:382-388). A validator using those files accepts a body with no pin. Making it a required Literal["1.0"] (set in constructors) would match “consumers pin on schema_version.”

2. src/api/routes/explain.py:107-118 — after a cache hit, format: markdown rebuilds trigger candidates from trigger.type, so the Trigger candidates section prints `deploy` instead of the original log line. The v1 trigger object has no message field; an additive detail (or keeping trigger_candidates in the cache payload) would preserve markdown.

3. tests/unit/test_query_schema.py:61-73 — contract tests equate published files to model_json_schema() and assert schema_version on some HTTP bodies. They do not jsonschema.validate live timeline/compare/ask/clusters responses against clients/jsonschema/*.v1.json, so response_model_exclude_unset=True dropping a field would not be caught uniformly.

Verdict

Ready to merge (0 must-fix, 0 should-fix)