Python SDK

The official Python SDK for smarts.bio. Supports sync and async usage, streaming responses, and all API endpoints.

Installation

pip install smarts-bio

Requires Python 3.9+. No extra dependencies needed for sync usage. Streaming usessseclient-py (included). Async support uses httpx (also included).

Quick start

from smartsbio import SmartsBio

client = SmartsBio(api_key="sk_live_...")

# Discover your workspaces
workspaces = client.workspaces.list()
ws_id = workspaces[0].id

# Run a query
response = client.query.run(
    prompt="Find BRCA1 variants associated with hereditary breast cancer",
    workspace_id=ws_id,
)
print(response.content)

Streaming

Use client.query.stream() to receive server-sent events as the agent generates its response. Ideal for long-running analyses.

from smartsbio import SmartsBio

client = SmartsBio(api_key="sk_live_...")

for chunk in client.query.stream(
    prompt="Perform a comprehensive variant analysis on the uploaded VCF file",
    workspace_id="ws_abc123",
):
    if chunk.type == "status":
        print(f"[{chunk.content}]", flush=True)
    elif chunk.type == "content":
        print(chunk.content, end="", flush=True)
    elif chunk.type == "done":
        print()  # newline at end

StreamChunk types

type	content field	Description
status	string	Agent status message (e.g., "Searching databases...")
content	string	Streamed response text fragment
tool_use	dict	Agent invoked a tool — contains tool name and input
done	None	Stream complete

Tools, files, and conversations

# List available tools
tools = client.tools.list()
for tool in tools:
    print(f"{tool.id}: {tool.description}")

# Run a tool directly
result = client.tools.run(
    tool_id="ncbi_search",
    input={"database": "pubmed", "query": "CRISPR off-target", "maxResults": 10}
)
print(result)

Error handling

from smartsbio import SmartsBio
from smartsbio.exceptions import (
    AuthenticationError,
    PermissionDeniedError,
    RateLimitError,
    APIError,
)

client = SmartsBio(api_key="sk_live_...")

try:
    response = client.query.run(prompt="Analyze this sequence...")
except AuthenticationError:
    print("Invalid or revoked API key")
except PermissionDeniedError as e:
    print(f"Key lacks required scope: {e}")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")

Configuration options

from smartsbio import SmartsBio

client = SmartsBio(
    api_key="sk_live_...",       # or set SMARTSBIO_API_KEY env var
    base_url="https://api.smarts.bio",  # default
    timeout=120,                  # seconds (default: 120)
    max_retries=3,                # automatic retries on 5xx (default: 3)
)