Metadata-Version: 2.4
Name: kicad-sch-api
Version: 0.0.2
Summary: Professional KiCAD schematic manipulation library with exact format preservation and AI agent integration
Author-email: Circuit-Synth <info@circuit-synth.com>
Maintainer-email: Circuit-Synth <info@circuit-synth.com>
License: MIT
Project-URL: Homepage, https://github.com/circuit-synth/kicad-sch-api
Project-URL: Documentation, https://circuit-synth.github.io/kicad-sch-api/
Project-URL: Repository, https://github.com/circuit-synth/kicad-sch-api.git
Project-URL: Bug Reports, https://github.com/circuit-synth/kicad-sch-api/issues
Project-URL: Changelog, https://github.com/circuit-synth/kicad-sch-api/blob/main/CHANGELOG.md
Keywords: kicad,schematic,eda,electronics,circuit-design,ai,automation,pcb
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sexpdata>=0.0.3
Requires-Dist: typing-extensions>=4.0.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Dynamic: license-file

# kicad-sch-api

**Professional KiCAD Schematic Manipulation Library with AI Agent Integration**


## 🚀 Key Features

- **📋 Exact Format Preservation**: Output matches KiCAD's native formatting exactly
- **⚡ High Performance**: Optimized for large schematics with symbol caching
- **🔧 Enhanced API**: Intuitive object-oriented interface with bulk operations
- **📚 Advanced Library Management**: Multi-source symbol lookup and caching
- **✅ Professional Validation**: Comprehensive error collection and reporting
- **🎯 KiCAD 9 Optimized**: Built specifically for latest KiCAD format

## 🆚 vs. Existing Solutions

| Feature | kicad-sch-api | kicad-skip | KiCAD Official API |
|---------|---------------|------------|-------------------|
| **Schematic Support** | ✅ Full | ✅ Full | ❌ PCB Only |
| **Format Preservation** | ✅ Exact | ❌ Basic | N/A |
| **Performance** | ✅ Optimized | ⚠️ Basic | N/A |
| **Library Management** | ✅ Advanced | ⚠️ Basic | N/A |
| **Runtime Dependencies** | ❌ None | ❌ None | ✅ KiCAD Required |

## 📦 Installation

```bash
# Install from PyPI (coming soon)
pip install kicad-sch-api

# Or install from source
git clone https://github.com/circuit-synth/kicad-sch-api.git
cd kicad-sch-api/python
pip install -e .

npm install
npm run build
```

## 🎯 Quick Start

### Basic Schematic Manipulation

```python
import kicad_sch_api as ksa

# Load existing schematic
sch = ksa.load_schematic('my_circuit.kicad_sch')

# Add components
resistor = sch.components.add('Device:R', ref='R1', value='10k', pos=(100, 100))
capacitor = sch.components.add('Device:C', ref='C1', value='0.1uF', pos=(150, 100))

# Update properties
resistor.footprint = 'Resistor_SMD:R_0603_1608Metric'
resistor.set_property('MPN', 'RC0603FR-0710KL')

# Connect components
sch.add_wire(resistor.get_pin_position('2'), capacitor.get_pin_position('1'))

# Save with exact format preservation
sch.save()  # Preserves original formatting exactly
```

### Advanced Operations

```python
# Bulk operations for large schematics
resistors = sch.components.filter(lib_id='Device:R')
for r in resistors:
    r.set_property('Tolerance', '1%')

# Search and analysis
power_components = sch.components.in_area(0, 0, 50, 50)
high_value_resistors = sch.components.filter(
    lib_id='Device:R', 
    value_pattern='*k'  # Components with 'k' in value
)

# Validation and error checking
issues = sch.validate()
if issues:
    print(f"Found {len(issues)} validation issues:")
    for issue in issues:
        print(f"  {issue}")

# Performance statistics
stats = sch.get_performance_stats()
print(f"Cache hit rate: {stats['symbol_cache']['hit_rate_percent']}%")
```



```json
{
  "kicad-sch": {
    "command": "node",
    "env": {
      "PYTHON_PATH": "python3",
      "KICAD_SCH_API_PATH": "/path/to/kicad-sch-api/python"
    }
  }
}
```

Then use natural language with your AI agent:

```
User: "Create a voltage divider circuit with two 10k resistors"

Claude: I'll create a voltage divider circuit for you.

1. Create new schematic
2. Add R1 (10k resistor) at (100, 100)
3. Add R2 (10k resistor) at (100, 150) 
4. Connect components with wires
5. Add voltage input and output labels
6. Save schematic with exact formatting

Your voltage divider circuit is ready! The circuit provides 50% voltage division
with two 10kΩ resistors in series configuration.
```

## 🏗️ Architecture

The library consists of two main components:

### Python Library (Core)
- **Enhanced Object Model**: Intuitive API with fast component collections
- **Exact Format Preservation**: S-expression writer that matches KiCAD output
- **Symbol Caching**: High-performance library symbol management
- **Comprehensive Validation**: Error collection and professional reporting

- **Python Bridge**: Reliable subprocess communication
- **Comprehensive Tools**: 15+ tools for complete schematic manipulation
- **Professional Error Handling**: Detailed error context for AI agents

## 🧪 Testing & Quality

```bash
# Python tests
cd python
python -m pytest tests/ -v --cov=kicad_sch_api

npm test

# Format preservation tests
python -m pytest tests/test_format_preservation.py -v
```

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🔗 Related Projects

- **[circuit-synth](https://github.com/circuit-synth/circuit-synth)**: Comprehensive circuit design automation
- **[kicad-skip](https://github.com/psychogenic/kicad-skip)**: Foundation S-expression parser

---

**Built with ❤️ by the Circuit-Synth team**
