lint-pdf 0.1.0b33

Detection-only PDF preflight engine

LintPDF

Detection-only PDF preflight engine — analyze packaging, label, and commercial-print PDFs against 500+ checks (image DPI, total area coverage, bleed, fonts, barcodes, color spaces, conformance, AI-assisted regulatory rules, …) and surface findings as structured JSON, HTML reports, or annotated PDFs.

LintPDF is an open-source PDF preflight engine with a hosted deployment at lintpdf.com. The OSS package IS the full engine — it includes the HTTP surface for submitting jobs and fetching results. You can self-host it standalone. There is no commercial SaaS tier, no multi-tenancy layer, no billing, no white-label reports, and no admin console sitting on top.

This repository is licensed under the GNU Affero General Public License v3.0 or later — see the licensing notes below for what that means in practice when you embed or modify the engine.

---

Table of contents

• What it does
• Quick start (Docker)
• Quick start (Python)
• Submit your first PDF
• Documentation
• Licensing
• Contributing
• Support

---

What it does

LintPDF answers one question: "is this PDF print-ready?"

You POST a file. The engine analyzes it across 500+ checks grouped into categories (image quality, color, fonts, packaging, barcodes, regulatory compliance, conformance, …) and returns:

• A verdict — pass, pass_with_warnings, or fail.
• A list of findings — each with an inspection id, severity, page number, bounding box, and a human-readable message.
• A rendered report — HTML, PDF, JSON, or annotated PDF.
• A viewer payload — separations, TAC heatmap, font list, layer toggles for the embedded React viewer (@printwithsynergy/lens-pdf).

The engine ships built-in profiles for GWG 2022 (sheetfed + digital), PDF/X-4, and packaging — and supports custom rulesets authored as JSON. AI-assisted features (Claude-driven audit, explanations, dieline detection, regulatory checks) are optional and self-skip cleanly when no AI inference service is configured.

For the deeper architectural picture see docs/ARCHITECTURE.md.

---

Quick start (Docker)

# Clone + boot the full stack (engine + Postgres + Redis + ClamAV)
git clone https://github.com/printwithsynergy/lint-pdf.git
cd lint-pdf
docker compose up -d

# Wait for /ready to return 200
curl http://localhost:8000/ready
# {"status":"ok","database":"connected","redis":"connected"}

The compose stack is a single-node OSS deploy with Celery worker + beat + ClamAV sidecar. For production / HA topology see docs/DEPLOYMENT.md.

---

Quick start (Python)

# 3.12+ required
uv pip install lintpdf

# Or pin to a specific git ref:
#   uv pip install "lintpdf @ git+https://github.com/printwithsynergy/lint-pdf.git@main"

# Minimum env (production refuses to boot without these)
export LINTPDF_SECRET_KEY=$(openssl rand -hex 32)
export LINTPDF_DATABASE_URL=postgresql://user:pass@localhost/lintpdf
export LINTPDF_REDIS_URL=redis://localhost:6379/0

# Boot the API
uvicorn lintpdf.api.app:create_app --factory --host 0.0.0.0 --port 8000

A complete environment-variable reference and the OSS-mode hard fails (production secret key + CORS wildcard) live in docs/DEPLOYMENT.md.

---

Submit your first PDF

# 1. Submit
curl -X POST http://localhost:8000/api/v1/jobs \
  -F "file=@artwork.pdf" \
  -F "profile_id=lintpdf-default"
# { "job_id": "job_abc…", "status": "queued" }

# 2. Poll
curl http://localhost:8000/api/v1/jobs/job_abc…
# { "id": "job_abc…", "status": "completed", "verdict": "pass_with_warnings", … }

# 3. One-call snapshot (job + reports + annotations + verdicts)
curl http://localhost:8000/api/v1/jobs/job_abc…/state | jq .

The engine boots without any auth out of the box — see docs/DEPLOYMENT.md#auth to wire in your own auth (single-user, OIDC, basic auth, or a custom middleware).

---

Documentation

Doc	Covers
docs/ARCHITECTURE.md	Component layout, request flow, the three-scope toggle cascade, snapshots, AI tier model.
docs/DEPLOYMENT.md	Self-hosting reference: env vars, services, Docker / Railway / single-node, OSS-mode toggle, security gates, backups.
docs/EXTENDING.md	Service overrides (email / entitlements / billing / auth) and analyzer plugin authoring quick reference.
docs/plugin-api.md	Full plugin Protocol reference — manifest fields, AnalyzerContext, banned imports, capability providers.
docs/CONTRIBUTING.md	Dev environment setup, test conventions, commit / PR style, the engine-purity tripwire.
docs/audit-phase1.md	Engineering record of the Phase 1 plugin-protocol refactor (background reading).

The hosted product's customer-facing docs (workflows, rulesets, brand profiles, integrations) live at lintpdf.com/docs.

---

Licensing

LintPDF is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

What that means in practice:

• Self-host for any use (commercial or otherwise) — no fee, no per-tenant cap, no notify-us clause. Run it on your own infra and ship reports to your customers.
• Modifications must be made available under the same AGPL-3.0+ license to anyone who interacts with your modified version including over a network (this is the "A" in AGPL — the network-use trigger). If you patch the engine and run it as a hosted service, your patches are AGPL.
• Commercial / proprietary use without disclosure — contact Think Neverland LLC about a commercial license. The hosted deployment at lintpdf.com runs the same open-source engine; the OSS package you are reading is the complete engine.

Copyright © 2024–2026 Think Neverland LLC.

Third-party dependencies retain their own licenses — see docs/CONTRIBUTING.md#third-party-licenses for the inventory.

---

Contributing

We accept patches via pull request. Before opening a PR:

1. Read docs/CONTRIBUTING.md — covers the engine-purity tripwire (analyzers must not import tenant/billing/storage modules), the OpenAPI-description discipline (every Pydantic field needs description=…), and the test pyramid.
2. Sign off your commits (git commit -s). LintPDF uses the Developer Certificate of Origin to track contributor licensing intent.
3. Run the tripwires locally — bash scripts/check_engine_purity.sh and python scripts/check_openapi_descriptions.py — and the pytest suite (pytest --no-header).

For larger changes (a new analyzer category, schema migration, public-API addition) open a discussion issue first so we can align on shape before you write code.

---

Support

• Hosted deployment — lintpdf.com — the same open-source engine, hosted and maintained by Think Neverland LLC.
• OSS issues — GitHub Issues for bug reports, feature requests, and security disclosures (mark security issues with the security label and we'll triage off-list).
• Commercial — [e-mail] for commercial licenses, embedded deployments, or paid support contracts.

---

LintPDF is a Think Neverland LLC project. The plugin-protocol refactor that shaped the current architecture is documented in docs/audit-phase1.md.