Skip to content

Shared Contract Shapes

The contract-freeze PR defines provider-neutral API and artifact shapes in raghelm/contracts.py. Feature lanes should import these models instead of defining local variants.

QueryPipeline request/response

QueryPipeline.run(QueryRequest) -> QueryResult is the canonical shape for both served /query behavior and production eval behavior.

Minimum QueryResult fields:

  • schema_version
  • request_id
  • run_id
  • mode
  • target
  • answer
  • retrieved_chunks
  • routing
  • cost
  • latency
  • trace_id

The current FastAPI /query response remains backward-compatible until Workstream A routes it through the canonical QueryPipeline, but new work should emit enough data to populate QueryResult.

Release-readiness artifacts

Release checks must normalize evidence into:

  • RAGRunManifest: machine/audit provenance for git SHA, corpus, chunking, embedding, backend, routing, prompt, judge, metrics, artifacts, and privacy flags.
  • ReleaseGate: deterministic policy decision with check-level evidence.
  • ReadinessScorecard: human-facing release decision linked to a manifest and gate.

Manifest provenance subsections are typed by contract:

  • SourceControlRef: repository, git_sha, optional branch, optional dirty
  • CorpusRef: corpus_id, source/document/chunk counts, optional manifest path
  • ChunkingSpec: strategy, chunk size, overlap, version
  • EmbeddingSpec: model, dimension, provider
  • BackendSpec: backend type, index, namespace, mode
  • PromptRef: prompt version/hash without requiring private prompt text storage
  • JudgeSpec: judge mode/model/rubric
  • PrivacySummary: private-data, full-prompt/full-context, synthetic-data, and public-claim flags

Observability artifacts

Local/private observability should persist TraceRecord objects by default. Trace records intentionally use hashes, chunk IDs, routing metadata, cost, latency, and outcomes rather than storing full private prompts/context by default.

ObservabilityStore freezes both write-side and minimum read-side behavior for downstream dashboard and CI work:

  • record_trace
  • record_scorecard
  • record_manifest
  • get_manifest
  • get_latest_scorecard
  • list_scorecards
  • list_traces

Agent artifacts

The narrow role-aligned agent demo should emit AgentRun objects with typed steps, budgets, trace IDs, stop reasons, and side-effect classification. This is a state-machine contract, not permission to build a broad autonomous-agent platform.

Contract enums

Enum Values
ExecutionMode local, local_demo, production
GateStatus ship, needs_review, block
CheckStatus pass, review, block
StepStatus pending, running, completed, failed, skipped
StopReason completed, budget_exhausted, max_steps, needs_human_approval, error
SideEffectRisk none, low, high
TargetType reference_rag, reference_agent, external_rag, external_agent

All versioned models currently accept schema_version: 1 only. Future breaking contract changes should add explicit migration handling rather than silently accepting a new shape.

Fixture source of truth

The contract fixture lives at:

tests/fixtures/contracts/core_objects.json

Contract tests live at:

tests/test_contracts.py

Run them with:

uv run pytest tests/test_contracts.py -q