pdf-email-optimizer 0.1.0__tar.gz

pdf_email_optimizer-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-20
+
+### Added
+
+- Installable Python package metadata and console scripts.
+- `python -m pdf_email_optimizer` support.
+- Shorthand CLI flags for targets, ranges, and profiles.
+- Audit-only mode.
+- Markdown report output and JSON output schema.
+- Optional `pikepdf`/`qpdf` lossless structural backend, enabled automatically
+  when installed and accepted only when it yields a smaller, pixel-identical
+  result. Toggle with `--pikepdf`/`--no-pikepdf`; install via
+  `pip install "pdf-email-optimizer[pikepdf]"`.
+- `benchmarks/make_fixtures.py` generates 12 redistributable, synthetic (CC0)
+  benchmark/test fixtures, including Illustrator- and InDesign-style exports.
+- `benchmarks/make_gallery.py` renders before/after side-by-side images, plus a
+  README gallery and a populated benchmark table with real size-reduction and
+  PSNR/RMS numbers.
+- Integration test suite (`tests/test_integration.py`, `integration` marker)
+  covering design-tool exports, photo brochures, screenshots, transparency,
+  forms/annotations, scans, and encrypted inputs.
+- `fixtures` and `pikepdf` optional dependency groups.
+- Benchmark harness, CI workflow, trusted-publishing workflow, documentation,
+  and governance files.
+
+### Notes
+
+- Benchmark harness records an honest original-vs-output render comparison
+  (PSNR/RMS) for every successful case and a row for failed cases.
+- Image recompression is gated on the smallest lossless candidate, so a
+  successful pikepdf pass can skip lossy work entirely.
+
+[Unreleased]: https://github.com/petehottelet/pdf-email-optimizer/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/petehottelet/pdf-email-optimizer/releases/tag/v0.1.0

pdf_email_optimizer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for improving PDF Email Optimizer.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest                     # full suite (includes slow integration tests)
+pytest -m "not integration"  # fast unit tests only
+pytest --cov
+ruff check .
+python -m build
+```
+
+## Tests
+
+- Unit tests live in `tests/` and use small synthetic PDFs generated at runtime.
+- Integration tests (`tests/test_integration.py`, marked `integration`) run the
+  optimizer end-to-end against realistic generated fixtures (design-tool
+  exports, photos, screenshots, transparency, forms, scans, encrypted files).
+  They require `reportlab` (included in the `dev` extra) and are skipped if it
+  is unavailable.
+- Include tests for behavior changes. For PDF edge cases, prefer small synthetic
+  fixtures that can be regenerated.
+
+## Fixtures
+
+Do not commit confidential or copyrighted PDFs. Use generated, public domain,
+CC0, or explicitly redistributable fixtures only, and document the origin and
+license of each fixture.
+
+The benchmark/test fixtures are synthesized from scratch:
+
+```bash
+python benchmarks/make_fixtures.py            # regenerate all fixtures
+python benchmarks/make_fixtures.py --only photo_brochure
+```
+
+See [`benchmarks/fixtures/README.md`](benchmarks/fixtures/README.md) for the
+catalog and what each fixture exercises.
+
+## Benchmarks and gallery
+
+```bash
+python benchmarks/run_benchmarks.py   # writes benchmarks/results/latest.{json,md}
+python benchmarks/make_gallery.py     # writes docs/gallery/*.png
+```
+
+When optimizer behavior changes, regenerate both and commit the updated
+`benchmarks/results/latest.md` and gallery images so published numbers stay
+honest. Never hand-edit benchmark numbers.
+
+## Optional backends
+
+- `pikepdf`/`qpdf`: lossless structural pass, installed via
+  `pip install "pdf-email-optimizer[pikepdf]"`. It bundles qpdf, so no system
+  binary is needed.
+- Ghostscript: external binary used only for the aggressive last-resort raster
+  rewrite.
+
+## Pull requests
+
+Keep changes focused, add tests, run `ruff check .` and `pytest`, and update the
+`[Unreleased]` section of [`CHANGELOG.md`](CHANGELOG.md).
+
+## Releases
+
+1. Move the `[Unreleased]` entries under a new version heading with the date.
+2. Bump the version in `pyproject.toml` (and the README badge).
+3. Tag the release and let CI build and publish.

pdf_email_optimizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pete Hottelet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdf_email_optimizer-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include requirements.txt
+include SKILL.md
+recursive-include agents *.yaml
+recursive-include assets *.png
+recursive-include benchmarks *.md *.py *.yaml *.json
+recursive-include docs *.md
+recursive-include examples *.md
+recursive-include schema *.json
+recursive-include scripts *.py
+recursive-include tests *.md *.py

pdf_email_optimizer-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: pdf-email-optimizer
+Version: 0.1.0
+Summary: Shrink PDFs to email-safe sizes while preserving visual quality.
+Author: PDF Email Optimizer contributors
+License: MIT
+Project-URL: Homepage, https://github.com/petehottelet/pdf-email-optimizer
+Project-URL: Issues, https://github.com/petehottelet/pdf-email-optimizer/issues
+Keywords: pdf,compression,email,optimization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pypdf>=4.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: pypdfium2>=4.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: jsonschema; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pikepdf>=8; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: reportlab>=4.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: qa
+Requires-Dist: pypdfium2>=4.0; extra == "qa"
+Provides-Extra: ghostscript
+Provides-Extra: pikepdf
+Requires-Dist: pikepdf>=8; extra == "pikepdf"
+Provides-Extra: fixtures
+Requires-Dist: reportlab>=4.0; extra == "fixtures"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" alt="PDF Email Optimizer" width="480">
+</p>
+
+# PDF Email Optimizer
+
+[![CI](https://github.com/petehottelet/pdf-email-optimizer/actions/workflows/ci.yml/badge.svg)](https://github.com/petehottelet/pdf-email-optimizer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pdf-email-optimizer.svg)](https://pypi.org/project/pdf-email-optimizer/)
+[![Python](https://img.shields.io/pypi/pyversions/pdf-email-optimizer.svg)](https://pypi.org/project/pdf-email-optimizer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Agent Skill](https://img.shields.io/badge/Agent_Skill-SKILL.md-orange.svg)](SKILL.md)
+
+![Profiles](https://img.shields.io/badge/profiles-quality_%7C_balanced_%7C_aggressive-blue)
+![Backends](https://img.shields.io/badge/backends-pypdf_%7C_pikepdf_%7C_ghostscript-555)
+![Optimizes](https://img.shields.io/badge/optimizes-photos_%7C_scans_%7C_screenshots_%7C_vectors-blueviolet)
+
+Shrink PDFs to email-safe sizes while preserving visual quality.
+
+PDF Email Optimizer is built for posters, brochures, reports, photo-heavy decks, and design-tool exports that need to fit under a target like 5-7 MB. It starts with structural cleanup, recompresses images only when needed, and reports when a requested size conflicts with visual quality.
+
+## Install
+
+From a checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+pdf-email-optimizer --help
+```
+
+Once published to a package index:
+
+```bash
+pipx install pdf-email-optimizer
+pdf-email-optimizer input.pdf output.pdf --target-mb 7 --profile quality
+```
+
+Also supported:
+
+```bash
+uvx pdf-email-optimizer input.pdf output.pdf --target 7mb
+python -m pdf_email_optimizer input.pdf output.pdf --target-mb 7
+```
+
+## Quick Start
+
+```bash
+# Ordinary email optimization
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7
+
+# Preserve photos, screenshots, maps, and other detail
+pdf-email-optimizer input.pdf output_email.pdf --target 7mb --quality
+
+# Land inside a 5-7 MB range when possible
+pdf-email-optimizer input.pdf output_email.pdf --range 5-7mb --quality
+
+# Produce a Markdown report beside the output
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7 --report report.md
+
+# Inspect without writing an optimized PDF
+pdf-email-optimizer input.pdf --audit
+```
+
+The source PDF is never overwritten. Existing output files are rejected unless `--force` is supplied.
+
+## Profiles
+
+| Profile | Use When | Behavior |
+|---|---|---|
+| `quality` | Photos, screenshots, maps, product images, "do not degrade" requests | High JPEG floor, protects small images, runs render QA, does not use Ghostscript by default |
+| `balanced` | General email delivery | Moderate recompression ladder and conservative structural cleanup |
+| `aggressive` | Smallest file matters more than perfect fidelity | Lower quality floor, smaller long-edge caps, optional Ghostscript fallback |
+
+If `quality` mode cannot hit the requested size, the tool keeps the smallest quality-preserving output and emits a direct warning with next steps.
+
+## Output
+
+Use `--json` for machine-readable summaries:
+
+```bash
+pdf-email-optimizer input.pdf output.pdf --target-mb 7 --json
+```
+
+The JSON contract is documented in [docs/json-output.md](docs/json-output.md) and validated by [schema/output-summary.schema.json](schema/output-summary.schema.json). Important fields include input/output size, target status, strategy, page count, private payload removals, image statistics, render QA, quality status, and warnings.
+
+## Gallery
+
+Original page (left) vs. email copy (right). All inputs are synthetic, CC0 fixtures generated by `benchmarks/make_fixtures.py`; regenerate the images with `python benchmarks/make_gallery.py`.
+
+**InDesign-style export — 2.35 MB → 0.18 MB (92% smaller, PSNR 57.8 dB)**
+
+![InDesign-style export before and after](docs/gallery/indesign_export.png)
+
+**Scanned document — 0.73 MB → 0.25 MB (66% smaller)**
+
+![Scanned document before and after](docs/gallery/scanned_pdf.png)
+
+**Repeated images — 0.81 MB → 0.14 MB (83% smaller, lossless dedupe)**
+
+![Repeated images before and after](docs/gallery/repeated_images.png)
+
+## Benchmarks
+
+The benchmark harness runs against the bundled redistributable fixtures:
+
+```bash
+python benchmarks/make_fixtures.py        # (re)generate CC0 sample PDFs
+python benchmarks/run_benchmarks.py --manifest benchmarks/benchmark_manifest.yaml --output benchmarks/results/latest.json
+```
+
+It writes JSON plus a Markdown table. Missing fixtures are marked as skipped so published results stay honest. The table below is generated output (`benchmarks/results/latest.md`); PSNR/RMS compare the optimized copy against the original render, and `inf`/`0.0` denote a pixel-identical (lossless) result.
+
+| Case | Input | Target | Profile | Output | Reduction | Target Hit | Worst PSNR | Worst RMS | Strategy |
+|---|---:|---:|---|---:|---:|---|---:|---:|---|
+| photo_brochure | 1.10 MB | 0.6 MB | quality | 1.10 MB | 0.1% | No | inf | 0.0 | pikepdf-structural |
+| indesign_export | 2.35 MB | 1 MB | balanced | 0.18 MB | 92.3% | Yes | 57.822 | 0.327679 | image-recompress |
+| illustrator_export | 0.01 MB | 7 MB | balanced | 0.01 MB | 18.6% | Yes | inf | 0.0 | structural-cleanup |
+| private_payload_export | 0.16 MB | 7 MB | quality | 0.16 MB | 0.1% | Yes | inf | 0.0 | structural-cleanup |
+| screenshot_report | 0.27 MB | 0.2 MB | quality | 0.09 MB | 66.4% | Yes | inf | 0.0 | structural-cleanup |
+| text_vector_document | 0.00 MB | 7 MB | balanced | 0.00 MB | 12.2% | Yes | inf | 0.0 | structural-cleanup |
+| scanned_pdf | 0.73 MB | 0.4 MB | balanced | 0.25 MB | 66.6% | Yes | inf | 0.0 | structural-cleanup |
+| mixed_transparency | 1.75 MB | 1 MB | quality | 1.75 MB | -0.0% | No | inf | 0.0 | structural-cleanup |
+| embedded_metadata | 0.12 MB | 7 MB | balanced | 0.12 MB | 0.1% | Yes | inf | 0.0 | structural-cleanup |
+| repeated_images | 0.81 MB | 0.5 MB | balanced | 0.14 MB | 83.2% | Yes | inf | 0.0 | structural-cleanup |
+| forms_annotations | 0.01 MB | 7 MB | quality | 0.01 MB | 3.9% | Yes | inf | 0.0 | structural-cleanup |
+| encrypted_pdf | - | 7.0 MB | balanced | failed | - | - | - | - | Encrypted PDFs must be unlocked before optimization. |
+
+The `quality` profile deliberately refuses to degrade `photo_brochure` and `mixed_transparency` below their targets, emitting a warning instead of shipping a blurry file.
+
+See [docs/benchmarking.md](docs/benchmarking.md) before adding fixtures.
+
+## Visual QA
+
+Render and compare two PDFs:
+
+```bash
+pdf-email-render-compare original.pdf optimized.pdf --output-dir qa-renders
+```
+
+This reports page-level pixel differences and can write original, optimized, and amplified diff PNGs for review.
+
+## Agent Usage
+
+The repo includes [SKILL.md](SKILL.md) for agent runtimes that load local skills. The short version:
+
+- Use `quality` when the user asks to preserve image fidelity.
+- Use `balanced` for ordinary email optimization.
+- Use `aggressive` only when visible quality loss is acceptable.
+- Report size, target status, strategy, and warnings.
+- Never overwrite the source PDF.
+
+More examples are in [docs/agent-usage.md](docs/agent-usage.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+pytest --cov
+ruff check .
+python -m build
+```
+
+CI runs linting, tests, coverage, package build, and CLI smoke checks on Python 3.9-3.13.
+
+## Documentation
+
+- [Installation](docs/installation.md)
+- [Examples](docs/examples.md)
+- [Benchmarking](docs/benchmarking.md)
+- [Compatibility](docs/compatibility.md)
+- [JSON output](docs/json-output.md)
+- [Agent usage](docs/agent-usage.md)
+- [Known limitations](docs/known-limitations.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## License
+
+[MIT](LICENSE)

pdf_email_optimizer-0.1.0/README.md

@@ -0,0 +1,178 @@
+<p align="center">
+  <img src="assets/logo.png" alt="PDF Email Optimizer" width="480">
+</p>
+
+# PDF Email Optimizer
+
+[![CI](https://github.com/petehottelet/pdf-email-optimizer/actions/workflows/ci.yml/badge.svg)](https://github.com/petehottelet/pdf-email-optimizer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pdf-email-optimizer.svg)](https://pypi.org/project/pdf-email-optimizer/)
+[![Python](https://img.shields.io/pypi/pyversions/pdf-email-optimizer.svg)](https://pypi.org/project/pdf-email-optimizer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Agent Skill](https://img.shields.io/badge/Agent_Skill-SKILL.md-orange.svg)](SKILL.md)
+
+![Profiles](https://img.shields.io/badge/profiles-quality_%7C_balanced_%7C_aggressive-blue)
+![Backends](https://img.shields.io/badge/backends-pypdf_%7C_pikepdf_%7C_ghostscript-555)
+![Optimizes](https://img.shields.io/badge/optimizes-photos_%7C_scans_%7C_screenshots_%7C_vectors-blueviolet)
+
+Shrink PDFs to email-safe sizes while preserving visual quality.
+
+PDF Email Optimizer is built for posters, brochures, reports, photo-heavy decks, and design-tool exports that need to fit under a target like 5-7 MB. It starts with structural cleanup, recompresses images only when needed, and reports when a requested size conflicts with visual quality.
+
+## Install
+
+From a checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+pdf-email-optimizer --help
+```
+
+Once published to a package index:
+
+```bash
+pipx install pdf-email-optimizer
+pdf-email-optimizer input.pdf output.pdf --target-mb 7 --profile quality
+```
+
+Also supported:
+
+```bash
+uvx pdf-email-optimizer input.pdf output.pdf --target 7mb
+python -m pdf_email_optimizer input.pdf output.pdf --target-mb 7
+```
+
+## Quick Start
+
+```bash
+# Ordinary email optimization
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7
+
+# Preserve photos, screenshots, maps, and other detail
+pdf-email-optimizer input.pdf output_email.pdf --target 7mb --quality
+
+# Land inside a 5-7 MB range when possible
+pdf-email-optimizer input.pdf output_email.pdf --range 5-7mb --quality
+
+# Produce a Markdown report beside the output
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7 --report report.md
+
+# Inspect without writing an optimized PDF
+pdf-email-optimizer input.pdf --audit
+```
+
+The source PDF is never overwritten. Existing output files are rejected unless `--force` is supplied.
+
+## Profiles
+
+| Profile | Use When | Behavior |
+|---|---|---|
+| `quality` | Photos, screenshots, maps, product images, "do not degrade" requests | High JPEG floor, protects small images, runs render QA, does not use Ghostscript by default |
+| `balanced` | General email delivery | Moderate recompression ladder and conservative structural cleanup |
+| `aggressive` | Smallest file matters more than perfect fidelity | Lower quality floor, smaller long-edge caps, optional Ghostscript fallback |
+
+If `quality` mode cannot hit the requested size, the tool keeps the smallest quality-preserving output and emits a direct warning with next steps.
+
+## Output
+
+Use `--json` for machine-readable summaries:
+
+```bash
+pdf-email-optimizer input.pdf output.pdf --target-mb 7 --json
+```
+
+The JSON contract is documented in [docs/json-output.md](docs/json-output.md) and validated by [schema/output-summary.schema.json](schema/output-summary.schema.json). Important fields include input/output size, target status, strategy, page count, private payload removals, image statistics, render QA, quality status, and warnings.
+
+## Gallery
+
+Original page (left) vs. email copy (right). All inputs are synthetic, CC0 fixtures generated by `benchmarks/make_fixtures.py`; regenerate the images with `python benchmarks/make_gallery.py`.
+
+**InDesign-style export — 2.35 MB → 0.18 MB (92% smaller, PSNR 57.8 dB)**
+
+![InDesign-style export before and after](docs/gallery/indesign_export.png)
+
+**Scanned document — 0.73 MB → 0.25 MB (66% smaller)**
+
+![Scanned document before and after](docs/gallery/scanned_pdf.png)
+
+**Repeated images — 0.81 MB → 0.14 MB (83% smaller, lossless dedupe)**
+
+![Repeated images before and after](docs/gallery/repeated_images.png)
+
+## Benchmarks
+
+The benchmark harness runs against the bundled redistributable fixtures:
+
+```bash
+python benchmarks/make_fixtures.py        # (re)generate CC0 sample PDFs
+python benchmarks/run_benchmarks.py --manifest benchmarks/benchmark_manifest.yaml --output benchmarks/results/latest.json
+```
+
+It writes JSON plus a Markdown table. Missing fixtures are marked as skipped so published results stay honest. The table below is generated output (`benchmarks/results/latest.md`); PSNR/RMS compare the optimized copy against the original render, and `inf`/`0.0` denote a pixel-identical (lossless) result.
+
+| Case | Input | Target | Profile | Output | Reduction | Target Hit | Worst PSNR | Worst RMS | Strategy |
+|---|---:|---:|---|---:|---:|---|---:|---:|---|
+| photo_brochure | 1.10 MB | 0.6 MB | quality | 1.10 MB | 0.1% | No | inf | 0.0 | pikepdf-structural |
+| indesign_export | 2.35 MB | 1 MB | balanced | 0.18 MB | 92.3% | Yes | 57.822 | 0.327679 | image-recompress |
+| illustrator_export | 0.01 MB | 7 MB | balanced | 0.01 MB | 18.6% | Yes | inf | 0.0 | structural-cleanup |
+| private_payload_export | 0.16 MB | 7 MB | quality | 0.16 MB | 0.1% | Yes | inf | 0.0 | structural-cleanup |
+| screenshot_report | 0.27 MB | 0.2 MB | quality | 0.09 MB | 66.4% | Yes | inf | 0.0 | structural-cleanup |
+| text_vector_document | 0.00 MB | 7 MB | balanced | 0.00 MB | 12.2% | Yes | inf | 0.0 | structural-cleanup |
+| scanned_pdf | 0.73 MB | 0.4 MB | balanced | 0.25 MB | 66.6% | Yes | inf | 0.0 | structural-cleanup |
+| mixed_transparency | 1.75 MB | 1 MB | quality | 1.75 MB | -0.0% | No | inf | 0.0 | structural-cleanup |
+| embedded_metadata | 0.12 MB | 7 MB | balanced | 0.12 MB | 0.1% | Yes | inf | 0.0 | structural-cleanup |
+| repeated_images | 0.81 MB | 0.5 MB | balanced | 0.14 MB | 83.2% | Yes | inf | 0.0 | structural-cleanup |
+| forms_annotations | 0.01 MB | 7 MB | quality | 0.01 MB | 3.9% | Yes | inf | 0.0 | structural-cleanup |
+| encrypted_pdf | - | 7.0 MB | balanced | failed | - | - | - | - | Encrypted PDFs must be unlocked before optimization. |
+
+The `quality` profile deliberately refuses to degrade `photo_brochure` and `mixed_transparency` below their targets, emitting a warning instead of shipping a blurry file.
+
+See [docs/benchmarking.md](docs/benchmarking.md) before adding fixtures.
+
+## Visual QA
+
+Render and compare two PDFs:
+
+```bash
+pdf-email-render-compare original.pdf optimized.pdf --output-dir qa-renders
+```
+
+This reports page-level pixel differences and can write original, optimized, and amplified diff PNGs for review.
+
+## Agent Usage
+
+The repo includes [SKILL.md](SKILL.md) for agent runtimes that load local skills. The short version:
+
+- Use `quality` when the user asks to preserve image fidelity.
+- Use `balanced` for ordinary email optimization.
+- Use `aggressive` only when visible quality loss is acceptable.
+- Report size, target status, strategy, and warnings.
+- Never overwrite the source PDF.
+
+More examples are in [docs/agent-usage.md](docs/agent-usage.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+pytest --cov
+ruff check .
+python -m build
+```
+
+CI runs linting, tests, coverage, package build, and CLI smoke checks on Python 3.9-3.13.
+
+## Documentation
+
+- [Installation](docs/installation.md)
+- [Examples](docs/examples.md)
+- [Benchmarking](docs/benchmarking.md)
+- [Compatibility](docs/compatibility.md)
+- [JSON output](docs/json-output.md)
+- [Agent usage](docs/agent-usage.md)
+- [Known limitations](docs/known-limitations.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## License
+
+[MIT](LICENSE)

pdf_email_optimizer-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+PDF Email Optimizer runs locally and does not upload PDFs or collect telemetry.
+
+Do not attach confidential PDFs to public issues. If you need to report a problem with sensitive material, create a synthetic or redacted fixture that reproduces the behavior.
+
+Report security concerns privately through the repository's security advisory flow when available.

pdf_email_optimizer-0.1.0/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: pdf-email-optimizer
+description: Shrink large PDFs to email-safe sizes while preserving visual quality, with safe defaults, JSON summaries, reports, audit mode, and render QA.
+license: MIT
+---
+
+# PDF Email Optimizer
+
+## Core Rules
+
+1. Never overwrite the source PDF. Write an optimized copy to a new path.
+2. Use `--quality` when the user mentions photos, images, screenshots, maps, visual fidelity, sharpness, or "do not degrade."
+3. Use `--balanced` for ordinary email optimization.
+4. Use `--aggressive` only when the user explicitly accepts visible quality loss or asks for the smallest possible file.
+5. Run render QA when available for quality-sensitive work.
+6. Report original size, final size, target status, profile, strategy, and warnings.
+7. If quality mode misses the target, say clearly that the target conflicts with image fidelity.
+
+## Commands
+
+```bash
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7
+pdf-email-optimizer input.pdf output_email.pdf --target 7mb --quality
+pdf-email-optimizer input.pdf output_email.pdf --range 5-7mb --quality
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 5 --preferred-mb 5 --balanced
+pdf-email-optimizer input.pdf output_small.pdf --target-mb 5 --aggressive
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7 --no-image-recompress
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7 --json
+pdf-email-optimizer input.pdf output_email.pdf --target-mb 7 --report report.md
+pdf-email-optimizer input.pdf --audit --json
+```
+
+Backward-compatible script form:
+
+```bash
+python scripts/optimize_pdf_email.py input.pdf output_email.pdf --target-mb 7
+```
+
+## Size Targets
+
+- "Under 7 MB" or "max 7 MB": use `--target-mb 7` or `--target 7mb`.
+- "Between 5 and 7 MB": use `--range 5-7mb`.
+- "Make it 5 MB": use `--target-mb 5 --preferred-mb 5`.
+- If cleanup alone makes the file smaller than a requested range, keep it smaller. Do not pad files.
+
+## Audit First
+
+Use audit mode when the user asks why a PDF is large or when the right strategy is unclear:
+
+```bash
+pdf-email-optimizer input.pdf --audit --json
+```
+
+Audit reports file size, page count, image count, private payload indicators, forms, annotations, transparency, masks, and recommended profile.
+
+## Visual QA
+
+When available:
+
+```bash
+pdf-email-render-compare original.pdf optimized.pdf --output-dir qa-renders
+```
+
+Check page count, missing layers, clipped art, changed colors, broken transparency, and softened important images. Automated render QA is a signal, not a human proof.
+
+## Quality Conflict Response
+
+Use this pattern when `quality` cannot hit the requested target:
+
+```text
+Target not met. The requested 5 MB target conflicts with the selected quality profile. Output is 8.4 MB.
+To go smaller, rerun with --profile aggressive, split the PDF, remove pages, or accept lower image fidelity.
+```
+
+## Failure Handling
+
+- Encrypted PDFs must be unlocked first.
+- Existing outputs require `--force`.
+- Transparent images may be skipped unless `--flatten-alpha` is appropriate.
+- Ghostscript is optional; if missing, report the warning and keep the best non-Ghostscript result.
+- For high-stakes documents, ask the user to spot-check the final PDF locally.

pdf_email_optimizer-0.1.0/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "PDF Email Optimizer"
+  short_description: "Hit target PDF filesizes with maximum visual quality"
+  icon_small: "./assets/icon.png"
+  icon_large: "./assets/logo.png"
+  brand_color: "#B0141B"
+  default_prompt: "Use $pdf-email-optimizer to reduce this PDF to an email-safe file size while preserving visual quality."