[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-94718":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":42,"readmeContent":43,"aiSummary":44,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":45,"discoverSource":46},94718,"paperreading","AOROM\u002Fpaperreading","AOROM","Evidence-grounded AI research workflow for traceable claims, explicit uncertainty, causal-language checks, and reviewable JSON, Markdown, and Excel exports.",null,"Python",110,3,2,1,0,41.81,"MIT License",false,"main",true,[22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"academic-research","academic-workflow","agent-skills","ai-research","causal-inference","codex","codex-skills","command-line-tool","data-provenance","evidence-grounded","evidence-traceability","evidence-verification","excel","literature-review","pydantic","python","reproducible-research","research-integrity","research-tools","research-workflow","2026-08-25 04:01:22","\u003Ch1 align=\"center\">PaperReading\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fassets\u002Fpaperreading-hero.png\" width=\"100%\" alt=\"PaperReading turns source documents into traceable evidence, structured research packages, and explicit verification states.\">\n\u003C\u002Fp>\n\n\u003Cdiv align=\"center\">\n  \u003Cp>\u003Cstrong>Evidence-grounded AI research workflow\u003C\u002Fstrong>\u003C\u002Fp>\n  \u003Cp>\n    Turn research material into versioned, reviewable artifacts.\u003Cbr>\n    Trace claims to evidence. Separate reporting from analysis. Keep uncertainty visible.\n  \u003C\u002Fp>\n  \u003Cp>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAOROM\u002Fpaperreading\u002Factions\u002Fworkflows\u002Fci.yml\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002FAOROM\u002Fpaperreading\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI status\">\u003C\u002Fa>\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-3776AB?logo=python&logoColor=white\" alt=\"Python 3.10 or newer\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-0.3.1-4C1\" alt=\"Version 0.3.1\">\n    \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-2EA44F\" alt=\"MIT License\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002FAOROM\u002Fpaperreading\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FAOROM\u002Fpaperreading?style=flat&logo=github&label=Stars\" alt=\"GitHub stars\">\u003C\u002Fa>\n  \u003C\u002Fp>\n  \u003Cp>\u003Cstrong>English\u003C\u002Fstrong> · \u003Ca href=\"README.zh-CN.md\">简体中文\u003C\u002Fa>\u003C\u002Fp>\n  \u003Cp>\n    \u003Ca href=\"#try-it-in-60-seconds\">Quick start\u003C\u002Fa> ·\n    \u003Ca href=\"#what-ships-in-v031\">Capabilities\u003C\u002Fa> ·\n    \u003Ca href=\"#how-it-works\">Architecture\u003C\u002Fa> ·\n    \u003Ca href=\"RESEARCH_PRINCIPLES.md\">Research principles\u003C\u002Fa> ·\n    \u003Ca href=\"ROADMAP.md\">Roadmap\u003C\u002Fa> ·\n    \u003Ca href=\"CONTRIBUTING.md\">Contribute\u003C\u002Fa>\n  \u003C\u002Fp>\n\u003C\u002Fdiv>\n\nPaperReading 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.\n\n> [!IMPORTANT]\n> **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.\n\n## From fluent summaries to defensible research artifacts\n\n| Research requirement | PaperReading rule |\n|---|---|\n| Traceability | Claims reference de-duplicated evidence spans with source and locator metadata |\n| Epistemic separation | Paper-reported content and researcher or AI-assisted analysis live in different objects |\n| Inference discipline | Causal wording requires an eligible design and an explicit identification strategy |\n| Explicit uncertainty | Verification returns `verified`, `partial`, or `failed`; migration never implies source checking |\n| Reproducibility | Versioned schemas, run metadata, deterministic migrations, and inspectable local files preserve provenance |\n| Compatibility | JSON, Markdown, legacy 13-field projection, and safe Excel append share one validated domain model |\n\nThese 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.\n\n## Try it in 60 seconds\n\nClone the repository, install the Core package, and validate the checked-in research package:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FAOROM\u002Fpaperreading.git\ncd paperreading\npython -m pip install -e .\npaperreading validate examples\u002Fpaper-package.example.json\n```\n\nThe 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.\n\n| If you want to… | Start here |\n|---|---|\n| Evaluate the artifact model | [`examples\u002Fpaper-package.example.json`](examples\u002Fpaper-package.example.json) and [versioned schemas](schemas\u002Fv0.3) |\n| Use the Codex workflow | [`skills\u002Fpapers-reading-skill`](skills\u002Fpapers-reading-skill) |\n| Integrate from Python | [Python API](#python-api) |\n| Preserve an Excel workflow | [Safe Excel compatibility](#safe-excel-compatibility) |\n| Understand research safeguards | [Research Principles](RESEARCH_PRINCIPLES.md) |\n| Help shape the project | [Roadmap](ROADMAP.md) and [contribution guide](CONTRIBUTING.md) |\n\n## What ships in v0.3.1\n\n| Capability | Status | Public contract |\n|---|---|---|\n| v0.3 research package | Implemented | `PaperPackage` separates document, grounded record, normalized evidence, analysis, audit, and run metadata |\n| Source-aware ingestion | Implemented | Deterministic UTF-8 text\u002FMarkdown plus optional text-based PDF parsing behind one `DocumentParser` port |\n| Extraction lifecycle | Implemented | Provider-neutral staged extraction, candidate\u002Fconflict preservation, explicit human review, and guarded finalization |\n| Offline JSON provider | Implemented | Replays inspectable candidate and evidence output without a network call or hidden model dependency |\n| Evidence graph | Implemented | Research objects reference de-duplicated `EvidenceSpan` nodes by stable ID |\n| Evidence verification v2 | Implemented | Source, page, block, section, text-hash, and local-window fuzzy quotation checks with explicit states |\n| v0.2 migration | Implemented | Deterministic `PaperRecord` → `PaperPackage` migration with visible provenance limitations |\n| Analysis separation | Implemented | Researcher assessments and extensions live outside the source-grounded record |\n| Causal-language guard | Implemented | Causal wording requires an eligible design and an explicit identification strategy |\n| Export and compatibility | Implemented | Lossless JSON, reviewable Markdown, legacy 13-field projection, and safe Excel append |\n| Local project storage | Implemented | Atomic, inspectable JSON files under `.paperreading\u002F`; no database required |\n| OCR \u002F hosted LLM \u002F PDF geometry \u002F batch \u002F search \u002F synthesis | Planned | Sequenced in the [roadmap](ROADMAP.md) and never presented as shipped |\n\n## How it works\n\n```mermaid\nflowchart LR\n    S[\"Text \u002F Markdown \u002F text-based PDF\"] --> I[\"Parser adapters\"]\n    I --> D[\"PaperDocument\"]\n    D --> E[\"Staged provider extraction\"]\n    E --> R[\"PaperDraft: candidates + conflicts\"]\n    R --> H[\"Explicit human review\"]\n    H --> P[\"Finalized PaperPackage\"]\n    V2[\"v0.2 PaperRecord\"] --> M[\"Deterministic migration\"]\n    M --> P[\"v0.3 PaperPackage\"]\n    D --> V[\"Evidence verifier\"]\n    P --> V\n    V --> O{\"Validated artifact\"}\n    O --> J[\"JSON\"]\n    O --> MD[\"Markdown\"]\n    O --> L[\"Legacy 13-field projection\"]\n    L --> X[\"Safe Excel exporter\"]\n```\n\nThe dependency direction is deliberate:\n\n```text\ndomain \u003C- migrations \u002F ingestion \u002F verification \u002F validation \u002F projections\n       \u003C- application use cases \u003C- CLI \u002F Skill \u002F exporters \u002F repositories\n```\n\nThe 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.\n\n## Research constitution\n\nThe normative [Research Principles](RESEARCH_PRINCIPLES.md) 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.\n\n## Explore the command workflow\n\nInstall optional PDF and Excel adapters only when they are needed:\n\n```bash\npython -m pip install -e \".[pdf,excel]\"\n```\n\nInitialize an inspectable local project:\n\n```bash\npaperreading init\n```\n\nThis creates `.paperreading\u002Fconfig.toml`, a manifest, and separate directories for documents, drafts, records, analyses, audits, and cache data.\n\nExercise the source-ingestion contract with the synthetic Markdown fixture:\n\n```bash\npaperreading ingest examples\u002Fsource.example.md\n```\n\nRun the complete, network-free Draft → Review → Finalize fixture:\n\n```bash\npaperreading ingest examples\u002Fsource.example.md --output document.json\npaperreading extract document.json \\\n  --provider-manifest examples\u002Fextraction-manifest.example.json \\\n  --output bundle.json\npaperreading review bundle.json \\\n  --decisions examples\u002Freview-decisions.example.json \\\n  --output reviewed.json\npaperreading finalize reviewed.json \\\n  --document document.json \\\n  --output package.json\npaperreading verify package.json --document document.json --strict\n```\n\n`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.\n\nExercise deterministic v0.2 migration without mutating the project:\n\n```bash\npaperreading migrate examples\u002Fpaper-record.example.json \\\n  --output paper-package.json\n```\n\nValidate, export, and project either version:\n\n```bash\npaperreading validate examples\u002Fpaper-record.example.json\npaperreading validate examples\u002Fpaper-package.example.json\npaperreading export examples\u002Fpaper-package.example.json review.md --format markdown\npaperreading project examples\u002Fpaper-package.example.json\n```\n\nVerify a package whose evidence IDs reference an ingested document:\n\n```bash\npaperreading verify package.json \\\n  --document .paperreading\u002Fdocuments\u002F\u003Cdocument-id>.json \\\n  --strict \\\n  --output verified-package.json\n```\n\nThe extraction fixture is linked to the synthetic Markdown source and can be strictly verified end to end. It contains invented, non-citable material. Extracting an arbitrary paper still requires a compatible provider; PaperReading does not silently make a model call or claim OCR capability.\n\n## The v0.3 artifact model\n\n```text\nPaperPackage\n├── document: DocumentManifest\n├── record: GroundedPaperRecord\n│   ├── metadata \u002F questions \u002F theory \u002F data \u002F variables \u002F design\n│   ├── source_claims -> evidence_ids[]\n│   ├── findings \u002F mechanisms \u002F heterogeneity \u002F robustness -> evidence_ids[]\n│   └── paper-reported limitations\n├── evidence_index: {evidence_id -> EvidenceSpan}\n├── analysis\n│   ├── researcher or AI-assisted assessments\n│   └── executable research extensions\n├── audit: optional method-audit report\n└── run: reproducibility metadata\n```\n\n`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.\n\nAn evidence span can include both logical and physical locators:\n\n```json\n{\n  \"evidence_id\": \"ev-0123456789abcdef\",\n  \"source_id\": \"src-0123456789abcdef\",\n  \"type\": \"TEXT\",\n  \"page\": 1,\n  \"section_path\": [\"Results\"],\n  \"block_id\": \"p1-b0007\",\n  \"char_start\": 420,\n  \"char_end\": 581,\n  \"quoted_text\": \"A source quotation used for verification.\"\n}\n```\n\nThe 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 and quotation resolve against the supplied `PaperDocument`; it still cannot establish that the paper's methods or claims are correct.\n\n## Schemas and compatibility\n\nThe root schema names remain convenient stable aliases. Immutable versioned contracts live under [`schemas\u002Fv0.2`](schemas\u002Fv0.2) and [`schemas\u002Fv0.3`](schemas\u002Fv0.3).\n\n| Input | Validate | JSON\u002FMarkdown | Legacy projection | Safe Excel |\n|---|---:|---:|---:|---:|\n| v0.2 `PaperRecord` | Yes | Yes | Yes | Yes |\n| v0.3 `PaperPackage` | Yes | Yes | Yes, when research extensions exist | Yes, through the same projection |\n\nMigration preserves the v0.2 13-field projection exactly. It does not pretend that legacy evidence has been checked against source content; migrated packages remain visibly marked `migrated` until verification runs.\n\n## Python API\n\n```python\nfrom datetime import datetime, timezone\nfrom pathlib import Path\n\nfrom paperreading import (\n    PaperRecord,\n    migrate_v02_to_v03,\n    to_legacy_13_fields,\n    validate_package,\n)\n\nrecord = PaperRecord.model_validate_json(\n    Path(\"record.json\").read_text(encoding=\"utf-8\")\n)\npackage = migrate_v02_to_v03(\n    record,\n    migrated_at=datetime.now(timezone.utc),\n)\nreport = validate_package(package)\n\nif report.valid:\n    legacy_row = to_legacy_13_fields(package)\n```\n\n## Safe Excel compatibility\n\n```bash\npaperreading export package.json literature.xlsx --format excel --sheet 中文\n```\n\nThe workbook must already contain `中文` and `英文` worksheets. The exporter:\n\n- validates the 12- or 13-column header contract;\n- detects duplicates without overwriting them;\n- preserves existing values, formulas, styles, tables, filters, and frozen panes;\n- creates a timestamped backup;\n- writes and reopens a temporary file for validation; and\n- replaces the source workbook atomically only after validation succeeds.\n\nThe legacy `skills\u002Fpapers-reading-skill\u002Fscripts\u002Fappend_paper_reading.py` entry point remains available for existing 13-field JSON integrations. No personal workbook path is committed; `PAPER_READING_WORKBOOK` may supply an existing local configuration.\n\n## Codex Skill\n\nCopy [`skills\u002Fpapers-reading-skill`](skills\u002Fpapers-reading-skill) into the Codex skills directory after installing the Core package, start a new session, and invoke `$papers-reading-skill`. The standalone Skill directory carries the same MIT license notice.\n\nThe Skill is an adapter, not a second implementation. It respects the supplied source boundary, constructs a source-grounded package or compatible v0.2 record, runs Core validation, reports uncertainty, and requests authorization before workbook mutation.\n\n## Documentation map\n\n| Document | Purpose |\n|---|---|\n| [Research Principles](RESEARCH_PRINCIPLES.md) | Normative rules for validity, evidence, inference, uncertainty, reproducibility, and ethics |\n| [Architecture](docs\u002Farchitecture.md) | Parser and provider ports, artifact lifecycle, identity rules, and finalization gates |\n| [Roadmap](ROADMAP.md) | Shipped boundaries, planned hypotheses, milestones, and release gates |\n| [Contribution guide](CONTRIBUTING.md) | Architecture, schema evolution, compatibility, testing, and research-integrity checks |\n| [Security policy](SECURITY.md) | Private vulnerability-reporting guidance and supported-version policy |\n| [Changelog](CHANGELOG.md) | Versioned record of public capability and compatibility changes |\n| [MIT License](LICENSE) | Permission to use, copy, modify, distribute, sublicense, and sell the project |\n\n## Project structure\n\n```text\npaperreading\u002F\n├── LICENSE                 # OSI-approved MIT open-source license\n├── RESEARCH_PRINCIPLES*.md # Bilingual academic-research contract\n├── docs\u002Fassets\u002F            # Repository presentation assets and provenance\n├── src\u002Fpaperreading\u002F\n│   ├── domain\u002F          # v0.2 and v0.3 strict models\n│   ├── ingestion\u002F       # text, Markdown, and optional text-based PDF parsers\n│   ├── providers\u002F       # extraction protocol and offline JSON adapter\n│   ├── migrations\u002F      # version-to-version transformations\n│   ├── verification\u002F    # source-content evidence checks\n│   ├── validation\u002F      # evidence-state and causal-language rules\n│   ├── application\u002F     # reusable use cases\n│   ├── repositories\u002F    # local atomic JSON adapter\n│   ├── projections\u002F     # legacy 13-field projection\n│   └── exporters\u002F       # JSON, Markdown, and Excel adapters\n├── schemas\u002F             # root aliases and versioned JSON Schemas\n├── skills\u002F              # Codex adapter\n├── examples\u002F            # synthetic, non-citable fixtures\n├── tests\u002F               # domain, CLI, migration, verifier, and Excel safety tests\n└── tools\u002F               # deterministic schema, example, and Skill checks\n```\n\n## Development\n\n```bash\npython -m pip install -e \".[excel,pdf,dev]\"\npython -m ruff check .\npython -m ruff format --check .\npython -m mypy\npython tools\u002Fexport_schemas.py --check\npython tools\u002Fgenerate_examples.py --check\npython tools\u002Fvalidate_skill.py skills\u002Fpapers-reading-skill\npython tools\u002Fvalidate_license.py\npython -m unittest discover -s tests -v\npython -m pip wheel --no-deps --wheel-dir dist .\npython tools\u002Fvalidate_license.py --wheel-dir dist\n```\n\nIf this direction is useful to your research workflow, consider [starring the repository](https:\u002F\u002Fgithub.com\u002FAOROM\u002Fpaperreading), opening an issue with a reproducible case, or contributing through [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nPaperReading is open-source software released under the [MIT License](LICENSE). Unless a file states otherwise, the license covers the repository's source code, schemas, synthetic examples, documentation, and presentation assets.\n\nThe MIT License does not grant rights to third-party papers, datasets, user-supplied inputs, or generated extracts. Those materials remain subject to their own copyright, privacy, confidentiality, consent, and redistribution terms.\n","PaperReading 是一个面向学术研究者的证据可追溯型AI工作流工具，旨在将文献材料转化为结构化、可审查的研究成果包。其核心功能包括：基于原文证据的声明溯源（支持定位到具体段落）、研究主张与原始报道内容的语义分离、因果性语言的合规性检查、不确定性显式标注（verified\u002Fpartial\u002Ffailed），以及导出为JSON、Markdown和Excel等可复审格式。项目采用Python实现，集成Pydantic验证与Codex技能，强调数据溯源、研究诚信与可重复性。适用于需要严谨证据支撑的文献综述、系统性评价、政策分析及AI辅助科研等场景。","2026-08-14 02:30:08","CREATED_QUERY"]