# Schematic PDF to JSON

Precision-first conversion of vector PDF circuit schematics into an
evidence-preserving `SchematicIR` JSON document. The project includes a Python
conversion engine, command-line interface, MCP server, reusable Codex skill,
and validation tools.

> This project deliberately prefers missing uncertain content over emitting
> plausible but incorrect electrical information. A result marked
> `needs_review` must not be treated as a verified netlist.

## Architecture

1. **PDF parsing** — extracts native text, vector paths, styles, coordinates,
   source IDs, and evidence.
2. **Primitive recognition** — identifies conservative wire, component, pin,
   junction, label, and network-flag candidates.
3. **Connectivity recovery** — applies explicit endpoint, T-junction, junction
   marker, and evidence-backed named-net rules.
4. **JSON output** — emits validated `SchematicIR`, unresolved issues, topology
   checks, and a deterministic hash.

Each conversion preserves all four stages as separate JSON artifacts.

## One-click agent installation

Codex plugin:

```powershell
codex plugin marketplace add ght123247/schematic-pdf-to-json --ref v0.2.0
codex plugin add schematic-pdf-to-json@schematic-pdf-tools
```

Start a new Codex task after installation. The bundled plugin installs its
isolated Python runtime automatically on the first MCP connection.

Claude Desktop, Cursor, and Gemini CLI on Windows:

```powershell
irm https://raw.githubusercontent.com/ght123247/schematic-pdf-to-json/v0.2.0/install.ps1 | iex
```

Claude Desktop, Cursor, and Gemini CLI on macOS/Linux:

```sh
curl -fsSL https://raw.githubusercontent.com/ght123247/schematic-pdf-to-json/v0.2.0/install.sh | sh
```

The installer creates an isolated runtime under
`~/.schematic-pdf-to-json`, preserves unrelated settings, backs up every
changed config, performs a real MCP handshake, and prints the tools it found.
Python 3.11 or newer is the only prerequisite.

See [Agent installation](docs/agent-installation.md) for selecting one agent,
custom allowed roots, upgrades, uninstalling, and manual configuration.

## Development install

Python 3.11 or newer is required.

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test]"
```

## Command line

```powershell
schematic-pdf inspect "D:\path\drawing.pdf"
schematic-pdf convert "D:\path\drawing.pdf" --output output\artifacts
schematic-pdf validate "D:\path\schematic.final.json"
```

The conversion output contains:

```text
job-.../
├── layer1/raw.json
├── layer2/semantic.json
├── layer3/connectivity.json
├── layer4/schematic.final.json
└── manifest.json
```

### Altium Designer PDF support

For native vector PDFs exported by Altium Designer, the recognizer selects an
Altium-specific profile automatically. It handles Altium's dark-blue wiring,
blue symbol graphics, black pin stubs, red/yellow sheet ports, adjacent
reference/value text pairs, large multi-pin IC bodies, and exact cross-page
named-net merging. Dense PCB-artwork pages embedded in a schematic PDF are
excluded with a reviewable warning instead of being interpreted as a
schematic.

The profile remains precision-first: unsupported or ambiguous values, pins,
symbols, and labels are omitted from resolved JSON and retained as issues for
manual review.

## MCP server

Start the stdio server with:

```powershell
schematic-pdf-mcp
```

Available tools:

- `inspect_schematic_pdf`
- `convert_schematic_pdf`
- `validate_schematic_ir`

The server exposes `schematic://schema/current` and staged artifacts through
`schematic://jobs/{job_id}/{stage}`. Restrict readable local paths with
`SCHEMATIC_PDF_ALLOWED_ROOTS`; set `SCHEMATIC_PDF_ARTIFACT_ROOT` to control the
artifact destination.

Generic MCP configuration:

```json
{
  "mcpServers": {
    "schematic-pdf": {
      "command": "schematic-pdf-mcp",
      "env": {
        "SCHEMATIC_PDF_ALLOWED_ROOTS": "D:\\schematics",
        "SCHEMATIC_PDF_ARTIFACT_ROOT": "D:\\schematic-output"
      }
    }
  }
}
```

## Accuracy and validation

The final JSON contains source evidence and explicit issues for unresolved
content. Schema validity and topology validity are independent of recognition
completeness. Important policies include:

- no inferred connection at a four-way crossing without explicit evidence;
- no invented pin numbers, reference-designator suffixes, or net names;
- ambiguous part-number-like text is omitted and reported for review;
- recognition changes must keep 100% precision on registered real-PDF
  regression samples.

Run the automated suite:

```powershell
python -m pytest
```

Run the EasyEDA-backed precision regression after placing authorized local
sample PDFs and truth exports at the paths registered in the script:

```powershell
python scripts\run_precision_regression.py
```

For a genuinely unseen PDF, lock the conversion before reading EDA truth:

```powershell
python scripts\blind_validate_pdf.py lock "Test_PDF_SCH\new.pdf"
python scripts\blind_validate_pdf.py compare `
  "output\blind\job-...\blind-lock.json" `
  "output\accuracy\new.easyeda-ground-truth.json"
```

Test schematics, EasyEDA truth exports, and generated artifacts are excluded
from the repository because they may contain proprietary circuit designs.

## Codex skill

The reusable skill is in [`skill/convert-schematic-pdf`](skill/convert-schematic-pdf).
It defines the precision-first workflow, acceptance order, validation policy,
MCP contract, and current limitations.

## Current limitations

- Native vector PDFs are the primary supported input.
- Native Altium Designer schematic exports have a dedicated auto-detected
  recognition profile; custom print styles may still require calibration.
- Raster OCR and raster primitive recognition are not implemented.
- Hidden pin numbers and ambiguous symbol identity remain unresolved.
- Long-distance value/label association is intentionally conservative.
- Human review is still required whenever blocking issues remain.

## License

[MIT](LICENSE)