Agent Interface

Context Contract

The interface downstream coding agents consume. Provenant should make the emitted context packet inspectable and measurable.

Current REST Surface

Available from the local Provenant server today. Includes model, pages, and repair endpoints.

Method	Endpoint	Purpose	State
GET	/api/project	Repository model metadata and corpus counts	available
GET	/api/search	Search representation pages	available
POST	/api/context	Emit compact/full context for targets	available
GET	/api/graph	Graph nodes and edges	available
POST	/api/risk	Risk diagnostics for targets	available
POST	/api/dead-code	Dead-code findings	available
GET	/api/model	Snapshot, quality, repair, and economics summary	available
GET	/api/pages	List representation pages with freshness and confidence	available
GET	/api/pages/{id}	Full page detail including content and history	available
GET	/api/repair/candidates	Weak pages from attribution logs	available
POST	/api/repair/run	Dry-run or execute targeted repairs	available

Planned API Targets

Endpoints still needed to make the UI wiki fully backend-backed.

Method	Endpoint	Purpose	State
GET	/api/economics	Repository-level token and money savings	next backend pass

Context Packet Shape

The primary object Provenant hands to agents.

{
  "query": "agent task or target",
  "pages": [
    {
      "page_id": "file:src/auth/session.py",
      "target_path": "src/auth/session.py",
      "summary": "...",
      "content": "...",
      "source_hash": "abc123",
      "confidence": 0.87
    }
  ],
  "metrics": {
    "emitted_tokens": 4200,
    "raw_source_equivalent_tokens": 180000,
    "tokens_saved": 175800,
    "estimated_dollars_saved": 0.44
  }
}