Layout and principles
soldermask/
design.py schema.py priors.py the model: prompt -> design. Five backends (claude-code, gemini,
claude, groq, mercury), SOLDERMASK_BACKEND to choose; the default,
claude-code, runs Claude Code headless on its own login with three
of the MCP server's tools (search_parts, pins, check_design) and is
the only backend whose schema lets a component carry `lcsc`
__main__.py `python -m soldermask`, which is cli.main()
wire.py the second turn, opt-in (`--wire` on the command line and the
evaluator; the app and the claude-code backend do not run it): the
parts as ordered and their real pin names in front of the model,
the nets against those
resolve.py parts.py packages.py parts against the catalogue, footprints;
resolve.declare/pinout/addressable go the other way,
from a chosen catalogue row to a design line and its pins
jlcparts.py params.py the parts dataset read off disk; the parametric index
jlcapi.py JLCPCB's own parts data through its signed open API: lookup by
code, the library paged, the whole of it as a snapshot (the
dump, then a detail record a code -- the parameters); the
catalogue jlcparts.py reads, written from that snapshot in the
mirror's own format by ingest() (`setup --parts`); the
authority stock and price are reconciled against
orderability.py can this board still be ordered?
symbols.py easyeda.py alternates.py KiCad symbols (fetched by setup: fetch_library), vendor
footprints, substitutes
eeformat.py EasyEDA's own format read -- pads, silk, pins, the 3D
model's uuid and offset -- in place of easyeda2kicad (AGPL);
a polygon pad keeps its outline (packages.Pad.poly), which
the clearance, ERC and fab checks measure and the .kicad_pcb
(a custom pad) and the Gerbers (a region) draw
datasheets.py jev.py the sheet itself: fetched from the listing's link, read by
pdftotext, its pin table transcribed once by the design stage's
model; its names laid on the vendor's symbol (with_sheet_names),
the two compared pin by pin -- a swap holds the pad back from
wiring -- and a refused pin name looked up through it, last of
all by Jev (a closed-question model, optional, taken at its floor)
componentlib.py the component library: facts read once from 97 parts'
datasheets (assets/components/<LCSC>.json), each with its
page, a verbatim quote and an audit status; applied() hands
out verified items only. designcheck.py (so every build's
ERC), conditions.py and grade.py read it;
tools/component_library.py writes and audits it.
get() reads the shipped record first, then one the reader
wrote into <cache>/components/
datasheet_reader.py the datasheet read on demand, opt-in
(SOLDERMASK_DATASHEET_READER=azure): the packet, read A
(DeepSeek-V4.1-Flash, the full record, search/page tools)
and read B (gpt-5.4, external parts, page images) at once,
merged one item a part; read C (gpt-5.4-mini on the drawings
at 300 dpi, off unless SOLDERMASK_READER_DRAW), a second
reading of figure values only; the two rules that held on pilot 3's
held-out half (module_internal, figure_agreement), the audit, stored in
the cache with its provenance and every answer; reread() rebuilds a
record from the stored answers; a per-read spend guard
(SOLDERMASK_READER_MAX_USD). Called only by mcp.py's
read_datasheet and `soldermask parts read`, never by a build
erc.py electrical.py electrical rule check; IPC-2221 and Ohm's law
designcheck.py what the parts' datasheets and the buses between them
require, as ERC rules: a pin over its absolute maximum
(component library), an enable tied off, a USB-C sink
with no Rd, an I2C line with no pull-up are errors;
crystal load caps, the sheet's bypass and program parts
and a fixed regulator's rail are warnings. Since 7 Nov:
a motor supply with no bulk and an LED that cannot conduct
are errors; bulk under a figure (driver, strip, servo), a
dim LED, a crystal resistor on XIN, an ESP32 EN with no
RC, an audio corner over 20 Hz and SWD without NRST are
warnings, each citing its source. Since 8 Nov a diode wired
backwards is an error (diode-direction) and one wired by bare
pad numbers a warning (diode-pins). Also warnings: a rail outside
a pin's recommended range (supply-range), a USB-C's CC pins on one
shared pull-down (usb-c-cc-shared), an Rd that is not 5.1k
(usb-c-rd). The rule names are the Violation kinds in
designcheck.py. power_tree()
reads each rail's source and loads back for check_design.
Does not import grade.py, so the grader stays outside
spice.py the circuit switched on in ngspice before it is placed; sim.json for the scope.
A World (sources behind leads, stepping loads, corners, LEDs lit
through the pins that drive them) changes the deck for conditions.py
conditions.py the board under the conditions it will meet, read off the design:
plugged in through a lead, loads stepping, a cell draining, parts at
their tolerance corners, an audio sweep; held to the library's and
the catalogue's limits. Report only, a proof (8 Oct 2026). A build
runs one piece of it: designcheck's audio-corner rule sweeps an
audio coupling cap with conditions.audio() inside every build's
ERC (since 8 Nov 2026); run(), the whole set, no build calls
rubric.py the reviewer's rules graded on every board built and said as
notes; the lines and the pro reference are assets/rubric.json
roles.py physics.py each part's job read off its wiring (bypass cap and the pins it
serves, a switcher's switch node, input and output caps and
divider, a crystal and its load caps, an ESD part and the
connector lines it guards, a USB or CAN pair), and what the
placement and the copper make of it in physical units: loop
inductance by Neumann's integral with a plane's return as its
image, switch-node copper, pair skew and impedance; review()
says, on every build, each check worse than three in four of
people's boards (assets/physics.json) and stores board["physics"]
layout_rules.py the datasheet's own layout rules (assets/layout_rules.json: quote,
page, sheet, limit and where the limit is from) checked on every
build: per-pin decoupling, a switcher's input cap, the exposed
pad's vias or its no-solder policy, a via-free cap path.
Advisory: notes, board["layout_rules"], verdict["layout_rules"];
never verdict.passed. tools/layout_rules_check.py builds the store
fabrules.py JLCPCB's published table (read 24 Sep 2026) checked on every
board built: below-minimum / extra-cost / risk, the assembly
service it needs; board["fab_rules"], gaps and notes
placer.py dsn.py ses.py placement on either side of the board, antenna keepouts, the edge a design names for a part (edge_goal), the areas a design asks to keep clear and a board read from a file's own outline, holes and copper kept clear (board_zones), the anneal watched frame by frame; the Specctra DSN each version stores and the session reader (freerouting, retired from the build, reads and writes them for the research tools)
mounting.py the mounting holes a design asks for (constraints.board.mounting_holes): one non-plated hole of no part a corner and a keepout ring round it, placed again when the board is sized; read off a prompt by from_prompt
keepout.py copper kept out from under a connector's body (kind `connector`, or a USB,
card-socket or DC-jack package by name) on the side it is mounted on: the
body less a cut from each of its own pads to the body's edge; the DSN's
keepouts, the .kicad_pcb's rule areas (which the A* router reads) and the
pour's stitching vias all ask it -- and a power corridor's, which a
router's netlist carries (Netlist.power_keepouts), and each area the
design asks to keep clear (constraints.keepouts -> Netlist.keepouts,
asked()), one a copper layer, refusing pads and pour as well
anneal_terms.py blocks.py what the anneal pays for past wirelength; functional blocks
filegeom.py what a board's KiCad file draws besides its pads, as the router must
see it: copper no pad owns, mask openings (owned by the one net whose
pads they expose), a dropped footprint's copper, and the outline's
edges; kicadpcb.read puts them on Netlist.obstacles and .outline, each
shape and hole ending with the part whose footprint draws it, and
router.problem keeps copper clear of them and inside the outline --
a part's own moved with it, the rest only while every part is at
Netlist.file_pose (router.carried, router.file_geometry_held);
router.fixed_held() says which of the file's fixed geometry holds on a placement (all of it wherever no pad sits on it); fab_art() is the file's outline and exact copper and mask art as the
fab files draw them (text read as a `box` for the router, not drawn);
fab_holes() is every non-plated hole the board is drilled with
(Package.holes and the file's, as the router meets them), which
kicad.write, the NPTH drill file, the mask, board.json and the
fab rules all draw from
router.py Lightcycle, the build's default router and this tree's own (`lightcycle`): every net routed at
once by negotiated congestion (PathFinder) on a fine grid, the rule
held exactly at every cell -- the search is the `lightcycle` wheel's
`route_board` (soldermask-org/lightcycle, pinned as
LIGHTCYCLE, installed by `soldermask setup`);
this builds the problem and reads the copper back as a ses.Routing;
`violations()` measures that copper with nothing the search shares
pairs.py differential pairs laid as pairs on the route a board ships
with: the middle routed as one wide net, offset into two
tracks, the two nets joined again (router._lay_pairs); each
pair's row, laid or left as routed and why, rides the route
pour.judge keeps (PourOutcome.pairs) and restate() puts the
kept route's notes on the board; on four layers the middle
goes on F.Cu, and on In2.Cu too with SOLDERMASK_PAIRS_IN2 (off).
A pair left as routed can have its room negotiated with the
board, routed again as one wide net (router._negotiate_pairs,
SOLDERMASK_PAIRS_NEGOTIATE=1, off by default)
widen.py a thin route grown back toward each net's width where the
board has room (shared a step a round, shoulders on a free
side), and the copper judged for heat: each narrow run's
rise, the lesser of IPC-2221 and its conduction into the
copper at its ends (`runs`), read by the verdict
tandem.py placing and routing in one loop: every candidate routed by
Lightcycle at once and ranked by what it did, and, where none
reached every pin, three fresh anneals routed and ranked with
them (the build does this when Lightcycle routes, the default;
SOLDERMASK_TANDEM=0 stands it down); repair() grows the router's
hot parts and re-anneals their neighbourhood, the instrument
that lost to those fresh anneals, and the build does not call it
abstract.py a board said at the size of its ideas: blocks round their anchors,
the links between them, the rails, the router's hot spots -- as a few
lines of text and back
astar.py pour.py fillet.py the A* router: first by name (constraints.rules.router `krt`,
or SOLDERMASK_ROUTER), and the board's router whenever
Lightcycle is not installed or cannot run it, with a gap saying
so (workspace._route_once); the ground plane -- and a local
one-layer zone for each high-current rail above it in
priority, its pads accounted one by one, poured from the
start on request (Netlist.power_pour, SOLDERMASK_POWER_POUR)
and, by default, as a second build of a board whose copper
alone failed, the build with fewer copper failures kept
(workspace.POWER_FALLBACK, SOLDERMASK_POWER_FALLBACK=0 turns it
off); tracks and rounded corners
escape.py escape stubs: a straight track out of each pad the
router's grid cannot end on, laid before each placement is
routed. On by default (SOLDERMASK_ESCAPE=0 turns them off),
and laid only on a board Lightcycle routes first: the A*
router finds its own way out, and astar.refuses() does not
count a stub as hand copper
planes.py a four-layer board (constraints.board.layers): by default
F.Cu signal, In1.Cu ground plane, In2.Cu signal, B.Cu signal
(MODE "gnd"); SOLDERMASK_PLANES=gnd+power makes In2.Cu the
busiest rail's plane. Which net each inner layer is (assign),
the layers a router is handed (signal_layers), and what the
notes say of it; the pour fills the planes, every surface pad
of a plane net gets a via beside it first (pour.ground_sites)
corridor.py a poured rail's zone as a corridor from its source to its
loads (SOLDERMASK_POWER_SHAPE / Netlist.power_shape `tree`
or `mould`; `hull` is pour.py's and the default): the source
by pin name, switch, series part or connector, each load's
current, a Steiner tree or physarum.rail()'s tubes sized
leg by leg, rastered, clipped and traced to polygons, and
the keepout every other net's router is handed; the layer
that strands no pad without room for a stitching via first
prune.py copper that joins nothing -- a via reaching its net on one
layer or none, a track end touching nothing of its net --
taken off the board pour.judge keeps, and kept off only if
KiCad, refilled, loses no connection
fold.py physarum.py a placement as a chord diagram; a slime mould routing it --
set up, loop, read out; the loop runs in mould/ when it is built;
rail() grows one power rail alone for corridor.py
congestion.py corpus.py routability.py the placer's picture of the board; every route kept; the model
precedent.py what each corpus board is, and the one most like this design as a seed
genome.py a placed board as one 64-bit word a part, exact to 0.1um, so a
corpus unpacks into model columns with a shift and a mask
gnn.py the graph judge: message passing over genome.graph, with or without
the mould's and the fold's readings; fit in torch, run in numpy
learn.py `soldermask learn`
gerber.py assembly.py Gerbers, drill, BOM, CPL
silk.py a part's silkscreen drawing -- the vendor's own, or drawn from the
pads and body -- and where it lands; the Gerber, the .kicad_pcb and
board.json all ask it, so they carry one drawing
silkfont.py isofont.py insignia.py the stroke font; ISO 3098 outlines; the maker's mark
kicad.py kicadcli.py models3d.py .kicad_pcb, kicad-cli DRC/render/ERC/netlist, vendor 3D models
sheet.py kicad_sch.py the schematic sheet laid out (roles, flow, ports, labels, wires,
text) and stored on the board; the .kicad_sch written from it
and read back for what it connects
kicadpcb.py a finished KiCad board read back as one to place and route;
repair_imported() gives kicad-cli's imports their net table
inventory.py stock and price at several quantities
repair.py evaluate.py the repair loop; pass@1 on this task; the verdict as a poll (repair.poll)
grade.py the model index's second judge: a finished board held against
what its prompt asked, clause by clause, from the parts as
ordered (catalogue row first, then the part's datasheet record
before a clause is called unknown); pass, fail or unknown; declared
or silent; board_from_kicad reads another tool's .kicad_pcb and
BOM into the same Board (pinfunction names, rail voltages from
net names); eight checks every board owes (powered, grounded,
transistors, leds, diodes, floating, dissipation, shorted); MCU helpers
(crystal, USB-C, native USB, strapping, isolation); mutants()
copperjudge.py the copper half of that judge, from any tool's .kicad_pcb: layers
the stack has and carries; whether fast pairs run coupled and
matched; whether the path a stated current takes carries it (the
net as a resistor network, solved, each run and via held to the
verdict's heat limit). Used by the hard held-out tasks
export.py render.py viewer.py board.json, board.svg, the standalone viewer
projects.py workspace.py diff.py versions on disk and the project bundle; the one build sequence; design diffs
edits.py a scoped edit, applied to what is already there
platforms.py stackup.py the MCUs a board is built around; what it is made of
version.py release.py config.py the app's version; releases; where things live
cli.py style.py skeleton.py the command line; its colour, and the picture a
terminal can show (inline image or braille); the
board's skeleton drawn from board.json for that
mcp.py the pipeline as an MCP tool server: every stage ours or the
caller's, one judge, no model call of its own (it sets
config.model_calls() off; --model-calls lifts it) except
read_datasheet under SOLDERMASK_DATASHEET_READER=azure; JSON-RPC
on stdin/stdout, by hand; SOLDERMASK_MCP_LOG, a line a call
tables.py a catalogue answer -- search rows, a pinout -- as lines a
model reads for half the tokens of the JSON, and back
gnm.py a board's state as gnm text (a line a part, a line a net) and back:
the token census's encoder, and place/score_placement/build
answered in lines with the placement as gnm, and read as one
(not genome.py, which is bits for a corpus)
mcp_http.py the same server over Streamable HTTP for a client that is
not on this machine: bearer keys (digests on disk), a
projects directory a key, one build slot at a time, the
precedent's placement withheld under a non-permissive
licence; nothing ships
app/
__init__.py serve(), the Flask factory, headers, compression; server_wrapper(), the ASGI app
serve() hands Hypercorn, which holds every body to BODY_MAX
(8 MB) but lets POST /api/projects/import carry a project zip up
to api.BUNDLE_UPLOAD_MAX (256 MB) for a request that already
carries the token, the login cookie or a trusted local client
api.py pages.py the JSON API; the HTML pages
benchmarks.py what /benchmarks reads off disk; it computes nothing
jobs.py bus.py turns.py auth.py background builds; the event bus (progress and the placing's frames are transient on it); a turn; access control
templates/ static/ Jinja pages; workbench.js, schematic.js, projects.js (the home:
ledger, disc, foot), platforms.js (the MCU token), mesh.js (the
vendor 3D models' wire format, decoded for the workbench and the
standalone export), partcloud.js (the selected part as a point
cloud in the details panel), benchmarks.js (/benchmarks), and the
stylesheets (tokens.css under all of them, workbench.css,
projects.css and platforms.css for the home, benchmarks.css,
instrument.css for About and the project cards); vendor/
(three.min.js and GLTFLoader.js, fetched by tools/fetch_three.py;
fonts.css and the files it names: the three faces, tokens.css and
tests/test_fonts.py say which is set in what)
mould/ the compiled cores (soldermask_mould): the mould's inner loop in
Rust, the same loop as physarum.py's numpy, a lane a net, a thread a
window, numpy carries it when it is not built; and the
placer's anneal (src/anneal.rs), placer.anneal()'s loop draw for
draw -- CPython's random stream, CPython's hypot, the cost summed
in local()'s order -- so a seed places the same on either. The
compiled anneal runs by default wherever the core is built
(SOLDERMASK_ANNEAL `auto`; `python` forces the reference, `rust`
makes a missing core an error); `pip install ./mould`
docs/ mkdocs.yml this manual; MkDocs builds it for the app's /docs
paper/ the write-ups: isonet.tex and mendicant.tex with their PDFs;
fig/ is drawn by tools/paper_figures.py from .cache's JSON
landing/ the public site (Vercel, vercel.json): static pages, scripts and
images, and the Python that writes their data from the tree --
board.py (the hero board), art.py and golfcu.py (the PCBGolf
entry's pictures and copper), shots.py (the app's screenshots,
from a real build through the app into .cache/landing-shots/),
about.py and retro.py (charts from the corpus and git), intro.py
(the wordmark as a video)
.github/workflows/tests.yml CI: tests/run.py on Python 3.11, 3.12 and 3.13 with the symbol
library fetched and the mould built, Lightcycle installed only
when a LIGHTCYCLE_TOKEN secret is set, then the mould's tests
again on the numpy loop
pypi-name/ a metadata-only release that holds the name `soldermask` on
public PyPI; it installs no code
serve.py `python serve.py` is `soldermask serve`, kept for old habits
build_backend.py setuptools, plus a copy of the top-level priors_blocks.json and
priors_zener.json into soldermask/assets/ so a wheel carries them
mine_blocks.py import_footprints.py the block miners (priors_blocks.json) and the footprint import
(assets/footprints.json); see tests.md's Other tools
solderdocs/ the same manual public at solderdocs.shwinnie.com: Fumadocs
(Next.js, static export); scripts/sync-docs.mjs turns docs/
into its content before every build, so the two cannot drift
bench/ the public routing and placement bench, started 26 Sep 2026:
referee.py judges a routed or placed board against its task
with kicad-cli and the standard library alone -- nothing from
soldermask, which tests/test_referee.py holds -- taking only the
entry's copper (or, on the placement track, where its parts
went, turned over or not, read off their pads) onto the task,
counting open connections apart from rule errors, and
counting a rule error only when the entry's copper is in
it, or, for a solder mask bridge, when the bare task lacks
it (referee 0.3, 30 Sep 2026; it forgave only what the bare
task's DRC reported, which KiCad 10.0.6 varies run to run);
and a third track, `referee.py board` (12 Nov 2026), which judges
any tool's whole board with no task: every connection made and
no rule error, overlapping courtyards and a footprint's own
drawing counted and not failed, its multilayer rules on a board
of four layers or more;
tasks.py makes tasks: a part's keepouts bound into its footprint
so they move with it, and an author's board as a routing task
(copper stripped, rewritten by kicad-cli, the canary stamped);
index/tasks/ (27 Sep 2026) the model index's task specs, one
file a prompt: its clauses asked-for and implied, and a check
over soldermask/grade.py's Board; all 60 of the evaluator's prompts;
review_template.html, the engineer review page's template
(the held-out tasks live outside this repo, in
../soldermask-heldout, so no session here tunes on them)
tests/ tools/ deploy/ the suite; snap.py, backfill_models.py, annotate_boards.py,
enclosure.py (a two-part case for a built board, base and lid
as STEP and STL with windows, holes and screw tabs, run in its
own build123d venv, .cache/cad-venv),
footprint_holes.py (the imported footprints' non-plated holes, and
with --pads their pads, drills and slots as this pipeline's reader
reads them, recovered from a source whose pads match, into
assets/footprints.json),
exa_boards.py, org_boards.py, fetch_kicad.py and kicad_boards.py
(the board bank: found by question or by vendor, fetched over
git, converted from Eagle/Altium/legacy through kicad-cli, kept;
`--layers 4,6` fills the multilayer bank beside the two-layer one),
graph_corpus.py and gnn_train.py (the corpus as graphs; the graph judge),
pic.py, pic_place.py, pic_perturb.py, pic_report.py (a photonic
chip read, placed by the channel fold, and judged by LiDAR);
place_bench.py (the placer against the board's author, the
literature's protocol: placed on the same outline, routed as traces
by A* and freerouting, judged by kicad-cli, paired per board, placer
variants as arms; suites `cypress` and `bank`) and azure_bench.py
(its arms sharded onto rented machines and collected home);
azure_build.py (one big Azure machine that builds as the laptop
does: up, push the tree, caches and Lightcycle at its pinned tag,
sync the code alone, ssh, get, status, down; for replay A/Bs and
the speed work);
antenna_ab.py (the placer's antenna-keepout term on and off, under
the old search and the new, on a drive's own antenna boards: every
anneal checked for copper in a zone, each board built as the drive
built it, no model);
physics_census.py (physics.report() on the replay's builds and on
people's two-layer boards, author copper and placement, and the
author's placement against the affinity census's anneals of the
same netlist; fills by kicad-cli into .cache/physics_census/);
affinity_census.py (the author's placement against one anneal of the
same board, pair by pair in thirteen netlist roles -- decap, ESD,
fine-pitch ring, edge and the rest -- each read past the board's own
wirelength ratio; rows keep the anneal's placement);
escape_oracle.py (the author's own escape copper on a fine-pitch
board, walked out from the pads 1 or 3 mm and handed to A* as copper
it may not move, against the bare board on the author's placement:
the ceiling of an escape policy before one is trained; `_pour` arms
pour ground as the product does, `ret` hands it escape_policy's);
escape_data.py (every fine-pitch pad's escape in the bank as its author
drew it, in the part's own frame, with where its net goes and a DRC
flag; split by repository, the gate's repositories held out and their
forks excluded; .cache/escape_data/);
escape_policy.py (the first escape learner: another author's fan-out
for the same package off the train split, matched on the whole pad
layout at four turns and chosen for where this board's nets go;
`self-test` scores it against held-out authors);
escape_geom.py (an escape as a decision -- via, direction, exit -- and
copper laid for it by A* at this rule round the part, pad by pad,
legal by construction, or all of a part's pads at once by negotiated
congestion (`negotiate`); escape_oracle's `dec`, `wpt` and `neg` arms);
revision_pairs.py (preference pairs from the git history of the bank's
boards: a later revision by the same designer that kept the parts and
moved them, followed across renames, kept as it goes; `report` asks
which rubric scalars move the way the rubric says is better, `moves`
where the moved parts went, `fit` what weights the pairs support);
rubric_reddit.py (what r/PrintedCircuitBoard's reviewers raise, counted per rule
against the catalogue from a year of the sub's review threads; `--fetch` the
repositories those threads link, pinned before the post; `--boards` writes
them as battle/reddit/ for `rubric.py --calibrate`; a remark is a label only
once a reader has confirmed it in review.json's `confirmed`);
rubric_within.py (can the rubric order one board's own anneals); pair_annotator.py
(trade-off pairs of a board's anneals for a person to choose between, and
the fit that reads the choices back); crystal_ab.py (the crystal term
under the router); deeppcb_board.py (a board DeepPCB shares, routed by ours);
route_bench.py (routers against each other on one stored placement,
one rule, one judge: the A* router and Lightcycle on the
KRT-levers pilot's 300 held-out boards, kicad-cli at 0.127/0.127,
the placement kept in the row so a later arm is judged on the
same board); referee_bench.py (those 300 routed again with the
copper kept under .cache/referee_bench/, each entry judged by
router_ab's judge and by bench/referee.py on the one file);
route_witness.py (witnesses from above: Lightcycle's referee failures
routed again under a portfolio of settings, a pass counted only
when its copper crosses no part's hole or copper);
plane_bench.py (four layers against two on the referee bench's
placements: the product's pour on two layers, its planes on
four, and four signal layers, each judged by bench/referee.py
against a task carrying the same zones; the two-layer row is
the referee bench's own);
route_limit.py (a floor under every router: per net, whether any
legal copper at the judge's narrowest rule can join its pads on
the 300's stored placements, leaning every choice the router's
way; checked against both routers' passes and Lightcycle's copper;
`--v2` runs it on the held-out tasks as placed, with the author's
keepouts as exact polygons);
flow_bound.py (the same question for every cut at once: cells
with route_limit's room per side, nets as a fractional flow, and
a weights certificate when no flow fits; on bench v2 tasks);
referee_place_bench.py (place_bench's 100 bank boards the same way:
the author's placement and today's placer through the referee's
placement track, then routed by A* and Lightcycle and judged twice);
bench_draft.py (the public routing set's first draft, under
.cache/bench-draft/: the bare-clean tasks with a canary in the title
block, provenance and licence class, Lightcycle's tuning flag,
both routers as baselines, and the fingerprints to commit to);
bench_v1.py and bench_v1_release.py (the public routing bench,
version 1: the authors' boards chosen, built, routed by A*,
Lightcycle and freerouting, judged, and assembled for publishing
under .cache/bench-v1/release/); bench_v2.py (the held-out
routing bench: tasks no router of ours was built on, every arm
in its own process under one clock, the code frozen into the run
directory first, under .cache/bench-v2/; `select-4l` picks the
four-layer bench, .cache/bench-4l/, split into a development half
and a held-out half run in .cache/bench-4l-test/);
bench_4l_report.py (that held-out run's report, as its protocol
states the analysis); layout_gym.py (the external layout
benchmark: open-source KiCad boards of 4 to 10 layers re-laid
at the author's placement and at ours, judged by kicad-cli under
each board's own rules, under .cache/layout-gym/; scan, select,
run, rejudge, report); gym_escape.py (escape stubs out of
fine-pitch pads, laid before routing: a gym setting, not the
build's); kicad_srj.py and
tscircuit_route.mjs (a task as tscircuit's SimpleRouteJson,
read by KiCad's own Python, and that router run on it in Node);
sim_conditions.py (stored designs through conditions.py, and the
score against the grader's targets and good boards);
sim_bench.py (faults injected into stored designs, one at a
time, and what the simulator and the design check catch;
splits dev, held and sep); contracts.py (each part's
datasheet record read as what it assumes and guarantees,
checked at every tolerance corner, scored on sim_bench's
faults; a research tool the build does not call);
designcheck_replay.py (the same stored designs, resolved once
and cached, through designcheck.py: the grader's targets, every
new fire on a good board, and `mutate`, defects seeded into the
good boards one class at a time); ab_drive.py (one MCP tool call
answered as the server answers it, for a design-flow A/B: the
drive id names the arm, and arm A runs the committed design
check and component library);
index_grade.py (a run's
boards graded against bench/index/tasks/, and with --mutate the
broken copies each check lets through, for review; --tasks-dir
for the held-out set; --source kicad grades our builds from
their files, --submission grades another tool's); index_review.py (the engineer review
packet: a sample of tasks with each clause's evidence and the
surviving mutants, into bench/index/review_template.html);
index_agent.py (the index's neutral agent, Claude or Gemini: a model designs a
board through a fresh MCP server per task, every API call's
tokens priced, budgets on turns, tool calls, time and dollars,
the first build judged by the verdict and the spec check);
kicad_specctra.py (KiCad's own
DSN export and SES import, run under KiCad's bundled Python);
cypress_h2h.py (NVlabs Cypress against our placer on
tandem_bench's 60 boards: export, round trip, judge;
Cypress itself needs a CUDA machine);
tandem_bench.py (the placer and router as one system:
six anneals a board, the A*-first order the product had against
Lightcycle's ranking and repair, and the repair against as
many fresh anneals); lightcycle_view.py (Lightcycle routing a board live in 3D at
127.0.0.1:8778 -- every net laid, ripped up and laid again, every
round's conflicts, from the search's own feed, router.solve's `watch`;
the PCBGolf viewer's scene); abstract_census.py (the board abstract's tokens
beside gnm's and the JSON wire's, the census's 60 boards and counter);
profile_build.py (where a build's seconds go: realise() in a scratch
cache with a timer on every stage, subprocess and request; `--cli`
for the whole command line; JSON under .cache/profile/);
jev.py (TypeSafe's Jev -- a closed-question model with a calibrated
probability, no generation -- asked three of the pipeline's own questions
against stored data: `verify` how a design handles each clause of its
prompt, `--inject` a clause it cannot carry; `resolve` which catalogue row
is the part asked for, the resolver's own rows, `--rule` with its policy
stated; `pins` which real pin a failed pin name meant; calls cached under
.cache/jev/, the key from TYPESAFE_API_KEY or .env);
datasheet_warm.py (the datasheet reader's warm-up: `scan` counts,
per LCSC code, the distinct boards in the bank that use it --
streamed out of the packed archive, PCBench and the reddit clones,
a part number mapped to its one code -- into
.cache/datasheet-warm/usage.json; `plan` ranks by those boards,
then JLCPCB's basic parts, then the stored designs and BOMs (the
user's projects too), keeps ICs and modules with a sheet link (the
full library's for a part out of stock), names each part's sources,
and calls nothing; `run --max-usd` reads them under a hard total,
skips any part with a record, and logs each read's cost; `find`
asks Exa for the maker's own PDF of a part whose catalogue copy is
a scan or a page, kept only when it names the part and its maker,
into .cache/datasheets/more_urls.json) and board_parts.py
(the codes and part numbers a board, schematic or BOM names: KiCad
6+ fields, KiCad 5 schematics, Eagle attributes, BOM columns);
datasheet_check.py (does the sheet close what the vendor's data
cannot: `fetch` every link for the parts the replay orders, with
the cost of pulling all 613k; `pins` the 20 stored pin-name
failures by the symbol, by the sheet, and by Jev given both;
`audit` every ordered symbol against its sheet, pin by pin);
the corpus and the board bank: azure_route.py (the bank routed on
rented machines, the verdicts merged home), azure_astar.py and
astar_relabel.py (the corpus labelled again by the A* router, each
example's stored placement kept, on rented machines or here, with
freerouting under the same judge as the control), azure_ab.py
(both routers on more seeds or new boards, rented), search_kicad.py
(.kicad_pcb files found by GitHub code search) and
fetch_open_schematics.py (the HuggingFace open-schematics boards
this pipeline can route);
what ships or is served: rubric_reference.py (the professional
reference in soldermask/assets/rubric.json), zener_blocks.py
(priors_zener.json from Diode's Zener modules), fetch_three.py
(three.js, pinned at r128, and its GLTFLoader into app/static/vendor/),
gnn_summary.py and mendicant_summary.py (`--write` the JSON the
/benchmarks page reads; no model trained), mcp_bench.py
(a drive through the MCP server written up as the evaluator's
results.json, for /benchmarks), paper_figures.py (paper/fig/ for
the Mendicant paper, every number read from .cache), film_capture.py,
record_film.py and record_phone.py (the PCBGolf film in tools/film/
and a live viewer, recorded as 9:16 video under .cache/phone/);
audits and controls: fab_check.py (stored builds against
fabrules.py, rule by rule), bom_value_audit.py (each designator's
value against the part its LCSC code names), sim_survey.py (the
simulation stage over every stored design, read-only), mcp_replay.py
(a drive's own designs built again through the MCP `build` with no
model: a re-run's control), datasheet_rules.py (the precision rules
for a reader's claims; datasheet_reader.py carries two of them) and
cypress_modal.py (NVlabs Cypress built and run on Modal's CUDA for
cypress_h2h.py);
parametric_index.py, rubric.py, isofont.py and appicon.py; service templates.
The other tools/*.py are single experiments: each one's question, run
and result are in the CHANGELOG's Unreleased log (grep its name),
and its own docstring says how to run it againThe pipeline is plain Python modules with no framework in them. workspace.realise() is the build sequence, and four callers use it and no copy of it: the app (app/turns.py), the command line (cli.py), the MCP server (mcp.py, and mcp_http.py through it) and the evaluator (evaluate.py). The CLI has since 11 Sep 2026; before that it ran its own copy and the two drifted four times. realise() hands back a Build, which unpacks to the five things a version stores and carries the placement, the copper, the report and the fill beside them for a caller that prints or checks more; tests/test_cli_build.py counts the calls. Anything that must hold for every board goes in realise() or in a function it calls, as verdict(), apply_constraints() and rubric.report() are.
Principles the code follows
Report, never hide. Every stage returns what it could not do, and that goes next to the result: gaps and notes on the netlist, unsupported from the model, the honest section on the command line, Advisories in the workbench. A silent except: continue is the thing to be most suspicious of in review.
Recall is not evidence. The model names functions and parts; pad numbers come from the symbol library, footprints from data, stock from the supplier. When something has to be borrowed — a pinout from a family, a footprint from a vendor — it is labelled assumed, not verified.
Check with something that did not make it. Gerbers are read back by gerbonara; the KiCad file is re-parsed and compared with the placement; with KiCad installed, its plot is compared with ours.
Measured, not chosen. Trace width, clearance, via size, decoupling values and block idioms come from a corpus of real boards; model orientation comes from the pads; the KiCad rotation sign was found by rendering all four and scoring them.
Repair must not launder. A dropped part costs more than an unresolved one, so deleting a problem never pays.
A model predicts; the oracle decides. The router orders the placements, not the model: where Lightcycle routes, tandem.rank routes every candidate and puts first the one that leaves fewest pins unreached, then least copper (since 26 Sep 2026, after the model's ranking of one board's own anneals measured at chance four times). The model's order is used only where Lightcycle cannot run or SOLDERMASK_TANDEM=0, and it never replaces the router. Its prediction is written beside the router's verdict on every board, a confident miss is said in words, and the route becomes the next training example. Whether the neural network beats the analytic baseline is a number in the model file, not an argument.
A wrong instrument is worse than none. The evaluator and the harness tests exist because two measurement faults have already cost real time.
Data is not code. projects/ is the user's work: immutable versions, atomic writes, migrations with backups, a trash instead of deletion, and it is not in git.
Conventions
- Python 3.11+, type hints, dataclasses, docstrings that say why. Modules explain their coordinate frame at the top when they have one (mm, origin bottom-left, y up — except KiCad, which is y down).
- Tests are plain scripts with a
check()helper and a finalN passed, M failedorn/m passedline;.venv/bin/python tests/run.pyruns them all (the barepythonmay not be the venv's, and the system Python has no numpy). - The front end is plain JavaScript with globals on purpose (
state,render,BOARD,scene2d), sotests/verify_3d.js,tests/verify_scene.pyandschematic.jscan reach it; no build step. - The copper view is a persistent scene: built once into
static/live/overlay, mutated afterwards, torn down only for a different board. A gesture writes one attribute; nothing readsgetBBoxorgetBoundingClientRectinside a move. - Files that another session or person may be editing are patched with exact-string replacements, not rewritten.