Fenolite
Headless, agent-first PCB design automation in Python. Fenolite lets an engineer — or an AI
coding agent — generate, open, verify, compare, convert and export printed-circuit-board projects
from Python code or a JSON-speaking command line, without a GUI. KiCad is the first backend (its
files, with kicad-cli as the verification oracle); a second backend for another major commercial
format family follows.
Status: version 0.2. A design script becomes a KiCad project with a board and a schematic, for KiCad 9.0 and 10.0. The loop below works on two-layer boards: the board is placed, routed by an external router, filled, checked by KiCad's own design-rule check and exported to fabrication files. The schematic is judged by KiCad's own electrical rules check, by its netlist and by its schematic parity test. What was proved for this version, and its limits, are in
docs/release/v0.2.md(docs/release/v0.1.mdfor the version before). Reading Altium files is new, and most of its evidence isINFERRED; the Altium target ofbuildis experimental.
Fenolite is the Portuguese word for phenolic board material — the laminate many of us etched our first circuit boards on.
Principles
- Agent-first CLI. JSON on stdout when not attached to a terminal, a fixed envelope, typed
errors, a small exit-code vocabulary, and writes only with
--confirm(--dry-runshows the plan). - Evidence on every answer. Each result says how it was verified (see below). Nothing is claimed that was not checked.
- No silent information loss. What Fenolite does not understand in a file is preserved, and a lossy operation stops unless explicitly allowed.
- Small, exact model. Integer nanometres and microdegrees, stable ids, canonical JSON that diffs cleanly in Git.
- Stdlib-only core.
pip install fenoliteinstalls no other package; heavier features are optional extras. - Your templates, not ours. Sheet frames and title blocks are generated from your own spec; Fenolite ships no organisation's templates, rules or libraries.
The model is described in docs/design-model.md; the CLI contract in docs/cli-contract.md.
What version 0.2 does
- The schematic.
fenolite buildwrites the schematic of the design beside the board, one sheet per module, which KiCad's ERC and parity test accept on 9.0 and 10.0 (docs/schematic.md). - Checks.
fenolite checkruns KiCad's ERC and DRC, compares the netlist of the schematic with the model and the board, and compares schematic and board without a tool (fenolite netlist,fenolite parity). - Tables and files. The bill of materials and the placement table (
fenolite bom,fenolite pnp) are rendered through a column template that you write (docs/assembly.md). Fabrication files and review renders (fenolite export,fenolite render) are described indocs/exports.md, andfenolite manifestlists every design file and artefact with its SHA-256 and a state. - Small questions.
diff,roundtrip,fmt,explain,restore,net,region,neighborsandpadsanswer one thing each, with paging and a concise form. - The layout is kept. A board edited in KiCad survives a rebuild, also when a module or a net is
renamed, and
fenolite sync --to-sourcewrites the placements into the source tree (docs/lens.md). - The design script. Six more rule kinds (hole to hole, hole clearance, annular width, courtyard,
silkscreen, creepage), exact quantities, typed interfaces, and your own drawing sheet and title block
(
docs/dsl.md,docs/sheet-templates.md). - Altium files are read.
inspect,check,diffandequivalenttake Altium documents, libraries and projects, read-only and without a tool (docs/altium.md,docs/equivalence.md), andfenolite analyzemeasures current capacity, clearance and creepage on a board (docs/analyses.md). What is proved of this, and one known defect, are in the release record.
Evidence labels
| Label | Meaning |
|---|---|
KICAD-VERIFIED |
accepted by kicad-cli of the stated version, and the claim confirmed by its output |
ORACLE-VERIFIED(<tool>) |
an independent parser or tool agreed |
CORPUS-VERIFIED |
round-trip holds on public files listed in the corpus manifest |
ALTIUM-VERIFIED(kit) |
confirmed by a native-tool acceptance run with archived results |
ALTIUM-VERIFIED(author-report) |
reported by the author from ordinary use; never enough for a release claim |
INFERRED |
deduced from public documentation; a hypothesis in docs/hypotheses.md tracks it |
UNKNOWN |
bytes or fields preserved without interpretation |
UNVERIFIED |
default for anything new |
A command's overall label is the lowest label of the steps it ran.
Install
pip install fenolite
It installs no other package. fenolite capabilities --json then says which external tools it found:
kicad-cli (KiCad 9.0 or 10.0) for the checks, the fills and the exports, and a router. It runs on Linux, macOS
and Windows.
The loop
The ten commands an agent runs, from a design script to fabrication files (agent/SKILL.md explains
each one and what to do when one fails):
fenolite capabilities --json
fenolite build examples/blink_2layer/design.py --out build/blink --dry-run --json
fenolite build examples/blink_2layer/design.py --out build/blink --confirm --json
fenolite place build/blink --strategy grid --confirm --json
fenolite route build/blink --router freerouting --confirm --json
fenolite fill build/blink --confirm --json
fenolite check build/blink --json
fenolite export build/blink -o build/blink/fab --all --manifest --confirm --json
fenolite render build/blink -o build/blink/views --svg --png --confirm --json
fenolite inspect build/blink/blink.kicad_pcb --json
Install for development
git clone <this repository>
cd fenolite
uv sync --extra dev
uv run fenolite --version
make check-fast # lint, format, types, residue scan and the tests that need no external tool
make check # everything, on parallel workers: the gate before a merge
Talk to it like an agent does:
uv run fenolite capabilities --json --fields tools # what is installed here
uv run fenolite capabilities --text # the same, for humans
echo $? # 0 ok, 2 usage, 4 confirm, 5 findings …
Optional extras: geo (polygon booleans), kicad-ipc (live KiCad session), mcp (MCP server),
oracles (Gerber re-parsers used in tests), dev. Routers need no extra: they run as separate programs.
Licence and provenance
Apache-2.0 (LICENSE, NOTICE). Format knowledge comes only from public sources; see LEGAL.md
for the clean-room rules and CONTRIBUTING.md for how to contribute. Every CI run and every commit
(after make hooks) passes a residue scan (tools/residue/) that blocks absolute paths, internal
identifier shapes and known non-public files; see docs/provenance.md for the provenance rules. AI agents working in this
repository: read AGENTS.md first.
Metadata
Release files for fenolite 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fenolite-0.2.0.tar.gz | 3.6 MB | With provenance | Details for fenolite-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fenolite-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for fenolite-0.2.0-py3-none-any.whl |
Total release size: 4.8 MB
Release files / fenolite-0.2.0.tar.gz
| Download URL | fenolite-0.2.0.tar.gz |
|---|---|
| Size | 3.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7d456bea7669e94d5454568da8646b3176d3b2d30032f8e684e6680bd8cc0b90
|
|
BLAKE2b-256 checksum How to use checksums |
2dc5aa1c20e4cb3344c0fe44244ab42a88040f0b28f2bd3b43b634612fbe6a5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / fenolite-0.2.0-py3-none-any.whl
| Download URL | fenolite-0.2.0-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b731f11007f9e2438dcfea208c0a0855d7e2c61387a48d1f3b23aa1887a8b785
|
|
BLAKE2b-256 checksum How to use checksums |
41aab911411986128090684fafa031532e98c5e276f7f287d009fbfa3ca08348
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logSecurity for fenolite 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for fenolite-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.