buildwithtrace-sdk 0.1.0__py3-none-any.whl

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

buildwithtrace_sdk/api/auth.py

@@ -0,0 +1,259 @@
+"""OAuth browser-based authentication flow."""
+
+import json
+import logging
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from threading import Thread
+from typing import Optional
+from urllib.parse import parse_qs, unquote, urlparse
+
+from buildwithtrace_sdk.config import get_backend_url
+from buildwithtrace_sdk.config.credentials import store_tokens
+
+logger = logging.getLogger(__name__)
+
+CALLBACK_TIMEOUT = 120
+
+
+class _OAuthCallbackHandler(BaseHTTPRequestHandler):
+    """HTTP handler that receives the OAuth callback."""
+
+    token_data: Optional[dict] = None
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        params = parse_qs(parsed.query)
+
+        if "code" in params:
+            self.server._auth_code = params["code"][0]
+            self._respond_success()
+        elif "token" in params or "access_token" in params:
+            token = params.get("token", params.get("access_token", [None]))[0]
+            refresh = params.get("refresh_token", [None])[0]
+            user_raw = params.get("user", [None])[0]
+            user_data = None
+            if user_raw:
+                try:
+                    user_data = json.loads(unquote(user_raw))
+                except (json.JSONDecodeError, TypeError):
+                    pass
+            self.server._token_data = {
+                "access_token": token,
+                "refresh_token": refresh,
+                "user": user_data,
+            }
+            self._respond_success()
+        elif "error" in params:
+            error = params["error"][0]
+            self.server._auth_error = error
+            self._respond_error(error)
+        else:
+            self._respond_error("No token or code received")
+
+    def _respond_success(self):
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        self.wfile.write(b"""<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+<h1>Authenticated!</h1><p>You can close this tab and return to your terminal.</p>
+<script>window.close()</script></body></html>""")
+
+    def _respond_error(self, error: str):
+        self.send_response(400)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        self.wfile.write(f"""<!DOCTYPE html><html><body style="font-family:system-ui;text-align:center;padding:60px">
+<h1>Authentication Failed</h1><p>{error}</p></body></html>""".encode())
+
+    def log_message(self, format, *args):
+        pass
+
+
+def _find_free_port() -> int:
+    """Find a free port for the local callback server."""
+    import socket
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+async def browser_oauth_login(provider: str = "google") -> dict:
+    """Run browser-based OAuth flow. Returns token data dict."""
+    port = _find_free_port()
+    callback_url = f"http://localhost:{port}/callback"
+
+    server = HTTPServer(("127.0.0.1", port), _OAuthCallbackHandler)
+    server._auth_code = None
+    server._token_data = None
+    server._auth_error = None
+    server.timeout = CALLBACK_TIMEOUT
+
+    def _serve_until_result():
+        for _ in range(5):
+            server.handle_request()
+            if server._token_data or server._auth_code or server._auth_error:
+                break
+
+    thread = Thread(target=_serve_until_result, daemon=True)
+    thread.start()
+
+    backend_url = get_backend_url()
+    auth_url = f"{backend_url}/api/v3/auth/{provider}/login?callback=cli&redirect_uri={callback_url}"
+
+    webbrowser.open(auth_url)
+
+    thread.join(timeout=CALLBACK_TIMEOUT)
+    server.server_close()
+
+    if server._auth_error:
+        raise RuntimeError(f"OAuth failed: {server._auth_error}")
+
+    if server._token_data:
+        store_tokens(
+            access_token=server._token_data["access_token"],
+            refresh_token=server._token_data["refresh_token"],
+            user_data=server._token_data.get("user"),
+        )
+        return server._token_data
+
+    if server._auth_code:
+        return await _exchange_code(server._auth_code)
+
+    raise RuntimeError(f"OAuth timed out after {CALLBACK_TIMEOUT}s. Try again or use: buildwithtrace auth login --email")
+
+
+async def _exchange_code(code: str) -> dict:
+    """Exchange an OAuth code for tokens via the backend."""
+    import httpx
+    backend_url = get_backend_url()
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.post(
+            f"{backend_url}/api/v3/auth/exchange-code",
+            json={"code": code},
+        )
+        if resp.status_code != 200:
+            raise RuntimeError(f"Code exchange failed: {resp.text}")
+
+        data = resp.json()
+        store_tokens(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            user_data=data.get("user"),
+        )
+        return data
+
+
+async def email_password_login(email: str, password: str) -> dict:
+    """Login with email and password directly."""
+    import httpx
+    backend_url = get_backend_url()
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.post(
+            f"{backend_url}/api/v3/auth/login",
+            json={"email": email, "password": password},
+        )
+        if resp.status_code != 200:
+            body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
+            raise RuntimeError(body.get("detail", f"Login failed: {resp.status_code}"))
+
+        data = resp.json()
+        store_tokens(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            user_data=data.get("user"),
+        )
+        return data
+
+
+def _cli_platform() -> str:
+    """Map the OS to the backend's platform vocabulary (macos|windows|linux)."""
+    import platform as _p
+    system = _p.system()
+    if system == "Darwin":
+        return "macos"
+    if system == "Windows":
+        return "windows"
+    if system == "Linux":
+        return "linux"
+    return system.lower() or "unknown"
+
+
+def _cli_version() -> str:
+    """Reported app version (best-effort).
+
+    Prefers the installed `buildwithtrace` CLI dist (when this SDK runs inside the
+    CLI wheel), then falls back to this SDK's own version, then "unknown". After
+    the SDK-as-core split this code ships in `buildwithtrace-sdk`, so the bare
+    `buildwithtrace` lookup alone would report "unknown" when used standalone.
+    """
+    from importlib.metadata import version
+
+    for dist in ("buildwithtrace", "buildwithtrace-sdk"):
+        try:
+            return version(dist)
+        except Exception:
+            continue
+    try:
+        from buildwithtrace_sdk import __version__
+        return __version__
+    except Exception:
+        return "unknown"
+
+
+async def register_device() -> None:
+    """Link this CLI install to the authenticated account (best-effort).
+
+    Sends the stable device_id + platform/version so the backend can record the
+    device and attempt to attribute a prior anonymous download to it. Never
+    raises -- linking is a nice-to-have, not part of the login contract.
+    """
+    import platform as _p
+
+    from buildwithtrace_sdk.api import post
+    from buildwithtrace_sdk.config import get_or_create_device_id
+
+    try:
+        await post(
+            "/auth/register-device",
+            json={
+                "device_id": get_or_create_device_id(),
+                "device_platform": _cli_platform(),
+                "os_version": _p.platform(),
+                "app_version": _cli_version(),
+                "linked_via": "cli",
+            },
+        )
+    except Exception as e:  # noqa: BLE001 - best-effort, must never break login
+        logger.debug("CLI device registration failed: %s", e)
+
+
+async def token_login(token: str) -> dict:
+    """Login with a pre-existing API token (for CI)."""
+    import httpx
+    backend_url = get_backend_url()
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        resp = await client.get(
+            f"{backend_url}/api/v3/auth/verify",
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        if resp.status_code != 200:
+            raise RuntimeError("Token verification failed")
+
+        data = resp.json()
+        if not data.get("valid"):
+            raise RuntimeError("Invalid or expired token")
+
+        store_tokens(
+            access_token=token,
+            refresh_token="",
+            user_data={
+                "id": data.get("user_id"),
+                "email": data.get("email"),
+                "full_name": data.get("full_name"),
+            },
+        )
+        return data

buildwithtrace_sdk/api/rest.py

@@ -0,0 +1,103 @@
+"""Synchronous (non-SSE) REST calls to the Trace backend.
+
+Used by the generation commands + MCP tools, which target the synchronous REST shim
+`POST /api/<version>/components/generate/{symbol,footprint}` (version from
+get_api_base_url(), default "latest") instead of the agent SSE stream — the agent's
+`generate_component` tool is gated to the newest API version, and the REST shim is the
+stable, version-independent path the CLI/SDK use for generation.
+"""
+
+import httpx
+
+from buildwithtrace_sdk.api.sse import _actionable_error
+from buildwithtrace_sdk.config import get_api_base_url
+from buildwithtrace_sdk.config.credentials import get_access_token, refresh_token
+
+# Server-side budget: datasheet parse (up to 420s) + generation (up to 180s). Give the
+# client generous headroom over that so we surface the server's own timeout, not ours.
+GENERATE_TIMEOUT = 660.0
+
+
+class RestError(Exception):
+    """A non-streaming REST call failed. `message` is already user-actionable."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+async def post_json(path: str, body: dict, timeout: float = 60.0) -> dict:
+    """POST JSON to `{api_base}{path}` with auth; refresh once on 401. Returns parsed JSON.
+
+    Raises RestError (with an actionable message) on any failure.
+    """
+    token = get_access_token()
+    if not token:
+        raise RestError("Not authenticated.\n  Fix: Run `buildwithtrace auth login`", 401)
+
+    url = f"{get_api_base_url()}{path}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+        "User-Agent": "trace-cli/0.1.0",
+    }
+    client_timeout = httpx.Timeout(timeout, connect=10.0)
+
+    for attempt in range(2):  # one retry to refresh an expired token
+        try:
+            async with httpx.AsyncClient(timeout=client_timeout) as client:
+                resp = await client.post(url, json=body, headers=headers)
+
+            if resp.status_code == 401 and attempt == 0:
+                new_token = await refresh_token()
+                if new_token:
+                    headers["Authorization"] = f"Bearer {new_token}"
+                    continue
+                raise RestError(_actionable_error(401, ""), 401)
+
+            if resp.status_code >= 400:
+                body_text = resp.text[:200] if resp.text else ""
+                raise RestError(_actionable_error(resp.status_code, body_text), resp.status_code)
+
+            return resp.json()
+        except httpx.ConnectError as e:
+            raise RestError(
+                "Cannot connect to Trace backend.\n  Fix: Check your network, or run `buildwithtrace doctor`."
+            ) from e
+        except httpx.TimeoutException as e:
+            raise RestError(
+                f"Request timed out after {int(timeout)}s.\n  Fix: Retry; large datasheets can take a while."
+            ) from e
+
+    raise RestError(_actionable_error(401, ""), 401)
+
+
+async def generate_component(
+    kind: str,
+    description: str,
+    datasheet_url: str | None = None,
+    package_type: str | None = None,
+    additional_instructions: str | None = None,
+) -> dict:
+    """Generate a symbol or footprint via the synchronous REST shim.
+
+    Returns the backend result dict (symbol: `kicad_sym`, `name`, ...; footprint:
+    `kicad_mod`, `name`, ...). Raises RestError on failure.
+    """
+    if kind not in ("symbol", "footprint"):
+        raise ValueError(f"kind must be 'symbol' or 'footprint', got {kind!r}")
+
+    # The shim requires description >= 5 chars; pad a bare/short part number.
+    desc = description.strip()
+    if len(desc) < 5:
+        desc = f"{desc} component".strip()
+
+    body: dict = {"description": desc}
+    if datasheet_url:
+        body["datasheet_url"] = datasheet_url
+    if additional_instructions:
+        body["additional_instructions"] = additional_instructions
+    if kind == "footprint" and package_type:
+        body["package_type"] = package_type
+
+    return await post_json(f"/components/generate/{kind}", body, timeout=GENERATE_TIMEOUT)