PCB Agent v2

An advanced AI-powered PCB routing application with intelligent BOM processing, automated component type detection, and professional KiCad schematic generation.

Quick Start

Prerequisites

• Python 3.8 or higher
• Node.js 14.x or higher
• Ollama (optional, for local AI model deployment)

Backend Setup

cd backend

# Install Python dependencies
pip install fastapi uvicorn pandas openpyxl python-dotenv sqlalchemy

# Initialize component libraries (REQUIRED)
python scripts/initialize_libraries.py

# Start the development server
uvicorn app.main:app --host 0.0.0.0 --port 3010 --reload

Recommended: Use a conda environment for dependency isolation:

conda create -n pcb-agent python=3.9
conda activate pcb-agent
cd backend
pip install fastapi uvicorn pandas openpyxl python-dotenv sqlalchemy
uvicorn app.main:app --host 0.0.0.0 --port 3010 --reload

Frontend Setup

cd frontend
npm install
npm start

The application will be available at http://localhost:3000

AI Model Setup (Optional - Local Deployment)

For local AI-powered enhancements, install and configure Ollama:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve

# Pull the recommended model (requires ~64GB RAM)
ollama pull gpt-oss:120b

Note: The system operates in graceful fallback mode if AI models are unavailable.

AI Integration

PCB Agent v2 supports multiple AI integration options:

Primary Model:

• gpt-oss:120b (120 billion parameters)
• Optimized for technical and engineering tasks
• Requires ~64GB RAM for optimal performance

Cloud Integration:

• OpenRouter API support (Kimi-K2, GPT-4, etc.)
• No local hardware requirements
• API key configuration required

Features:

• Advanced component analysis and classification
• Intelligent schematic generation
• Circuit pattern recognition
• Automatic fallback to rule-based generation if AI unavailable

Key Features

BOM Processing:

• Multi-format support: CSV, Excel, JSON
• Automatic component type detection (25+ types)
• Robust parsing with encoding detection

Schematic Generation:

• Professional net label system
• KiCad 7.x format compatibility
• IEEE/IEC standard compliance
• Coordinate-free LLM integration

Component Management:

• Comprehensive KiCad symbol library integration
• Pin position calculation (±0.01mm precision)
• Rotation and transformation support
• Component metadata system

Connection Wizard:

• Natural language connection input
• AI-assisted electrical connection definition
• Base schematic preservation
• Multi-step enhancement workflow

API Endpoints

Primary Production Endpoints

POST /api/v1/bom/convert-with-labels

• Professional schematic generation with net labels
• Primary endpoint for production use
• Returns KiCad .kicad_sch format

POST /api/v1/bom/parse

• BOM file analysis and component detection
• Returns component list with types and metadata

GET /api/v1/bom/llm-status

• AI service status and model availability
• Returns available models and connection status

Connection Wizard Endpoints (Enhanced Workflow)

POST /api/v1/bom/convert-with-labels?enable_wizard=true

• Generate base schematic
• Returns wizard_session_id for enhancement

POST /api/v1/wizard/enhance/{session_id}

• Enhance base schematic with user-defined connections
• Preserves all existing components
• AI-powered connection interpretation

Architecture

Backend (Python/FastAPI):

• FastAPI 0.104.1 for REST API
• pandas 2.0.3 for BOM processing
• SQLite for component library management
• Ollama integration for local AI models
• OpenRouter integration for cloud AI models

Frontend (React/TypeScript):

• React 19.1.0
• TypeScript 4.9.5
• HTML5 Canvas for visualization
• Three.js for 3D PCB rendering

Infrastructure:

• Docker Compose support
• PostgreSQL (production)
• Redis (caching)
• Nginx (reverse proxy)

Development

Running Tests

The project includes an organized test suite:

cd backend

# Run all tests
./tests/run_all_tests.sh

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/validation/
pytest tests/benchmarks/

Project Structure

PCB_Agent.v2/
├── backend/
│   ├── app/
│   │   ├── api/routes/      # API endpoints
│   │   ├── services/        # Business logic
│   │   ├── utils/           # Utility functions
│   │   └── middleware/      # Request/response middleware
│   ├── data/                # KiCad libraries
│   ├── scripts/             # Utility scripts
│   └── tests/               # Test suite
│       ├── unit/            # Unit tests
│       ├── integration/     # Integration tests
│       ├── validation/      # Validation tests
│       └── benchmarks/      # Performance benchmarks
├── frontend/
│   └── src/
│       ├── components/      # React components
│       ├── services/        # API services
│       └── utils/           # Frontend utilities
└── README.md

System Requirements

Minimum:

• 8GB RAM (rule-based generation only)
• 4 CPU cores
• 10GB disk space

Recommended (with AI):

• 64GB RAM (for gpt-oss:120b model)
• 8+ CPU cores
• 50GB disk space

Cloud Alternative:

• 4GB RAM (using OpenRouter API)
• 2 CPU cores
• 10GB disk space
• OpenRouter API key

Environment Configuration

Create a .env file in the backend directory:

# Optional: OpenRouter API (cloud AI)
OPENROUTER_API_KEY=your_api_key_here

# Optional: LangSmith tracing
LANGSMITH_API_KEY=your_api_key_here
LANGSMITH_PROJECT=pcb-agent

# Optional: Supabase (for connection wizard storage)
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key

Troubleshooting

Library Initialization Error:

python backend/scripts/initialize_libraries.py

Port Conflicts:

# Kill processes on occupied ports
lsof -ti:3010 | xargs kill -9  # Backend
lsof -ti:3000 | xargs kill -9  # Frontend

Ollama Connection Issues:

# Verify Ollama is running
curl http://localhost:11434/api/tags

# Restart Ollama service
ollama serve

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please ensure:

• All tests pass before submitting
• Code follows existing style conventions
• Documentation is updated for new features
• Commit messages are descriptive

Support

For issues, questions, or feature requests, please open an issue in the repository.