Metadata-Version: 2.4
Name: buildwithtrace-sdk
Version: 0.1.0
Summary: Trace Python SDK — programmatic client for the Trace AI EDA backend.
Project-URL: Homepage, https://buildwithtrace.com
Project-URL: Repository, https://github.com/buildwithtrace/sdk-python
Author-email: Trace <hello@buildwithtrace.com>
License: MIT
Keywords: ai,eda,kicad,pcb,sdk,trace
Requires-Python: >=3.10
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# buildwithtrace-sdk

Python SDK for [Trace](https://buildwithtrace.com) — programmatic access to the Trace AI EDA backend (symbol/footprint generation, semantic component search, and chat/agent over your KiCad designs).

```bash
pip install buildwithtrace-sdk
```

```python
from buildwithtrace_sdk import Trace

client = Trace(api_key="...")  # or TRACE_API_KEY env var

sym = client.generate_symbol("LM7805 5V voltage regulator")
sym.save("./symbols/")                      # writes LM7805.kicad_sym

fp = client.generate_footprint("SOIC-8 3.9x4.9mm")
fp.save("./footprints/")                    # writes SOIC-8.kicad_mod

for r in client.search("3.3V LDO", type="symbol", limit=5):
    print(r.name, r.library)

# Read-only Q&A about a design:
ans = client.ask("What ERC violations exist?", project_dir="./my-board/")
print(ans.text)

# Agent mode — the SDK runs the client-side tool loop locally (sandboxed):
res = client.chat("Add a 100nF decoupling cap on VCC", mode="agent", project_dir="./my-board/")
print(res.text)
```

Get an API key: `buildwithtrace auth token` (CLI) or buildwithtrace.com/dashboard/settings > Developer.

## Notes

- `chat(mode="agent")` / `"plan"` produce file-editing tool calls. The SDK runs a
  standalone, client-side tool-execution loop: when you pass `project_dir`, file ops
  (read/write/search_replace/list_dir/grep/delete) and local ERC/DRC/export run on your
  machine with the SAME safety as the desktop/CLI (extension allowlist, project-dir
  sandbox, symlink-safe path resolution), looping until the turn completes. Writes are
  auto-approved (programmatic agent). Without a `project_dir`, an emitted tool call
  raises `TraceToolExecutionError` (file ops can't be sandboxed); GUI-only tools
  (canvas snapshots, layer toggles) are always reported as unsupported.
- `.trace_sch`/`.trace_pcb` writes are converted to KiCad format via the bundled
  converter when available; if the converter isn't importable the file is still written
  and the turn continues (conversion is reported as failed, not fatal).
- BYOK supported via `chat(..., llm_provider=, llm_api_key=, llm_model_id=)`.

Extracted from the `buildwithtrace` CLI repo. The CLI re-exports `Trace` for
backward compatibility (`from buildwithtrace import Trace`).
