buildwithtrace-sdk 0.1.0__tar.gz

buildwithtrace_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    if: github.repository_owner == 'elcruzo' || github.repository_owner == 'buildwithtrace'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Test
+        run: pytest -q
+
+      - name: Lint
+        run: ruff check src/

buildwithtrace_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+# Publishes buildwithtrace-sdk to PyPI on a version tag via OIDC Trusted
+# Publishing — NO PyPI token stored. Requires a Trusted Publisher on PyPI for
+# this repo + workflow (pypi.org -> your project -> Publishing, or a "pending
+# publisher" before the first release). Tag: `git tag v0.1.0 && git push origin v0.1.0`.
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write   # OIDC token for PyPI Trusted Publishing
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      # No password/token: authenticates via the PyPI OIDC trusted publisher.
+      - name: Publish to PyPI (OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

buildwithtrace_sdk-0.1.0/.github/workflows/sync-to-org.yml

@@ -0,0 +1,24 @@
+# Syncs elcruzo/trace-sdk-python -> buildwithtrace/sdk-python on push to main.
+name: Sync to Organization
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  sync:
+    if: github.repository_owner == 'elcruzo'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.ORG_PUSH_TOKEN }}
+          persist-credentials: false
+
+      - name: Push to org repo
+        env:
+          ORG_PUSH_TOKEN: ${{ secrets.ORG_PUSH_TOKEN }}
+        run: |
+          git remote add org https://x-access-token:${ORG_PUSH_TOKEN}@github.com/buildwithtrace/sdk-python.git
+          git push org HEAD:main

buildwithtrace_sdk-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.DS_Store
+
+# Local secrets — never commit (PyPI recovery codes, tokens, etc.)
+.secrets/
+
+# local dev-only (not published)
+publish.sh
+AGENTS.md

buildwithtrace_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+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`).

buildwithtrace_sdk-0.1.0/README.md

@@ -0,0 +1,50 @@
+# 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`).

buildwithtrace_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "buildwithtrace-sdk"
+dynamic = ["version"]
+description = "Trace Python SDK — programmatic client for the Trace AI EDA backend."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Trace", email = "hello@buildwithtrace.com" }]
+keywords = ["trace", "eda", "pcb", "kicad", "sdk", "ai"]
+dependencies = [
+    "httpx>=0.27.0",
+    "httpx-sse>=0.4.0",
+    "keyring>=25.0",
+    "platformdirs>=4.0",
+    "tomli-w>=1.0",
+    "tomli>=2.0; python_version < '3.11'",
+    # rich is used only by the engine binary downloader's progress UI (lazy import).
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6.0",
+]
+
+[project.urls]
+Homepage = "https://buildwithtrace.com"
+Repository = "https://github.com/buildwithtrace/sdk-python"
+
+# Single source of truth for the version: read __version__ from the package.
+[tool.hatch.version]
+path = "src/buildwithtrace_sdk/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/buildwithtrace_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+# E501 (line length) is advisory — many lines are long error/URL strings we
+# intentionally don't wrap. All correctness rules (F*, etc.) stay on.
+ignore = ["E501"]

buildwithtrace_sdk-0.1.0/src/buildwithtrace_sdk/__init__.py

@@ -0,0 +1,26 @@
+"""Trace Python SDK — programmatic access to Trace AI for PCB/schematic design.
+
+    from buildwithtrace_sdk import Trace
+    client = Trace(api_key="...")
+    sym = client.generate_symbol("LM7805 5V regulator")
+"""
+
+from buildwithtrace_sdk.client import (
+    GenerateResult,
+    SearchResult,
+    TextResult,
+    Trace,
+    TraceError,
+    TraceToolExecutionError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Trace",
+    "GenerateResult",
+    "SearchResult",
+    "TextResult",
+    "TraceError",
+    "TraceToolExecutionError",
+]

buildwithtrace_sdk-0.1.0/src/buildwithtrace_sdk/api/__init__.py

@@ -0,0 +1,181 @@
+"""HTTP API client — httpx with auth, retry, environment switching."""
+
+import asyncio
+import logging
+from typing import Any, AsyncIterator, Optional
+
+import httpx
+
+from buildwithtrace_sdk.config import get_api_base_url, get_backend_url
+from buildwithtrace_sdk.config.credentials import get_access_token, get_refresh_token, store_tokens
+
+logger = logging.getLogger(__name__)
+
+REQUEST_TIMEOUT = 30.0
+CONNECT_TIMEOUT = 10.0
+STREAM_TIMEOUT = 300.0
+MAX_RETRIES = 3
+RETRY_BACKOFF = [1.0, 2.0, 4.0]
+
+
+class TraceAPIError(Exception):
+    """Raised when the Trace API returns an error."""
+
+    def __init__(self, status_code: int, message: str, code: str = ""):
+        self.status_code = status_code
+        self.message = message
+        self.code = code
+        super().__init__(f"[{status_code}] {message}")
+
+
+class AuthRequiredError(TraceAPIError):
+    """Raised when authentication is required but no token available."""
+
+    def __init__(self):
+        super().__init__(401, "Authentication required. Run: buildwithtrace auth login")
+
+
+def _get_headers() -> dict[str, str]:
+    """Build request headers with auth token if available."""
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": "trace-cli/0.1.0",
+    }
+    token = get_access_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+async def _try_refresh_token() -> bool:
+    """Attempt to refresh the access token. Returns True on success."""
+    refresh_token = get_refresh_token()
+    if not refresh_token:
+        return False
+
+    backend_url = get_backend_url()
+    async with httpx.AsyncClient(timeout=httpx.Timeout(REQUEST_TIMEOUT, connect=CONNECT_TIMEOUT)) as client:
+        try:
+            resp = await client.post(
+                f"{backend_url}/api/v3/auth/refresh",
+                json={"refresh_token": refresh_token},
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                store_tokens(
+                    access_token=data["access_token"],
+                    refresh_token=data["refresh_token"],
+                    user_data=data.get("user"),
+                )
+                return True
+        except httpx.HTTPError:
+            pass
+    return False
+
+
+async def request(
+    method: str,
+    path: str,
+    json: Optional[dict] = None,
+    params: Optional[dict] = None,
+    require_auth: bool = True,
+    timeout: float = REQUEST_TIMEOUT,
+) -> dict[str, Any]:
+    """Make an API request with auth, retry, and error handling."""
+    if require_auth and not get_access_token():
+        raise AuthRequiredError()
+
+    url = f"{get_api_base_url()}{path}"
+
+    for attempt in range(MAX_RETRIES):
+        headers = _get_headers()
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            try:
+                resp = await client.request(
+                    method, url, json=json, params=params, headers=headers
+                )
+            except httpx.ConnectError:
+                raise TraceAPIError(
+                    0, f"Cannot connect to {get_backend_url()}. Run: buildwithtrace doctor"
+                )
+            except httpx.TimeoutException:
+                if attempt < MAX_RETRIES - 1:
+                    await asyncio.sleep(RETRY_BACKOFF[attempt])
+                    continue
+                raise TraceAPIError(408, "Request timed out")
+
+        if resp.status_code == 401:
+            if await _try_refresh_token():
+                continue
+            raise TraceAPIError(401, "Session expired. Run: buildwithtrace auth login")
+
+        if resp.status_code == 429:
+            if attempt < MAX_RETRIES - 1:
+                retry_after = float(resp.headers.get("Retry-After", RETRY_BACKOFF[attempt]))
+                logger.info(f"Rate limited. Retrying in {retry_after}s...")
+                await asyncio.sleep(retry_after)
+                continue
+            raise TraceAPIError(429, "Rate limited. Try again later.")
+
+        if resp.status_code == 402:
+            raise TraceAPIError(402, "Quota exceeded. Run: buildwithtrace billing upgrade")
+
+        if resp.status_code >= 500:
+            if attempt < MAX_RETRIES - 1:
+                await asyncio.sleep(RETRY_BACKOFF[attempt])
+                continue
+            raise TraceAPIError(resp.status_code, "Server error. Try again later.")
+
+        if resp.status_code >= 400:
+            ct = resp.headers.get("content-type", "")
+            if "application/json" in ct:
+                body = resp.json()
+            else:
+                body = {"detail": resp.text[:200]}
+            raise TraceAPIError(
+                resp.status_code,
+                body.get("detail", body.get("message", resp.text[:200])),
+                code=body.get("code", ""),
+            )
+
+        ct = resp.headers.get("content-type", "")
+        if "application/json" in ct:
+            return resp.json()
+        return {"_raw": resp.text, "_status": resp.status_code}
+
+    raise TraceAPIError(0, "Max retries exceeded")
+
+
+async def stream_sse(
+    path: str,
+    json: Optional[dict] = None,
+    require_auth: bool = True,
+) -> AsyncIterator[dict]:
+    """Stream SSE events from the backend (for /chat/stream, /pcb/autoroute)."""
+    from httpx_sse import aconnect_sse
+
+    if require_auth and not get_access_token():
+        raise AuthRequiredError()
+
+    url = f"{get_api_base_url()}{path}"
+    headers = _get_headers()
+
+    async with httpx.AsyncClient(timeout=httpx.Timeout(STREAM_TIMEOUT, connect=10.0)) as client:
+        async with aconnect_sse(client, "POST", url, json=json, headers=headers) as event_source:
+            async for event in event_source.aiter_sse():
+                if event.data:
+                    try:
+                        import json as json_mod
+                        yield {"event": event.event, "data": json_mod.loads(event.data)}
+                    except (ValueError, TypeError):
+                        yield {"event": event.event, "data": event.data}
+
+
+async def get(path: str, **kwargs) -> dict:
+    """GET request shorthand."""
+    return await request("GET", path, **kwargs)
+
+
+async def post(path: str, **kwargs) -> dict:
+    """POST request shorthand."""
+    return await request("POST", path, **kwargs)