Metadata-Version: 2.4
Name: schemaseed
Version: 1.0.1
Summary: Data-driven KiCad schematic generator
Author-email: PalBotics <p.lydick@draftekdesign.com>
License: MIT
Project-URL: Homepage, https://github.com/PalBotics/schemaseed
Project-URL: Repository, https://github.com/PalBotics/schemaseed
Project-URL: Issues, https://github.com/PalBotics/schemaseed/issues
Keywords: kicad,schematic,eda,hardware,pcb
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kiutils>=1.4.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: sexpdata>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

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

[![CI](https://github.com/PalBotics/schemaseed/actions/workflows/ci.yml/badge.svg)](https://github.com/PalBotics/schemaseed/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/schemaseed)](https://pypi.org/project/schemaseed/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![KiCad 10](https://img.shields.io/badge/KiCad-10.x-brightgreen)](https://www.kicad.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

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

```yaml
# 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

```bash
pip install schemaseed
```

Or from source:

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

---

## Quick start

### Generate a schematic from YAML

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

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

### Validate without generating

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

### Search available symbols

```bash
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:

```yaml
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:

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

```bash
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](CONTRIBUTING.md) for contribution guidelines.

---

## License

MIT — see [LICENSE](LICENSE).
