paperreading

PaperReading is an alpha-stage Python core and Codex Skill for researchers and research-tool builders who need more than a fluent summary. Its schemas and validators preserve the chain from a source location to a claim, distinguish paper-reported content from later interpretation, guard causal language, and keep legacy research exports reviewable.

[!IMPORTANT] Current scope: v0.3.1 ingests UTF-8 text, Markdown, and text-based PDFs; replays staged extraction through an auditable JSON provider; enforces Draft → Review → Finalize; and verifies quotations with local fuzzy alignment. PDF support does not provide OCR, layout geometry, table reconstruction, or figure extraction. Hosted AI providers, batch jobs, SQLite search, cross-paper synthesis, and automatic gap discovery remain planned.

From fluent summaries to defensible research artifacts

These rules make five questions answerable: what the paper reported, where the supporting evidence lives, whether that locator was checked, what the design permits us to infer, and how the artifact changed over time.

Try it in 60 seconds

Clone the repository, install the Core package, and validate the checked-in research package:

git clone https://github.com/AOROM/paperreading.git
cd paperreading
python -m pip install -e .
paperreading validate examples/paper-package.example.json

The fixture returns valid: true, evidence_count: 4, and finding_count: 1. It also returns four explicit EVIDENCE_NOT_VERIFIED warnings because the example was migrated from v0.2 and has not been checked against source content. That visible limitation is part of the contract, not hidden noise.

What ships in v0.3.1

How it works

flowchart LR
    S["Text / Markdown / text-based PDF"] --> I["Parser adapters"]
    I --> D["PaperDocument"]
    D --> E["Staged provider extraction"]
    E --> R["PaperDraft: candidates + conflicts"]
    R --> H["Explicit human review"]
    H --> P["Finalized PaperPackage"]
    V2["v0.2 PaperRecord"] --> M["Deterministic migration"]
    M --> P["v0.3 PaperPackage"]
    D --> V["Evidence verifier"]
    P --> V
    V --> O{"Validated artifact"}
    O --> J["JSON"]
    O --> MD["Markdown"]
    O --> L["Legacy 13-field projection"]
    L --> X["Safe Excel exporter"]

The dependency direction is deliberate:

domain <- migrations / ingestion / verification / validation / projections
       <- application use cases <- CLI / Skill / exporters / repositories

The domain layer imports no Typer, OpenPyXL, model SDK, storage adapter, or Codex runtime. File storage and Excel are replaceable adapters; the schemas remain the center of the system.

Research constitution

The normative Research Principles derive project decisions from academic validity, traceability, falsifiability, reproducibility, and research ethics. They take precedence over compatibility, convenience, performance, and growth metrics. A capability that cannot state its research object, evidence, inference boundary, uncertainty, and failure behavior is not ready to ship.

Explore the command workflow

Install optional PDF and Excel adapters only when they are needed:

python -m pip install -e ".[pdf,excel]"

Initialize an inspectable local project:

paperreading init

This creates .paperreading/config.toml, a manifest, and separate directories for documents, drafts, records, analyses, audits, and cache data.

Exercise the source-ingestion contract with the synthetic Markdown fixture:

paperreading ingest examples/source.example.md

Run the complete, network-free Draft → Review → Finalize fixture:

paperreading ingest examples/source.example.md --output document.json
paperreading extract document.json \
  --provider-manifest examples/extraction-manifest.example.json \
  --output bundle.json
paperreading review bundle.json \
  --decisions examples/review-decisions.example.json \
  --output reviewed.json
paperreading finalize reviewed.json \
  --document document.json \
  --output package.json
paperreading verify package.json --document document.json --strict

paperreading read combines ingestion and extraction when a project repository is desired. The JSON provider is a deterministic replay adapter for evaluation and integration; it is not a hosted LLM. A future model adapter must implement the same provider contract and preserve candidate evidence, uncertainty, and run metadata.

Exercise deterministic v0.2 migration without mutating the project:

paperreading migrate examples/paper-record.example.json \
  --output paper-package.json

Validate, export, and project either version:

paperreading validate examples/paper-record.example.json
paperreading validate examples/paper-package.example.json
paperreading export examples/paper-package.example.json review.md --format markdown
paperreading project examples/paper-package.example.json

Verify a package whose evidence IDs reference an ingested document:

paperreading verify package.json \
  --document .paperreading/documents/<document-id>.json \
  --strict \
  --output verified-package.json

The extraction fixture is linked to the synthetic Markdown source and can be strictly verified end to end. It contains invented, non-citable materi