# circuit-synth
Pythonic circuit design for professional KiCad projects
## Overview
Circuit Synth is an open-source Python library that fits seamlessly into normal EE workflows without getting too fancy. Unlike domain-specific languages that require learning new syntax, circuit-synth uses simple, transparent Python code that any engineer can understand and modify.
**Core Principles:**
- **Simple Python Code**: No special DSL to learn - just Python classes and functions
- **Transparent to Users**: Generated KiCad files are clean and human-readable
- **Bidirectional Updates**: KiCad can remain the source of truth - import existing projects and export changes back
- **Normal EE Workflow**: Integrates with existing KiCad-based development processes
**Current Status**: Circuit-synth is ready for professional use with the following capabilities:
- **Full KiCad Integration**: Generate complete KiCad projects with schematics and PCB layouts
- **Schematic Annotations**: Automatic docstring extraction and manual text annotations with tables
- **Netlist Generation**: Export industry-standard KiCad netlist files (.net) for seamless PCB workflow
- **Hierarchical Design Support**: Multi-sheet projects with proper organization and connectivity
- **Professional Component Management**: Complete footprint, symbol, and library integration
- Places components functionally (not yet optimized for intelligent board layout)
- Places schematic parts (without intelligent placement algorithms)
- Generates working KiCad projects suitable for professional development
## Example
```python
from circuit_synth import *
@circuit(name="esp32s3_simple")
def esp32s3_simple():
"""Simple ESP32-S3 circuit with decoupling capacitor and debug header"""
# Create power nets
_3V3 = Net('3V3')
GND = Net('GND')
# ESP32-S3 module
esp32s3 = Component(
symbol="RF_Module:ESP32-S3-MINI-1",
ref="U",
footprint="RF_Module:ESP32-S2-MINI-1"
)
# Decoupling capacitor
cap_power = Component(
symbol="Device:C",
ref="C",
value="10uF",
footprint="Capacitor_SMD:C_0603_1608Metric"
)
# Debug header
debug_header = Component(
symbol="Connector_Generic:Conn_02x03_Odd_Even",
ref="J",
footprint="Connector_IDC:IDC-Header_2x03_P2.54mm_Vertical"
)
# Power connections
esp32s3["3V3"] += _3V3 # Power pin
esp32s3["GND"] += GND # Ground pin
# Decoupling capacitor connections
cap_power[1] += _3V3
cap_power[2] += GND
# Debug header connections
debug_header[1] += esp32s3['EN']
debug_header[2] += _3V3
debug_header[3] += esp32s3['TXD0']
debug_header[4] += GND
debug_header[5] += esp32s3['RXD0']
debug_header[6] += esp32s3['IO0']
if __name__ == '__main__':
circuit = esp32s3_simple()
# Generate KiCad netlist for PCB workflow
circuit.generate_kicad_netlist("esp32s3_simple.net")
# Generate complete KiCad project
circuit.generate_kicad_project("esp32s3_simple")
```
## Schematic Annotations
Circuit-synth includes a powerful annotation system for adding documentation directly to your KiCad schematics:
### Automatic Docstring Extraction
```python
from circuit_synth import *
from circuit_synth.core.annotations import enable_comments
@enable_comments # Automatically extracts docstring as schematic annotation
@circuit(name="documented_circuit")
def power_filter_circuit():
"""Power filtering circuit for clean 3.3V supply.
This circuit provides stable power filtering using a 10uF ceramic capacitor
placed close to the power input for optimal performance."""
# Circuit implementation...
```
### Manual Annotations
```python
from circuit_synth.core.annotations import TextBox, TextProperty, Table
# Add text boxes with background
circuit.add_annotation(TextBox(
text="⚠️ Critical: Verify power supply ratings before connection!",
position=(50, 30),
background_color='yellow',
size=(80, 20)
))
# Add component tables
table = Table(
data=[
["Component", "Value", "Package", "Notes"], # Header row
["C1", "10uF", "0603", "X7R ceramic"],
["R1", "1kΩ", "0603", "1% precision"]
],
position=(20, 100)
)
circuit.add_annotation(table)
```
## Key Differentiators
### Bidirectional KiCad Integration
Unlike other circuit design tools that generate KiCad files as output only, circuit-synth provides true bidirectional updates:
- **Import existing KiCad projects** into Python for programmatic modification
- **Export Python circuits** to clean, readable KiCad projects
- **Hierarchical Structure Support** - correctly handles complex multi-level circuit hierarchies
- **KiCad remains source of truth** - make manual changes in KiCad and sync back to Python
- **Hybrid workflows** - combine manual design with automated generation
**Hierarchical Conversion Features:**
- **Multi-level Hierarchies**: Supports arbitrary depth circuit nesting (main → subcircuit → sub-subcircuit)
- **Proper Import Chains**: Generates clean Python imports matching KiCad hierarchical structure
- **Parameter Passing**: Automatically handles net parameter passing between hierarchical levels
- **Clean Code Generation**: Produces readable, maintainable Python code with proper separation of concerns
### Engineering-Friendly Approach
- **No Domain-Specific Language**: Uses standard Python syntax that any engineer can read and modify
- **Transparent Output**: Generated KiCad files are clean and human-readable, not machine-generated gibberish
- **Fits Existing Workflows**: Designed to integrate with normal EE development processes, not replace them
- **Professional Development**: Built for real engineering teams, not just hobbyists
### Additional Features
- **Pythonic Circuit Design**: Define circuits using intuitive Python classes and decorators
- **KiCad Netlist Export**: Generate industry-standard .net files for PCB layout workflows
- **Hierarchical Design Support**: Multi-sheet projects with proper organization and cross-references
- **Component Management**: Built-in component library with easy extensibility
- **Smart Placement**: Automatic component placement algorithms
- **Type Safety**: Full type hints support for better IDE integration
- **Professional Output**: Clean, human-readable KiCad files suitable for production use
- **Extensible Architecture**: Clean interfaces for custom implementations
## AI-Powered Development
Circuit-synth includes a specialized Claude agent for expert guidance on circuit-synth syntax, structure, and best practices. The agent helps with:
- **Code Reviews**: Analyzing circuit-synth projects for proper structure and conventions
- **Best Practices**: Guidance on component reuse, net management, and circuit organization
- **Syntax Help**: Examples and patterns for proper circuit-synth implementation
- **Refactoring**: Suggestions for improving code maintainability and clarity
### Using the Circuit-Synth Agent
The agent is available in `.claude/agents/circuit-synth.md` and specializes in:
```python
# Component reuse patterns the agent recommends
C_10uF_0805 = Component(
symbol="Device:C", ref="C", value="10uF",
footprint="Capacitor_SMD:C_0805_2012Metric"
)
# Then instantiate with unique references
cap_input = C_10uF_0805()
cap_input.ref = "C4" # Override ref for specific instance
```
The agent provides structured feedback on:
- Component definition and reuse patterns
- Circuit structure and @circuit decorator usage
- Net management and naming conventions
- Pin connection syntax (integer vs string access)
- Code organization and maintainability
## Quick Start
Try circuit-synth immediately without installation:
```bash
# Clone the repository
git clone https://github.com/circuit-synth/circuit-synth.git
cd circuit-synth
# Run the example (automatically installs dependencies with uv)
uv run python examples/example_kicad_project.py
```
This will generate a complete KiCad project in the `example_kicad_project/` directory, including:
- Hierarchical schematic files (.kicad_sch)
- PCB layout file (.kicad_pcb)
- KiCad netlist file (.net)
- JSON netlist file (.json)
## KiCad Netlist Generation
Circuit-synth provides industry-standard KiCad netlist generation for seamless PCB layout workflows:
### Basic Netlist Export
```python
from circuit_synth import *
@circuit
def my_circuit():
# Define your circuit...
pass
if __name__ == '__main__':
circuit = my_circuit()
# Generate KiCad netlist (.net file)
circuit.generate_kicad_netlist("my_circuit.net")
# Generate JSON netlist for analysis
circuit.generate_json_netlist("my_circuit.json")
```
### Features
- **Industry Standard Format**: Generates KiCad-compatible .net files
- **Hierarchical Design Support**: Multi-sheet projects with proper organization
- **Complete Component Data**: Includes footprints, values, datasheets, and library references
- **Perfect KiCad Import**: Zero warnings, zero errors when importing into KiCad
- **Scalable**: Works with simple 3-component circuits to complex 20+ component systems
### Verification
All generated netlists are validated through KiCad import:
```
Reading netlist file 'my_circuit.net'.
Using reference designators to match symbols and footprints.
Processing symbol 'U1:RF_Module:ESP32-S2-MINI-1'.
...
Total warnings: 0, errors: 0.
```
### Integration with PCB Workflow
1. **Design in Python**: Define circuits using circuit-synth syntax
2. **Generate Netlist**: Export to KiCad-compatible .net format
3. **Import to KiCad**: Load netlist directly into KiCad PCB editor
4. **Layout PCB**: Use KiCad's routing and placement tools
5. **Manufacturing**: Generate Gerber files and assembly drawings
## Installation
### Using uv (Recommended)
```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install circuit-synth for development
uv pip install -e ".[dev]"
```
### Using pip (in virtual environment)
Since this package isn't published to PyPI yet, install from source:
```bash
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Clone and install
git clone https://github.com/circuit-synth/circuit-synth.git
cd circuit-synth
pip install -e ".[dev]"
```
### Development Setup
For development work:
```bash
# Clone the repository
git clone https://github.com/circuit-synth/circuit-synth.git
cd circuit-synth
# Install with development dependencies using uv
uv sync
# Or with pip
pip install -e ".[dev]"
```
### Using Docker
Circuit-synth can be run in Docker containers with full KiCad library support:
```bash
# Build the Docker image
./docker/build-docker.sh
# Run any circuit-synth command in Docker
./scripts/circuit-synth-docker python examples/example_kicad_project.py
# Run with interactive shell
./scripts/circuit-synth-docker --interactive bash
# Run without KiCad libraries (faster startup)
./scripts/circuit-synth-docker --no-libs python -c "import circuit_synth; print('Ready!')"
```
**Docker Features:**
- Pre-configured environment with all dependencies
- Official KiCad symbol and footprint libraries included
- Automatic file persistence to local `output/` directory
- Security through non-root user execution
- Two Dockerfile options: simplified Python-only (main) and full Rust build (`docker/Dockerfile.rust-build`)
**Docker Commands:**
```bash
# Universal command runner
./scripts/circuit-synth-docker <any-python-command>
# KiCad library-specific runner
./scripts/run-with-kicad.sh --official-libs
# Docker Compose services (from docker/ directory)
cd docker && docker-compose up circuit-synth # Basic service
cd docker && docker-compose up circuit-synth-dev # Development mode
cd docker && docker-compose up circuit-synth-test # Test runner
```
**Docker Build Options:**
```bash
# Quick Python-only build (recommended)
./docker/build-docker.sh
# Full build with Rust modules (advanced users)
docker build -f docker/Dockerfile.rust-build -t circuit-synth-rust .
# Windows users
./docker/build-docker.bat
```
#### Docker Attribution
The Docker implementation is a collaborative effort:
- **Original implementation**: Kumuda Subramanyam Govardhanam (@KumudaSG) - comprehensive Rust module compilation support
- **Enhancements**: KiCad library integration, simplified Python-only build, universal command runners, and build automation
## Documentation
Full documentation is available at [https://circuit-synth.readthedocs.io](https://circuit-synth.readthedocs.io)
## Contributing
We welcome contributions! Here's how to get started:
### Development Setup
**Prerequisites:**
- Python 3.9 or higher
- [uv](https://docs.astral.sh/uv/) (recommended package manager)
- Git
**Getting Started:**
1. **Fork and clone the repository:**
```bash
git clone https://github.com/yourusername/circuit-synth.git
cd circuit-synth
```
2. **Install dependencies (recommended with uv):**
```bash
# Install the project in development mode
uv pip install -e ".[dev]"
# Install dependencies
uv sync
```
3. **Alternative installation with pip:**
```bash
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
```
**Development Guidelines:**
- Follow existing code style and patterns
- Write tests for new functionality
- Update documentation as needed
- Test your changes with `uv run python examples/example_kicad_project.py`
- Use the Docker environment for testing: `./scripts/circuit-synth-docker python examples/example_kicad_project.py`
## Manual Testing Checklist
**Run these manual tests on every major change to ensure system integrity:**
### 1. Core Example Script Testing
**Local Environment:**
```bash
# Run the primary example script locally
uv run python examples/example_kicad_project.py
# Verify generated files exist
ls -la example_kicad_project/
```
**Docker Environment:**
```bash
# Test the same script in Docker environment
./scripts/circuit-synth-docker python examples/example_kicad_project.py
# Verify files are generated in Docker context
./scripts/circuit-synth-docker ls -la example_kicad_project/
```
**Verification Steps:**
- ✅ Script completes without errors
- ✅ Generates complete KiCad project directory
- ✅ Creates `.kicad_sch`, `.kicad_pcb`, `.kicad_pro`, and `.net` files
- ✅ Annotation system debug output appears (docstring extraction)
### 2. KiCad Project Inspection
**Open Generated Project in KiCad:**
```bash
# Open the generated project
kicad example_kicad_project/example_kicad_project.kicad_pro
```
**Schematic Verification:**
- ✅ All components are placed and visible
- ✅ Net connections are correct (no unconnected pins)
- ✅ Hierarchical structure is properly organized
- ✅ Annotations appear as text boxes with docstring content
- ✅ Component references are sequential and logical (R1, R2, C1, C2, etc.)
- ✅ Net names are clean and descriptive (5V, 3V3, GND, USB_DM, etc.)
**PCB Layout Verification:**
- ✅ All components are placed on PCB (not overlapping)
- ✅ All nets have proper connectivity (ratsnest shows connections)
- ✅ Footprints are correct and match schematic symbols
- ✅ Bounding boxes are drawn around components (if `draw_bounding_boxes=True`)
### 3. Docker Command Testing
**Basic Docker Commands:**
```bash
# Test help command
./scripts/circuit-synth-docker --help
# Test version information
./scripts/circuit-synth-docker python -c "import circuit_synth; print(circuit_synth.__version__)"
# Test package installation status
./scripts/circuit-synth-docker pip list | grep circuit-synth
```
**File System Operations:**
```bash
# Test file creation and access
./scripts/circuit-synth-docker touch test_file.txt
./scripts/circuit-synth-docker ls -la test_file.txt
./scripts/circuit-synth-docker rm test_file.txt
```
### 4. Regression Test Suite
**Automated Test Execution:**
```bash
# Run unit tests
uv run pytest tests/unit/test_core_circuit.py -v
# Run functional tests
cd tests/functional_tests/test_01_resistor_divider && uv run python test_netlist_comparison.py
cd tests/functional_tests/test_02_import_resistor_divider && uv run python test_kicad_import.py
cd tests/functional_tests/test_03_round_trip_python_kicad_python && uv run python test_round_trip.py
cd tests/functional_tests/test_04_nested_kicad_sch_import && uv run python test_complex_hierarchical_structure.py
# Run integration tests
uv run pytest tests/kicad_netlist_exporter/test_sheet_hierarchy.py -v
uv run pytest tests/kicad_netlist_exporter/test_netlist_exporter_basics.py -v
```
**Success Criteria:**
- ✅ All unit tests pass (18/18)
- ✅ All functional tests complete successfully
- ✅ Integration tests pass without errors
- ✅ No regression in existing functionality
### 5. System Integration Verification
**Web Dashboard (if available):**
```bash
# Test dashboard startup
uv run circuit-synth-web
# Verify: Dashboard starts without critical errors
```
**LLM Analysis Pipeline:**
```bash
# Test analysis system availability
uv run python -m circuit_synth.intelligence.scripts.llm_circuit_analysis --help
# Verify: Help output appears, no import errors
```
### 6. Advanced Validation
**Hierarchical Structure Testing:**
- ✅ Test complex hierarchical projects (3+ levels deep)
- ✅ Verify proper nested import chains in generated Python
- ✅ Confirm parameter passing through hierarchy levels
- ✅ Check that KiCad→Python→KiCad round-trip preserves structure
**Bidirectional Sync Testing:**
- ✅ Import existing KiCad project to Python
- ✅ Modify Python code and regenerate KiCad
- ✅ Verify changes appear correctly in KiCad
- ✅ Test that manual KiCad changes can be preserved
**Component and Net Validation:**
- ✅ Test various component types (resistors, capacitors, ICs, connectors)
- ✅ Verify footprint assignments are correct
- ✅ Check net naming conventions and cleanup
- ✅ Test pin mapping for complex components (ESP32, connectors)
### 7. Performance and Resource Testing
**Resource Usage:**
```bash
# Monitor memory usage during generation
time uv run python examples/example_kicad_project.py
# Check generated file sizes are reasonable
du -h example_kicad_project/
```
**Docker Performance:**
```bash
# Test Docker startup time
time ./scripts/circuit-synth-docker echo "Docker ready"
# Compare Docker vs local execution time
time ./scripts/circuit-synth-docker python examples/example_kicad_project.py
```
### 8. Error Handling and Edge Cases
**Error Condition Testing:**
- ✅ Test with invalid component references
- ✅ Test with missing footprints or symbols
- ✅ Test with circular hierarchical dependencies
- ✅ Verify graceful error messages and recovery
**Edge Case Validation:**
- ✅ Test empty circuits
- ✅ Test very large circuits (100+ components)
- ✅ Test circuits with no nets
- ✅ Test circuits with only power nets
## Manual Testing Frequency
**Before Each Commit:**
- Run core example script (local + Docker)
- Execute unit tests
- Verify no regressions in key functionality
**Before Each Release:**
- Complete full manual testing checklist
- Perform KiCad project inspection
- Run entire regression test suite
- Test Docker commands and environment
- Validate hierarchical and bidirectional features
**After Major Refactoring:**
- Execute complete testing checklist
- Additional focus on changed subsystems
- Performance regression testing
- Cross-platform validation (if applicable)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- Documentation: [https://circuit-synth.readthedocs.io](https://circuit-synth.readthedocs.io)
- Issues: [GitHub Issues](https://github.com/circuit-synth/circuit-synth/issues)
- Discussions: [GitHub Discussions](https://github.com/circuit-synth/circuit-synth/discussions)
Raw data
{
"_id": null,
"home_page": null,
"name": "circuit-synth",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"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/4e/03/b0c27da93921bb190f3a600712cff4b6a59d9f8fd5e4448c2a79554c2d4e/circuit_synth-0.1.0.tar.gz",
"platform": null,
"description": "# circuit-synth\n\nPythonic circuit design for professional KiCad projects\n\n## Overview\n\nCircuit Synth is an open-source Python library that fits seamlessly into normal EE workflows without getting too fancy. Unlike domain-specific languages that require learning new syntax, circuit-synth uses simple, transparent Python code that any engineer can understand and modify.\n\n**Core Principles:**\n- **Simple Python Code**: No special DSL to learn - just Python classes and functions\n- **Transparent to Users**: Generated KiCad files are clean and human-readable\n- **Bidirectional Updates**: KiCad can remain the source of truth - import existing projects and export changes back\n- **Normal EE Workflow**: Integrates with existing KiCad-based development processes\n\n**Current Status**: Circuit-synth is ready for professional use with the following capabilities:\n- **Full KiCad Integration**: Generate complete KiCad projects with schematics and PCB layouts\n- **Schematic Annotations**: Automatic docstring extraction and manual text annotations with tables\n- **Netlist Generation**: Export industry-standard KiCad netlist files (.net) for seamless PCB workflow\n- **Hierarchical Design Support**: Multi-sheet projects with proper organization and connectivity\n- **Professional Component Management**: Complete footprint, symbol, and library integration\n- Places components functionally (not yet optimized for intelligent board layout)\n- Places schematic parts (without intelligent placement algorithms)\n- Generates working KiCad projects suitable for professional development\n\n## Example\n\n```python\nfrom circuit_synth import *\n\n@circuit(name=\"esp32s3_simple\")\ndef esp32s3_simple():\n \"\"\"Simple ESP32-S3 circuit with decoupling capacitor and debug header\"\"\"\n \n # Create power nets\n _3V3 = Net('3V3')\n GND = Net('GND')\n \n # ESP32-S3 module\n esp32s3 = Component(\n symbol=\"RF_Module:ESP32-S3-MINI-1\",\n ref=\"U\",\n footprint=\"RF_Module:ESP32-S2-MINI-1\"\n )\n \n # Decoupling capacitor\n cap_power = Component(\n symbol=\"Device:C\",\n ref=\"C\", \n value=\"10uF\",\n footprint=\"Capacitor_SMD:C_0603_1608Metric\"\n )\n \n # Debug header\n debug_header = Component(\n symbol=\"Connector_Generic:Conn_02x03_Odd_Even\",\n ref=\"J\",\n footprint=\"Connector_IDC:IDC-Header_2x03_P2.54mm_Vertical\"\n )\n \n # Power connections\n esp32s3[\"3V3\"] += _3V3 # Power pin\n esp32s3[\"GND\"] += GND # Ground pin\n \n # Decoupling capacitor connections\n cap_power[1] += _3V3\n cap_power[2] += GND\n \n # Debug header connections\n debug_header[1] += esp32s3['EN']\n debug_header[2] += _3V3\n debug_header[3] += esp32s3['TXD0']\n debug_header[4] += GND\n debug_header[5] += esp32s3['RXD0']\n debug_header[6] += esp32s3['IO0']\n\nif __name__ == '__main__':\n circuit = esp32s3_simple()\n \n # Generate KiCad netlist for PCB workflow\n circuit.generate_kicad_netlist(\"esp32s3_simple.net\")\n \n # Generate complete KiCad project\n circuit.generate_kicad_project(\"esp32s3_simple\")\n```\n\n## Schematic Annotations\n\nCircuit-synth includes a powerful annotation system for adding documentation directly to your KiCad schematics:\n\n### Automatic Docstring Extraction\n\n```python\nfrom circuit_synth import *\nfrom circuit_synth.core.annotations import enable_comments\n\n@enable_comments # Automatically extracts docstring as schematic annotation\n@circuit(name=\"documented_circuit\")\ndef power_filter_circuit():\n \"\"\"Power filtering circuit for clean 3.3V supply.\n \n This circuit provides stable power filtering using a 10uF ceramic capacitor\n placed close to the power input for optimal performance.\"\"\"\n \n # Circuit implementation...\n```\n\n### Manual Annotations\n\n```python\nfrom circuit_synth.core.annotations import TextBox, TextProperty, Table\n\n# Add text boxes with background\ncircuit.add_annotation(TextBox(\n text=\"\u26a0\ufe0f Critical: Verify power supply ratings before connection!\",\n position=(50, 30),\n background_color='yellow',\n size=(80, 20)\n))\n\n# Add component tables\ntable = Table(\n data=[\n [\"Component\", \"Value\", \"Package\", \"Notes\"], # Header row\n [\"C1\", \"10uF\", \"0603\", \"X7R ceramic\"],\n [\"R1\", \"1k\u03a9\", \"0603\", \"1% precision\"]\n ],\n position=(20, 100)\n)\ncircuit.add_annotation(table)\n```\n\n## Key Differentiators\n\n### Bidirectional KiCad Integration\nUnlike other circuit design tools that generate KiCad files as output only, circuit-synth provides true bidirectional updates:\n- **Import existing KiCad projects** into Python for programmatic modification\n- **Export Python circuits** to clean, readable KiCad projects\n- **Hierarchical Structure Support** - correctly handles complex multi-level circuit hierarchies\n- **KiCad remains source of truth** - make manual changes in KiCad and sync back to Python\n- **Hybrid workflows** - combine manual design with automated generation\n\n**Hierarchical Conversion Features:**\n- **Multi-level Hierarchies**: Supports arbitrary depth circuit nesting (main \u2192 subcircuit \u2192 sub-subcircuit)\n- **Proper Import Chains**: Generates clean Python imports matching KiCad hierarchical structure\n- **Parameter Passing**: Automatically handles net parameter passing between hierarchical levels\n- **Clean Code Generation**: Produces readable, maintainable Python code with proper separation of concerns\n\n### Engineering-Friendly Approach\n- **No Domain-Specific Language**: Uses standard Python syntax that any engineer can read and modify\n- **Transparent Output**: Generated KiCad files are clean and human-readable, not machine-generated gibberish\n- **Fits Existing Workflows**: Designed to integrate with normal EE development processes, not replace them\n- **Professional Development**: Built for real engineering teams, not just hobbyists\n\n### Additional Features\n- **Pythonic Circuit Design**: Define circuits using intuitive Python classes and decorators\n- **KiCad Netlist Export**: Generate industry-standard .net files for PCB layout workflows\n- **Hierarchical Design Support**: Multi-sheet projects with proper organization and cross-references\n- **Component Management**: Built-in component library with easy extensibility \n- **Smart Placement**: Automatic component placement algorithms\n- **Type Safety**: Full type hints support for better IDE integration\n- **Professional Output**: Clean, human-readable KiCad files suitable for production use\n- **Extensible Architecture**: Clean interfaces for custom implementations\n\n## AI-Powered Development\n\nCircuit-synth includes a specialized Claude agent for expert guidance on circuit-synth syntax, structure, and best practices. The agent helps with:\n\n- **Code Reviews**: Analyzing circuit-synth projects for proper structure and conventions\n- **Best Practices**: Guidance on component reuse, net management, and circuit organization \n- **Syntax Help**: Examples and patterns for proper circuit-synth implementation\n- **Refactoring**: Suggestions for improving code maintainability and clarity\n\n### Using the Circuit-Synth Agent\n\nThe agent is available in `.claude/agents/circuit-synth.md` and specializes in:\n\n```python\n# Component reuse patterns the agent recommends\nC_10uF_0805 = Component(\n symbol=\"Device:C\", ref=\"C\", value=\"10uF\",\n footprint=\"Capacitor_SMD:C_0805_2012Metric\"\n)\n\n# Then instantiate with unique references\ncap_input = C_10uF_0805()\ncap_input.ref = \"C4\" # Override ref for specific instance\n```\n\nThe agent provides structured feedback on:\n- Component definition and reuse patterns\n- Circuit structure and @circuit decorator usage\n- Net management and naming conventions\n- Pin connection syntax (integer vs string access)\n- Code organization and maintainability\n\n## Quick Start\n\nTry circuit-synth immediately without installation:\n\n```bash\n# Clone the repository\ngit clone https://github.com/circuit-synth/circuit-synth.git\ncd circuit-synth\n\n# Run the example (automatically installs dependencies with uv)\nuv run python examples/example_kicad_project.py\n```\n\nThis will generate a complete KiCad project in the `example_kicad_project/` directory, including:\n- Hierarchical schematic files (.kicad_sch)\n- PCB layout file (.kicad_pcb) \n- KiCad netlist file (.net)\n- JSON netlist file (.json)\n\n## KiCad Netlist Generation\n\nCircuit-synth provides industry-standard KiCad netlist generation for seamless PCB layout workflows:\n\n### Basic Netlist Export\n```python\nfrom circuit_synth import *\n\n@circuit\ndef my_circuit():\n # Define your circuit...\n pass\n\nif __name__ == '__main__':\n circuit = my_circuit()\n \n # Generate KiCad netlist (.net file)\n circuit.generate_kicad_netlist(\"my_circuit.net\")\n \n # Generate JSON netlist for analysis\n circuit.generate_json_netlist(\"my_circuit.json\")\n```\n\n### Features\n- **Industry Standard Format**: Generates KiCad-compatible .net files\n- **Hierarchical Design Support**: Multi-sheet projects with proper organization \n- **Complete Component Data**: Includes footprints, values, datasheets, and library references\n- **Perfect KiCad Import**: Zero warnings, zero errors when importing into KiCad\n- **Scalable**: Works with simple 3-component circuits to complex 20+ component systems\n\n### Verification\nAll generated netlists are validated through KiCad import:\n```\nReading netlist file 'my_circuit.net'. \nUsing reference designators to match symbols and footprints.\nProcessing symbol 'U1:RF_Module:ESP32-S2-MINI-1'.\n...\nTotal warnings: 0, errors: 0.\n```\n\n### Integration with PCB Workflow\n1. **Design in Python**: Define circuits using circuit-synth syntax\n2. **Generate Netlist**: Export to KiCad-compatible .net format\n3. **Import to KiCad**: Load netlist directly into KiCad PCB editor\n4. **Layout PCB**: Use KiCad's routing and placement tools\n5. **Manufacturing**: Generate Gerber files and assembly drawings\n\n## Installation\n\n### Using uv (Recommended)\n\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install circuit-synth for development\nuv pip install -e \".[dev]\"\n```\n\n### Using pip (in virtual environment)\n\nSince this package isn't published to PyPI yet, install from source:\n\n```bash\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Clone and install\ngit clone https://github.com/circuit-synth/circuit-synth.git\ncd circuit-synth\npip install -e \".[dev]\"\n```\n\n### Development Setup\n\nFor development work:\n\n```bash\n# Clone the repository\ngit clone https://github.com/circuit-synth/circuit-synth.git\ncd circuit-synth\n\n# Install with development dependencies using uv\nuv sync\n\n# Or with pip\npip install -e \".[dev]\"\n```\n\n### Using Docker\n\nCircuit-synth can be run in Docker containers with full KiCad library support:\n\n```bash\n# Build the Docker image\n./docker/build-docker.sh\n\n# Run any circuit-synth command in Docker\n./scripts/circuit-synth-docker python examples/example_kicad_project.py\n\n# Run with interactive shell\n./scripts/circuit-synth-docker --interactive bash\n\n# Run without KiCad libraries (faster startup)\n./scripts/circuit-synth-docker --no-libs python -c \"import circuit_synth; print('Ready!')\"\n```\n\n**Docker Features:**\n- Pre-configured environment with all dependencies\n- Official KiCad symbol and footprint libraries included\n- Automatic file persistence to local `output/` directory\n- Security through non-root user execution\n- Two Dockerfile options: simplified Python-only (main) and full Rust build (`docker/Dockerfile.rust-build`)\n\n**Docker Commands:**\n```bash\n# Universal command runner\n./scripts/circuit-synth-docker <any-python-command>\n\n# KiCad library-specific runner\n./scripts/run-with-kicad.sh --official-libs\n\n# Docker Compose services (from docker/ directory)\ncd docker && docker-compose up circuit-synth # Basic service\ncd docker && docker-compose up circuit-synth-dev # Development mode\ncd docker && docker-compose up circuit-synth-test # Test runner\n```\n\n**Docker Build Options:**\n```bash\n# Quick Python-only build (recommended)\n./docker/build-docker.sh\n\n# Full build with Rust modules (advanced users)\ndocker build -f docker/Dockerfile.rust-build -t circuit-synth-rust .\n\n# Windows users\n./docker/build-docker.bat\n```\n\n#### Docker Attribution\n\nThe Docker implementation is a collaborative effort:\n- **Original implementation**: Kumuda Subramanyam Govardhanam (@KumudaSG) - comprehensive Rust module compilation support\n- **Enhancements**: KiCad library integration, simplified Python-only build, universal command runners, and build automation\n\n## Documentation\n\nFull documentation is available at [https://circuit-synth.readthedocs.io](https://circuit-synth.readthedocs.io)\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Setup\n\n**Prerequisites:**\n- Python 3.9 or higher\n- [uv](https://docs.astral.sh/uv/) (recommended package manager)\n- Git\n\n**Getting Started:**\n\n1. **Fork and clone the repository:**\n ```bash\n git clone https://github.com/yourusername/circuit-synth.git\n cd circuit-synth\n ```\n\n2. **Install dependencies (recommended with uv):**\n ```bash\n # Install the project in development mode\n uv pip install -e \".[dev]\"\n \n # Install dependencies\n uv sync\n ```\n\n3. **Alternative installation with pip:**\n ```bash\n # Create and activate virtual environment\n python -m venv venv\n source venv/bin/activate # On Windows: venv\\Scripts\\activate\n \n # Install in development mode\n pip install -e \".[dev]\"\n ```\n\n**Development Guidelines:**\n- Follow existing code style and patterns\n- Write tests for new functionality\n- Update documentation as needed\n- Test your changes with `uv run python examples/example_kicad_project.py`\n- Use the Docker environment for testing: `./scripts/circuit-synth-docker python examples/example_kicad_project.py`\n\n## Manual Testing Checklist\n\n**Run these manual tests on every major change to ensure system integrity:**\n\n### 1. Core Example Script Testing\n\n**Local Environment:**\n```bash\n# Run the primary example script locally\nuv run python examples/example_kicad_project.py\n\n# Verify generated files exist\nls -la example_kicad_project/\n```\n\n**Docker Environment:**\n```bash\n# Test the same script in Docker environment\n./scripts/circuit-synth-docker python examples/example_kicad_project.py\n\n# Verify files are generated in Docker context\n./scripts/circuit-synth-docker ls -la example_kicad_project/\n```\n\n**Verification Steps:**\n- \u2705 Script completes without errors\n- \u2705 Generates complete KiCad project directory\n- \u2705 Creates `.kicad_sch`, `.kicad_pcb`, `.kicad_pro`, and `.net` files\n- \u2705 Annotation system debug output appears (docstring extraction)\n\n### 2. KiCad Project Inspection\n\n**Open Generated Project in KiCad:**\n```bash\n# Open the generated project\nkicad example_kicad_project/example_kicad_project.kicad_pro\n```\n\n**Schematic Verification:**\n- \u2705 All components are placed and visible\n- \u2705 Net connections are correct (no unconnected pins)\n- \u2705 Hierarchical structure is properly organized\n- \u2705 Annotations appear as text boxes with docstring content\n- \u2705 Component references are sequential and logical (R1, R2, C1, C2, etc.)\n- \u2705 Net names are clean and descriptive (5V, 3V3, GND, USB_DM, etc.)\n\n**PCB Layout Verification:**\n- \u2705 All components are placed on PCB (not overlapping)\n- \u2705 All nets have proper connectivity (ratsnest shows connections)\n- \u2705 Footprints are correct and match schematic symbols\n- \u2705 Bounding boxes are drawn around components (if `draw_bounding_boxes=True`)\n\n### 3. Docker Command Testing\n\n**Basic Docker Commands:**\n```bash\n# Test help command\n./scripts/circuit-synth-docker --help\n\n# Test version information\n./scripts/circuit-synth-docker python -c \"import circuit_synth; print(circuit_synth.__version__)\"\n\n# Test package installation status\n./scripts/circuit-synth-docker pip list | grep circuit-synth\n```\n\n**File System Operations:**\n```bash\n# Test file creation and access\n./scripts/circuit-synth-docker touch test_file.txt\n./scripts/circuit-synth-docker ls -la test_file.txt\n./scripts/circuit-synth-docker rm test_file.txt\n```\n\n### 4. Regression Test Suite\n\n**Automated Test Execution:**\n```bash\n# Run unit tests\nuv run pytest tests/unit/test_core_circuit.py -v\n\n# Run functional tests\ncd tests/functional_tests/test_01_resistor_divider && uv run python test_netlist_comparison.py\ncd tests/functional_tests/test_02_import_resistor_divider && uv run python test_kicad_import.py \ncd tests/functional_tests/test_03_round_trip_python_kicad_python && uv run python test_round_trip.py\ncd tests/functional_tests/test_04_nested_kicad_sch_import && uv run python test_complex_hierarchical_structure.py\n\n# Run integration tests\nuv run pytest tests/kicad_netlist_exporter/test_sheet_hierarchy.py -v\nuv run pytest tests/kicad_netlist_exporter/test_netlist_exporter_basics.py -v\n```\n\n**Success Criteria:**\n- \u2705 All unit tests pass (18/18)\n- \u2705 All functional tests complete successfully\n- \u2705 Integration tests pass without errors\n- \u2705 No regression in existing functionality\n\n### 5. System Integration Verification\n\n**Web Dashboard (if available):**\n```bash\n# Test dashboard startup\nuv run circuit-synth-web\n# Verify: Dashboard starts without critical errors\n```\n\n**LLM Analysis Pipeline:**\n```bash\n# Test analysis system availability\nuv run python -m circuit_synth.intelligence.scripts.llm_circuit_analysis --help\n# Verify: Help output appears, no import errors\n```\n\n### 6. Advanced Validation\n\n**Hierarchical Structure Testing:**\n- \u2705 Test complex hierarchical projects (3+ levels deep)\n- \u2705 Verify proper nested import chains in generated Python\n- \u2705 Confirm parameter passing through hierarchy levels\n- \u2705 Check that KiCad\u2192Python\u2192KiCad round-trip preserves structure\n\n**Bidirectional Sync Testing:**\n- \u2705 Import existing KiCad project to Python\n- \u2705 Modify Python code and regenerate KiCad\n- \u2705 Verify changes appear correctly in KiCad\n- \u2705 Test that manual KiCad changes can be preserved\n\n**Component and Net Validation:**\n- \u2705 Test various component types (resistors, capacitors, ICs, connectors)\n- \u2705 Verify footprint assignments are correct\n- \u2705 Check net naming conventions and cleanup\n- \u2705 Test pin mapping for complex components (ESP32, connectors)\n\n### 7. Performance and Resource Testing\n\n**Resource Usage:**\n```bash\n# Monitor memory usage during generation\ntime uv run python examples/example_kicad_project.py\n\n# Check generated file sizes are reasonable\ndu -h example_kicad_project/\n```\n\n**Docker Performance:**\n```bash\n# Test Docker startup time\ntime ./scripts/circuit-synth-docker echo \"Docker ready\"\n\n# Compare Docker vs local execution time \ntime ./scripts/circuit-synth-docker python examples/example_kicad_project.py\n```\n\n### 8. Error Handling and Edge Cases\n\n**Error Condition Testing:**\n- \u2705 Test with invalid component references\n- \u2705 Test with missing footprints or symbols\n- \u2705 Test with circular hierarchical dependencies\n- \u2705 Verify graceful error messages and recovery\n\n**Edge Case Validation:**\n- \u2705 Test empty circuits\n- \u2705 Test very large circuits (100+ components)\n- \u2705 Test circuits with no nets\n- \u2705 Test circuits with only power nets\n\n## Manual Testing Frequency\n\n**Before Each Commit:**\n- Run core example script (local + Docker)\n- Execute unit tests\n- Verify no regressions in key functionality\n\n**Before Each Release:**\n- Complete full manual testing checklist\n- Perform KiCad project inspection\n- Run entire regression test suite\n- Test Docker commands and environment\n- Validate hierarchical and bidirectional features\n\n**After Major Refactoring:**\n- Execute complete testing checklist\n- Additional focus on changed subsystems\n- Performance regression testing\n- Cross-platform validation (if applicable)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- Documentation: [https://circuit-synth.readthedocs.io](https://circuit-synth.readthedocs.io)\n- Issues: [GitHub Issues](https://github.com/circuit-synth/circuit-synth/issues)\n- Discussions: [GitHub Discussions](https://github.com/circuit-synth/circuit-synth/discussions)\n",
"bugtrack_url": null,
"license": null,
"summary": "Pythonic circuit design for production-ready KiCad projects",
"version": "0.1.0",
"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": "04c769af95b857eb4311d9fbbdbabf6aed0fcfe61cbcd0b732d82b0cfa2e0fb6",
"md5": "8eaa4f892e5a6079da7400f0b41eb141",
"sha256": "598696bc71f2b216228a7f51552acd2e4ccac19e22429847b9e38c5493fb0ee3"
},
"downloads": -1,
"filename": "circuit_synth-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8eaa4f892e5a6079da7400f0b41eb141",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 1050082,
"upload_time": "2025-07-28T01:37:51",
"upload_time_iso_8601": "2025-07-28T01:37:51.577621Z",
"url": "https://files.pythonhosted.org/packages/04/c7/69af95b857eb4311d9fbbdbabf6aed0fcfe61cbcd0b732d82b0cfa2e0fb6/circuit_synth-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4e03b0c27da93921bb190f3a600712cff4b6a59d9f8fd5e4448c2a79554c2d4e",
"md5": "f70e31d4aab39eb795f4f913958ce00c",
"sha256": "80c73d912891f050b7e3f8e59be18b004102c29f7032f05ca016ba4c0f116cc5"
},
"downloads": -1,
"filename": "circuit_synth-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f70e31d4aab39eb795f4f913958ce00c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 868676,
"upload_time": "2025-07-28T01:37:53",
"upload_time_iso_8601": "2025-07-28T01:37:53.987053Z",
"url": "https://files.pythonhosted.org/packages/4e/03/b0c27da93921bb190f3a600712cff4b6a59d9f8fd5e4448c2a79554c2d4e/circuit_synth-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 01:37:53",
"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"
}
JSON
