circuit-weaver 0.15.0

Programmatic circuit design, validation, and KiCad artifact generation

KiCad automation for people building real hardware.
Programmatic schematic generation, strict validation, BOM + sourcing workflows, and a clean API surface
that takes you from design intent all the way to quote-ready KiCad outputs.

---

What It Is

Circuit Weaver has two layers that work together:

Layer	What it is	Use it for
circuit_weaver package	Python library + FastAPI server	Canonical design IR, transactional patching, strict validation, KiCad artifact generation
skills/, project-skills/, agents/, rules/	Workflow layer	BOM auditing, part sourcing, KiCad analysis, placement, manufacturing, AI/operator playbooks

It is designed for:

• Engineers who want KiCad-native automation without giving up real schematic outputs
• AI/agent workflows that need a strict, machine-readable contract instead of ad hoc script chains
• Downstream hardware projects that want a reusable engine instead of maintaining a custom generator forever

---

Why Circuit Weaver

Most hardware automation lands at one of two bad extremes:

• A pile of one-off scripts only the original author can operate
• A flashy design layer disconnected from actual KiCad deliverables

Circuit Weaver sits in the useful middle:

Property	What it means
Canonical spec first	YAML / Design IR is the single source of truth
KiCad-native outputs	Generates real .kicad_sch files, reports, and review SVGs
Strict validity gates	Structural, electrical, implementation, and presentation checks — not just "did it export"
Agent-compatible	Patch, validate, diff, generate, and feed PCB constraints back in predictable, machine-readable flows
Downstream-friendly	The engine is generic; each hardware project owns its own design assets

---

Demo

Try the sample design:

cd samples/zigbee_humidistat
circuit-weaver generate zigbee_humidistat.yaml -o ./output --no-svg --no-require-valid
circuit-weaver cost-bom zigbee_humidistat.yaml --qty 1,10,100
circuit-weaver optimize-placement zigbee_humidistat.yaml --iterations 1000 --seed 42
circuit-weaver placement-viewer zigbee_humidistat.yaml -o output/viewer.html
circuit-weaver design-enclosure --board-width 50 --board-height 40 --component-height 10 -o output/enclosure.scad
circuit-weaver export-jlcpcb zigbee_humidistat.yaml -o output/jlcpcb

Sample design: samples/zigbee_humidistat/

See docs/DEMO_COMMANDS.md for complete step-by-step guide.

---

How It Works

The flow in plain English

1 — Requirements capture Start with block intent, interfaces, power rails, buses, and constraints. Codex, OpenCode, Kilo, or Claude + the engineer define the system without hand-drawing every schematic page from scratch.

2 — Part sourcing The digikey, mouser, and lcsc workflow skills turn vague component choices into concrete MPNs, package decisions, datasheets, and purchasing options.

3 — Build the canonical spec circuit_weaver assembles part bindings, block topology, support-circuit requirements, and all overrides into a single machine-readable YAML design IR. This is the contract everything else reads from.

4 — Generate schematics and validate The engine emits .kicad_sch files, placement hints, review SVGs, and a design report. It also auto-generates common support passives and runs four grouped validation checks: structural, electrical, implementation, and presentation.

5 — KiCad review + human polish Generated schematics are typically around ~90% complete for serious hardware work. The last pass is still human: page aesthetics, net label readability, and the editorial judgment that is still inherently design-specific.

6 — PCB update and route Pull the schematic into KiCad PCB, place parts, route critical nets manually, and use autoroute / Freerouting for non-critical nets where it actually helps.

7 — Quote-ready package The result is a clean path to BOMs and outputs ready to hand to PCBWay, JLCPCB, or your preferred fabrication vendor.

---

Quick Start

Installation

Option 1: PyPI (Recommended)

pip install circuit-weaver

Or with workflow skills (includes BOM, sourcing, KiCad analysis, etc.):

pip install circuit-weaver[skills]

Verify installation:

circuit-weaver --version

Register the /circuit-weaver skill globally in Claude Code (one-time):

circuit-weaver install-skills

Option 2: From Source (For Development)

git clone https://github.com/mattpainter701/kicad_automations.git
cd kicad_automations
pip install -e ".[dev]"

Then register skills:

circuit-weaver install-skills

Use in Claude Code

Open Claude Code in any project and type:

/circuit-weaver

The skill will guide you through designing a circuit with automated IC research, passive generation, and manufacturing export.

Or: Use the Offline CLI Wizard

circuit-weaver design-wizard

Interactive guide that works completely offline (no agents or APIs). Generates a YAML spec you can then validate and generate.

Validate a design

circuit-weaver validate src/circuit_weaver/examples/iot_sensor.yaml

Generate KiCad artifacts

circuit-weaver generate src/circuit_weaver/examples/iot_sensor.yaml --output out/iot_sensor

Run a Sample Design

To test the complete workflow without using the skill:

# 1. Validate a sample design
py -m circuit_weaver validate samples/iot_sensor_node/iot_sensor_node.yaml

# 2. Generate schematic and report
py -m circuit_weaver generate samples/iot_sensor_node/iot_sensor_node.yaml -o ./output

# 3. Export for JLCPCB
py -m circuit_weaver export-jlcpcb samples/iot_sensor_node/iot_sensor_node.yaml -o ./jlcpcb

Generated files (schematic, BOM, CPL, design report) ready for review or ordering.

Use the Python API

from circuit_weaver.mvp import (
    validate_design,
    apply_design_patch,
    generate_artifacts,
    diff_designs,
    ingest_pcb_feedback,
)

# Validate a canonical design spec
report = validate_design(spec)

# Apply a transactional patch and re-validate
result = apply_design_patch(spec, patch)

# Generate the full KiCad artifact bundle
bundle = generate_artifacts(spec, output_dir="out/design")

Run the HTTP API

uvicorn circuit_weaver.api:app --host 0.0.0.0 --port 5000

Endpoint	Description
GET /health	Service health check
GET /templates	Available subcircuit templates
POST /generate	YAML spec → ZIP of .kicad_sch files + report
POST /generate/from-bom	CSV BOM upload → ZIP of schematics
POST /validate	YAML spec → validation results JSON
POST /mvp/validate	Canonical spec → grouped mvp_strict validation
POST /mvp/generate	Canonical spec → full KiCad artifact ZIP
POST /mvp/apply-patch	Transactional patch + re-validation
POST /mvp/diff	Semantic diff between two specs
POST /mvp/pcb-feedback	Merge PCB feedback back into the design spec

---

Python Package Surface

Core transaction flow

spec → normalize → validate → patch → revalidate → generate KiCad artifacts

Public API functions

Function	What it does
validate_design(spec)	Strict grouped validation — returns a ValidationReport
apply_design_patch(spec, patch)	In-memory mutation with reject-on-failure
generate_artifacts(spec, output_dir)	Emits the full KiCad bundle + report
diff_designs(old_spec, new_spec)	Semantic change report between two specs
ingest_pcb_feedback(spec, feedback)	Feeds layout constraints back into the design spec

Validation model

mvp_strict checks are grouped into four categories:

Group	Checks
structural	Topology, connections, hierarchy
electrical	Power, ground, net integrity
implementation	Part bindings, footprint assignments
presentation	Labels, pin numbers, sheet readability

"The schematic generated" is not enough — the output also needs to be loadable, internally coherent, and reviewable.

---

Repo Layout

kicad_automations/
├─ AGENTS.md                  # Cross-agent repo instructions
├─ opencode.json              # OpenCode/Kilo project config
├─ .agents/skills/            # Repo-local skill entrypoints for OpenCode/Kilo
├─ .opencode/agents/          # OpenCode/Kilo subagent definitions
├─ src/circuit_weaver/        # Core engine: IR, MVP, validators, exporters, helpers
│   ├─ api.py                 # FastAPI HTTP server
│   ├─ mvp.py                 # Public-facing workflow functions
│   ├─ design_ir.py           # Canonical design intermediate representation
│   ├─ generator.py           # KiCad schematic generator
│   ├─ validator.py           # Validation check runner
│   ├─ subcircuits/           # Reusable circuit template library
│   └─ helpers/               # Impedance, placement, silkscreen utilities
├─ tests/                     # Package-level regression coverage
├─ skills/                    # Global KiCad / BOM / sourcing / vendor skills
├─ project-skills/            # Project workflow templates (kicad_gen, autoroute, sim…)
├─ agents/                    # Hardware reviewer AI personas
├─ rules/                     # Repo-native KiCad workflow policy
└─ assets/                    # README visuals and branding

---

Agent Platforms

Circuit Weaver now ships repo-native support for Claude Code, Codex, OpenCode, and Kilo.

Platform	What this repo provides
Claude Code	Global/project installs via .claude/skills
Codex	Root AGENTS.md guidance plus global skill installs to ~/.codex/skills
OpenCode	AGENTS.md, opencode.json, .opencode/agents, and .agents/skills compatibility shims
Kilo	Same repo assets as OpenCode; Kilo consumes the shared opencode.json / .opencode config surface

Platform-specific install paths, naming rules, and downstream examples live in docs/agent-platforms.md. Installers require an explicit target selection. There is no implicit Claude-only default anymore.

---

Workflow Skills

Global skills (install via ./install.sh or ./install.ps1)

• circuit-weaver — master orchestrator skill (agent-driven IC research via Perplexity, fastest path)
• design_wizard — manual step-by-step design guide (human-in-the-loop)
• kicad — schematic, PCB, and Gerber analysis
• bom — BOM management, auditing, and export
• digikey, mouser, lcsc — part sourcing and datasheet sync
• jlcpcb, pcbway — manufacturing file prep and quoting
• ee — general electrical engineering helpers
• vivado — FPGA design integration

Or use the CLI directly:

• circuit-weaver design-wizard — interactive offline wizard (no agents/APIs, works standalone)

Project skill templates (install into downstream repos)

• kicad_gen — project-local schematic generation playbook
• kicad_hierarchy — hierarchical sheet management
• kicad_validate — project validation runner
• kicad_pinmap — pin mapping and netlist management
• kicad_pcb_place — guided part placement
• autoroute — Freerouting integration
• sim — simulation setup helpers

# Bash: install global skills for Claude, Codex, OpenCode, and Kilo
./install.sh --platform all

# PowerShell: same install on Windows
./install.ps1 -Platform all

# Install downstream project templates into the shared open-agent directory
./install.sh --project-platform agents
./install.ps1 -ProjectPlatform agents

OpenCode, Kilo, and .agents/skills targets require kebab-case skill IDs. The installers convert source template names like kicad_gen into installed IDs like kicad-gen automatically.

---

Downstream Boundary

Keep upstream in kicad_automations:

• circuit_weaver package code and helpers
• Generic skills and project-skill templates
• Repo-native agents and rules

Keep downstream in each hardware project:

• Project wrappers like generate_via_engine.py
• Project-specific BOMs and pin maps
• Local symbol and footprint libraries
• Generated KiCad artifacts
• Project-local integration tests

This boundary keeps the engine generic while each hardware program owns its actual design assets.

---

Example: Buck Converter Workflow

End-to-end worked example

Analyze the schematic

python3 skills/kicad/scripts/analyze_schematic.py buck.kicad_sch --output buck_analysis.json

Find missing sourcing data

python3 skills/bom/scripts/bom_manager.py analyze buck.kicad_sch --json

Pull datasheets and vendor metadata

python3 skills/digikey/scripts/sync_datasheets_digikey.py buck.kicad_sch

Export manufacturing BOMs

python3 skills/bom/scripts/bom_manager.py export buck.kicad_sch -o bom/bom.csv
python3 skills/bom/scripts/bom_manager.py order bom/bom.csv --boards 3 --spares 2

Review PCB quality

python3 skills/kicad/scripts/analyze_pcb.py buck.kicad_pcb

---

Reference Documentation

Document	Description
API Reference	Public Python functions — signatures, parameters, return types, examples
CLI Reference	All CLI subcommands with flags, examples, and exit codes
Validation Codes	All 10 validation check categories with severity, sub-codes, and fix guidance
Design IR Schema	Annotated YAML schema for the canonical design intermediate representation
Template Reference	Full parameter reference for all 30 subcircuit templates (auto-generated)

Quick discovery from CLI:

# List all templates
circuit-weaver list-templates

# Detailed params for each template
circuit-weaver list-templates --verbose

# Generate a scaffold YAML for a buck converter
circuit-weaver scaffold --template buck --ref U1

---

CI/CD Integration

Two GitHub Actions workflows run automatically:

• CI (ci.yml) — ruff lint + pytest across Python 3.10–3.13 on every push/PR
• Design Validation (validate-design.yml) — circuit-weaver validate --strict on all sample and example specs when design files change

To add design validation to your own repo, copy .github/workflows/validate-design.yml and adjust the paths filter to match your spec locations.

---

Contributing

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks
pre-commit install

# Run linting
python -m ruff check src tests

# Run tests
python -m pytest tests -q

Pre-commit hooks run automatically on git commit:

• ruff — lint + format Python files
• check-yaml — validate YAML syntax
• validate-designs — run circuit-weaver validate --strict on changed design specs

---

Status

Working now (v0.14.0-alpha)

• Full MVP API surface (validate, patch, generate, diff, pcb-feedback)
• FastAPI HTTP server with all endpoints
• 200+ tests, CI on every push, design validation CI
• Subcircuit template library (30 templates, all with contract validation)
• 10-check validation pipeline with --strict mode for production
• Electrical quality scorer (0–100 with A–F grade)
• Costed BOM via LCSC pricing at volume breaks (cost-bom)
• JLCPCB BOM+CPL export, Gerber export (export-jlcpcb, export-gerbers)
• Visual design diff with SVG side-by-side comparison (diff --svg)
• DigiKey/Mouser/LCSC symbol autoloader with 30-day cache
• SVG placement editor — export/import placements via Inkscape
• Datasheet + spec harvesting — download datasheets, extract thermal/SI/passive specs (harvest-specs, extract-specs)
• SPICE model fetcher — TI, ADI, Microchip, ON Semi URL patterns (fetch-spice)
• Simulated annealing placement optimizer — thermal, SI, DFM, cost objectives (optimize-placement)
• Interactive HTML placement viewer — net highlighting, thermal heatmap, CSV export (placement-viewer)
• PyPI distribution with install-skills command for Claude Code / Codex / OpenCode / Kilo
• Pre-commit hooks, GitHub Actions CI, release automation

Active next steps

• Signal integrity constraint solver (USB/DDR/LVDS length matching)
• Thermal analysis with heatmap SVG output
• Dual-sided assembly BOM + CPL
• Panelization hints generator

---

License

MIT. See LICENSE.