# Runtime API Adapter

`scripts/runtime_api.py` exposes the sanitized archive artifacts through a local read-only JSON API. It is intentionally small: no framework, no database, no credentials, and no write endpoints.

Use it when another tool needs to pull dataset metadata, incidents, patterns, safe usage examples, prompt/result evidence links, prompt/result walkthroughs, per-example citation bundles, coverage matrices, defense cookbook control-family routes, operator use cases, audit scenarios, eval cases, or public eval result registry summaries without parsing repository files directly.

## Start

The recommended local entrypoint is the archive CLI:

```text
python scripts/archive_cli.py summarize
python scripts/archive_cli.py routes
python scripts/archive_cli.py serve --host 127.0.0.1 --port 8765
```

Verify generated release exports without network access:

```text
python scripts/archive_cli.py export --check-only
```

The CLI also exposes `validate` and `generate` commands for maintainers who want the same local gates used by CI.

You can still run the API script directly:

```text
python scripts/runtime_api.py --host 127.0.0.1 --port 8765
```

List supported routes without starting the server:

```text
python scripts/runtime_api.py --list-routes
```

## Optional Runtime Bundle

Releases include a zip bundle for operators who want only the read-only API and its required sanitized artifacts:

```text
python scripts/package_runtime_api.py
```

Generated files:

- `dist/runtime-api-manifest.json`: included files, counts, route list, launch commands, safety boundary, bundle size, and SHA-256 checksum.
- `dist/runtime-api-bundle.zip`: `scripts/runtime_api.py`, runtime docs, citation files, and the `dist/` JSON/JSONL artifacts needed by the API.

After extracting the zip, run:

```text
python scripts/runtime_api.py --host 127.0.0.1 --port 8765
```

The bundle intentionally excludes `data/`, `.git/`, `.codex/`, and write/upload handlers.

## Optional Container

Build and run the read-only API container from checked-in generated artifacts:

```text
docker build -t agent-prompt-injection-zoo .
docker run --rm -p 8765:8765 agent-prompt-injection-zoo
```

The `Dockerfile` copies only `scripts/runtime_api.py` and the sanitized `dist/` artifacts required by the API. `.dockerignore` excludes `data/`, `.git/`, `.codex/`, tests, and generated workspace-only state. GitHub Pages remains the default publication path; the container is only a local or operator-managed API option.

## Routes

| Route | Purpose |
|---|---|
| `/api/health` | Counts, schema version, and supported routes |
| `/api/routes` | Route list |
| `/api/dataset-metadata` | Dataset card metadata, reuse boundary, release counts, citation path, machine-readable files, and API routes |
| `/api/archive` | Full `dist/archive.json` export |
| `/api/sources` and `/api/sources/{id}` | Source records |
| `/api/incidents` and `/api/incidents/{id}` | Incident records |
| `/api/patterns` and `/api/patterns/{id}` | Pattern records |
| `/api/usage-examples` and `/api/usage-examples/{id}` | Safe example records; single-record responses also include linked Agentic RAG, walkthrough, audit, eval, safety, incident, pattern, and source context when the citation bundle is available |
| `/api/prompt-result-evidence-map` and `/api/prompt-result-evidence-map/{example_id}` | Reverse map from each prompt/result example to Agentic RAG answers, audit scenarios, eval cases, and safety reviews |
| `/api/prompt-result-walkthroughs` and `/api/prompt-result-walkthroughs/{answer_id}` | Question-first paths from Agentic RAG answers to sanitized prompt/result examples, Sufficient Context checks, audit scenarios, eval cases, and API routes |
| `/api/prompt-result-citation-bundles` and `/api/prompt-result-citation-bundles/{example_id}` | One-stop per-example bundles with prompt/result text plus source, incident, pattern, safety review, Agentic RAG, walkthrough, audit, and eval records |
| `/api/raw-prompt-evidence` and `/api/raw-prompt-evidence/{example_id}` | Verified public original prompts with observed results, safety controls, Agentic RAG answer IDs, audit scenarios, eval cases, detail pages, and API paths |
| `/api/prompt-result-coverage-matrix` | Pattern x Source family x Control family coverage matrix for every prompt/result example |
| `/api/defense-cookbook` | Control-family cookbook with controls, patterns, sanitized prompt/result examples, and eval cases |
| `/api/operator-use-cases` and `/api/operator-use-cases/{id}` | Deployment-facing chooser cards for practical agent-security situations, with prompt/result examples, observed results, eval cases, walkthroughs, and API paths |
| `/api/audit-scenarios` and `/api/audit-scenarios/{id}` | Operator audit scenarios |
| `/api/eval-cases` and `/api/eval-cases/{case_id}` | JSONL eval cases |
| `/api/eval-summary` | Current eval summary |
| `/api/eval-result-registry` | Public-safe eval run registry with model, defense, date, case family, verdict counts, pass rate, source kind, and review status |
| `/api/agentic-rag-answers` and `/api/agentic-rag-answers/{id}` | Offline Agentic RAG answer traces with plans, snippets, sufficiency checks, and citations |

Collection routes support `limit`, `q`, and exact field filters.

```text
/api/incidents?priority=P0&limit=5
/api/dataset-metadata
/api/incidents?q=claude%20code&limit=10
/api/eval-cases?limit=3
/api/eval-result-registry
/api/agentic-rag-answers?limit=1
/api/prompt-result-evidence-map/ex-github-issue-title-ci-agent
/api/prompt-result-walkthroughs/ci-coding-agent-issue-metadata
/api/prompt-result-citation-bundles/ex-github-issue-title-ci-agent
/api/raw-prompt-evidence/ex-github-issue-title-ci-agent
/api/prompt-result-coverage-matrix
/api/defense-cookbook
/api/operator-use-cases/use-ci-coding-agent-issue-metadata
```

## Boundary

The adapter only reads checked-in sanitized artifacts. It does not run live target systems, execute eval cases, run a live LLM/RAG backend, fetch remote sources, accept result uploads, or expose secrets. The eval result registry is generated from reviewed public-safe rows only and rejects raw transcript fields, live URLs, secrets, and unreviewed operator output. Production deployments should put it behind the operator's normal hosting, logging, and access-control layer.