> [!WARNING]
> **Pre-1.0.** ZapTrace is a verification-first EDA kernel, not a fabrication guarantee. All generated outputs require human engineering review before fabrication or use. See [Safety Disclaimer](#safety-disclaimer).
> [!NOTE]
> **Proof Pack = evidence layer, not absolute correctness.** Proof packs record configured checks, artifacts, assumptions, and pass/fail evidence. A clean proof pack does not mean a board is manufacturer-approved, production-ready, or safe to fabricate without review.
---
## What ZapTrace Is
- **A Python SDK** for programmatic electronics design — parse, validate, place, route, export.
- **A CLI** (`zaptrace`) for quick design iteration from the terminal.
- **An MCP server** (`zaptrace-mcp`) whose default `expert` surface exposes 93 design tools plus 3 session-administration tools, with smaller task-oriented `inspect`, `design`, `verify`, `repair`, and `release` surfaces for bounded workflows.
- **A REST API** for web-based design workflows.
- **A verification engine** — Electrical Rule Checking (ERC) + Design Rule Checking (DRC) baked in.
- **A manufacturing export pipeline** — Gerber RS-274X, Excellon drill, BOM, pick-and-place, KiCad.
- **A proof-pack generator** — auditable, reproducible artifact bundles for every design.
## What ZapTrace Is Not
- ❌ **Not a replacement for KiCad, Altium, or Eagle** — ZapTrace is a *backend engine*, not a full PCB editor GUI.
- ❌ **Not a general-purpose SPICE simulator or solver-grade sign-off tool** — ZapTrace can export SPICE and run bounded ngspice-backed evidence gates, but these do not replace full analog verification or qualified engineering review.
- ❌ **Not a replacement for human engineering judgment** — all outputs require review before fabrication.
- ❌ **Not fabrication-proven** — ZapTrace is pre-1.0. Manufacturing outputs are experimental.
- ❌ **Not fabrication-ready or production-ready** — no claim of fitness for manufacturing is made.
- ❌ **Proof Pack is not a correctness guarantee** — it is an evidence layer that records what was checked and what passed/failed. Absence of errors does not mean the design is correct or manufacturable.
- ❌ **KiCad Oracle (ERC/DRC) is external validation, not absolute correctness** — it catches rule violations the rules know about. A passing KiCad Oracle check does not guarantee a working circuit.
- ❌ **Fab profiles are not manufacturer approvals** — built-in profiles match common manufacturer capabilities, but you must verify against your specific manufacturer's current specifications. Always obtain pre-fabrication approval.
- ❌ **GitHub hardware CI cannot catch all hardware errors** — CI runs on simulated or limited hardware; physical validation (probe, power-up, functional test) is irreplaceable.
---
## Status
| Area | Status |
|------|--------|
| Design parsing | ✅ Implemented |
| Schematic synthesis | ⚠️ Template selection (keyword-matches a pre-built template; not from-scratch synthesis) |
| ERC (Electrical Rule Checking) | ✅ Implemented |
| Component placement | ✅ Implemented |
| Grid-based routing | ✅ Implemented |
| Net-aware smart routing | ✅ Implemented |
| DRC (Design Rule Checking) | ✅ Implemented |
| Net classification (EE knowledge) | ✅ Implemented |
| Copper pour generation | ✅ Implemented |
| Gerber RS-274X export | ✅ Implemented |
| Excellon drill export | ✅ Implemented |
| BOM (CSV + JSON) export | ✅ Implemented |
| Pick-and-place export | ✅ Implemented |
| KiCad schematic export | ✅ Implemented |
| KiCad hierarchical project import | ✅ Implemented |
| EasyEDA Standard import/export (round-trip ≥0.75) | ✅ Implemented (single flat JSON; import-only, no PCB editor) |
| EasyEDA Pro writer (import-only via KiCad) | ✅ Implemented (ZIP+JSONL; distinct from Standard) |
| Altium ASCII schematic import | ✅ Implemented (ASCII export only; OLE binary not supported) |
| SVG schematic rendering | ✅ Implemented |
| Manufacturing ZIP bundle | ✅ Implemented |
| MCP server (96 exposed tools: 93 design + 3 session administration) | ✅ Implemented |
| Power-tree architecture planner + netlist emit | ✅ Implemented |
| REST API server | ✅ Implemented |
| Design diff | ✅ Implemented |
| Full pipeline (autopilot) | ✅ Implemented |
| Proof-pack system | ✅ Implemented — evidence/sign-off foundation; not a correctness guarantee |
| Plugin system | 🚧 Experimental — signed runtime policy documented; production sandboxing still required |
| Review Studio | ✅ Implemented — human-review panels, proof-pack evidence, benchmark readiness |
| SPICE netlist export | ✅ Implemented foundation — DC gate is evidence/skip aware, not full analog sign-off |
| DFM (Design for Manufacturing) | ✅ Implemented foundation — fab profiles, manufacturing evidence, current/thermal/SI risk reports |
| Multi-board design | 🔮 Planned — post-0.3.0 |
| RF/microwave awareness | 🔮 Planned |
---
## v0.3.0 Release Scope
ZapTrace 0.3.0 is an evidence-hardening release. It adds bounded autonomous sign-off vocabulary, requirements coverage, assumption evidence, KiCad oracle evidence, manufacturing/DFM evidence, component/datasheet/footprint provenance, layout/power/SI/PI risk reports, known-failure benchmark mutation coverage, and Review Studio benchmark readiness panels.
This release still makes no fabrication-readiness claim. A pass means the configured evidence gates did not block; it does **not** mean the design is manufacturer-approved, production-ready, or safe to fabricate without human engineering review.
---
## Quickstart
ZapTrace is pre-1.0. The registry distribution identity is `zaptrace-eda` while the Python import package and CLI remain `zaptrace`. `v0.3.5` is available on PyPI; its immutable tagged workflow failed the container-security gate before GitHub Release creation, so the tag is retained as partial-release evidence rather than rewritten. Active development has advanced to `0.3.6.dev0`. For a clean PyPI install of the latest published package:
```bash
uv venv --python 3.13
uv pip install "zaptrace-eda==0.3.5"
source .venv/bin/activate
# Run diagnostics
zaptrace doctor
# First run: scaffold a design locally (the published wheel does not
# contain the repository's examples/ directory).
zaptrace init sensor-demo --template esp32_i2c_sensor
zaptrace parse sensor-demo/design.yaml
zaptrace view sensor-demo/design.yaml --output sensor-demo/review
# Create KiCad/inspection outputs inside the working directory.
# Generation success does not mean ERC/DRC or fabrication readiness.
zaptrace pipeline --source sensor-demo/design.yaml --output sensor-demo/build
```
---
## CLI Usage
```bash
# Parse a design YAML
zaptrace parse design.yaml
# Inspect a parsed design
zaptrace inspect my_design
# Run ERC validation
zaptrace erc my_design
# List ERC rules
zaptrace erc-rules
# Place components
zaptrace place my_design
# Route nets
zaptrace route my_design
# Generate BOM
zaptrace bom my_design
zaptrace bom my_design --format json
# Generate design report
zaptrace report my_design --output report.md
# Render schematic SVG
zaptrace svg my_design --output schematic.svg
# Export to KiCad
zaptrace kicad my_design output/kicad/
# Diff two designs
zaptrace diff design_a design_b
# Search library
zaptrace library search resistor
zaptrace library get 0402_10k
# Run full pipeline
zaptrace pipeline --source design.yaml --output build/
zaptrace pipeline --intent "ESP32 I2C sensor node"
```
---
## Python SDK Usage
```python
from zaptrace.core.parser import parse_file
from zaptrace.erc.runner import ERCRunner
from zaptrace.algo.placer import place_components
from zaptrace.algo.router import route_design_smart
from zaptrace.export.manufacturing import generate_manufacturing_bundle
from zaptrace.ee.classifier import classify_design
# Parse
design = parse_file("design.yaml")
# Validate
runner = ERCRunner()
erc_result = runner.run(design)
# Classify nets
classify_design(design)
# Place & route
positions = place_components(design)
routing, route_result = route_design_smart(design, positions)
# Export
bundle = generate_manufacturing_bundle(design, "build/")
print(f"Gerber layers: {list(bundle['gerber_layers'].keys())}")
```
---
## MCP Usage
ZapTrace exposes an MCP server for AI agent integration.
```bash
# Start MCP server (stdio mode)
zaptrace-mcp
# Start MCP server (HTTP loopback mode)
zaptrace-mcp-http
```
Configure in your AI client's MCP settings:
```json
{
"mcpServers": {
"zaptrace": {
"command": "zaptrace-mcp"
}
}
}
```
See [MCP quickstart](docs/mcp/quickstart.md) for the tool catalog and [agent plugin publication](docs/agent-plugin-publication.md) for product-owned skills, runtime boundaries, and activation gates.
---
## REST API Usage
```bash
# Start the secure loopback server on 127.0.0.1:8080.
zaptrace-api
# Health does not require a bearer token.
curl http://127.0.0.1:8080/health
```
For the authenticated REST and MCP HTTP Compose deployment, copy `.env.example`, set both token values, and run `docker compose up --build --wait`. See [REST API production hardening](docs/api-rest-production.md) and [MCP HTTP deployment](docs/mcp-http-deployment.md).
---
## Manufacturing Export
ZapTrace generates all files needed for PCB fabrication:
| Artifact | Format | Status |
|----------|--------|--------|
| Copper layers | Gerber RS-274X | ✅ |
| Drill file | Excellon | ✅ |
| Bill of Materials | CSV / JSON | ✅ |
| Pick-and-place | CSV | ✅ |
| Manufacturing bundle | ZIP | ✅ |
| KiCad project | .kicad_pcb, .kicad_sch | ✅ |
| Schematic | SVG | ✅ |
| Design report | Markdown | ✅ |
```bash
# Generate everything
zaptrace export manufacturing my_design --output build/board
```
---
## Proof Pack
A Proof Pack is an auditable, reproducible artifact bundle that explains what ZapTrace generated and why.
```bash
zaptrace proof-pack design.yaml --output build/proof-pack
```
Each proof pack contains:
- Design inputs and normalized model
- ERC results (what was checked and what passed/failed)
- DRC results
- BOM and supply-chain overview
- All manufacturing artifacts
- Decision log
- Reproducibility metadata
- Warnings and review checklist
See [docs/strategy/proof-pack-spec.md](docs/strategy/proof-pack-spec.md) for details.
---
## Verification Model
ZapTrace uses a layered verification model. Each layer produces evidence; none is a correctness guarantee.
### Evidence Layers
| Layer | What It Does | What It Does NOT Do |
|-------|-------------|---------------------|
| **Parser** | Validates design YAML structure and constraints | Does not verify circuit functionality |
| **ERC (29 rules)** | Checks electrical rules (net connectivity, pin compatibility, power, power-tree, DNP-aware) | Does not simulate the circuit or verify timing |
| **DRC (16 rules)** | Checks physical design rules (clearance, width, drill) | Does not guarantee manufacturability |
| **KiCad Oracle** | Exports to KiCad and runs KiCad's ERC/DRC as external validation | KiCad may have different rules; a pass does not mean the design is correct |
| **Proof Pack** | Records all verification results, artifact hashes, environment metadata, and decisions | Evidence of what was checked, not a guarantee of correctness |
| **Fab Profiles** | Documents manufacturer capabilities (min trace, min drill, layers) | Not a manufacturer approval; always verify with your fab house |
| **GitHub Hardware CI** | Runs hardware-level integration checks on available runners | Cannot reproduce all real-world hardware conditions; physical testing required |
### What "Verification-First" Means
- Verification is **built into the pipeline**, not bolted on after export.
- Every design artifact has an auditable chain: who checked what, with which tool, and what result.
- The design pipeline stops on hard errors (ERC/DRC failures) and requires explicit override.
- **Human engineering review is mandatory** before fabrication. No automated tool can replace domain expertise.
### Non-Claims
ZapTrace does **not** claim:
- **Fabrication-ready** — no automated verification pipeline can guarantee a board will fabricate correctly.
- **Production-ready** — pre-1.0; APIs and outputs may change.
- **Manufacturer-approved** — fab profiles are reference configurations, not approvals.
- **Guaranteed correctness** — all verification tools have blind spots.
- **Fully automatic manufacturing** — every manufacturing output requires human review and fab house approval.
---
## Architecture
```mermaid
graph TD
A[YAML Design File] --> B[Parser]
A1[Natural Language Intent] --> B1[Synthesis Engine]
B1 --> B
B --> C[Design Model
