schemaseed 1.0.0

Data-driven KiCad schematic generator

SchemaSeed

Data-driven KiCad schematic generator. Describe your circuit as a structured YAML or netlist file — SchemaSeed emits a .kicad_sch with symbols placed and connected, verified by two built-in correctness oracles.

---

What it does

SchemaSeed closes a gap in hardware workflows where the schematic is typically assembled by hand and used as the source of truth. SchemaSeed inverts this: you write a concise circuit description, and the tool generates a schematic you can open directly in KiCad, run ERC on, and push to PCB layout — without placing a single symbol by hand.

# power_protection.yaml
meta:
  title: power_protection

parts:
  - ref: Q1
    symbol: Transistor_FET:Q_PMOS_GSD
    value: DMG2305UX
    footprint: Package_TO_SOT_SMD:SOT-23
  - ref: R1
    symbol: Device:R
    value: 100k
    footprint: Resistor_SMD:R_0402_1005Metric
  # ...

nets:
  GATE:    [Q1.1, R1.1]
  GND:     [R1.2]

schemaseed generate examples/power_protection.yaml
  parts: 9   nets: 7   labels: 14   power symbols: 6
  oracles: geometric PASS, round-trip PASS

---

Requirements

• Python 3.12+
• KiCad 10.x installed (for symbol library resolution)

---

Installation

pip install schemaseed

Or from source:

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

---

Quick start

Generate a schematic from YAML

schemaseed generate examples/power_protection.yaml
schemaseed generate examples/power_protection.yaml -o out/my_circuit.kicad_sch
schemaseed generate examples/power_protection.yaml --grid-pitch 25.4

Generate from a KiCad netlist

schemaseed generate my_project.net -o out/my_project.kicad_sch

Validate without generating

schemaseed check examples/power_protection.yaml
schemaseed check examples/power_protection.yaml --strict --report-file out/report.txt

Search available symbols

schemaseed symbols search R
schemaseed symbols search LM358 --lib-path /path/to/custom/libs

---

Input format

SchemaSeed accepts two input formats:

Native YAML/JSON (recommended) — write your circuit description directly:

meta:
  title: my_circuit

parts:
  - ref: R1
    symbol: Device:R        # KiCad library:symbol
    value: 10k
    footprint: Resistor_SMD:R_0402_1005Metric

nets:
  VIN:  [R1.1]             # terse form: ref.pin
  GND:  [R1.2]
  # Verbose form with explicit pin discriminator:
  SIG:
    - {ref: R1, pin: "1", by: number}

KiCad netlist (.net, kicadsexpr format) — export from KiCad and feed directly:

kicad-cli sch export netlist --format kicadsexpr my_project.kicad_sch -o my_project.net
schemaseed generate my_project.net

---

Correctness oracles

SchemaSeed runs two oracles on every generated schematic:

Geometric oracle (pre-write): Every net label coordinate is verified against the known pin endpoint before the file is written. Catches arithmetic bugs before they reach disk.

Round-trip oracle (post-write): The emitted schematic is parsed back via kiutils, labels are matched to pin endpoints, and the reconstructed netlist is compared against the input. Catches kiutils serialization surprises.

Both oracles must pass for the generate command to succeed. Oracle failures exit with code 4 (generator bug) — not a user error.

---

CLI reference

schemaseed generate INPUT [-o OUTPUT] [--lib-path PATH]
                          [--grid-pitch MM] [--no-power-symbols]
                          [--power-nets NET=power:SYMBOL]
                          [--strict] [--verify-erc]

schemaseed check INPUT [--strict] [--format yaml|json]
                       [--lib-path PATH] [--report-file PATH]

schemaseed symbols search QUERY [--lib-path PATH] [--project-dir PATH]

schemaseed version

---

Exit codes

Code	Meaning
0	Success
1	Validation or data error (malformed input, ambiguous pin reference)
2	Symbol resolution failure (library not found, symbol not in library)
4	Generator bug — oracle assertion failed

---

Known limitations (v1.0)

• Grid placement only — parts are placed in a single row with fixed spacing. Manual rearrangement in KiCad is expected for production schematics.
• No rotation — all symbols placed at angle 0.
• Single-sheet schematics — hierarchical sheets not yet supported.
• KiCad 10 only — earlier KiCad versions are not tested.

---

Development

git clone https://github.com/PalBotics/schemaseed.git
cd schemaseed
pip install -e ".[dev]"
python -m pytest tests/ -v

Tests requiring a real KiCad install skip automatically on machines without one. The portable suite (non-KiCad tests) runs anywhere.

See CONTRIBUTING.md for contribution guidelines.

---

License

MIT — see LICENSE.