Inclusio

Inclusio

Publishing that includes everyone.

Accessibility-first publishing engine for LaTeX, packaged as a Python CLI. PDF/UA-2 + WTPDF + PDF/A-4f triple-conformance, C2PA + PAdES + SLSA provenance, multi-format emission (HTML5 / JATS / EPUB3), LLM-augmented judges, and an MCP server for agent integration.

Contents

• Install — pip, optional extras, source
• Quick Start — first tagged PDF in 60 seconds
• Features — what the engine ships
• Usage — common Python + CLI recipes
• Architecture — the engine's package layout
• Examples — six runnable scenarios
• Documentation — quickstart, tutorials, reference
• Publishing against an external content tree
• Development — local validation gate
• Security — signed commits, provenance, audit
• License

Install

pip install inclusio                       # engine + CLI
pip install 'inclusio[mcp]'                # + FastMCP server
pip install 'inclusio[provenance]'         # + pyhanko (PAdES)
pip install 'inclusio[dev]'                # + pytest, ruff, sphinx, interrogate

Requires Python ≥ 3.11 and a LuaLaTeX toolchain on PATH. Linux,macOS, and WSL are supported (native Windows works for the Pythonsurface; the LaTeX gate needs WSL or a TeX Live install).

Build from source

git clone https://github.com/sebastienrousseau/inclusio.git
cd inclusio
./bin/setup        # check toolchain + install dev extras
make test          # smoke suite
make coverage      # full suite (gate: 97 %)

Quick Start

A complete worked example you can paste into a fresh directory:

pip install inclusio

# Grab the minimal example, build + audit + emit + judge:
git clone --depth=1 https://github.com/sebastienrousseau/inclusio
cd inclusio/examples/01-hello-world && make

That single make produces build/hello.pdf (PDF/UA-2 + WTPDF +PDF/A-4f triple-conformance), runs veraPDF over it, and exitsnon-zero if any flavour fails.

Drive the same surface from Python:

# quickstart.py
import subprocess
from pathlib import Path

# 1. Render + build the bundled "hello" fixture — the CLI is the
#    canonical entry point for the LaTeX step.
subprocess.run(
    ["python", "-m", "inclusio.cli.build", "build", "--doc", "hello"],
    cwd="examples/01-hello-world",
    check=True,
)

# 2. Audit the produced PDF in-process — pure-Python, no subprocess.
from inclusio.cli import audit

pdfs = audit.collect_pdfs(
    target=Path("examples/01-hello-world/build"),
    build_dir=Path("examples/01-hello-world/build"),
    registry_stems={"hello"},
)
report = audit.audit(pdfs)
assert report["summary"]["fail"] == 0, "veraPDF reported a failure"
print(f'  PASS  {report["summary"]["pdfs"]} PDF(s), '
      f'{report["summary"]["pass"]}/{report["summary"]["total"]} checks')
# →   PASS  1 PDF(s), 3/3 checks

Features

• Tagged PDF, by default. Every build emits a PDF/UA-2 +WTPDF + PDF/A-4f triple-conforming artefact via the LaTeXkernel's tagpdf integration. The veraPDF audit gate is wiredinto CI and exits non-zero on any FAIL.
• Multi-format emission. The same LaTeX source produces HTML5(WCAG-clean), JATS XML (1.3, JATS4R-ready), and EPUB3 viaPandoc.
• LLM-augmented judges. ATS (Workday / Greenhouse / Leverheuristic), citation grounding, and JD-to-CV fit — localllama.cpp or BYO-key cloud (Anthropic / OpenAI), withheuristic-only fallback when the LLM is unreachable.
• Content provenance. C2PA Content Credentials (viac2patool), PAdES B-T / B-LT / B-LTA signatures (viapyhanko), and SLSA L3 build attestation (viaactions/attest-build-provenance).
• MCP server. inclusio-mcp exposes list_docs, audit_pdf,render, and doc_count so Claude Code, Cursor, Continue, orany other MCP client can drive the engine.
• JSON Resume importer. inclusio import-resume converts ajsonresume.org v1 document into the engine's CV YAML schema.
• Brief-driven CV tailoring. ATS-clean variants tailoredagainst a job description with British-English cleanup andconsistency lint.

Usage

Build, audit, judge a registered document

inclusio build --doc cv --mode draft        # → build/cv.pdf
inclusio audit --strict                     # → veraPDF, non-zero on FAIL
inclusio judge --doc cv --judge ats         # → grade + findings

Score a CV against a job description

# score_cv.py — fully runnable: drop into a directory with brief.txt + cv.txt
from pathlib import Path
from inclusio.judge import jd_fit

jd_text = Path("brief.txt").read_text(encoding="utf-8")
cv_text = Path("cv.txt").read_text(encoding="utf-8")

report = jd_fit.score_jd_fit(jd_text, cv_text)
print(f"score:   {report.score}/100   grade: {report.grade}")
print(f"missing: {sorted(report.metrics['missing_required'])[:5]}")
# → score:   78/100   grade: B
# → missing: ['opentelemetry', 'rust']

Drive the engine over MCP

inclusio-mcp                          # stdio (Claude Code default)
inclusio-mcp --http --port 8765       # Streamable HTTP

Wire into Claude Code via ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "inclusio": {
      "command": "inclusio-mcp",
      "env": { "INCLUSIO_CONTENT_DIR": "/absolute/path/to/content" }
    }
  }
}

Embed C2PA Content Credentials

inclusio provenance --doc cv \
  --cert /path/to/cert.pem \
  --key  /path/to/key.pem \
  --output build/cv.c2pa.pdf

Architecture

inclusio/                  # Python package
  cli/                     # build · audit · render · tailor · judge · emit · provenance · …
  judge/                   # ats · citations · jd_fit · local_llm · cloud_llm
  emit/                    # pandoc (HTML5 / JATS XML / EPUB3)
  provenance/              # c2pa (c2patool) · pades (pyhanko)
  mcp/                     # FastMCP server
  tools/                   # fix_semantic · stamp_pdfs · overlay
core/                      # LaTeX classes (.cls) and styles (.sty)
templates/                 # Jinja2 templates for the template-driven docs
benches/                   # pytest-benchmark micro-benchmarks
examples/                  # Six self-contained runnable scenarios
docs/                      # Sphinx documentation

External consumers supply their own content tree (LaTeX sources,YAML metadata, brand assets) and point the engine at it throughINCLUSIO_CONTENT_DIR or --content-dir. The repo's own src/and data/ directories double as the public-engine self-testfixtures.

Examples

Each folder has its own Makefile (make help lists targets) anda README.md with the why + the how.

Documentation

• Quickstart — five-minute walkthrough.
• Tutorials — four end-to-end walkthroughspaired 1 : 1 with the examples.
• Architecture — public-engine vscontent-repo boundary, sprint history, decision log.
• Tagged PDF — the conformance stack.
• Multi-format — HTML / JATS / EPUB.
• Judges — ATS, citations, JD-fit, LLMrerank contract.
• Provenance — C2PA, PAdES, SLSA.
• MCP server — tool + resource surface.

Publishing against an external content tree

make publish CONTENT_DIR=/absolute/path/to/your-content-repo

The content repo supplies its own data/meta.yaml (documentregistry) and src/**.tex (LaTeX sources). The engine reads nostate from outside INCLUSIO_CONTENT_DIR once it's set.

Development

make test          # smoke (≤ 20 s)
make coverage      # full suite + 97 % gate (~3 min)
make docstrings    # 100 % interrogate gate
make benchmark     # pytest-benchmark micro-budgets
make audit-strict  # veraPDF, exits non-zero on any FAIL
make docs          # Sphinx

All commits to main are squash-merged via PR. Branch protectionrequires Lint (ruff) + Public Engine Checks (py3.11 / 3.12 / 3.13) + the Signed-commit gate to pass. SeeCONTRIBUTING.md.

Security

• SSH-signed commits. Every commit on main is GitHub-verified.
• Signed tags. Release tags are ED25519-signed.
• SLSA L3 build provenance (gated on the repo being public oron a paid GitHub plan).
• PyPI Trusted Publishing wiring (pypa/gh-action-pypi-publish)in release.yml; flip vars.PYPI_TRUSTED_PUBLISHING=true oncethe PyPI publisher is configured.
• Cloud LLM keys are env-var only — inclusio never auto-discovers credentials from disk.

Report vulnerabilities per SECURITY.md.

Related MCP Servers

Sibling MCP servers by the same author — each targets a different agent workflow:

MCP Registry

mcp-name: io.github.sebastienrousseau/inclusio-mcp

Install the MCP server with pip install 'inclusio[mcp]' (the mcp extra pulls in mcp[cli]>=1.27.0). Run with inclusio-mcp — stdio transport, exposes accessibility-publishing tools to Claude Desktop, Cursor, and other MCP clients.

License

MIT. © 2026 Sebastien Rousseau.