rrxiv-python

What It Is#

rrxiv-python is the reference implementation of the rrxiv protocol — the open standard for research preprints as immutable atoms plus a structured claim graph. One package carries the whole vertical: a .tex → Canonical Intermediate Representation (CIR) parser, Pydantic-v2 models generated from the protocol's JSON Schemas, an async + sync HTTP client, a FastAPI server, and a Typer CLI. It is the executable witness for the protocol's conformance suite, and it runs in production behind api.rrxiv.com.

Why It Matters#

A protocol is only as real as its reference code. rrxiv-python is what makes rrxiv adoptable rather than aspirational: fork it and you have a working instance in one command, with a memory store for play and SQLite (and, ahead, Postgres) for persistence. Because the same library both parses papers into CIR and serves them over HTTP, "does this paper conform?" and "does this server conform?" are answered by one codebase — and pinned by 400+ tests plus a cross-conformance suite that runs the protocol-level tests against the in-process server.

What Ships in 0.1#

• rrxiv.models — Pydantic v2 models generated from the protocol JSON Schemas (Paper, Claim, Annotation, Citation, CIR, plus enums), so the wire format and the type system can't drift.
• rrxiv.parser — .tex → CIR, recognising the rrxiv.cls \claim / \evidence / \dependson markup and emitting schema-validated JSON.
• rrxiv.client — async and sync HTTP clients with a retry policy and ed25519 signature middleware on the write path.
• rrxiv.server — a FastAPI app factory with eight routers (auth, papers, claims, annotations, snapshots, search, submissions, sources) over a pluggable Store (memory / SQLite / future Postgres).
• A first-class CLI — parse, validate, submit, snapshot, doctor for authoring; ORCID / agent / anonymous login; serve and seed-store for ops; papers / claims / search as a read client; and a full annotation group including bulk post-batch.
• rrxiv.testing — a live_server pytest fixture so downstream projects can test against a real HTTP instance, not a mock.

Ecosystem Fit#

rrxiv-python is the library half of the rrxiv protocol; the canonical rrxiv.com deployment is just this package plus a thin Fly.io overlay that pins a commit and bakes in the seed corpus. Install the base library to parse and validate papers locally, or rrxiv[server] to stand up your own instance. The protocol's COOKBOOK walks the CLI end-to-end — parse a paper, run a local instance, retract a claim, replicate a result, take a snapshot. MIT licensed, Python 3.11+.