Metadata-Version: 2.4
Name: kaicad
Version: 0.2.0
Summary: AI-powered KiCad schematic editor
Author: Gunes Yilmaz
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/hunes3d/kAIcad
Project-URL: Repository, https://github.com/hunes3d/kAIcad
Project-URL: Issues, https://github.com/hunes3d/kAIcad/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kicad-skip==0.2.5
Requires-Dist: sexpdata<2.0.0,>=1.0.0
Requires-Dist: mcp<3.0.0,>=2.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: openai<2.0.0,>=1.0.0
Requires-Dist: flask<4.0.0,>=3.0.0
Requires-Dist: flask-wtf<2.0.0,>=1.2.0
Requires-Dist: flask-limiter<4.0.0,>=3.5.0
Requires-Dist: waitress<4.0.0,>=3.0.2
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: typer<1.0.0,>=0.9.0
Requires-Dist: watchdog<5.0.0,>=3.0.0
Requires-Dist: keyring<26.0.0,>=24.0.0
Requires-Dist: argon2-cffi<26.0.0,>=25.1.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: pywin32>=312; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.2.0; extra == "dev"
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov<6.0.0,>=4.0.0; extra == "dev"
Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.8.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.13.0; extra == "dev"
Requires-Dist: detect-secrets<2.0.0,>=1.5.0; extra == "dev"
Requires-Dist: pip-audit<3.0.0,>=2.10.1; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "test"
Requires-Dist: pytest-cov<6.0.0,>=4.0.0; extra == "test"
Dynamic: license-file

﻿<div align="center">
  <img src="assets/kaicad.svg" alt="kAIcad Logo" width="320" />

  <h1>kAIcad</h1>
  <p><strong>AI‑powered sidecar for KiCad schematics</strong></p>

  <p>
    <a href="https://github.com/hunes3d/kAIcad/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/hunes3d/kAIcad/actions/workflows/ci.yml/badge.svg"></a>
    <img alt="Python" src="https://img.shields.io/badge/python-3.10+-blue.svg">
    <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg"></a>
    <img alt="Version" src="https://img.shields.io/badge/version-0.2.0-green.svg">
  </p>

  <p>Describe a change in plain English → get a plan → apply it to your <code>.kicad_sch</code> file.</p>
</div>

## What it does

- “Add LED and 1k resistor between VCC and GND” → places LED + resistor and wires nets
- “Connect U1 pin 3 to R5 pin 2” → makes the connection via wire/label
- After applying, it can run ERC and export PDF/netlist with KiCad CLI

## Highlights

- 🤖 Policy-gated planning with `gpt-5.6-luna` at reasoning effort `max`
- 🖥️ Three UIs: CLI, Desktop (Tkinter), and a production Web service with a loopback-only backend
- 📚 Direct symbol import from configured native KiCad libraries
- 🛡️ Transactional apply with validation, backup, and atomic replacement
- 🔍 Inspect components, nets, and hierarchical sheets
- ✅ Optional post‑apply: ERC, PDF, and netlist export
- 🔌 Local stdio MCP v2 server with read-only inspect/plan/verify tools and receipt-gated apply
- 🔐 Stores API keys in your OS keychain when available
- 🌐 Opt-in single-account remote login behind Tailscale or another same-host HTTPS proxy

## Quick start

### Windows (PowerShell)

Prerequisites:
- Python 3.10+
- KiCad 8 or 9 CLI on PATH (verify with: `kicad-cli --version`)
- One planner auth path: an OpenAI API key with Luna access, or official Codex CLI `codex login` with ChatGPT

#### Option A — pipx (recommended):

```powershell
pipx install git+https://github.com/hunes3d/kAIcad.git

# Choose subscription auth (API-key mode can instead use the OS keyring or process environment)
codex login
$env:KAICAD_AUTH_MODE = "codex_subscription"

# Launch the interactive launcher to choose your UI
kaicad        # Interactive menu to select CLI, Desktop, or Web

# Or launch directly
kaicad --cli      # Command-line interface
kaicad --desktop  # Desktop GUI (Tkinter)
kaicad-cli    # Same as 'kaicad --cli'
kaicad-desk   # Same as 'kaicad --desktop'

# Production web service: store a fresh session secret, then run in the foreground
kaicad-serve --generate-secret
kaicad-serve --project C:\path\to\project

# Authenticated public access from a source checkout (password is prompted twice without echo)
& .\scripts\remote-access.ps1 -Action ProvisionAccount -Username <account>
$sourceArchive = "$env:LOCALAPPDATA\kAIcad\releases\kaicad-source-$(git rev-parse --short HEAD).tar.gz"
New-Item -ItemType Directory -Force (Split-Path $sourceArchive) | Out-Null
git archive --format=tar.gz --output=$sourceArchive HEAD
& .\scripts\remote-access.ps1 -Action StartBackend -Username <account> -Project C:\path\to\project -SourceArchive $sourceArchive
# In a second terminal; explicitly confirms public Tailscale Funnel exposure:
& .\scripts\remote-access.ps1 -Action EnablePublic -ConfirmPublicExposure
```

The exposure action requires loopback `/healthz` and `/readyz` JSON 200 before it changes Tailscale configuration.

#### Option B — dev install:

```powershell
git clone https://github.com/hunes3d/kAIcad.git
cd kAIcad
python -m venv .venv
.\.venv\Scripts\activate
pip install -e .

Copy-Item .env.example .env
# Edit .env to select API-key or Codex-subscription authentication

# Launch directly
python -m kaicad.ui.launcher  # Interactive menu
python -m kaicad.ui.cli       # CLI
python -m kaicad.ui.desktop   # Desktop GUI
# `kaicad-web` is a development server; use `kaicad-serve` for production.
```

### macOS / Linux (Bash/Zsh)

Prerequisites:
- Python 3.10+
- KiCad 8 or 9 CLI on PATH (verify with: `kicad-cli --version`)
  - macOS: Install KiCad.app, then add to PATH:  
    `export PATH="/Applications/KiCad/KiCad.app/Contents/MacOS:$PATH"`
  - Linux: Install via package manager (e.g., `apt install kicad` on Ubuntu/Debian)
- One planner auth path: an OpenAI API key with Luna access, or official Codex CLI `codex login` with ChatGPT

#### Option A — pipx (recommended):

```bash
pipx install git+https://github.com/hunes3d/kAIcad.git

codex login
export KAICAD_AUTH_MODE=codex_subscription

# Launch your preferred UI
kaicad-desk  # Desktop GUI
# Production web: kaicad-serve --generate-secret && kaicad-serve --project /path/to/project
```

#### Option B — dev install:

```bash
git clone https://github.com/hunes3d/kAIcad.git
cd kAIcad
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

cp .env.example .env
# Edit .env to select API-key or Codex-subscription authentication

python -m kaicad.ui.desktop   # Desktop GUI
# python -m kaicad.ui.cli      # CLI
```

## VS Code tasks

Tasks are preconfigured:
- sidecar — CLI
- desktop-gui — Desktop GUI
- web-gui — Web UI
- erc / pdf / netlist — KiCad CLI helpers
- plan:demo — Generate a demo plan
- e2e:export-pdf — Plan → apply → export PDF

Use Ctrl+Shift+B to open the task picker.

## Configuration

Use a local `.env` file or environment variables:

- OPENAI_API_KEY — required only in API-key mode; billed as OpenAI API usage
- KAICAD_AUTH_MODE — `openai_api_key` or `codex_subscription`
- OPENAI_MODEL — fixed by product policy to `gpt-5.6-luna`
- OPENAI_REASONING_EFFORT — fixed by product policy to `max`
- OPENAI_TEMPERATURE — default 0.0
- KAICAD_SESSION_SECRET — strong production Web session secret; prefer `kaicad-serve --generate-secret` (OS keyring)
- KAICAD_STATE_DIR — optional absolute private Web state directory
- KAICAD_CLI_PATH — optional explicit `kicad-cli` executable path
- KAICAD_PROJECT — default project path
- KAICAD_APPROVAL_SECRET — private 32+ byte HMAC secret required only for destructive MCP apply

See `.env.example` for a ready-to-copy template.

For local and authenticated remote deployment, account rotation/revocation, health checks, backups, rollback, and
incident response, follow the [production runbook](docs/production.md). `kaicad --web` delegates to the production
runtime; `kaicad-web --dev` and `python -m kaicad.ui.web.app --dev` are development-only. The kAIcad backend always
binds loopback. Remote mode requires `--public-origin`, `--remote-user`, a pinned `--project`, an isolated
`--state-dir`, the deployed revision's `--source-archive`, and a same-host HTTPS proxy; never bind the application to a
LAN or public address.

ChatGPT subscription login is not generic API authentication or API billing. The `codex_subscription` provider invokes
the official Codex CLI after `codex login`; kAIcad never reads Codex or browser tokens itself. Select
`KAICAD_AUTH_MODE=codex_subscription` for that path, or `openai_api_key` for Responses API billing. Both paths force
Luna/max. See
[Planning, approval, ERC, and local MCP](docs/automation.md).

## Local MCP server

Install the package, set `KAICAD_PROJECT` to the project directory containing one top-level `.kicad_pro` and its
same-stem root schematic, and configure your MCP host to run `kaicad-mcp`. Inspect, plan, and verify are read-only. Apply requires a separately issued receipt bound to the exact
plan and source snapshot; the server intentionally has no approve tool. Export that receipt through the interactive
`kaicad-approve --schematic ... --plan ... --output ...` command. All paths are confined to the configured root.

See [the MCP setup and security contract](docs/automation.md#local-mcp-v2-server) for a host configuration example,
tool annotations, approval-secret handling, bulk limits, and ERC behavior.

## Dependency resolution & release checks

`pyproject.toml` is the single source of truth for runtime, test, and development dependency ranges. Install from source
with `pip install .`; for development, use `pip install -r requirements-dev.txt` (equivalent to
`pip install -e ".[dev]"`). `requirements.txt` is only a compatibility wrapper around the project metadata.

This library intentionally does not publish one universal `requirements.lock`. A lock compiled on one Python and OS
can contain the wrong environment markers or artifacts for another target. Instead, CI resolves the project metadata
and runs the full test suite on Python 3.10 through 3.14 across Windows, Linux, and macOS. The release job also builds
the wheel and source distribution, rebuilds the wheel from the source distribution, and verifies isolated MCP, UI,
provider imports, package data, and console entry points.

These bounded ranges make installs resolvable, not bit-for-bit identical over time. Applications that require an exact
environment should generate and retain a lock for each deployment Python/OS target, then test that target-specific
lock before release rather than reusing it as a universal library lock.

Run the same local checks with:

```bash
python -m pip install -e ".[dev]"
python -m pytest -q
python scripts/verify_distribution.py
```

## Tips & troubleshooting

### Common issues

- **A symbol cannot be added?**
  kAIcad imports symbols directly instead of relying on a custom kicad-skip API. It searches an existing embedded
  definition, the project `sym-lib-table`, then configured KiCad installation tables and roots. The direct importer
  supports KiCad 8 and 9 schematic grammars only. KiCad 7 schematics are rejected and must be upgraded and re-saved in
  KiCad 8 or 9; KiCad 10 is not yet supported and requires dedicated grammar fixtures and validation.
  Native `.kicad_sym` libraries (including installed `.kicad_symdir` layouts) are supported; legacy `.lib` files and
  non-file providers are not. A root schematic reused in multiple project or sheet-path contexts is ambiguous and is
  rejected rather than assigned guessed instance metadata. Any such failure leaves the schematic unchanged. See
  [Known Issues](docs/known-issues.md) for the full limits.

- **What happens if an apply fails?**
  Apply operations are staged and validated before commit. Dry runs, import/parser/writer failures, and a source file
  changed by another process do not write the schematic or create a misleading success backup. When enabled, baseline
  and staged ERC run before commit and any new error blocks the write. A successful apply then creates the backup and
  atomically replaces the source; optional PDF/netlist exports run afterward.

- **Production Web UI exits immediately?**
  Run `kaicad-serve --generate-secret`, then check `kaicad-serve --help` and the
  [production runbook](docs/production.md). The server fails closed when its secret or loopback configuration is unsafe.

- **Remote login is not ready?**
  Provision the configured username again with `kaicad-serve --provision-account <account>` and check
  `kaicad-serve --account-status <account>`. Remote startup requires an exact HTTPS public origin, a pinned project,
  and a same-host loopback proxy.

- **KiCad tools not found?**  
  - Windows: Add `C:\Program Files\KiCad\9.0\bin` to PATH and re-open your shell.
  - macOS: Add KiCad to PATH: `export PATH="/Applications/KiCad/KiCad.app/Contents/MacOS:$PATH"`
  - Linux: Ensure `kicad-cli` is installed and on PATH (e.g., `which kicad-cli`)

- **Model errors?**  
  Ensure Luna/max is configured. In API mode, confirm Responses API access. In subscription mode, run
  `codex login status` and confirm it reports ChatGPT authentication.

- **Python version issues?**  
  - Linux/macOS: Use `python3` instead of `python`
  - Verify version with: `python --version` (or `python3 --version`)

### Platform-specific notes

- **macOS**: The desktop GUI requires Tkinter (included with python.org Python, may need separate install for Homebrew Python)
- **Linux**: Install `python3-tk` package for desktop GUI support (e.g., `apt install python3-tk` on Ubuntu/Debian)
- **Windows**: Tkinter is included with standard Python installer

## Wiki

Documentation is available in the `docs/` folder:

- **[Known Issues & Workarounds](docs/known-issues.md)** — Current limitations and how to work around them ⚠️
- [Production Runbook](docs/production.md) — Local/remote startup, Tailscale exposure, account lifecycle, and rollback
- [Architecture](docs/architecture.md) — System design and module overview
- [Planning, Approval, ERC & MCP](docs/automation.md) — Model policy, bulk validation, receipts, and local MCP setup
- [Component Inspection](docs/component-inspection.md) — Querying components and nets
- [Hierarchical Sheets](docs/hierarchical-sheets.md) — Working with hierarchical designs
- [Dev Notes](docs/dev-notes.md) — Development guidelines
- [Roadmap](docs/roadmap.md) — Future plans
- [Changelog](docs/changelog.md) — Version history

Or visit the GitHub Wiki: https://github.com/hunes3d/kAIcad/wiki

## License

AGPL-3.0 — see [`LICENSE`](LICENSE).

## Acknowledgments

- **kicad-skip 0.2.5** — Stock KiCad schematic parsing and document operations
- **sexpdata** — Direct parsing and generation of native KiCad symbol s-expressions
- OpenAI — language models
- KiCad — Open‑source EDA suite
