bretbouchard/kicad-agent-pcb-adapter

kicad-agent PCB Reasoning Adapter

LoRA adapter for Qwen/Qwen2.5-0.5B-Instruct, fine-tuned for PCB spatial reasoning analysis. Part of kicad-agent.

What it does

Generates structured PCB board analysis with coordinate-grounded <point x,y> tags:

• Component identification and positioning
• Net connectivity analysis
• Spatial distribution assessment
• Routing quality evaluation

Quick Start

# Install kicad-agent (adapters auto-download from this repo on first use)
pip install kicad-agent

# Analyze any KiCad file — runs locally, no API key needed
kicad-agent analyze board.kicad_pcb

Output:

Board analysis: 85 components across 62 nets on 4-layer PCB.
Key components (8 of 85): U1 (ATmega328P) at <point 126.7,41.9>; R1 (10k) at <point 118.1,66.1>...
Connectivity: 62 nets with 140 connections.
Spatial distribution: medium complexity board...

Training

Stage	Method	Samples	Loss
SFT	Supervised fine-tuning	6,696	2.20 -> 0.69
GRPO	Rejection sampling (ReST)	200/gen round	0.46 -> 0.28

Training data: 7,441 ChatML samples from real KiCad projects, electronics design textbooks (Douglas Self), component databases, and gold-standard routing analysis. Quality-filtered by a custom neural reward model (75% discrimination rate between correct and corrupted chains).

One of the training sources is DeepSeek's spatial reasoning paper — the methodology paper that describes how to train models for coordinate-grounded reasoning. Training the model on the paper about training the model. Turtles all the way down.

Usage with mlx-lm

from mlx_lm import load, generate

# Load with SFT adapter
model, tokenizer = load("Qwen/Qwen2.5-0.5B-Instruct", adapter_path="bretbouchard/kicad-agent-pcb-adapter/sft")

# Load with GRPO adapter (best quality)
model, tokenizer = load("Qwen/Qwen2.5-0.5B-Instruct", adapter_path="bretbouchard/kicad-agent-pcb-adapter/grpo")

# Generate PCB analysis
prompt = (
    "<|im_start|>system\nYou are a PCB design expert.<|im_end|>\n"
    "<|im_start|>user\nAnalyze this PCB: 85 components, 62 nets, 4 layers, 101.5x53.3mm.<|im_end|>\n"
    "<|im_start|>assistant\n"
)
response = generate(model, tokenizer, prompt=prompt, max_tokens=512)
print(response)

Usage with kicad-agent Python API

from kicad_agent.llm.local_client import LocalLLMClient

# Auto-downloads adapter from this HF repo on first use
client = LocalLLMClient()

# Analyze a board
analysis = client.analyze_board(
    board_name="my-board", n_components=85, n_nets=62,
    n_layers=4, width_mm=101.52, height_mm=53.34,
)
print(analysis)

Files

• sft/adapters.safetensors — SFT LoRA weights (rank=16, 16 layers)
• sft/adapter_config.json — LoRA configuration
• grpo/adapters.safetensors — GRPO ReST LoRA weights (recommended)
• grpo/adapter_config.json — LoRA configuration

Requirements

• mlx-lm >= 0.21
• Apple Silicon Mac (M1+)
• For auto-download: huggingface_hub package

Part of kicad-agent — structural editing of KiCad files where the model never directly edits source files.