soldermaskdocs

Design (the model)

The design stage turns a prompt into a structured design: the parts, the nets and a board size. Everything after it builds from that design, and none of it knows which model wrote it.

A design has these parts. Every field is documented in design.json.

FieldWhat it holds
summaryOne line saying what the board is
boardA name, the width and height in mm, and size_asked when the prompt sets the size
componentsEach part: reference, kind, what to buy, package, value, purpose
netsWhich pins connect, with a voltage and a current for power nets
assumptionsWhat the model assumed that the prompt did not say
decisionsOpen design choices, each with two or three options and one recommended
unsupportedWhat the prompt asked for that the model could not carry

Four functions call the model:

  • design.generate(prompt) returns a design. The command line, the evaluator and the repair loop use it.
  • design.converse(prompt) is for a chat turn in the app. It returns the model's reply, plus a design only when the message changed the board. A question gets an answer and no rebuild.
  • design.revise(prompt) is for a change to a board the app already has. It returns the reply and a patch, not a whole design. A part the patch does not name stays on the board.
  • design.structured(prompt, schema, system) is one call that is not a design. The wiring turn (--wire) uses it, and so does reading a datasheet's pin table.

Backends

Claude Code (default)GeminiClaudeGroqMercury
Selectnothing, or SOLDERMASK_BACKEND=claude-code--backend gemini--backend claude--backend groqSOLDERMASK_BACKEND=mercury
CredentialsThe claude command line, logged inGEMINI_API_KEY or GOOGLE_API_KEYANTHROPIC_API_KEY, or a profile from ant auth loginGROQ_API_KEYINCEPTION_API_KEY
Default modelclaude-fable-5-2gemini-3.8-flashclaude-opus-5openai/gpt-oss-120bmercury-2.5
SchemaEnforced as written, plus lcsc on a partEnforced as writtenEnforced as writtenBounds relaxedEnforced unless the endpoint objects
Cost recordedTokens, billing, and list price apartTokensTokens, and cost at $5 / $25 per millionTokens, and cost at $0.15 / $0.75 per millionTokens, and cost at $0.04 / $0.15 per million
  • --model overrides the model id.
  • --effort sets Claude's effort (default high). Claude runs with adaptive thinking and 16,000 output tokens.
  • SILIXON_BACKEND still works in place of SOLDERMASK_BACKEND.

The Claude Code backend

The default backend runs Claude Code without a window, on the account it is logged into. A claude.ai plan pays for it, not an API key.

To set it up:

  1. Install Claude Code, so claude is on your PATH.
  2. Run claude once and log in with your claude.ai account.
  3. Start the app or run the command line as usual.

A design turn is a loop, not one call. The model can call three tools of the MCP server: search_parts, pins and check_design. It looks parts up, reads their real pin names, and checks the design before it answers. Each call shows as a line in the build log.

It gets nothing else from your machine. It runs in an empty folder. It loads no settings, hooks, plugins or CLAUDE.md, and has no shell or file access. Every other tool of the MCP server is refused.

A part can be pinned. Of the backends, only this one may set lcsc on a component, because only it can look a code up. A code that search_parts or pins did not return in the same turn is removed. The design's unsupported list names the part and the code. For an edit, the reply names them instead. A person or an MCP client can pin a part too (design.json).

A plan records no cost. The board records billing and list_usd, the list price of the same tokens. cost_usd stays empty, so a plan's turns never add up as money spent.

An API key is not used. The backend removes ANTHROPIC_API_KEY from its environment, so the claude.ai login is used. Use --backend claude to design on a key instead.

SettingDefaultWhat it sets
SOLDERMASK_CLAUDE_CODE_MODELclaude-fable-5-2The model it asks for
SOLDERMASK_CLAUDE_CODE_TIMEOUT_S900How long one turn may take, in seconds

A missing install or login is one line, not a traceback:

Claude Code is not installed here (no claude on PATH). Install it from https://claude.com/claude-code and log in with claude, or set SOLDERMASK_BACKEND=gemini.

Claude Code is not logged in. Run claude once and log in with your claude.ai account, or set SOLDERMASK_BACKEND=gemini.

The other backends name their missing key the same way.

A relaxed schema is reported. Groq's strict mode rejects minimum, maximum and minItems, so those limits become requests in the prompt. If Gemini or Mercury rejects a schema keyword, the call is retried without additionalProperties. Either way, the design's unsupported list says the schema was relaxed.

What the model is told

The system prompt sets these hard constraints:

  • Two copper layers, or four when the prompt asks. Four is read off the prompt into constraints.board.layers, so the design does not list it as unsupported. Any other count goes in unsupported. On four layers, the first inner layer is a ground plane and the other three carry signals. Ground is a copper pour on both outer layers, so a ground pin costs the router nothing.
  • The board size is a guess. The pipeline resizes the board to its parts once they are known. When the prompt sets the size, the model sets board.size_asked, and the board is never made smaller.
  • Only supported packages. Every part must use one of the supported packages, because those are the only footprints that exist.
  • Two-terminal parts use pins 1 and 2. A diode or an LED names its ends A and K instead. Most diodes number the cathode pad 1, so a number would name different ends to different readers.
  • ICs use pin function names, exactly as the datasheet writes them: VI, VO, GND, EN, SDA. Never pin numbers. Multi-unit parts qualify names as A.+, B.-.
  • Modules use FROM_PART. An ESP32, a radar or a GPS module is kind: "module" with package FROM_PART. Its footprint and pin names then come from the vendor's data for that exact part number.
  • Placement belongs to the pipeline, on both sides. When the front is full, surface-mount parts nobody has to reach go on the back. Connectors, switches, LEDs and modules stay on the front. A request for a one-sided board is honoured. A request for a part in a particular place goes in unsupported, naming constraints.pinned.
  • Prefer parts JLCPCB stocks as basic parts.
  • Decouple every IC, and give every power rail bulk capacitance.
  • Every power and ground net gets a voltage_v and a current_a. Use null for signal nets, and null when the load is unknown.

Pin 1 on an LED is a position, not a pad number. Vendors number LED pads differently, so resolve.py reads which pad the ordered part calls its anode and wires 1 to it. The design check warns when a diode's ends are given as numbers (diode-pins).

A pin function name can be checked against the part's symbol. A recalled pin number cannot, which is why ICs never use numbers.

The prompt also tells the model what the pipeline reports on its own, so it does not repeat it in unsupported:

  • A radio module's antenna gets a copper keepout on both layers, read from its footprint.
  • Where the ground pour cannot reach a pad, the pipeline stitches it or routes it, and says which.

Decisions. A prompt can leave a real fork open, such as battery or mains power. The model then lists two or three options in decisions and marks one recommended. It builds the recommended one, so there is always a board.

Unsupported. The unsupported list is published beside the board, word for word. It holds real limitations only, not hedges.

What is read off the prompt

The pipeline also reads the prompt itself. What it finds goes into the constraints, which the model cannot write.

The prompt asks forIt lands inSee
Four copper layersconstraints.board.layersFour layers
One side of partsconstraints.board.sidesBoth sides
A router by nameconstraints.rules.routerRouters
A compact or a roomy boardconstraints.board.sizeWhen the board is too big
Mounting holesconstraints.board.mounting_holesMounting holes

A prompt that asks for three or more layers gets four, and one that asks for one layer gets two. The build says so.

Priors

The prompt ends with block idioms measured from real open-hardware boards.

Block idioms. priors_blocks.json lists, for each IC symbol, the passives drawn within 40 mm of it and how often. An IC counts when it appears at least four times across at least two projects. mine_blocks.py builds the file from .kicad_sch files. The six most common blocks go into the system prompt, with their three most frequent companions each.

priors.py holds more numbers measured from real boards. They are not in the prompt.

PriorValueMeasured fromUsed for
Median trace width0.25 mm (10th percentile 0.171 mm)86,801 trace segments on 86 routed KiCad boardsThe placer's congestion estimate, and a fallback where no rule is set
Median clearance0.20 mmthe same boardsThe placer's congestion estimate, and a fallback where no rule is set
Median via0.60 mm pad, 0.30 mm drillthe same boardsThe via the routers place
Component mixcapacitors 24.8%, resistors 15.4%144 schematicsNothing reads it
Capacitors per IC5.1the same schematicsNothing reads it
Decoupling value100nF (bulk: 1uF)the same schematicsNothing reads it

The routers do not route at the median. Lightcycle and the A* router both route at 0.127 mm track and clearance. See Routers.

Current sets copper width. A net's current_a is the steady current in amps. electrical.py sizes the net's trace to it by IPC-2221. A null routes at the board's signal track: 0.127 mm, or a person's floor (constraints.rules.min_track_mm). That track carries about half an amp. So the schema asks for null rather than a guess, because a guess gets etched.

Copper too narrow for its declared current fails the verdict. See Copper too narrow for its current.

The schema

The design is checked against a narrow JSON schema. The model describes intent. It does not invent footprints, part numbers or pad geometry, because the pipeline resolves those against real data.

The most important field is search: what to buy. It is a manufacturer part number when the model is sure one exists, otherwise a short description of the part. It is searched against the parts catalogue. A search that finds nothing drops the part. The gaps list says so, and the board fails its verdict.

On this page