centralia

Court PDF opinion extractor: a PDF plus a court id in, a typed document out.

Try it in your browser → No install, nothing uploaded — the real package runs client-side on Pyodide, and your PDF is parsed in the tab.

python -m pip install centralia      # Python 3.12+

from centralia import read

r = read("opinion.pdf", court_id="mont")   # path, bytes, or file object

r["cluster"]["docket_number"]              # 'DA 25-0040'
[o["author"] for o in r["opinions"]]
# ['Justice Laurie McKinnon delivered the Opinion of the Court.',
#  'Justice James Jeremiah Shea, concurring.',
#  'Justice Jim Rice, dissenting.']

Three writings, each with its own author, footnotes and text — recovered from a PDF that labels none of them.

The problem it solves

Getting the text out of a court PDF is easy; pdftotext does it. What is hard is that an opinion is a document with parts, and the PDF says nothing about them. Nothing marks which lines are the caption, where the syllabus ends and the opinion begins, which paragraphs belong to the dissent rather than the majority, whose footnote is whose, or which line is a page number instead of a sentence. All of it has to be recovered from how the page is set — position, size, leading, indentation, and the rules the printer drew.

And every court sets its pages differently. centralia reads 241 of them.

Thresholds are measured from each document's own geometry rather than tuned per court, and nothing is ever dropped silently: every row removed as furniture is returned in removed, with the page and box it came from, so "did we lose anything?" is arithmetic instead of a judgment call.

Of the 241 courts wired, 191 are released through this API — meaning every document in that court's test corpus has been read and checked by a human. The rest raise rather than quietly returning a worse reading (see Courts still being worked on).

What read returns

r["status"]        # valid | review | scanned | failed
r["court_id"]      # the id you passed, echoed back
r["form"]          # 'AO 245C' where the paper is a pre-printed form, else None
r["cluster"]       # the case: citation, docket, dates (as printed + ISO), panel, parties
r["opinions"]      # one entry per writing: author, pages, footnotes, html and text
r["headmatter"]    # the caption block: rows, by_role, text, html, html_inline,
                   #   footnotes, untinted
r["endmatter"]     # anything after the last writing, same shape, minus the notes
r["sections"]      # named sections the court printed (syllabus, headnotes) where it did
r["removed"]       # every row taken out as furniture: kind, page, text, bbox
r["warnings"]      # what the reader wants you to know about the source
r["diagnostics"]   # page facts and anything unplaced — reported, never judged
r["html"]          # the document's text, without review furniture
r["review_html"]   # the reviewer's page: criteria box, Removed panel, role tints
r["casebody"]      # Harvard casebody XML
r["versions"]      # what produced this reading, centralia's own version first

headmatter and endmatter carry a by_role map — which rows the court's own reader claimed and as what (court, caption, docket, date, title, counsel, panel, citation, lower-court, syllabus, case-info, author) — and untinted, the rows no reader claimed. That second number is the honest measure of how much of a caption was actually read.

removed is the audit trail: nothing is dropped silently, so a running head, a folio, an e-filing stamp, a chambers letterhead or a caption-box graphic all appear here with the page and box they came from.

Forms: papers that were filled in, not written

Not every document a court files is something a judge composed. A sentence is entered on AO 245B, a defendant is ordered to appear on AO 467, a district takes its minutes on its clerk's own template — pre-printed sheets whose words belong to the form and whose blanks belong to the court. Read as prose they come apart quietly: the caption walk takes the form's field labels for parties, and every prose measure comes back clean because there is no prose in them to be wrong about.

r["form"] names the form where the sheet names itself, and is None for a paper a judge wrote. r["diagnostics"]["is_form"] is the same answer as a boolean, for a caller that only needs to branch:

r = read("judgment.pdf", court_id="nced")

r["form"]                       # 'AO 245C'
r["diagnostics"]["is_form"]     # True
r["cluster"]["parties"]         # …read off a grid of blanks. Do not trust it.

The value is what the paper prints — an Administrative Office number ('AO 245C', 'AO 467'), a court's own template ('minutes'), or the bare 'form' where a sheet captions its blanks without naming itself. The form is recorded beside doc_type, not inside it, because the two answer different questions: AO 245B is a judgment and AO 467 an order, and both are forms.

Treat it as a gate, not a decoration. On a form, cluster is what the caption reader made of a table of labelled blanks, and status will often still say valid — the reading accounted for every line on the page, which is the only thing that status has ever claimed.

The HTML an ingest stores

A writing's html, and the cover's html_inline, are the portable renders: no chip a host page would print itself, nothing set in classes only this package's stylesheet knows, and the footnotes wired — each mark anchors to its note and each note links back, namespaced per writing (ref-o2-7 / fn-o2-7) so several writings shown on one host page, each restarting its numbering at 1, cannot collide. The cover's notes travel inside html_inline rather than beside it, so a substituted party's * is not a dangling mark. review_html is the other kind: the reviewer's page, which does assume our CSS.

versions names the centralia that wrote the payload alongside the pipeline's own versions, so a consumer decides payload shape by a number instead of sniffing the markup.

Courts still being worked on

from centralia import read, released_courts, CourtNotReleased, UnknownCourt

released_courts()                      # frozenset of ids that are finished
read("x.pdf", court_id="mad")          # raises CourtNotReleased
read("x.pdf", court_id="mad", allow_pending=True)   # read it anyway
read("x.pdf", court_id="typo")         # raises UnknownCourt

An unregistered id raises rather than falling back: core's generic reader would still return status: valid, just read worse, and a typo should not look like a thin court.

Lower level, for callers that want the objects

from centralia import extract, render_opinion

result = extract("opinion.pdf", court_id="mont")
result.document          # typed Document
result.trace             # per-decision evidence chains
render_opinion(result.document.opinions[0])

Also exported: render_html, render_body, render_headmatter, render_hm_inline, render_casebody, opinion_text, and render_opinion_ingest(op, ns, hm_sig="") — the portable form of a writing that read puts in opinions[].html, where render_opinion is the review page's own drawing. Plus the model types (Document, Criteria, Meta, Opinion) and the date helpers to_iso / all_iso. Pass include_document=True to read to get the typed Document alongside the dict.

Dates

Dates are returned twice: as the court printed them (date_filed) and as YYYY-MM-DD where that can be read without guessing (date_filed_iso, or None). diagnostics["dates_unparsed"] names the ones that did not parse.

Status is a report, not a gate

diagnostics carries the page-level facts a caller needs to decide for itself: which pages are a raster (scan_pages), which pages have no text layer at all so their words are absent (text_missing_pages), which carry unmapped glyphs (cid_pages), whether the paper was filled in rather than written (is_form), and what the extractor could not place (residual).

Contributing

DEVELOPMENT.md is the orientation: how the engine works and why it works that way, the eleven pipeline stages, a file-by-file map, when page geometry can be trusted and when it cannot, how a court is added, the five oracles that say whether a reading is right, and what is left to do.

The test corpus is ~10,000 real court PDFs. It is too large for git, so it lives as a list of links:

uv sync --dev
uv run python scripts/fetch_corpus.py               # fetch the corpus
uv run python harness/cli.py render $(ls assets)    # render every court
uv run python harness/cli.py serve                  # the review viewer