circuitron: Instructions file for Codex

Instructions for working on Circuitron

Circuitron is an AI-powered PCB design accelerator that converts natural language requirements into SKiDL scripts, KiCad schematics, and PCB layouts using a multi-agent orchestration pipeline.

Architecture Overview

Core Pipeline Flow

The system follows a sophisticated, multi-stage agent workflow defined in circuitron/pipeline.py. It is not a simple linear sequence but includes robust, nested correction loops.

1. Planner → Plan Editor (optional user feedback loop)
2. Part Finder → Part Selector
3. Documentation Agent (gathers context via RAG)
4. Code Generator
5. Validation & Correction Loop:
   • The Validator agent checks the generated code.
   • If validation fails, the Corrector agent attempts to fix it. This loop continues until the code is valid or a retry limit is reached.
6. Runtime Check & Correction Loop:
   • A runtime check is performed in a Docker container.
   • If it fails, the Runtime Corrector agent attempts a fix. This loop continues until the script runs successfully.
7. ERC (Electrical Rule Check) & Handling Loop:
   • The ERC Handler agent runs ERC checks.
   • If errors or unapproved warnings are found, it attempts to fix them. This loop continues until ERC passes or warnings are explicitly accepted by the agent.
8. Final Execution: The final, validated script is executed to produce KiCad files.

Each agent has specific responsibilities and uses the OpenAI Agents SDK with structured Pydantic models defined in circuitron/models.py.

Key Components

• Agents (circuitron/agents.py): Specialized OpenAI agents for each pipeline stage.
• MCP Server (circuitron/mcp_manager.py): A single, shared connection for RAG documentation, code validation, and hallucination detection.
• Tools (circuitron/tools.py): Docker-isolated functions for calculations, KiCad library searches, and ERC checks.
• UI (circuitron/ui/app.py): A Rich-based terminal interface for progress tracking and interactive plan editing.