niko3x/kicadrouterai

KiCad Router AI

AI-powered PCB router for KiCad using Graph Neural Networks and Reinforcement Learning with FP8 precision.

Features

• 19 Tag-based constraints: Define routing rules in schematic (impedance, length matching, topology, EMI/EMC)
• GNN + PPO: Graph neural network encodes board state, PPO learns routing policy
• FP8 precision: Train on consumer GPUs (RTX 4060+ for most boards)
• Action masking: Tags create hard constraints - AI cannot violate them
• KiCad integration: Native plugin for PCBnew (coming soon)

Quick Start on Vast.ai

# 1. Clone from HuggingFace
git clone https://huggingface.co/niko3x/kicadrouterai
cd kicadrouterai

# 2. Run setup (installs KiCad, PyTorch, everything)
chmod +x setup_vastai.sh
./setup_vastai.sh

# 3. Train
source .venv/bin/activate
python train.py --timesteps 1000000

Local Development

# Clone
git clone https://huggingface.co/niko3x/kicadrouterai
cd kicadrouterai

# Create venv and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Install PyTorch (with CUDA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install torch-geometric stable-baselines3 gymnasium

# Run tests
pytest tests/ -v

Project Structure

kicadrouterai/
├── src/
│   ├── tags/           # 19 tag types with Pydantic schemas
│   │   ├── base.py     # Tag/TagType/TagPriority
│   │   ├── schemas.py  # All tag definitions
│   │   └── loader.py   # JSON loading, templates
│   ├── core/           # Constraint engine
│   │   ├── action_space.py    # Action encoding
│   │   ├── constraint_engine.py  # Action masking
│   │   └── board_graph.py     # GNN graph representation
│   ├── router/         # AI model
│   │   ├── model.py         # GNN with GAT layers
│   │   ├── environment.py   # Gym wrapper
│   │   ├── trainer.py       # FP8 PPO trainer
│   │   └── inference.py     # Production router
│   └── gui/            # KiCad plugin (TODO)
├── tests/              # Unit tests
├── examples/           # Example tag configs
├── train.py            # Training script
├── setup_vastai.sh     # Vast.ai setup
├── push_to_hf.sh       # Push to HuggingFace
└── clone_from_hf.sh    # Clone from HuggingFace

Tag Types

Category	Tags
Impedance	IMPEDANCE_SINGLE, IMPEDANCE_DIFF (differential pairs)
Topology	TOPOLOGY (FLY_BY for DDR, STAR, T_BRANCH)
Length	LENGTH_MATCH (serpentine tuning)
EMI/EMC	GROUND_RETURN, EDGE_CONTROL, CROSSTALK_CONTROL
Via	VIA_ADVANCED (layer pairs, stubs, back-drill)
Power	POWER_TRACK, DECOUPLING_HIERARCHY, SWITCHING_NODE
Thermal	THERMAL_MANAGEMENT (pad arrays, copper pour)
Special	CRYSTAL, ANTENNA_ZONE
Layout	PLACEMENT_LOCK, ROUTING_ZONE, FANOUT_PATTERN

GPU Requirements (FP8)

Phase	Complexity	VRAM	GPU
1	Simple (5-20 nets)	2 GB	RTX 3050
2	Medium (50-150 nets)	4 GB	RTX 4060
3	Complex (150-500 nets)	6 GB	RTX 4060 Ti
4	BGA/High-Speed (500+)	12-20 GB	RTX 4090

Training

# Basic training
python train.py --timesteps 100000

# With custom tags
python train.py --tags examples/example_tags.json --timesteps 500000

# Resume from checkpoint
python train.py --resume checkpoints/checkpoint_50000.pt

# Monitor with TensorBoard
tensorboard --logdir logs

HuggingFace Sync

# Push changes
./push_to_hf.sh

# Clone on new machine
./clone_from_hf.sh

License

MIT