Zaptrace

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.

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:

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

# 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

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.

# Start MCP server (stdio mode)
zaptrace-mcp

# Start MCP server (HTTP loopback mode)
zaptrace-mcp-http

Configure in your AI client's MCP settings:

{
  "mcpServers": {
    "zaptrace": {
      "command": "zaptrace-mcp"
    }
  }
}

See MCP quickstart for the tool catalog and agent plugin publication for product-owned skills, runtime boundaries, and activation gates.

---

REST API Usage

# 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 and MCP HTTP deployment.

---

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	✅

# 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.

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 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

graph TD
    A[YAML Design File] --> B[Parser]
    A1[Natural Language Intent] --> B1[Synthesis Engine]
    B1 --> B

    B --> C[Design Model<br/>Pydantic]
    C --> D[EE Knowledge<br/>Classifier]

    D --> E[ERC Engine]
    E --> F{RC Passed?}

    F -->|Yes| G[Placer]
    F -->|No| H[Suggest Patches]
    H --> C

    G --> I[Router]
    I --> J[DRC Engine]

    J --> K{DRC Passed?}
    K -->|Yes| L[Export Pipeline]
    K -->|No| I

    L --> M[Gerber]
    L --> N[Excellon]
    L --> O[BOM]
    L --> P[Pick-and-Place]
    L --> Q[KiCad]
    L --> R[SVG Schematic]

    L --> S[Proof Pack Generator]
    S --> T[manifest.json + artifacts]

    C --> U[MCP Server]
    C --> V[REST API]
    C --> W[CLI]

---

Example Gallery

Example	Description
ESP32 I2C Sensor Node	ESP32-C3 reading temperature/humidity over I2C
RP2040 USB HID	RP2040-based USB keyboard controller
USB-C LiPo Charger	USB-C powered LiPo charger with protection
STM32 RS485 Node	Industrial STM32 RS485 Modbus node
nRF52840 BLE Sensor	BLE environmental sensor with nRF52840

See examples/ for design YAML files and walkthroughs.

---

Safety Disclaimer

⚠️ ELECTRONICS DESIGN IS INHERENTLY RISKY.

ZapTrace is pre-1.0 software. All outputs — schematics, layouts, manufacturing files — must be reviewed by a qualified electrical engineer before fabrication or use.

Incorrect PCB designs can cause:

• Fire or thermal damage
• Equipment damage
• Electrical shock
• Radio interference (legal liability)
• Complete system failure

ZapTrace is provided as-is, without warranty of any kind. The maintainers assume no liability for damages arising from the use of this software or its outputs.

Verification tools are evidence layers, not correctness guarantees.

• A passing ERC/DRC/KiCad Oracle check does not mean the design is correct or manufacturable.
• A valid Proof Pack attests what was checked, not that the design is safe.
• GitHub hardware CI cannot replace physical testing.
• Fab profiles are reference configurations, not manufacturer approvals.

If you are not an electrical engineer, consult one before fabricating any ZapTrace-generated design.

See docs/SAFETY.md for the full safety policy.

---

Persistent local state

Controlled deployments can persist committed designs, immutable version lineage, snapshots, transactions, audit events, object ACLs, and evidence identities in local SQLite:

export ZAPTRACE_SESSION_STORE_ROOT="$HOME/.local/share/zaptrace/state"
zaptrace-mcp

Persistence is opt-in; unset deployments retain process-local behavior. Isolated workers cannot write durable state directly, active proof/release references protect artifacts from retention cleanup, and startup fails closed on schema or integrity errors. See Persistent versioned state for backup, restore, migration, deployment modes, and non-claims.

---

Roadmap

Horizon	Focus
Legacy baseline (v0.3.3)	PyPI-only release without public Git provenance; preserved as immutable historical evidence
Failed candidate (v0.3.4)	Aborted release candidate at commit 76ecc97; workflow failed before publication and is preserved immutably as failed evidence
Partial release (v0.3.5)	PyPI artifacts published and verified; container-security gate failed before GitHub Release creation, so the immutable tag is retained as partial-release evidence
Active development (0.3.6.dev0)	Post-release development line; future publication must pass container security before TestPyPI/PyPI promotion
Next (v0.4.0)	Topology and layout depth, bounded evaluation coverage, review evidence, and controlled release-readiness hardening
Later	Larger component library, live distributor integrations, deeper routing fidelity, solver-grade SI/PI/thermal integrations, multi-board workflows

See docs/ROADMAP.md for the full roadmap.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

• Issue tracker: GitHub Issues
• Questions and design discussion: use GitHub Discussions; use Issues for confirmed bugs and scoped work
• Code of Conduct: CODE_OF_CONDUCT.md

---

License

Current project-authored ZapTrace source code is available under the PolyForm Noncommercial License 1.0.0. Commercial use requires a separate written license from the copyright holder; see COMMERCIAL-LICENSING.md and LICENSING.md.

Earlier versions and revisions already released under MIT remain available under the MIT terms that applied when they were published. Third-party material keeps its own license terms.

---

Current Limitations

• Pre-1.0: APIs are unstable and may change without notice.
• No interactive PCB GUI: Primary surfaces are CLI, SDK, MCP, REST, generated artifacts, and Review Studio evidence views.
• No fabrication approval: No claim of manufacturing readiness is made; all outputs require qualified human engineering review.
• Heuristic analysis: Current thermal, SI/PI, impedance, current-density, and power reports are evidence pre-checks, not solver-grade sign-off.
• Algorithmic routing: Routing is grid/net-aware, but not a professional push-and-shove interactive router.
• Bounded synthesis: Synthesis is block/template/requirements driven, not open-ended from-scratch invention for arbitrary circuits.
• Limited package/library breadth: Many module, DFN/LGA/aQFN/RJ45/RF land patterns still require datasheet-backed geometry expansion.
• KiCad Oracle is external validation: KiCad's own ERC/DRC has limitations. A passing check does not guarantee circuit functionality.
• Fab profiles are not manufacturer approval: Always verify against your specific fab house and current manufacturer capabilities.
• Benchmark pass is regression evidence: It does not imply fabrication safety or production readiness.
• GitHub hardware CI ≠ physical testing: CI cannot reproduce all real-world failure modes.
• KiCad export is primarily outbound: Import/round-trip fidelity is still a future hardening area.
• Plugin system is experimental: Signed-runtime policy exists, but production sandboxing requires further hardening.

Repository Maturity and Community Health

ZapTrace is managed as a pre-1.0 professional source-available project. The repository keeps its maturity evidence, governance, contribution expectations, release process, and security posture public so users and contributors can review the project's operating model.

• Repository maturity report
• OpenSSF evidence
• OpenSSF gap analysis
• Governance
• Maintainers and access continuity
• Support policy
• Development standards
• Testing policy
• Release process
• Dependency management
• Release integrity verification

Current maturity target: professional source-available engineering maturity. Earlier OpenSSF/FLOSS evidence describes the MIT-licensed period and should not be read as a current FLOSS-license claim; governance limitations such as solo maintenance also remain explicit.