Split a scientific journal-issue PDF into clean, per-article PDFs — each with validated metadata and verifiable checksums, so downstream teams can trust the output instead of re-checking it by hand.
One long issue goes in; you get one PDF per article (correct page ranges), plus structured metadata (CSV/JSON), a manifest, a processing report, and SHA-256 checksums.
Scientific journals ship as long, multi-article PDF issues. Before any indexing, review, archiving, or data work can start, each issue has to be split into separate per-article files — with the right page ranges and metadata.
Done by hand, this is slow, repetitive, and easy to get wrong — and it has to happen for every issue, every time. A single mismatched page range or dropped article quietly corrupts everything downstream.
This project shows the automated, verifiable alternative: a clean pipeline that turns an issue into per-article PDFs plus structured, checked, reproducible article-level data.
Journal issue (PDF, N articles)
│
▼ page range per article (from metadata; boundary detection is the integration point)
[Split] cut each article's pages into its own PDF
│
▼
[Validate] reconcile counts & pages: PDFs = articles = CSV rows = JSON records
│
▼
Result: N per-article PDFs -> articles/<article_id>.pdf (primary deliverable)
+ validated CSV/JSON metadata, manifest, report, checksums (verification evidence)
The per-article PDFs are the deliverable; the metadata, manifest, and SHA-256 checksums are the evidence that the split is complete and correct. The repository implements splitting, validation, export, and verification end to end on synthetic data. The page ranges come from issue metadata; automatic article-boundary detection from raw PDF text is the one stage a production adaptation adds.
Downstream work depends on this output being correct, so correctness is built into the pipeline, not assumed:
- Reconciled — the split is validated end to end: number of per-article PDFs, CSV rows, and JSON records all agree, and the article page counts sum to the issue's page count (no gaps, no overlap).
- Verifiable — each run ships with a manifest and per-file SHA-256 checksums (article PDFs and metadata).
- Reproducible — deterministic output: the same issue produces byte-identical per-article PDFs and exports.
- Auditable — an issue-level processing report records what was detected, split, exported, and validated.
python -m pip install -e ".[dev]"
python tools/generate_sample.py
python examples/quickstart.pyThe demo writes a sample journal issue to data/sample/input/ and, to data/sample/output/, one PDF per article under articles/, plus articles.csv, articles.json, and workflow-evidence artifacts (export_manifest.json, issue_processing_report.json, checksums.sha256).
Sample output:
data/sample/output/articles/SPLIT-001.pdf (pages 1-4)
data/sample/output/articles/SPLIT-002.pdf (pages 5-8)
data/sample/output/articles/SPLIT-003.pdf (pages 9-12)
article_id,title,page_start,page_end,sha256
SPLIT-001,Synthetic Cohort Study of Editorial Workflow Timing,1,4,aff9...
SPLIT-002,Rule-Based Detection of Article Headers in Journal Issues,5,8,357e...
SPLIT-003,Integrity Checks for Article-Level CSV and JSON Exports,9,12,29a9...
Primary deliverable — one PDF per article: data/sample/output/articles/<article_id>.pdf, containing exactly that article's pages.
Accompanying metadata (CSV + JSON):
| Field | Description |
|---|---|
article_id |
Stable article identifier for downstream processing |
title |
Article title |
authors |
Semicolon-separated author list in CSV; list of strings in JSON |
page_start |
First page of the article block |
page_end |
Last page of the article block |
sha256 |
Deterministic SHA-256 digest for metadata integrity checks |
The pipeline does not just emit files — it emits proof the split is correct. Each run produces a manifest recording the core output invariant:
{
"issue_id": "ISSUE-2026-01",
"articles_expected": 3,
"articles_exported": 3,
"article_pdfs": 3,
"csv_rows": 3,
"json_records": 3,
"validation_status": "passed"
}An issue-level processing report summarizes the run:
{
"issue_id": "ISSUE-2026-01",
"pages_total": 12,
"articles_detected": 3,
"articles_exported": 3,
"article_pdfs": 3,
"csv_rows": 3,
"json_records": 3,
"validation_status": "passed"
}And checksums.sha256 records deterministic SHA-256 values for every per-article PDF plus articles.csv, articles.json, and export_manifest.json — so any later change is detectable.
The same pattern — turn a messy source document into validated, traceable, structured output — applies wherever teams process documents at scale:
- Scientific and medical journal processing
- Research archive digitization
- Regulatory and compliance document processing
- Structured metadata extraction pipelines
- Pre-indexing and RAG data preparation
Journal issue (PDF) + article metadata
│
▼
ArticleMetadata models (typed contracts)
│
▼
Splitter (PyMuPDF) → per-article PDFs
│
▼
Validator → CSV/JSON writers → manifest / report / checksums → downstream workflow
Each stage has a typed contract, so a real boundary-detection backend can be added without changing the public output format.
See docs/architecture.md (implemented data flow), docs/architecture_overview.md (intended pipeline shape), and docs/roadmap.md (phases).
pytest tests/ -v
ruff check src/ tests/ examples/ tools/CI runs on GitHub Actions. All tests use synthetic sample data — no private data required.
Problem. Scientific journal PDFs must be split into reliable, per-article files before editorial, indexing, or data work can begin — a repetitive, error-prone manual task that recurs for every issue.
Solution. A clean pipeline that splits an issue into per-article PDFs and produces validated, checksummed article-level metadata with manifests and reproducibility built in, so downstream teams can trust the output instead of re-verifying it.
Result. A reliable, auditable foundation for document-processing workflows — designed so a real article-boundary detector can be added without changing the output contract that downstream systems depend on.
Role. Sole engineer — architecture, splitting, data contract, validators, CI, and the public-safe framing that keeps the repository shareable without exposing internal systems or private data.
This public repository demonstrates the split-and-verify foundation on synthetic samples:
- Synthetic sample data — no real publications or authors; safe to run in seconds with no setup.
- Implemented: per-article PDF splitting by page range (PyMuPDF), typed article-metadata models, CSV/JSON export contracts, manifest/report/checksum artifacts, end-to-end reconciliation, and CI.
- The integration layer: automatic article-boundary detection from raw PDF text is the stage a production adaptation adds — here the page ranges are supplied via issue metadata.
The splitting, contract, validation, and verification are real; automatic boundary detection is the layer left open for adaptation to a specific publisher's sources.
- Python 3.11+
- PyMuPDF — PDF splitting
- CSV / JSON export with manifest, report, and checksum artifacts
- pytest — testing · ruff — linting
- GitHub Actions CI
MIT