codex-pdf 0.1.1__tar.gz

codex_pdf-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e . pytest
+      - name: Test
+        run: pytest
+      - name: Parity Gate (Deep Profile)
+        run: |
+          python - <<'PY'
+          import fitz
+          from pathlib import Path
+          root = Path("tmp-parity")
+          root.mkdir(exist_ok=True)
+          path = root / "fixture.pdf"
+          doc = fitz.open()
+          page = doc.new_page(width=612, height=792)
+          page.insert_text((72, 72), "codex parity fixture")
+          doc.save(path)
+          PY
+          codex-pdf parity --fixtures-root tmp-parity --profile deep --max-files 5

codex_pdf-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.pyc
+dist/
+build/
+*.egg-info/
+coverage.xml
+htmlcov/

codex_pdf-0.1.1/LICENSE

@@ -0,0 +1,7 @@
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+codexPDF is distributed under the GNU Affero General Public License v3.0
+or (at your option) any later version.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see https://www.gnu.org/licenses/.

codex_pdf-0.1.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: codex-pdf
+Version: 0.1.1
+Summary: Authoritative, versioned PDF facts contract for Think Neverland tools.
+Author-email: Think Neverland <dev@thinkneverland.com>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: pikepdf>=9.0
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pymupdf>=1.24
+Description-Content-Type: text/markdown
+
+---
+title: "Overview"
+description: "Authoritative read-only PDF facts engine for Think Neverland tools. Versioned contract, schema-validated output, and consumer-agnostic extraction."
+group: "Getting started"
+order: 1
+slug: "overview"
+---
+
+# codexPDF
+
+`codexPDF` is Think Neverland's authoritative, read-only PDF facts reference.
+
+Other engines consult `codexPDF` for canonical document facts instead of
+re-parsing PDFs independently. The contract is versioned and schema-validated.
+
+## Status
+
+Current baseline includes:
+
+- Python package (`codex_pdf`) with typed models
+- CLI (`codex-pdf extract|schema|validate|probe|parity`)
+- Versioned schemas in `schemas/v1/`
+- Golden output harness under `tests/golden/`
+
+## Quickstart
+
+```bash
+uv sync
+uv run codex-pdf probe input.pdf --json
+uv run codex-pdf extract input.pdf --pretty > out.json
+uv run codex-pdf validate out.json
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile summary --max-files 5
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile inventory --max-files 5
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile deep --max-files 5
+```
+
+Optional external baseline comparison (consumer-specific adapter provided at runtime):
+
+```bash
+uv run codex-pdf parity \
+  --fixtures-root /path/to/pdfs \
+  --profile summary \
+  --baseline-command "<your_command_with_{pdf}_placeholder>"
+```
+
+## Contract
+
+The public API is the JSON contract rooted at `CodexDocument`.
+
+- Schema path: `schemas/v1/codex-document.schema.json`
+- Runtime model: `codex_pdf.models.v1.CodexDocument`
+- Stability policy: SemVer (`major` for breaking contract changes)
+
+## Documentation
+
+| Topic | Doc |
+| --- | --- |
+| Architecture and boundaries | [docs/architecture.md](./docs/architecture.md) |
+| CLI commands and usage patterns | [docs/cli.md](./docs/cli.md) |
+| Contract and schema versioning | [docs/contract.md](./docs/contract.md) |
+| Parity profiles and baselines | [docs/parity.md](./docs/parity.md) |
+| Preflight ingest adapters | [docs/preflight-ingest.md](./docs/preflight-ingest.md) |
+| Migration sequencing | [docs/migration-plan.md](./docs/migration-plan.md) |
+| Legacy discovery audit | [docs/discovery-audit.md](./docs/discovery-audit.md) |
+| Backward compatibility requirements | [docs/backward-compatibility.md](./docs/backward-compatibility.md) |
+| Cleanup stop-gates policy | [docs/cleanup-stop-gates.md](./docs/cleanup-stop-gates.md) |
+
+## License
+
+AGPL-3.0-or-later.

codex_pdf-0.1.1/README.md

@@ -0,0 +1,70 @@
+---
+title: "Overview"
+description: "Authoritative read-only PDF facts engine for Think Neverland tools. Versioned contract, schema-validated output, and consumer-agnostic extraction."
+group: "Getting started"
+order: 1
+slug: "overview"
+---
+
+# codexPDF
+
+`codexPDF` is Think Neverland's authoritative, read-only PDF facts reference.
+
+Other engines consult `codexPDF` for canonical document facts instead of
+re-parsing PDFs independently. The contract is versioned and schema-validated.
+
+## Status
+
+Current baseline includes:
+
+- Python package (`codex_pdf`) with typed models
+- CLI (`codex-pdf extract|schema|validate|probe|parity`)
+- Versioned schemas in `schemas/v1/`
+- Golden output harness under `tests/golden/`
+
+## Quickstart
+
+```bash
+uv sync
+uv run codex-pdf probe input.pdf --json
+uv run codex-pdf extract input.pdf --pretty > out.json
+uv run codex-pdf validate out.json
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile summary --max-files 5
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile inventory --max-files 5
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile deep --max-files 5
+```
+
+Optional external baseline comparison (consumer-specific adapter provided at runtime):
+
+```bash
+uv run codex-pdf parity \
+  --fixtures-root /path/to/pdfs \
+  --profile summary \
+  --baseline-command "<your_command_with_{pdf}_placeholder>"
+```
+
+## Contract
+
+The public API is the JSON contract rooted at `CodexDocument`.
+
+- Schema path: `schemas/v1/codex-document.schema.json`
+- Runtime model: `codex_pdf.models.v1.CodexDocument`
+- Stability policy: SemVer (`major` for breaking contract changes)
+
+## Documentation
+
+| Topic | Doc |
+| --- | --- |
+| Architecture and boundaries | [docs/architecture.md](./docs/architecture.md) |
+| CLI commands and usage patterns | [docs/cli.md](./docs/cli.md) |
+| Contract and schema versioning | [docs/contract.md](./docs/contract.md) |
+| Parity profiles and baselines | [docs/parity.md](./docs/parity.md) |
+| Preflight ingest adapters | [docs/preflight-ingest.md](./docs/preflight-ingest.md) |
+| Migration sequencing | [docs/migration-plan.md](./docs/migration-plan.md) |
+| Legacy discovery audit | [docs/discovery-audit.md](./docs/discovery-audit.md) |
+| Backward compatibility requirements | [docs/backward-compatibility.md](./docs/backward-compatibility.md) |
+| Cleanup stop-gates policy | [docs/cleanup-stop-gates.md](./docs/cleanup-stop-gates.md) |
+
+## License
+
+AGPL-3.0-or-later.

codex_pdf-0.1.1/docs/architecture.md

@@ -0,0 +1,35 @@
+---
+title: "Architecture"
+description: "codexPDF boundaries, extraction pipeline shape, and the contract-first model used by downstream tools."
+group: "Getting started"
+order: 2
+---
+
+# Architecture
+
+`codexPDF` is a contract-first facts engine for PDF documents.
+
+## Boundary
+
+- Read-only extraction only.
+- No rendering, layout, mutation, or rule adjudication.
+- Consumer-agnostic output: same contract regardless of caller.
+
+## Pipeline
+
+1. Input PDF bytes are loaded by the extractor layer.
+2. Domain extractors populate `CodexDocument` fields (pages, boxes, fonts,
+   images, color spaces, OCG/layers, annotations, transparency, trapping).
+3. Output is serialized as JSON against published schema definitions in
+   `schemas/v1/`.
+
+## Primary contract
+
+- Runtime model: `codex_pdf.models.v1.CodexDocument`
+- Schema: `schemas/v1/codex-document.schema.json`
+- Version marker: `schema_version` field in payload
+
+## Consumer relationship
+
+Downstream engines should treat codex output as the source of truth for
+document facts and keep any product-specific behavior in adapter layers.

codex_pdf-0.1.1/docs/backward-compatibility.md

@@ -0,0 +1,24 @@
+---
+title: "Backward Compatibility"
+description: "Consumer payload compatibility expectations during codexPDF rollout and cutover."
+group: "Project"
+order: 8
+---
+
+# Backward Compatibility Requirements
+
+During migration, preserve the existing consumer payloads while introducing
+codex-backed data:
+
+- `lint-pdf` viewer essentials shape:
+  - `pdf_version`, `page_count`, `is_encrypted`, `pages`, `info_dict`
+- findings payload fields consumed by `lint-pdf-ui`:
+  - `inspection_id`, `severity`, `page_num`, `bbox`, `message`, `details`
+- `loupe-pdf/types` public contracts:
+  - `PageInfo`, `LayerInfo`, `ViewerConfig`, `ColorSample`
+
+Compatibility strategy:
+
+1. Keep existing endpoints unchanged.
+2. Introduce codex fields as additive (`codex_*`) metadata.
+3. Maintain feature-flagged fallback to legacy parser paths.

codex_pdf-0.1.1/docs/cleanup-stop-gates.md

@@ -0,0 +1,25 @@
+---
+title: "Cleanup Stop Gates"
+description: "Release gates required before downstream parser deletion and hard cutover enforcement."
+group: "Project"
+order: 9
+---
+
+# STOP-Gated Cleanup Policy
+
+No deletions of parse code in downstream repositories are permitted until all
+conditions below pass and are approved.
+
+## Required gates
+
+1. Dual-run parity report on reference corpus is green.
+2. Contract schema remains backward-compatible for pinned consumers.
+3. Latest shipping release candidates of `lint-pdf` and `loupe-pdf` pass CI with codex enabled.
+4. Explicit go/no-go approval recorded for each repository cleanup PR.
+
+## Candidate cleanup targets (future)
+
+- `lint-pdf`: direct parser/semantic extraction branches replaced by codex adapter.
+- `loupe-pdf`: byte-scan spot extraction where codex provides canonical data.
+- `lint-pdf-ui`: legacy field alias handling after all APIs converge.
+- `assay-pdf`: none required; codex remains optional shell-out integration.

codex_pdf-0.1.1/docs/cli.md

@@ -0,0 +1,44 @@
+---
+title: "CLI"
+description: "Command reference for extract, schema, validate, probe, and parity workflows."
+group: "Getting started"
+order: 3
+---
+
+# CLI
+
+`codex-pdf` exposes a contract-oriented CLI.
+
+## Commands
+
+- `extract <input_pdf>` — emit full `CodexDocument` JSON.
+- `schema` — print schema JSON (published or runtime-generated).
+- `validate <codex_json>` — validate output against published schema.
+- `probe <input_pdf>` — return lightweight metadata summary.
+- `parity` — compare codex projections against baseline projections.
+
+## Common usage
+
+```bash
+uv run codex-pdf extract input.pdf --pretty > out.json
+uv run codex-pdf validate out.json
+uv run codex-pdf probe input.pdf --json
+```
+
+## Parity usage
+
+```bash
+uv run codex-pdf parity \
+  --fixtures-root tests/fixtures \
+  --profile deep \
+  --max-files 10
+```
+
+Baseline command mode:
+
+```bash
+uv run codex-pdf parity \
+  --fixtures-root /path/to/pdfs \
+  --profile summary \
+  --baseline-command "<command with {pdf} placeholder>"
+```

codex_pdf-0.1.1/docs/contract.md

@@ -0,0 +1,36 @@
+---
+title: "Contract and Schemas"
+description: "CodexDocument model, schema publishing approach, and compatibility policy."
+group: "Reference"
+order: 4
+---
+
+# Contract and Schemas
+
+The codex public contract is rooted at `CodexDocument`.
+
+## Runtime model
+
+- Python model: `codex_pdf.models.v1.CodexDocument`
+- Child types: page boxes, inventories, fonts, images, color spaces, OCGs,
+  annotations, preflight reports, and warnings
+
+## Published schemas
+
+- Schema root: `schemas/v1/codex-document.schema.json`
+- Child schemas: `schemas/v1/codex-*.schema.json`
+- Changelog: `schemas/CHANGELOG.md`
+
+## Versioning policy
+
+- `schema_version` in payload tracks contract version.
+- Breaking contract changes increment major version.
+- Non-breaking additive changes use minor/patch increments.
+
+## Validation
+
+Use the CLI validator:
+
+```bash
+uv run codex-pdf validate out.json
+```

codex_pdf-0.1.1/docs/discovery-audit.md

@@ -0,0 +1,61 @@
+---
+title: "Discovery Audit"
+description: "Initial cross-repo parsing inventory used to design codexPDF migration boundaries and ownership."
+group: "Project"
+order: 6
+---
+
+# Discovery Audit
+
+This audit captures parse-related extraction surfaces before migration.
+
+## lint-pdf
+
+- `src/lintpdf/parser/pikepdf_adapter.py`
+  - `PikePDFAdapter.open`, `parse_content_stream`, `get_stream_data`
+  - **Disposition:** move/rewrite into codex extractor core.
+- `src/lintpdf/semantic/builder.py`
+  - `SemanticModelBuilder.build`
+  - **Disposition:** rewrite into codex semantic inventory builder.
+- `src/lintpdf/semantic/interpreter.py`
+  - `ContentStreamInterpreter.interpret`
+  - **Disposition:** rewrite with codex event inventory contracts.
+- `src/lintpdf/imports/*.py`
+  - `PitStopXmlParser`, `Callas*Parser`, `AcrobatXmlParser`
+  - **Disposition:** adapt into codex preflight ingest adapters.
+
+## lint-pdf-ui
+
+- `packages/viewer-shared/src/PdfViewer.tsx`
+  - `mergeConfig` JSON normalization for viewer payloads.
+  - **Disposition:** stay in UI; add codex compatibility fields.
+- `packages/viewer-shared/src/lintpdf/sources/finding-overlay.ts`
+  - finding-to-overlay translation.
+  - **Disposition:** stay in UI boundary adapter.
+
+## loupe-pdf
+
+- `browser/index.ts`
+  - `extractOcgIds`, `detectSpotInksFromPdfBytes`
+  - **Disposition:** move facts extraction to codex, keep rendering in loupe.
+- `fallback-pdfjs/index.ts`
+  - fallback page/layer extraction.
+  - **Disposition:** keep as visualization fallback path.
+- `types/index.ts`
+  - core viewer contracts.
+  - **Disposition:** extend for codex document transport shape.
+
+## assay-pdf
+
+- `src/assay_pdf/spec/parser.py`
+  - GWG workbook parsing.
+  - **Disposition:** stay in assay.
+- `src/assay_pdf/harness/runners/*.py`
+  - engine output parsing.
+  - **Disposition:** add codex CLI shell-out runner; keep MIT boundary.
+
+## Overlap highlights
+
+- Duplicate parse facts for OCG/layers across `lint-pdf` and `loupe-pdf`.
+- Spot/separation extraction differs in completeness.
+- UI contract naming drift risk (`findings_source` vs historical `preflight_source`).

codex_pdf-0.1.1/docs/migration-plan.md

@@ -0,0 +1,32 @@
+---
+title: "Migration Plan"
+description: "Phased rollout plan for moving PDF fact extraction from downstream engines into codexPDF."
+group: "Project"
+order: 7
+---
+
+# Migration Plan
+
+## Phase 0 (this repo)
+
+1. Publish `CodexDocument` contract and schema.
+2. Ship CLI (`extract`, `schema`, `validate`, `probe`).
+3. Commit golden output harness.
+
+## Phase 1 (non-destructive adapters)
+
+1. `lint-pdf`: optional codex-backed extraction path behind feature flag.
+2. `lint-pdf-ui`: accept codex payload metadata fields while preserving existing config.
+3. `loupe-pdf`: add contract type for codex-fed metadata facts.
+4. `assay-pdf`: add codex subprocess runner (`codex-pdf extract`) with no in-process import.
+
+## Phase 2 (parity hardening)
+
+1. Run dual-path comparisons on reference corpus.
+2. Resolve mismatches in page boxes, OCG inventory, and spot metadata.
+3. Freeze schema at `1.0.0` once parity gates pass.
+
+## Phase 3 (STOP-gated cleanup)
+
+- No parser deletion until explicit approval.
+- Submit one deletion proposal per repo with before/after API compatibility proof.

codex_pdf-0.1.1/docs/parity.md

@@ -0,0 +1,36 @@
+---
+title: "Parity"
+description: "Projection-based parity checks used to compare codex output with external baselines."
+group: "Reference"
+order: 5
+---
+
+# Parity
+
+Parity verifies that codex output matches an expected projection shape.
+
+## Profiles
+
+- `summary` — core viewer essentials (version, page count, encryption, boxes)
+- `inventory` — aggregate and per-page inventory counts
+- `deep` — expanded conformance/trapping/count snapshots
+
+## Output
+
+Parity writes a JSON report with:
+
+- profile
+- fixture set
+- per-file case results
+- diff list per case
+- total diff count
+
+## Typical workflow
+
+```bash
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile summary
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile inventory
+uv run codex-pdf parity --fixtures-root tests/fixtures --profile deep
+```
+
+Use `--fail-on-diff` in CI for gating.

codex_pdf-0.1.1/docs/preflight-ingest.md

@@ -0,0 +1,33 @@
+---
+title: "Preflight Ingest"
+description: "Adapters that normalize external preflight reports into codex issue payloads."
+group: "Reference"
+order: 6
+---
+
+# Preflight Ingest
+
+codex includes report adapters to normalize external findings into a
+single issue model.
+
+## Supported formats
+
+- `lintpdf_json`
+- `callas_json`
+- `callas_xml`
+- `pitstop_xml`
+- `acrobat_xml`
+
+## Normalized output
+
+All adapters emit `CodexPreflightReport` with:
+
+- `source_engine`
+- `ingest_format`
+- normalized `issues` list (`CodexIssue`)
+- optional ingest warnings
+
+## Entry point
+
+- Adapter module: `codex_pdf.preflight_ingest.adapters`
+- Dispatcher: `parse_preflight_report(content, fmt)`

codex_pdf-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-pdf"
+version = "0.1.1"
+description = "Authoritative, versioned PDF facts contract for Think Neverland tools."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "AGPL-3.0-or-later"
+authors = [{ name = "Think Neverland", email = "dev@thinkneverland.com" }]
+dependencies = [
+  "pydantic>=2.8",
+  "jsonschema>=4.23",
+  "PyMuPDF>=1.24",
+  "pikepdf>=9.0",
+]
+
+[project.scripts]
+codex-pdf = "codex_pdf.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codex_pdf"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]