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 ingests UTF-8 text and Markdown, migrates v0.2 records, normalizes evidence by stable ID, and verifies text locators and quotations. It does not yet parse PDFs, call an AI provider, run batch jobs, search a SQLite library, synthesize multiple papers, or discover research gaps automatically.

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

How it works

flowchart LR
    S["UTF-8 text or Markdown"] --> I["Deterministic ingestion"]
    I --> D["PaperDocument"]
    V2["v0.2 PaperRecord"] --> M["Deterministic migration"]
    M --> P["v0.3 PaperPackage"]
    D --> V["Evidence verifier"]
    P --> V
    A["Skill or extraction adapter"] --> P
    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 Excel support only when it is needed:

python -m pip install -e ".[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

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 checked-in ingestion and migration examples exercise separate contracts; they are not automatically linked. In v0.3, a Skill or another extraction adapter constructs the source-linked package. PaperReading itself does not yet infer a complete research record from arbitrary prose.

The v0.3 artifact model

PaperPackage
├── document: DocumentManifest
├── record: GroundedPaperRecord
│   ├── metadata / questions / theory / data / variables / design
│   ├── source_claims -> evidence_ids[]
│   ├── findings / mechanisms / heterogeneity / robustness -> evidence_ids[]
│   └── paper-reported limitations
├── evidence_index: {evidence_id -> EvidenceSpan}
├── analysis
│   ├── researcher or AI-assisted assessments
│   └── executable research extensions
├── audit: optional method-audit report
└── run: reproducibility metadata

GroundedPaperRecord contains source-derived information. ResearchAnalysis contains interpretation and proposed extensions. Keeping them separate prevents a generated idea from being mistaken for a paper finding.

An evidence span can include both logical and physical locators:

{
  "evidence_id": "ev-0123456789abcdef",
  "source_id": "src-0123456789abcdef",
  "type": "TEXT",
  "page": 1,
  "section_path": ["Results"],
  "block_id": "p1-b0007",
  "char_start": 420,
  "char_end": 581,
  "quoted_text": "A source quotation used for verification."
}

The traceability score measures locator specificity. It is not a truth probability, study-quality score, causal-validity score, or external-validity judgment. Verification checks whether the locator