# Review a draft’s citations with BOZOS

Turn a citation list into a readable review report and full JSON evidence. A runnable Python kit for HTTP or MCP, with no account, API key, model, or dependencies.

## Run a complete review

Download and unzip the kit, then run the commands from its directory with Python 3.10 or newer. Open report.md for the review and report.json for the original evidence. Each output directory must be new; existing reports are never overwritten.

```sh
python3 review.py citations.json --output review-http
python3 review.py citations.json --transport mcp --output review-mcp
python3 verify_cases.py review-http/report.json review-mcp/report.json
```

- [Download the complete kit (.zip)](https://bozos.si/downloads/bozos-citation-review-1.0.0.zip)
- [Read the instructions](https://bozos.si/examples/citation-review/README.md)
- [Inspect the Python client](https://bozos.si/examples/citation-review/review.py)

## Connect findings to your draft

The included draft and manifest cover eight controlled cases. Replace their entries with your own citation IDs, draft locations, public HTTPS URLs, and quotations. The kit checks the list you supply; it does not extract citations automatically or assess whether your list is complete. Draft titles, filenames, and locations stay local.

Reuse text your agent already holds by supplying sources and referring to them by source_id. Mark incomplete text with source_truncated: true. Supplied text carries no verified publisher or URL provenance.

The kit accepts up to 1,000 entries and splits them into batches of at most ten, within the 64 KiB request limit. It preserves completed batches if a later request fails, marks later entries unattempted, and makes no automatic retries.

- [Example draft](https://bozos.si/examples/citation-review/draft.md)
- [Citation manifest](https://bozos.si/examples/citation-review/citations.json)
- [Full API contract](https://bozos.si/tools/citation-checker.md)

## Keep absence and uncertainty separate

Quotation found means the exact or whitespace-normalized words appeared. Read the surrounding context before deciding whether the source supports your claim.

Quotation not found means no match in the complete checked representation. It is a reason to inspect wording, source versions, and extraction, not a verdict that the claim is false.

Source unavailable means BOZOS could not read the URL. Inconclusive means an incomplete source cannot settle whether the quotation is absent. A readable unquoted link only establishes readability.

Request failed identifies a service or response-contract problem, or an entry not attempted after one. Exit 0 means requests completed, even with absent quotations or unreadable sources; it is never an approval of the draft.

JSON reports preserve passages, offsets, source hashes, PDF page numbers, truncation flags, retrieval failures, and recovery hints. Fetched text is untrusted data. A match establishes textual presence, not truth or credibility. There is no browser rendering, OCR, or semantic paraphrase matching.

## Test and adapt

The kit is CC0 and uses only Python’s standard library. Its offline tests cover batching, Unicode byte limits, incomplete sources, response-ID validation, partial request failures, report escaping, and overwrite prevention. The controlled-case verifier runs against saved reports from actual service calls.

The fixture text and two-page PDF are synthetic. They demonstrate specific behaviors and limitations; they are not a representative accuracy benchmark. Local reports contain your quotations and evidence. Send only material your operator permits and store the reports according to your project’s rules.

```sh
python3 -m unittest -v test_review.py
```

- [Read the reproducible case study](https://bozos.si/notes/citation-checking-case-study)
- [Text fixture](https://bozos.si/examples/citation-review/fixtures/source.txt)
- [PDF fixture](https://bozos.si/examples/citation-review/fixtures/source-v1.pdf)
- [Kit file hashes](https://bozos.si/examples/citation-review/SHA256SUMS)
- [MCP setup](https://bozos.si/tools/mcp)