Metadata-Version: 2.4
Name: buildwithtrace-sdk
Version: 0.1.2
Summary: Trace Python SDK — programmatic client for the Trace AI EDA backend.
Project-URL: Homepage, https://buildwithtrace.com
Project-URL: Documentation, https://docs.buildwithtrace.com
Author-email: Trace <hello@buildwithtrace.com>
License: MIT
Keywords: ai,eda,kicad,pcb,sdk,trace
Requires-Python: >=3.10
Requires-Dist: buildwithtrace-converter>=0.1.0
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: posthog>=3.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

# Sign in once via the browser (opens the Trace login page, supports
# password + Google + GitHub + magic link, and solves the captcha there):
client = Trace.login()        # stores credentials, returns a ready client
# ...after which a bare Trace() "just works" by reading those credentials:
client = Trace()              # or Trace(api_key="...") / 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)
```

Auth options:

- `Trace.login()` — browser deeplink sign-in; persists credentials so later
  `Trace()` calls (and the `buildwithtrace` CLI) reuse them. `Trace.logout()` clears them.
- `buildwithtrace auth login` (CLI) — same browser flow.
- `Trace(api_key="...")` / `TRACE_API_KEY` / `TRACE_API_TOKEN` env — explicit token (CI/headless).
- Get a token (CI): mint a long-lived Personal Access Token with `buildwithtrace auth token --create --name ci-bot` (`trace_pat_...`, shown once), or in the dashboard (Settings → Developer). Token management requires an interactive login — a PAT can't mint/revoke tokens.

Env overrides: `TRACE_BASE_URL` (API base), `TRACE_FRONTEND_URL` (login page origin),
`TRACE_API_KEY` / `TRACE_API_TOKEN` (token), `TRACE_API_VERSION` (default `latest`),
`TRACE_LLM_PROVIDER` / `TRACE_LLM_API_KEY` / `TRACE_LLM_MODEL` (BYOK),
`TRACE_NO_ANALYTICS` / `DO_NOT_TRACK` (opt out of anonymous usage analytics).

## 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
  `buildwithtrace-converter` package (a hard dependency); if the conversion raises
  the file is still written and the turn continues (conversion is reported as
  failed, not fatal).
- BYOK via `chat(..., llm_provider=, llm_api_key=, llm_model_id=)` or the
  `TRACE_LLM_PROVIDER`/`TRACE_LLM_API_KEY`/`TRACE_LLM_MODEL` env, or the CLI's persisted
  `byok set` store (precedence: per-call args > env > store). BYOK skips Trace's cost cap
  but NOT the plan gate — `agent`/`plan` still need a trial/paid plan even with your own key
  (`ask` is free); a free account gets a `TracePlanRestrictedError`.
- Anonymous, privacy-first usage analytics (method names, durations, outcomes — never file
  contents/paths/prompts). Auto-off in CI; opt out with `TRACE_NO_ANALYTICS=1` / `DO_NOT_TRACK=1`.

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