kaos-citations

Part of Kelvin Agentic OS (KAOS) — open agentic infrastructure for legal work, built by 273 Ventures. See the full KAOS package map for the rest of the stack.

Structured, high-performance citation identification and extraction. Text in, typed Citation records out — frozen Pydantic models with raw / normalized / span provenance, Bluebook modifiers (signal, pin_cite, parenthetical, weight, subsequent_history, stable cite_id cross-references), and family-specific structured fields (volume / reporter / page / year / court / case_name; CFR title + section; SEC filing form; ASC topic-subtopic-section; etc.).

Pure-Python, fully offline, deterministic, Rust-backed matching, ~5× faster than eyecite on the SCOTUS corpus we benchmark against. Two runtime deps (kaos-core + kaos-nlp-core) — no httpx, no eyecite, no Python re-module imports.

60 supported kinds across four domains:

• Legal (25 kinds): case law (federal + state), U.S. Code, CFR, Federal Register, U.S. Constitution, Federal Rules + USSG, IRS guidance, Treasury Regs, executive actions, public laws + bills + reports + Cong. Rec., Restatements, Uniform Acts + Model Codes, agency adjudications + manuals, AG/OLC opinions, bar ethics, internet
  • archive URLs
• Financial (19 kinds): SEC filings + releases + staff guidance + named regulations (Reg. S-X / S-K / G / AB / M / FD / BTR / S-T), FINRA (rules / notices / disciplinary), exchange rules (NYSE / Nasdaq / Cboe / MSRB / OCC), banking (Fed Reserve / FDIC / OCC / CFPB / NCUA), Basel, CFTC, NAIC, FFIEC call reports, FATF / IOSCO
• Accounting (13 kinds): FASB ASC + ASU + legacy (FAS / FIN / FSP / EITF / CON / APB / ARB), PCAOB, AICPA, IFRS family (IFRS / IAS / IFRIC / SIC), IAASB, IESBA, GASB, FASAB, government audit (OMB / GAO / Yellow Book), NAIC SAP, sustainability frameworks (GRI / SASB / TCFD / ISSB / ESRS)
• Identifier (3 kinds): DOI, PubMed, arXiv (opt-in)

Identification + extraction only. Citation resolution (URL building, body fetching) and claim verification belong to the rest of the KAOS stack (kaos-source, kaos-web, kaos-llm-core's Cited[T], kaos-agents).

Architecture

Identification and extraction route through kaos-nlp-core's Rust+PyO3 primitives. There is no Python re module and no third-party tokenizer in the runtime path:

• MultiPatternMatcher (Aho-Corasick) over reporter spellings — one linear pass identifies every reporter token candidate.
• RegexMatcher (Rust regex crate) for per-family tail patterns (volume / page / pin cite / parenthetical, etc.).
• PunktTokenizer with the bundled legal model (~27,000 abbreviations) for sentence-boundary anchoring during Bluebook signal binding and string-cite grouping.
• FstSet for known-vocabulary lookups — reporters, courts, case-name abbreviations, journals, statute reporters, US states.
• Tokenizer for word-level operations.

Reporter / court / journal / case-name-abbreviation data is vendored under kaos_citations/data/ from the Free Law Project's reporters_db and courts_db (BSD-2). The full upstream license texts are preserved in LICENSE.vendored. kaos- citations consumes the JSON data only — no upstream Python code is imported at runtime.

Install

uv add "kaos-citations>=0.1.0"
# or
pip install "kaos-citations>=0.1.0"

kaos-citations requires Python 3.13 or newer.

Quick start

from kaos_citations import extract_citations

text = (
    "The court held that 17 CFR 240.10b-5(b) applies to insider "
    "trading, citing Brown v. Board of Education, 347 U.S. 483 (1954). "
    "See also U.S. Const. amend. I."
)

for c in extract_citations(text):
    print(f"  [{c.kind:<10}] {c.normalized!r:<30}  span={c.span}")

  [cfr       ] '17 CFR 240.10b-5(b)'           span=(20, 39)
  [case      ] '347 U.S. 483 (1954)'           span=(104, 116)
  [const     ] 'U.S. Const. amend. I'          span=(134, 154)

The base install handles every citation family — there are no extras-gated extractors. Filter with extract_citations(text, kinds=...):

extract_citations(text, kinds=("case", "cfr"))   # only case + CFR
extract_citations(text, kinds=("statute",))      # only U.S.C. / state codes

raw vs normalized vs span

For most citation families raw == text[span[0]:span[1]] == normalized. Two exceptions to know about:

• Case citations: span covers only the volume-reporter-page anchor (347 U.S. 483), matching eyecite's contract. normalized reconstructs the canonical vol reporter page (year) form (347 U.S. 483 (1954)), pulling the year from a date parenthetical that sits outside span.
• Citations with normalised reporters / spacing: raw preserves the exact source spelling (e.g. 347 U. S. 483); normalized rewrites to the Bluebook canonical (347 U.S. 483).

When you need the exact source bytes, use text[c.span[0]:c.span[1]]. When you need a stable, reporter-canonical string, use c.normalized.

Concepts

Citation kinds

Pass any of these as elements of the kinds= filter. The full per-family taxonomy with canonical examples and structured fields lives in docs/CITATION_TAXONOMY.md.

arxiv is opt-in — academic preprints are rarely cited in legal / financial / accounting writing, so the dispatcher excludes them by default to avoid noise. Add it explicitly to the filter when you want it:

extract_citations(text, kinds=("arxiv", "doi", "pmid"))

CLI

kaos-citations ships a single entry-point script, kaos-citations-serve, that boots an MCP server exposing the three read-only tools (kaos-citations-extract, kaos-citations-validate, kaos-citations-doctor) and the kaos-citations://kinds resource:

kaos-citations-serve                  # stdio (for Claude Code, Codex, ...)
kaos-citations-serve --http --port 8765

Or via the kaos-mcp manager: kaos-mcp serve --module citations.

Compatibility & status

Documentation

Per-package reference: docs/ in this repo, especially docs/CITATION_TAXONOMY.md.

Cross-cutting KAOS guides (agentic patterns, persona presets, settings policy, citations, MCP data flow, migration to 0.1.0 GA) live in kaos-modules/docs/guides/ — see in particular citation-kinds.md.

Companion packages

kaos-citations is one of the packages in the Kelvin Agentic OS. The broader stack:

Packages depend on kaos-core; everything else is opt-in. Mix and match the ones you need.

Development

git clone https://github.com/273v/kaos-citations
cd kaos-citations
uv sync --group dev

Install pre-commit hooks (recommended — they run the same checks as CI on every commit, scoped to staged files):

uvx pre-commit install
uvx pre-commit run --all-files     # one-time full sweep

Manual QA commands (the same set CI runs):

uv run ruff format --check kaos_citations tests
uv run ruff check kaos_citations tests
uv run ty check kaos_citations tests
uv run pytest -m "not live and not network and not slow and not integration"

Build from source

uv build
uv pip install dist/*.whl

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, quality gates, pull request expectations, and engineering standards. By contributing you agree to follow the project conduct expectations and certify the Developer Certificate of Origin v1.1 — sign every commit with git commit -s. Please open an issue before starting on a non-trivial change so we can align on scope.

Security

For security issues, please do not file a public issue. Report privately via GitHub Private Vulnerability Reporting or email security@273ventures.com. See SECURITY.md for the full disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 273 Ventures LLC. Built for kelvin.legal.