traceforge-pcb 1.0.0__tar.gz

traceforge_pcb-1.0.0/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# traceforge working files
+.traceforge/scratch/
+.traceforge/reports/
+
+# KiCad backups and caches
+*-backups/
+*.kicad_prl
+fp-info-cache
+*.lck
+_autosave-*
+
+# outputs generated from the examples
+examples/**/*.kicad_pro
+examples/**/*.kicad_sch
+examples/**/*.kicad_pcb
+examples/**/outputs/
+.venv

traceforge_pcb-1.0.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes. Versions follow semantic versioning. Dates are release dates.
+
+## Unreleased
+
+### Fixed
+- Installing the `mcp` extra (and so `.[dev]`) on Intel Macs no longer tries to build `cryptography`
+  from source (which needs Rust, OpenSSL and pkg-config): it stays on 48.x, the last release with
+  x86_64 macOS wheels.
+
+## 1.0.0
+
+First public release. The package is published on PyPI as `traceforge-pcb`; the import
+package and the command are still `traceforge`.
+
+### Agent and interfaces
+- Terminal agent (`traceforge`, `run`, `plan`, `ask`) with approvals, saved threads, skills, hooks,
+  background commands, image attachments, context compaction and cost metering.
+- Providers: Anthropic, OpenAI (Responses API), Gemini and local OpenAI-compatible servers; model
+  routing by kind of work.
+- MCP server for editors and agent hosts, a plugin for Claude Code, an ACP server (Zed and others),
+  a full-screen terminal UI, a LangChain Runnable, and a hosted mode with organisations, roles,
+  pooled quotas, spend caps, an audit log and OIDC sign-in.
+- Desktop app (local server, board viewer, editor, update check, PyInstaller packaging) and a KiCad
+  plugin (action plugin for KiCad 7/8, IPC plugin for KiCad 9/10).
+
+### Design, schematic and board
+- Design spec compiler: parts, footprints and pin-to-net maps become a KiCad project with a grouped,
+  wired schematic (power symbols, hierarchical sheets, layout linter) and a board with outline, net
+  classes and fab rules. Writes KiCad 7, 8, 9 and 10 files; reads KiCad 6 to 10 and Altium projects.
+- Placement by pins and function (decoupling, crystals, series parts, edge connectors, both board sides),
+  shaped outlines, cut-outs, slots, castellated edges, mounting holes, fiducials and panels.
+- Router: any layer count, per-layer roles and directions, inner signal layers, negotiated rip-up,
+  off-grid fine-pitch escapes, coupled differential pairs with length tuning and per-layer
+  impedance widths, length-matching groups, power and ground planes (split planes, pad vias,
+  stitching, island check, fill and re-check), dense-package fan-out (QFN, QFP, BGA, fine-pitch connectors),
+  net-class layer limits and keep-outs, a per-net report with impedance and reference planes.
+- Stackup model with JLCPCB presets and a closed-form impedance calculator.
+
+### Verification and outputs
+- KiCad ERC and DRC with schematic parity, built-in fab-limit, courtyard, edge-connector, silkscreen and
+  routing checks, multi-layer checks (plane gaps and splits, return vias, via stubs, balance, rings,
+  fab stackup), deterministic circuit checks, parts verification gate against datasheet pinouts.
+- `traceforge validate`: staged pre-fab review with grounded findings, JUnit output and a fix prompt.
+- Gerbers, drill, BOM (with supplier merge, alternates and sourcing brief), placement file, netlist,
+  SVG renders, 3D model assignment, SPICE simulation (ngspice, LTspice export), firmware scaffolds
+  from the pin map.
+- `traceforge bench`: an open benchmark (build, review and edit tasks) with a neutral scorer.
+
+### Known limits
+- Not every multi-layer example routes to zero open connections with zero DRC errors. Measured on KiCad 7
+  with the examples' finer clearance rules: `usb_hub_4layer` 0 open but one placer courtyard overlap;
+  `rp2040_4layer` 2 to 3 open (the +1V1 pin of the 0.4 mm QFN is boxed in); `cm_carrier_6layer` 4 open (three
+  nets cross the 0.5 mm connector fan-out band); `mcu_8layer` about 24 open (the interior balls of the 0.8 mm
+  BGA need via-in-pad, an extra-cost fab option, or finer rules than through vias allow). These four are
+  skipped in the example gate (`.ci-skip`); the numbers and causes are in `docs/multilayer-results.md`.
+  Pair lengths and skew in the route report are measured on the written board.
+- Through vias only: no blind or buried vias, no microvias. Impedance is from closed-form formulas, not a
+  field solver; the fab's own stackup has the final say. Length matching covers pairs and groups, not
+  DDR timing budgets.
+- Schematic labels can still overlap power-symbol text on dense ICs (`docs/schematics.md`).
+- JLCPCB 4/6/8 layer limits and bottom-side placement-file rotation were not verified against the fab.
+- Verified on Linux with KiCad 7, 8, 9 and 10. macOS, Windows and Python 3.14 have not been run in
+  full; the KiCad plugin has not been run in a live KiCad GUI. KiCad 7 runs with reduced checks.
+- No head-to-head benchmark scores are published.

traceforge_pcb-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for helping. Bug reports with a small KiCad project that reproduces the problem are the most useful thing you can send. The documentation index is [docs/index.md](docs/index.md).
+
+## Setup
+
+```bash
+git clone https://github.com/ashutosh-rath02/traceforge && cd traceforge
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The distribution is published as `traceforge-pcb`; the package and the command are `traceforge`. Python 3.11 or newer.
+
+Install KiCad with its standard symbol and footprint libraries to run the full test suite; tests that need KiCad skip themselves otherwise. Traceforge supports KiCad 7, 8, 9 and 10 and the suite is expected to pass on all four.
+
+## Testing
+
+```bash
+pytest -q                          # your local KiCad; the full suite takes about 15 minutes
+pytest -q tests/test_route.py      # one file while you work
+```
+
+Run the suite on every KiCad version you did not install with the official images (needs Docker; each run takes
+about 15 to 20 minutes and installs the package fresh inside the container):
+
+```bash
+scripts/ci-local.sh 8.0            # also 9.0 and 10.0; extra arguments go to pytest
+```
+
+The script runs the full test suite, then builds every example and runs KiCad ERC on it (examples with a
+`.ci-skip` file are skipped: they do not yet route to zero unrouted nets, see
+[docs/multilayer-results.md](docs/multilayer-results.md)). If `docker info` fails, start the daemon first
+(`dockerd`). The hosted CI workflows in `.github/workflows/` run the same jobs plus macOS and Windows installs;
+those two have not produced results yet, so a change that touches paths, process launching or the desktop app
+should be tried on those systems by hand if you can.
+
+Notes:
+
+- The ACP server needs `agent-client-protocol` below 1.0 (the 1.0 release changed the module API); `pyproject.toml`
+  caps it. If `tests/test_acp.py` fails with `module acp has no attribute ...`, you have 1.0 installed:
+  `pip install "agent-client-protocol>=0.12,<1.0"`.
+- Agent tests use the scripted `FakeClient` in `tests/conftest.py`, so no test calls a real API and none needs a key.
+- Router changes are measured, not eyeballed: `scripts/multilayer_baseline.py` routes the multi-layer examples and
+  reports unrouted connections and KiCad DRC errors, `scripts/speed_board.py out.yaml` writes the synthetic 150-net
+  board for timing, and `scripts/score_hard_tier.py --route --offline` scores the hard-tier reference boards. Routing
+  is time-limited, so compare several runs before claiming an improvement, and never weaken a check or a scoring rule
+  to make a number go green.
+
+## Before opening a pull request
+
+```bash
+ruff format .
+ruff check .
+pytest -q
+```
+
+- Keep changes focused, and add or update tests for behaviour changes.
+- Generated KiCad output must still pass KiCad's netlist export and DRC; `tests/test_board.py` checks this for the examples, `tests/test_tutorials.py` runs the offline commands of the tutorials.
+- If you change the system prompt or tool descriptions, describe what behaviour you expect to change and how you checked it.
+- If you change a spec option, update [docs/multilayer.md](docs/multilayer.md) or the relevant page in `docs/`, and the schema in `src/traceforge/design/spec.py`.
+
+## Good first areas
+
+- Router: dense-connector escape (the open connections on `cm_carrier_6layer`, `rp2040_4layer` and `usb_hub_4layer`), return vias next to a pair's layer changes, plane-gap-aware pair routing.
+- Schematics: label placement next to dense ICs ([docs/schematics.md](docs/schematics.md)).
+- Placement: rotation search, keeping decoupling capacitors next to their pins.
+- Fab profiles: more manufacturers, with links to their published capabilities; checking the JLCPCB 4, 6 and 8 layer limits against a real order.
+- Validation: more deterministic checks (fiducials, test points, thermal relief, acid traps).
+- Platforms: running the test suite and the desktop app on macOS and Windows, and the KiCad plugin inside a live KiCad window.

traceforge_pcb-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Traceforge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.