buildwithtrace-sdk 0.1.2

Trace Python SDK — programmatic client for the Trace AI EDA backend.

buildwithtrace-sdk

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

pip install buildwithtrace-sdk

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).