circuit_synth

Name	circuit_synth JSON
Version	0.9.1 JSON
	download
home_page	None
Summary	Pythonic circuit design for production-ready KiCad projects
upload_time	2025-10-12 21:02:34
maintainer	None
docs_url	None
author	None
requires_python	>=3.12
license	None
keywords	circuit design kicad electronics pcb schematic
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # circuit-synth

**Python-based circuit design with KiCad integration and AI acceleration.**

Generate professional KiCad projects from Python code with hierarchical design, version control, and automated documentation.

## 🚀 First Time User? Start Here!

**Complete working example in 3 minutes:**

```bash
# 1. Install circuit-synth
pip install circuit-synth

# 2. Create a new project with working example
uv run cs-new-project my_first_board

# 3. Generate KiCad files from the example
cd my_first_board/circuit-synth
uv run python example_project/circuit-synth/main.py

# 4. Open in KiCad (generated in ESP32_C6_Dev_Board/)
open ESP32_C6_Dev_Board/ESP32_C6_Dev_Board.kicad_pro
```

**That's it!** You now have a complete ESP32-C6 development board schematic and PCB.

**What you just created:**
- ✅ ESP32-C6 microcontroller with proper power connections
- ✅ USB-C connector with CC resistors
- ✅ 3.3V voltage regulator
- ✅ LED with current-limiting resistor
- ✅ Complete KiCad project ready to edit/manufacture

**Next steps:**
- Modify `example_project/circuit-synth/main.py` to customize your circuit
- Re-run `uv run python example_project/circuit-synth/main.py` to regenerate KiCad files
- Open KiCad to view/edit your schematic and PCB layout

## Installation

```bash
# Install with uv (recommended)
uv add circuit-synth

# Or with pip
pip install circuit-synth
```

## Configuration

### Logging Control

By default, circuit-synth runs with minimal logging output (WARNING level). To enable detailed logs for debugging:

```bash
# Enable verbose logging via environment variable
export CIRCUIT_SYNTH_LOG_LEVEL=INFO

# Or set it in your Python script
import os
os.environ['CIRCUIT_SYNTH_LOG_LEVEL'] = 'INFO'
```

Available log levels:
- `ERROR`: Only show errors
- `WARNING`: Show warnings and errors (default)
- `INFO`: Show informational messages, progress updates
- `DEBUG`: Show detailed debugging information

## Quick Start

```bash
# Create new project with example circuit
uv run cs-new-project

# This generates a complete ESP32-C6 development board
cd circuit-synth && uv run python example_project/circuit-synth/main.py
```

## Example: Power Supply Circuit

```python
from circuit_synth import *

@circuit(name="Power_Supply")
def power_supply(vbus_in, vcc_3v3_out, gnd):
    """5V to 3.3V power regulation subcircuit"""
    
    # Components with KiCad integration
    regulator = Component(
        symbol="Regulator_Linear:AMS1117-3.3", 
        ref="U",
        footprint="Package_TO_SOT_SMD:SOT-223-3_TabPin2"
    )
    
    # Input/output capacitors
    cap_in = Component(symbol="Device:C", ref="C", value="10uF",
                      footprint="Capacitor_SMD:C_0805_2012Metric")
    cap_out = Component(symbol="Device:C", ref="C", value="22uF",
                       footprint="Capacitor_SMD:C_0805_2012Metric")
    
    # Explicit connections
    regulator["VI"] += vbus_in    # Input pin
    regulator["VO"] += vcc_3v3_out # Output pin
    regulator["GND"] += gnd
    
    cap_in[1] += vbus_in
    cap_in[2] += gnd
    cap_out[1] += vcc_3v3_out
    cap_out[2] += gnd

@circuit(name="Main_Circuit")
def main_circuit():
    """Complete circuit with hierarchical design"""
    
    # Create shared nets
    vbus = Net('VBUS')
    vcc_3v3 = Net('VCC_3V3')
    gnd = Net('GND')
    
    # Use the power supply subcircuit
    power_circuit = power_supply(vbus, vcc_3v3, gnd)

# Generate KiCad project
if __name__ == "__main__":
    circuit = main_circuit()
    circuit.generate_kicad_project("my_board")
```

## Core Features

- **Professional KiCad Output**: Generate .kicad_pro, .kicad_sch, .kicad_pcb files with modern kicad-sch-api integration
- **Hierarchical Design**: Modular subcircuits like software modules  
- **Atomic KiCad Operations**: Add/remove individual components from existing schematics with rollback safety
- **Modern KiCad Integration**: Uses PyPI kicad-sch-api (v0.1.1+) for professional schematic generation
- **Component Intelligence**: JLCPCB & DigiKey integration, symbol/footprint verification
- **Fast JLCPCB Search**: Direct search with 80% speed improvement, 90% less tokens
- **AI Integration**: Claude Code agents for automated design assistance
- **Circuit Debugging**: AI-powered PCB troubleshooting with systematic fault-finding
- **FMEA Analysis**: Comprehensive reliability analysis with physics-based failure models
- **Test Generation**: Automated test plans for validation
- **Version Control**: Git-friendly text-based circuit definitions

## KiCad-sch-api Integration

Circuit-synth integrates with the modern **kicad-sch-api** PyPI package - a valuable standalone tool that was extracted from circuit-synth for broader community use.

### Benefits of kicad-sch-api
- **Professional KiCad Files**: Generates industry-standard .kicad_sch files with proper formatting
- **Symbol Library Integration**: Full access to KiCad's extensive symbol libraries  
- **Hierarchical Support**: Clean handling of complex multi-sheet designs
- **Version Compatibility**: Works with modern KiCad versions (v7.0+)

### Hybrid Architecture
Circuit-synth uses a hybrid approach combining the best of both worlds:
- **Legacy System**: Handles component positioning and hierarchical structure
- **Modern API**: Professional schematic file writing via kicad-sch-api
- **Intelligent Selection**: Automatically chooses the right approach per schematic type

```python
# The modern API integration is automatic - just use circuit-synth as normal!
@circuit(name="MyCircuit")
def my_design():
    # Your circuit design here
    pass

# Behind the scenes: circuit-synth + kicad-sch-api = professional results
```

### Standalone kicad-sch-api Usage
The kicad-sch-api package is also valuable as a standalone tool for Python KiCad integration:

```bash
pip install kicad-sch-api
```

Visit the [kicad-sch-api repository](https://github.com/circuit-synth/kicad-sch-api) for standalone usage examples.

## AI-Powered Design

### Claude Code Commands

```bash
# Component search
/find-symbol STM32                    # Search KiCad symbols
/find-footprint LQFP64                # Find footprints
/find-parts "STM32F407" --source jlcpcb   # Check JLCPCB availability
/find-stm32 "3 SPIs, USB"             # STM32-specific search

# Circuit generation
/generate-validated-circuit "ESP32 IoT sensor" mcu

# Fast JLCPCB CLI (no agents, 80% faster)
jlc-fast search STM32G4               # Direct search
jlc-fast cheapest "10uF 0805"         # Find cheapest option
```

### 🤖 AI Assistance

When using Claude Code, you can ask for help with:

- **Component Selection**: "Find me a 3.3V regulator available on JLCPCB"
- **Circuit Design**: "Design a USB-C power supply with protection"
- **KiCad Integration**: "What footprint should I use for LQFP-48?"
- **Troubleshooting**: "My board isn't powering on - help debug"
- **SPICE Simulation**: "Simulate this amplifier circuit"
- **Test Planning**: "Generate test procedures for my power supply"

The AI agents will automatically select the right tools and expertise for your request.

## 🚀 Commands

### Project Creation
```bash
cs-new-project              # Complete project setup with ESP32-C6 example
```

### Circuit Generation
```bash
cd circuit-synth && uv run python example_project/circuit-synth/main.py    # Generate KiCad files from Python code
```

### Available Commands

```bash
# Component Search
/find-symbol STM32              # Search KiCad symbols
/find-footprint LQFP64          # Find footprints
/find-parts "STM32F407" --source jlcpcb   # Check availability
/find-stm32 "3 SPIs, USB"       # STM32-specific search

# Circuit Generation
/generate-validated-circuit "ESP32 IoT sensor" mcu
/validate-existing-circuit      # Validate circuit code

# Fast JLCPCB CLI
jlc-fast search STM32G4         # Direct search
jlc-fast cheapest "10uF 0805"   # Find cheapest option

# FMEA Analysis
/analyze-fmea my_circuit.py     # Run reliability analysis
```

## ⚡ Atomic KiCad Operations

Circuit-synth provides atomic operations for surgical modifications to existing KiCad schematics, enabling incremental updates without regenerating entire projects:

### Production API

```python
from circuit_synth.kicad.atomic_integration import AtomicKiCadIntegration, migrate_circuit_to_atomic

# Initialize atomic integration for a KiCad project
atomic = AtomicKiCadIntegration("/path/to/project")

# Add components using atomic operations
atomic.add_component_atomic("main", {
    'symbol': 'Device:R',
    'ref': 'R1',
    'value': '10k',
    'footprint': 'Resistor_SMD:R_0603_1608Metric',
    'position': (100, 80)
})

# Remove components
atomic.remove_component_atomic("main", "R1")

# Fix hierarchical main schematics with sheet references
subcircuits = [
    {"name": "USB_Port", "filename": "USB_Port.kicad_sch", "position": (35, 35), "size": (43, 25)},
    {"name": "Power_Supply", "filename": "Power_Supply.kicad_sch", "position": (95, 35), "size": (44, 20)}
]
atomic.fix_hierarchical_main_schematic(subcircuits)

# Migrate JSON netlist to KiCad using atomic operations
migrate_circuit_to_atomic("circuit.json", "output_project/")
```

### Key Benefits

- **True Atomic Operations**: Add/remove individual components with rollback safety
- **Hierarchical Sheet Management**: Fixes blank main schematics automatically
- **Production Integration**: Seamless integration with existing circuit-synth pipeline  
- **S-Expression Safety**: Proper parsing with backup/restore on failure
- **JSON Pipeline Integration**: Full compatibility with circuit-synth JSON format

### Use Cases

- **Incremental Updates**: Add components to existing designs without full regeneration
- **Debug and Fix**: Resolve blank schematic issues (like ESP32-C6 project)
- **External Integration**: Third-party tools can manipulate circuit-synth schematics
- **Advanced Workflows**: Power users building custom automation

## FMEA and Quality Assurance

Circuit-synth includes comprehensive failure analysis capabilities to ensure your designs are reliable:

### Automated FMEA Analysis

```python
from circuit_synth.quality_assurance import EnhancedFMEAAnalyzer
from circuit_synth.quality_assurance import ComprehensiveFMEAReportGenerator

# Analyze your circuit for failures
analyzer = EnhancedFMEAAnalyzer()
circuit_context = {
    'environment': 'industrial',    # Set operating environment
    'safety_critical': True,        # Affects severity ratings
    'production_volume': 'high'     # Influences detection ratings
}

# Generate comprehensive PDF report (50+ pages)
generator = ComprehensiveFMEAReportGenerator("My Project")
report_path = generator.generate_comprehensive_report(
    analysis_results,
    output_path="FMEA_Report.pdf"
)
```

### What Gets Analyzed

- **300+ Failure Modes**: Component failures, solder joints, environmental stress
- **Physics-Based Models**: Arrhenius, Coffin-Manson, Black's equation
- **IPC Class 3 Compliance**: High-reliability assembly standards
- **Risk Assessment**: RPN (Risk Priority Number) calculations
- **Mitigation Strategies**: Specific recommendations for each failure mode

### Command Line FMEA

```bash
# Quick FMEA analysis
uv run python -m circuit_synth.tools.quality_assurance.fmea_cli my_circuit.py

# Specify output file
uv run python -m circuit_synth.tools.quality_assurance.fmea_cli my_circuit.py -o FMEA_Report.pdf

# Analyze with custom threshold
uv run python -m circuit_synth.tools.quality_assurance.fmea_cli my_circuit.py --threshold 150
```

See [FMEA Guide](docs/FMEA_GUIDE.md) for detailed documentation.

## Library Sourcing System

Hybrid component discovery across multiple sources with automatic fallback:

### Setup
```bash
cs-library-setup                    # Show configuration status
cs-setup-snapeda-api YOUR_KEY       # Optional: SnapEDA API access  
cs-setup-digikey-api KEY CLIENT_ID  # Optional: DigiKey API access
```

### Usage
Enhanced `/find-symbol` and `/find-footprint` commands automatically search:
1. **Local KiCad** (user installation)
2. **DigiKey GitHub** (150 curated libraries, auto-converted)
3. **SnapEDA API** (millions of components)
4. **DigiKey API** (supplier validation)

Results show source tags: `[Local]`, `[DigiKey GitHub]`, `[SnapEDA]`, `[DigiKey API]`

## Fast JLCPCB Component Search

The optimized search API provides direct JLCPCB component lookup without agent overhead:

### Python API

```python
from circuit_synth.manufacturing.jlcpcb import fast_jlc_search, find_cheapest_jlc

# Fast search with filtering
results = fast_jlc_search("STM32G4", min_stock=100, max_results=5)
for r in results:
    print(f"{r.part_number}: {r.description} (${r.price}, stock: {r.stock})")

# Find cheapest option
cheapest = find_cheapest_jlc("0.1uF 0603", min_stock=1000)
print(f"Cheapest: {cheapest.part_number} at ${cheapest.price}")
```

### CLI Usage

```bash
# Search components
jlc-fast search "USB-C connector" --min-stock 500

# Find cheapest with stock
jlc-fast cheapest "10k resistor" --min-stock 10000

# Performance benchmark
jlc-fast benchmark
```

### Performance Improvements

- **80% faster**: ~0.5s vs ~30s with agent-based search
- **90% less tokens**: 0 LLM tokens vs ~500 per search
- **Intelligent caching**: Avoid repeated API calls
- **Batch operations**: Search multiple components efficiently

## Project Structure

```
my_circuit_project/
├── example_project/
│   ├── circuit-synth/
│   │   ├── main.py              # ESP32-C6 dev board (hierarchical)
│   │   ├── power_supply.py      # 5V→3.3V regulation
│   │   ├── usb.py               # USB-C with CC resistors
│   │   ├── esp32c6.py           # ESP32-C6 microcontroller
│   │   └── led_blinker.py       # Status LED control
│   └── ESP32_C6_Dev_Board/      # Generated KiCad files
│       ├── ESP32_C6_Dev_Board.kicad_pro
│       ├── ESP32_C6_Dev_Board.kicad_sch
│       ├── ESP32_C6_Dev_Board.kicad_pcb
│       └── ESP32_C6_Dev_Board.net
├── README.md                # Project guide
├── CLAUDE.md                # AI assistant instructions
└── pyproject.toml           # Project dependencies
```


## Why Circuit-Synth?

| Traditional EE Workflow | With Circuit-Synth |
|-------------------------|-------------------|
| Manual component placement | `python example_project/circuit-synth/main.py` → Complete project |
| Hunt through symbol libraries | Verified components with JLCPCB & DigiKey availability |
| Visual net verification | Explicit Python connections |
| GUI-based editing | Version-controlled Python files |
| Copy-paste patterns | Reusable circuit functions |
| Manual FMEA documentation | Automated 50+ page reliability analysis |

## Resources

- [Documentation](https://docs.circuit-synth.com)
- [Examples](https://github.com/circuit-synth/examples)
- [Contributing](CONTRIBUTING.md)

## Development Setup

```bash
# Clone and install
git clone https://github.com/circuit-synth/circuit-synth.git
cd circuit-synth
uv sync

# Run tests
uv run pytest

# Optional: Register Claude Code agents
uv run register-agents
```


For 6x performance improvement:

```bash

# Build modules

# Test integration
```

## Testing

```bash
# Run comprehensive tests
./tools/testing/run_full_regression_tests.py

# Python tests only
uv run pytest --cov=circuit_synth

# Pre-release regression test
./tools/testing/run_full_regression_tests.py

# Code quality
black src/ && isort src/ && flake8 src/ && mypy src/
```

## KiCad Requirements

KiCad 8.0+ required:

```bash
# macOS
brew install kicad

# Linux
sudo apt install kicad

# Windows
# Download from kicad.org
```

## Troubleshooting

Install the AI-powered KiCad plugin for direct Claude Code integration:

```bash
# Install KiCad plugins
uv run cs-setup-kicad-plugins
```

**Usage:**
- **PCB Editor**: Tools → External Plugins → "Circuit-Synth AI"  
- **Schematic Editor**: Tools → Generate BOM → "Circuit-Synth AI"

## 🛠️ Advanced Configuration

### Environment Variables

```bash
# Optional performance settings
export CIRCUIT_SYNTH_PARALLEL_PROCESSING=true

# KiCad path override (if needed)
export KICAD_SYMBOL_DIR="/custom/path/to/symbols"
export KICAD_FOOTPRINT_DIR="/custom/path/to/footprints"
```

### Component Database Configuration

```bash
# JLCPCB API configuration (optional)
export JLCPCB_API_KEY="your_api_key"
export JLCPCB_CACHE_DURATION=3600  # Cache for 1 hour

# DigiKey API configuration (optional, for component search)
export DIGIKEY_CLIENT_ID="your_client_id"
export DIGIKEY_CLIENT_SECRET="your_client_secret"
# Or run: python -m circuit_synth.manufacturing.digikey.config_manager
```

## 🔍 Component Sourcing

circuit-synth provides integrated access to multiple component distributors for real-time availability, pricing, and specifications.

### Unified Multi-Source Search (Recommended)
Search across all suppliers with one interface:
```python
from circuit_synth.manufacturing import find_parts

# Search all suppliers
results = find_parts("0.1uF 0603 X7R", sources="all")

# Search specific supplier
jlc_results = find_parts("STM32F407", sources="jlcpcb")
dk_results = find_parts("LM358", sources="digikey")

# Compare across suppliers
comparison = find_parts("3.3V regulator", sources="all", compare=True)
print(comparison)  # Shows price/availability comparison table

# Filter by requirements
high_stock = find_parts("10k resistor", min_stock=10000, max_price=0.10)
```

### JLCPCB Integration
Best for PCB assembly and production:
```python
from circuit_synth.manufacturing.jlcpcb import search_jlc_components_web

# Find components available for assembly
results = search_jlc_components_web("STM32F407", max_results=10)
```

### DigiKey Integration  
Best for prototyping and wide selection:
```python
from circuit_synth.manufacturing.digikey import search_digikey_components

# Search DigiKey's 8M+ component catalog
results = search_digikey_components("0.1uF 0603 X7R", max_results=10)

# Get detailed pricing and alternatives
from circuit_synth.manufacturing.digikey import DigiKeyComponentSearch
searcher = DigiKeyComponentSearch()
component = searcher.get_component_details("399-1096-1-ND")
alternatives = searcher.find_alternatives(component, max_results=5)
```

### DigiKey Setup
```bash
# Interactive configuration
python -m circuit_synth.manufacturing.digikey.config_manager

# Test connection
python -m circuit_synth.manufacturing.digikey.test_connection
```

See [docs/DIGIKEY_SETUP.md](docs/DIGIKEY_SETUP.md) for detailed setup instructions.

### Multi-Source Strategy
- **Prototyping**: Use DigiKey for fast delivery and no minimums
- **Small Batch**: Compare JLCPCB vs DigiKey for best value
- **Production**: Optimize with JLCPCB for integrated assembly
- **Risk Mitigation**: Maintain alternatives from multiple sources

## 🐛 Troubleshooting

### Common Issues

**KiCad Symbol/Footprint Not Found:**
```bash
# Verify KiCad installation
kicad-cli version

# Search for components (with Claude Code)
/find-symbol STM32
/find-footprint LQFP64
```

**Build Issues:**
```bash
# Clean rebuild
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## 🏗️ Architecture Overview

### Technical Stack
- **Frontend**: Python 3.9+ with type hints
- **KiCad Integration**: Direct file format support (.kicad_pro, .kicad_sch, .kicad_pcb)
- **AI Integration**: Claude Code agents with specialized circuit design expertise

### File Structure
```
circuit-synth/
├── src/circuit_synth/           # Python package
│   ├── core/                    # Core circuit representation
│   ├── kicad/                   # KiCad file I/O
│   ├── component_info/          # Component databases
│   ├── manufacturing/           # JLCPCB, DigiKey, etc.
│   └── simulation/              # SPICE integration
├── example_project/             # Complete usage example
├── tests/                       # Test suites
└── tools/                       # Development and build tools (organized by category)
```

## 🤝 Contributing

### Development Workflow
1. **Fork repository** and create feature branch
2. **Follow coding standards** (black, isort, mypy)
3. **Add tests** for new functionality
4. **Update documentation** as needed
5. **Submit pull request** with clear description

### Coding Standards
- **Python**: Type hints, dataclasses, SOLID principles
- **Documentation**: Clear docstrings and inline comments
- **Testing**: Comprehensive test coverage for new features

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

**Professional PCB Design with Python**

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "circuit_synth",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": null,
    "keywords": "circuit, design, kicad, electronics, pcb, schematic",
    "author": null,
    "author_email": "Circuit Synth Contributors <contact@circuitsynth.com>",
    "download_url": "https://files.pythonhosted.org/packages/fd/21/7cc11a8899a7fc3a4ae3bf387c015e789edcb330d21c77bee6f21a669989/circuit_synth-0.9.1.tar.gz",
    "platform": null,
    "description": "# circuit-synth\n\n**Python-based circuit design with KiCad integration and AI acceleration.**\n\nGenerate professional KiCad projects from Python code with hierarchical design, version control, and automated documentation.\n\n## \ud83d\ude80 First Time User? Start Here!\n\n**Complete working example in 3 minutes:**\n\n```bash\n# 1. Install circuit-synth\npip install circuit-synth\n\n# 2. Create a new project with working example\nuv run cs-new-project my_first_board\n\n# 3. Generate KiCad files from the example\ncd my_first_board/circuit-synth\nuv run python example_project/circuit-synth/main.py\n\n# 4. Open in KiCad (generated in ESP32_C6_Dev_Board/)\nopen ESP32_C6_Dev_Board/ESP32_C6_Dev_Board.kicad_pro\n```\n\n**That's it!** You now have a complete ESP32-C6 development board schematic and PCB.\n\n**What you just created:**\n- \u2705 ESP32-C6 microcontroller with proper power connections\n- \u2705 USB-C connector with CC resistors\n- \u2705 3.3V voltage regulator\n- \u2705 LED with current-limiting resistor\n- \u2705 Complete KiCad project ready to edit/manufacture\n\n**Next steps:**\n- Modify `example_project/circuit-synth/main.py` to customize your circuit\n- Re-run `uv run python example_project/circuit-synth/main.py` to regenerate KiCad files\n- Open KiCad to view/edit your schematic and PCB layout\n\n## Installation\n\n```bash\n# Install with uv (recommended)\nuv add circuit-synth\n\n# Or with pip\npip install circuit-synth\n```\n\n## Configuration\n\n### Logging Control\n\nBy default, circuit-synth runs with minimal logging output (WARNING level). To enable detailed logs for debugging:\n\n```bash\n# Enable verbose logging via environment variable\nexport CIRCUIT_SYNTH_LOG_LEVEL=INFO\n\n# Or set it in your Python script\nimport os\nos.environ['CIRCUIT_SYNTH_LOG_LEVEL'] = 'INFO'\n```\n\nAvailable log levels:\n- `ERROR`: Only show errors\n- `WARNING`: Show warnings and errors (default)\n- `INFO`: Show informational messages, progress updates\n- `DEBUG`: Show detailed debugging information\n\n## Quick Start\n\n```bash\n# Create new project with example circuit\nuv run cs-new-project\n\n# This generates a complete ESP32-C6 development board\ncd circuit-synth && uv run python example_project/circuit-synth/main.py\n```\n\n## Example: Power Supply Circuit\n\n```python\nfrom circuit_synth import *\n\n@circuit(name=\"Power_Supply\")\ndef power_supply(vbus_in, vcc_3v3_out, gnd):\n    \"\"\"5V to 3.3V power regulation subcircuit\"\"\"\n    \n    # Components with KiCad integration\n    regulator = Component(\n        symbol=\"Regulator_Linear:AMS1117-3.3\", \n        ref=\"U\",\n        footprint=\"Package_TO_SOT_SMD:SOT-223-3_TabPin2\"\n    )\n    \n    # Input/output capacitors\n    cap_in = Component(symbol=\"Device:C\", ref=\"C\", value=\"10uF\",\n                      footprint=\"Capacitor_SMD:C_0805_2012Metric\")\n    cap_out = Component(symbol=\"Device:C\", ref=\"C\", value=\"22uF\",\n                       footprint=\"Capacitor_SMD:C_0805_2012Metric\")\n    \n    # Explicit connections\n    regulator[\"VI\"] += vbus_in    # Input pin\n    regulator[\"VO\"] += vcc_3v3_out # Output pin\n    regulator[\"GND\"] += gnd\n    \n    cap_in[1] += vbus_in\n    cap_in[2] += gnd\n    cap_out[1] += vcc_3v3_out\n    cap_out[2] += gnd\n\n@circuit(name=\"Main_Circuit\")\ndef main_circuit():\n    \"\"\"Complete circuit with hierarchical design\"\"\"\n    \n    # Create shared nets\n    vbus = Net('VBUS')\n    vcc_3v3 = Net('VCC_3V3')\n    gnd = Net('GND')\n    \n    # Use the power supply subcircuit\n    power_circuit = power_supply(vbus, vcc_3v3, gnd)\n\n# Generate KiCad project\nif __name__ == \"__main__\":\n    circuit = main_circuit()\n    circuit.generate_kicad_project(\"my_board\")\n```\n\n## Core Features\n\n- **Professional KiCad Output**: Generate .kicad_pro, .kicad_sch, .kicad_pcb files with modern kicad-sch-api integration\n- **Hierarchical Design**: Modular subcircuits like software modules  \n- **Atomic KiCad Operations**: Add/remove individual components from existing schematics with rollback safety\n- **Modern KiCad Integration**: Uses PyPI kicad-sch-api (v0.1.1+) for professional schematic generation\n- **Component Intelligence**: JLCPCB & DigiKey integration, symbol/footprint verification\n- **Fast JLCPCB Search**: Direct search with 80% speed improvement, 90% less tokens\n- **AI Integration**: Claude Code agents for automated design assistance\n- **Circuit Debugging**: AI-powered PCB troubleshooting with systematic fault-finding\n- **FMEA Analysis**: Comprehensive reliability analysis with physics-based failure models\n- **Test Generation**: Automated test plans for validation\n- **Version Control**: Git-friendly text-based circuit definitions\n\n## KiCad-sch-api Integration\n\nCircuit-synth integrates with the modern **kicad-sch-api** PyPI package - a valuable standalone tool that was extracted from circuit-synth for broader community use.\n\n### Benefits of kicad-sch-api\n- **Professional KiCad Files**: Generates industry-standard .kicad_sch files with proper formatting\n- **Symbol Library Integration**: Full access to KiCad's extensive symbol libraries  \n- **Hierarchical Support**: Clean handling of complex multi-sheet designs\n- **Version Compatibility**: Works with modern KiCad versions (v7.0+)\n\n### Hybrid Architecture\nCircuit-synth uses a hybrid approach combining the best of both worlds:\n- **Legacy System**: Handles component positioning and hierarchical structure\n- **Modern API**: Professional schematic file writing via kicad-sch-api\n- **Intelligent Selection**: Automatically chooses the right approach per schematic type\n\n```python\n# The modern API integration is automatic - just use circuit-synth as normal!\n@circuit(name=\"MyCircuit\")\ndef my_design():\n    # Your circuit design here\n    pass\n\n# Behind the scenes: circuit-synth + kicad-sch-api = professional results\n```\n\n### Standalone kicad-sch-api Usage\nThe kicad-sch-api package is also valuable as a standalone tool for Python KiCad integration:\n\n```bash\npip install kicad-sch-api\n```\n\nVisit the [kicad-sch-api repository](https://github.com/circuit-synth/kicad-sch-api) for standalone usage examples.\n\n## AI-Powered Design\n\n### Claude Code Commands\n\n```bash\n# Component search\n/find-symbol STM32                    # Search KiCad symbols\n/find-footprint LQFP64                # Find footprints\n/find-parts \"STM32F407\" --source jlcpcb   # Check JLCPCB availability\n/find-stm32 \"3 SPIs, USB\"             # STM32-specific search\n\n# Circuit generation\n/generate-validated-circuit \"ESP32 IoT sensor\" mcu\n\n# Fast JLCPCB CLI (no agents, 80% faster)\njlc-fast search STM32G4               # Direct search\njlc-fast cheapest \"10uF 0805\"         # Find cheapest option\n```\n\n### \ud83e\udd16 AI Assistance\n\nWhen using Claude Code, you can ask for help with:\n\n- **Component Selection**: \"Find me a 3.3V regulator available on JLCPCB\"\n- **Circuit Design**: \"Design a USB-C power supply with protection\"\n- **KiCad Integration**: \"What footprint should I use for LQFP-48?\"\n- **Troubleshooting**: \"My board isn't powering on - help debug\"\n- **SPICE Simulation**: \"Simulate this amplifier circuit\"\n- **Test Planning**: \"Generate test procedures for my power supply\"\n\nThe AI agents will automatically select the right tools and expertise for your request.\n\n## \ud83d\ude80 Commands\n\n### Project Creation\n```bash\ncs-new-project              # Complete project setup with ESP32-C6 example\n```\n\n### Circuit Generation\n```bash\ncd circuit-synth && uv run python example_project/circuit-synth/main.py    # Generate KiCad files from Python code\n```\n\n### Available Commands\n\n```bash\n# Component Search\n/find-symbol STM32              # Search KiCad symbols\n/find-footprint LQFP64          # Find footprints\n/find-parts \"STM32F407\" --source jlcpcb   # Check availability\n/find-stm32 \"3 SPIs, USB\"       # STM32-specific search\n\n# Circuit Generation\n/generate-validated-circuit \"ESP32 IoT sensor\" mcu\n/validate-existing-circuit      # Validate circuit code\n\n# Fast JLCPCB CLI\njlc-fast search STM32G4         # Direct search\njlc-fast cheapest \"10uF 0805\"   # Find cheapest option\n\n# FMEA Analysis\n/analyze-fmea my_circuit.py     # Run reliability analysis\n```\n\n## \u26a1 Atomic KiCad Operations\n\nCircuit-synth provides atomic operations for surgical modifications to existing KiCad schematics, enabling incremental updates without regenerating entire projects:\n\n### Production API\n\n```python\nfrom circuit_synth.kicad.atomic_integration import AtomicKiCadIntegration, migrate_circuit_to_atomic\n\n# Initialize atomic integration for a KiCad project\natomic = AtomicKiCadIntegration(\"/path/to/project\")\n\n# Add components using atomic operations\natomic.add_component_atomic(\"main\", {\n    'symbol': 'Device:R',\n    'ref': 'R1',\n    'value': '10k',\n    'footprint': 'Resistor_SMD:R_0603_1608Metric',\n    'position': (100, 80)\n})\n\n# Remove components\natomic.remove_component_atomic(\"main\", \"R1\")\n\n# Fix hierarchical main schematics with sheet references\nsubcircuits = [\n    {\"name\": \"USB_Port\", \"filename\": \"USB_Port.kicad_sch\", \"position\": (35, 35), \"size\": (43, 25)},\n    {\"name\": \"Power_Supply\", \"filename\": \"Power_Supply.kicad_sch\", \"position\": (95, 35), \"size\": (44, 20)}\n]\natomic.fix_hierarchical_main_schematic(subcircuits)\n\n# Migrate JSON netlist to KiCad using atomic operations\nmigrate_circuit_to_atomic(\"circuit.json\", \"output_project/\")\n```\n\n### Key Benefits\n\n- **True Atomic Operations**: Add/remove individual components with rollback safety\n- **Hierarchical Sheet Management**: Fixes blank main schematics automatically\n- **Production Integration**: Seamless integration with existing circuit-synth pipeline  \n- **S-Expression Safety**: Proper parsing with backup/restore on failure\n- **JSON Pipeline Integration**: Full compatibility with circuit-synth JSON format\n\n### Use Cases\n\n- **Incremental Updates**: Add components to existing designs without full regeneration\n- **Debug and Fix**: Resolve blank schematic issues (like ESP32-C6 project)\n- **External Integration**: Third-party tools can manipulate circuit-synth schematics\n- **Advanced Workflows**: Power users building custom automation\n\n## FMEA and Quality Assurance\n\nCircuit-synth includes comprehensive failure analysis capabilities to ensure your designs are reliable:\n\n### Automated FMEA Analysis\n\n```python\nfrom circuit_synth.quality_assurance import EnhancedFMEAAnalyzer\nfrom circuit_synth.quality_assurance import ComprehensiveFMEAReportGenerator\n\n# Analyze your circuit for failures\nanalyzer = EnhancedFMEAAnalyzer()\ncircuit_context = {\n    'environment': 'industrial',    # Set operating environment\n    'safety_critical': True,        # Affects severity ratings\n    'production_volume': 'high'     # Influences detection ratings\n}\n\n# Generate comprehensive PDF report (50+ pages)\ngenerator = ComprehensiveFMEAReportGenerator(\"My Project\")\nreport_path = generator.generate_comprehensive_report(\n    analysis_results,\n    output_path=\"FMEA_Report.pdf\"\n)\n```\n\n### What Gets Analyzed\n\n- **300+ Failure Modes**: Component failures, solder joints, environmental stress\n- **Physics-Based Models**: Arrhenius, Coffin-Manson, Black's equation\n- **IPC Class 3 Compliance**: High-reliability assembly standards\n- **Risk Assessment**: RPN (Risk Priority Number) calculations\n- **Mitigation Strategies**: Specific recommendations for each failure mode\n\n### Command Line FMEA\n\n```bash\n# Quick FMEA analysis\nuv run python -m circuit_synth.tools.quality_assurance.fmea_cli my_circuit.py\n\n# Specify output file\nuv run python -m circuit_synth.tools.quality_assurance.fmea_cli my_circuit.py -o FMEA_Report.pdf\n\n# Analyze with custom threshold\nuv run python -m circuit_synth.tools.quality_assurance.fmea_cli my_circuit.py --threshold 150\n```\n\nSee [FMEA Guide](docs/FMEA_GUIDE.md) for detailed documentation.\n\n## Library Sourcing System\n\nHybrid component discovery across multiple sources with automatic fallback:\n\n### Setup\n```bash\ncs-library-setup                    # Show configuration status\ncs-setup-snapeda-api YOUR_KEY       # Optional: SnapEDA API access  \ncs-setup-digikey-api KEY CLIENT_ID  # Optional: DigiKey API access\n```\n\n### Usage\nEnhanced `/find-symbol` and `/find-footprint` commands automatically search:\n1. **Local KiCad** (user installation)\n2. **DigiKey GitHub** (150 curated libraries, auto-converted)\n3. **SnapEDA API** (millions of components)\n4. **DigiKey API** (supplier validation)\n\nResults show source tags: `[Local]`, `[DigiKey GitHub]`, `[SnapEDA]`, `[DigiKey API]`\n\n## Fast JLCPCB Component Search\n\nThe optimized search API provides direct JLCPCB component lookup without agent overhead:\n\n### Python API\n\n```python\nfrom circuit_synth.manufacturing.jlcpcb import fast_jlc_search, find_cheapest_jlc\n\n# Fast search with filtering\nresults = fast_jlc_search(\"STM32G4\", min_stock=100, max_results=5)\nfor r in results:\n    print(f\"{r.part_number}: {r.description} (${r.price}, stock: {r.stock})\")\n\n# Find cheapest option\ncheapest = find_cheapest_jlc(\"0.1uF 0603\", min_stock=1000)\nprint(f\"Cheapest: {cheapest.part_number} at ${cheapest.price}\")\n```\n\n### CLI Usage\n\n```bash\n# Search components\njlc-fast search \"USB-C connector\" --min-stock 500\n\n# Find cheapest with stock\njlc-fast cheapest \"10k resistor\" --min-stock 10000\n\n# Performance benchmark\njlc-fast benchmark\n```\n\n### Performance Improvements\n\n- **80% faster**: ~0.5s vs ~30s with agent-based search\n- **90% less tokens**: 0 LLM tokens vs ~500 per search\n- **Intelligent caching**: Avoid repeated API calls\n- **Batch operations**: Search multiple components efficiently\n\n## Project Structure\n\n```\nmy_circuit_project/\n\u251c\u2500\u2500 example_project/\n\u2502   \u251c\u2500\u2500 circuit-synth/\n\u2502   \u2502   \u251c\u2500\u2500 main.py              # ESP32-C6 dev board (hierarchical)\n\u2502   \u2502   \u251c\u2500\u2500 power_supply.py      # 5V\u21923.3V regulation\n\u2502   \u2502   \u251c\u2500\u2500 usb.py               # USB-C with CC resistors\n\u2502   \u2502   \u251c\u2500\u2500 esp32c6.py           # ESP32-C6 microcontroller\n\u2502   \u2502   \u2514\u2500\u2500 led_blinker.py       # Status LED control\n\u2502   \u2514\u2500\u2500 ESP32_C6_Dev_Board/      # Generated KiCad files\n\u2502       \u251c\u2500\u2500 ESP32_C6_Dev_Board.kicad_pro\n\u2502       \u251c\u2500\u2500 ESP32_C6_Dev_Board.kicad_sch\n\u2502       \u251c\u2500\u2500 ESP32_C6_Dev_Board.kicad_pcb\n\u2502       \u2514\u2500\u2500 ESP32_C6_Dev_Board.net\n\u251c\u2500\u2500 README.md                # Project guide\n\u251c\u2500\u2500 CLAUDE.md                # AI assistant instructions\n\u2514\u2500\u2500 pyproject.toml           # Project dependencies\n```\n\n\n## Why Circuit-Synth?\n\n| Traditional EE Workflow | With Circuit-Synth |\n|-------------------------|-------------------|\n| Manual component placement | `python example_project/circuit-synth/main.py` \u2192 Complete project |\n| Hunt through symbol libraries | Verified components with JLCPCB & DigiKey availability |\n| Visual net verification | Explicit Python connections |\n| GUI-based editing | Version-controlled Python files |\n| Copy-paste patterns | Reusable circuit functions |\n| Manual FMEA documentation | Automated 50+ page reliability analysis |\n\n## Resources\n\n- [Documentation](https://docs.circuit-synth.com)\n- [Examples](https://github.com/circuit-synth/examples)\n- [Contributing](CONTRIBUTING.md)\n\n## Development Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/circuit-synth/circuit-synth.git\ncd circuit-synth\nuv sync\n\n# Run tests\nuv run pytest\n\n# Optional: Register Claude Code agents\nuv run register-agents\n```\n\n\nFor 6x performance improvement:\n\n```bash\n\n# Build modules\n\n# Test integration\n```\n\n## Testing\n\n```bash\n# Run comprehensive tests\n./tools/testing/run_full_regression_tests.py\n\n# Python tests only\nuv run pytest --cov=circuit_synth\n\n# Pre-release regression test\n./tools/testing/run_full_regression_tests.py\n\n# Code quality\nblack src/ && isort src/ && flake8 src/ && mypy src/\n```\n\n## KiCad Requirements\n\nKiCad 8.0+ required:\n\n```bash\n# macOS\nbrew install kicad\n\n# Linux\nsudo apt install kicad\n\n# Windows\n# Download from kicad.org\n```\n\n## Troubleshooting\n\nInstall the AI-powered KiCad plugin for direct Claude Code integration:\n\n```bash\n# Install KiCad plugins\nuv run cs-setup-kicad-plugins\n```\n\n**Usage:**\n- **PCB Editor**: Tools \u2192 External Plugins \u2192 \"Circuit-Synth AI\"  \n- **Schematic Editor**: Tools \u2192 Generate BOM \u2192 \"Circuit-Synth AI\"\n\n## \ud83d\udee0\ufe0f Advanced Configuration\n\n### Environment Variables\n\n```bash\n# Optional performance settings\nexport CIRCUIT_SYNTH_PARALLEL_PROCESSING=true\n\n# KiCad path override (if needed)\nexport KICAD_SYMBOL_DIR=\"/custom/path/to/symbols\"\nexport KICAD_FOOTPRINT_DIR=\"/custom/path/to/footprints\"\n```\n\n### Component Database Configuration\n\n```bash\n# JLCPCB API configuration (optional)\nexport JLCPCB_API_KEY=\"your_api_key\"\nexport JLCPCB_CACHE_DURATION=3600  # Cache for 1 hour\n\n# DigiKey API configuration (optional, for component search)\nexport DIGIKEY_CLIENT_ID=\"your_client_id\"\nexport DIGIKEY_CLIENT_SECRET=\"your_client_secret\"\n# Or run: python -m circuit_synth.manufacturing.digikey.config_manager\n```\n\n## \ud83d\udd0d Component Sourcing\n\ncircuit-synth provides integrated access to multiple component distributors for real-time availability, pricing, and specifications.\n\n### Unified Multi-Source Search (Recommended)\nSearch across all suppliers with one interface:\n```python\nfrom circuit_synth.manufacturing import find_parts\n\n# Search all suppliers\nresults = find_parts(\"0.1uF 0603 X7R\", sources=\"all\")\n\n# Search specific supplier\njlc_results = find_parts(\"STM32F407\", sources=\"jlcpcb\")\ndk_results = find_parts(\"LM358\", sources=\"digikey\")\n\n# Compare across suppliers\ncomparison = find_parts(\"3.3V regulator\", sources=\"all\", compare=True)\nprint(comparison)  # Shows price/availability comparison table\n\n# Filter by requirements\nhigh_stock = find_parts(\"10k resistor\", min_stock=10000, max_price=0.10)\n```\n\n### JLCPCB Integration\nBest for PCB assembly and production:\n```python\nfrom circuit_synth.manufacturing.jlcpcb import search_jlc_components_web\n\n# Find components available for assembly\nresults = search_jlc_components_web(\"STM32F407\", max_results=10)\n```\n\n### DigiKey Integration  \nBest for prototyping and wide selection:\n```python\nfrom circuit_synth.manufacturing.digikey import search_digikey_components\n\n# Search DigiKey's 8M+ component catalog\nresults = search_digikey_components(\"0.1uF 0603 X7R\", max_results=10)\n\n# Get detailed pricing and alternatives\nfrom circuit_synth.manufacturing.digikey import DigiKeyComponentSearch\nsearcher = DigiKeyComponentSearch()\ncomponent = searcher.get_component_details(\"399-1096-1-ND\")\nalternatives = searcher.find_alternatives(component, max_results=5)\n```\n\n### DigiKey Setup\n```bash\n# Interactive configuration\npython -m circuit_synth.manufacturing.digikey.config_manager\n\n# Test connection\npython -m circuit_synth.manufacturing.digikey.test_connection\n```\n\nSee [docs/DIGIKEY_SETUP.md](docs/DIGIKEY_SETUP.md) for detailed setup instructions.\n\n### Multi-Source Strategy\n- **Prototyping**: Use DigiKey for fast delivery and no minimums\n- **Small Batch**: Compare JLCPCB vs DigiKey for best value\n- **Production**: Optimize with JLCPCB for integrated assembly\n- **Risk Mitigation**: Maintain alternatives from multiple sources\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n**KiCad Symbol/Footprint Not Found:**\n```bash\n# Verify KiCad installation\nkicad-cli version\n\n# Search for components (with Claude Code)\n/find-symbol STM32\n/find-footprint LQFP64\n```\n\n**Build Issues:**\n```bash\n# Clean rebuild\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## \ud83c\udfd7\ufe0f Architecture Overview\n\n### Technical Stack\n- **Frontend**: Python 3.9+ with type hints\n- **KiCad Integration**: Direct file format support (.kicad_pro, .kicad_sch, .kicad_pcb)\n- **AI Integration**: Claude Code agents with specialized circuit design expertise\n\n### File Structure\n```\ncircuit-synth/\n\u251c\u2500\u2500 src/circuit_synth/           # Python package\n\u2502   \u251c\u2500\u2500 core/                    # Core circuit representation\n\u2502   \u251c\u2500\u2500 kicad/                   # KiCad file I/O\n\u2502   \u251c\u2500\u2500 component_info/          # Component databases\n\u2502   \u251c\u2500\u2500 manufacturing/           # JLCPCB, DigiKey, etc.\n\u2502   \u2514\u2500\u2500 simulation/              # SPICE integration\n\u251c\u2500\u2500 example_project/             # Complete usage example\n\u251c\u2500\u2500 tests/                       # Test suites\n\u2514\u2500\u2500 tools/                       # Development and build tools (organized by category)\n```\n\n## \ud83e\udd1d Contributing\n\n### Development Workflow\n1. **Fork repository** and create feature branch\n2. **Follow coding standards** (black, isort, mypy)\n3. **Add tests** for new functionality\n4. **Update documentation** as needed\n5. **Submit pull request** with clear description\n\n### Coding Standards\n- **Python**: Type hints, dataclasses, SOLID principles\n- **Documentation**: Clear docstrings and inline comments\n- **Testing**: Comprehensive test coverage for new features\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n**Professional PCB Design with Python**\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Pythonic circuit design for production-ready KiCad projects",
    "version": "0.9.1",
    "project_urls": {
        "Documentation": "https://circuit-synth.readthedocs.io",
        "Homepage": "https://github.com/circuit-synth/circuit-synth",
        "Issues": "https://github.com/circuit-synth/circuit-synth/issues",
        "Repository": "https://github.com/circuit-synth/circuit-synth"
    },
    "split_keywords": [
        "circuit",
        " design",
        " kicad",
        " electronics",
        " pcb",
        " schematic"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "55be3f446169e669e54d1ab2fba884e419ca0901f1e74a5483779a559eec3390",
                "md5": "ec7406398bc6f0c33a0e9376acae4528",
                "sha256": "971626c7e24e56beaa05ea729b990c545e522bad891ec7cc00fef002bccb9d84"
            },
            "downloads": -1,
            "filename": "circuit_synth-0.9.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "ec7406398bc6f0c33a0e9376acae4528",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 1099550,
            "upload_time": "2025-10-12T21:02:29",
            "upload_time_iso_8601": "2025-10-12T21:02:29.060004Z",
            "url": "https://files.pythonhosted.org/packages/55/be/3f446169e669e54d1ab2fba884e419ca0901f1e74a5483779a559eec3390/circuit_synth-0.9.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "fd217cc11a8899a7fc3a4ae3bf387c015e789edcb330d21c77bee6f21a669989",
                "md5": "7bf92f14eb1f46cf786fa4b8f5718ed2",
                "sha256": "87d3c7e300ab6a917e47e4db316109eae27617427666bf42a46d7a300f0f3f55"
            },
            "downloads": -1,
            "filename": "circuit_synth-0.9.1.tar.gz",
            "has_sig": false,
            "md5_digest": "7bf92f14eb1f46cf786fa4b8f5718ed2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 932277,
            "upload_time": "2025-10-12T21:02:34",
            "upload_time_iso_8601": "2025-10-12T21:02:34.233140Z",
            "url": "https://files.pythonhosted.org/packages/fd/21/7cc11a8899a7fc3a4ae3bf387c015e789edcb330d21c77bee6f21a669989/circuit_synth-0.9.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-12 21:02:34",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "circuit-synth",
    "github_project": "circuit-synth",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "circuit_synth"
}