Python Quickstart

Step 1 — Install the SDK

pip install keylightdigital-nexus

Requires only Python stdlib. No heavy dependencies. Python 3.8+ compatible.

Step 2 — Set your API key

Create an API key at /dashboard/keys, then set it as an environment variable:

export NEXUS_API_KEY="nxs_your_api_key_here"

Step 3 — Create your first trace

Wrap your agent run with a trace, and add a span for each step — LLM calls, tool uses, API fetches:

import os
from nexus_client import NexusClient

nexus = NexusClient(
    api_key=os.environ["NEXUS_API_KEY"],
    base_url="https://nexus.keylightdigital.dev",
    agent_id="my-python-agent",
)

# Start a trace for this agent run
trace = nexus.start_trace(name="Summarize document")

# Add a span for each step
span = trace.add_span(
    name="fetch_document",
    input={"url": "https://example.com/doc.pdf"},
)
# ... do work ...
span.end(output={"chars": 4200}, status="ok")

llm_span = trace.add_span(
    name="llm_summarize",
    input={"model": "gpt-4o", "prompt_tokens": 2100},
)
# ... call LLM ...
llm_span.end(output={"summary": "...", "completion_tokens": 420}, status="ok")

# Finish the trace
trace.end(status="success")

Step 4 — Handle errors

Wrap your logic in try/except and set status="error" on failure. Error traces trigger email alerts for Pro users.

trace = nexus.start_trace(name="Process order")
span = trace.add_span(name="validate_payment")

try:
    result = process_payment(order)
    span.end(output={"result": result}, status="ok")
    trace.end(status="success")
except Exception as e:
    span.end(error=str(e), status="error")
    trace.end(status="error", metadata={"error": str(e)})

Step 5 — Async support

The SDK is fully compatible with async/await. SDK calls are synchronous by default — for non-blocking async use, wrap with asyncio.to_thread():

import asyncio
import os
from nexus_client import NexusClient

nexus = NexusClient(
    api_key=os.environ["NEXUS_API_KEY"],
    base_url="https://nexus.keylightdigital.dev",
    agent_id="async-agent",
)

async def run_agent(query: str) -> str:
    trace = nexus.start_trace(name="async_query", metadata={"query": query})
    span = trace.add_span(name="llm_call", input={"query": query})
    try:
        response = await call_llm_async(query)
        span.end(output={"response": response}, status="ok")
        trace.end(status="success")
        return response
    except Exception as e:
        span.end(error=str(e), status="error")
        trace.end(status="error")
        raise

asyncio.run(run_agent("What is 2 + 2?"))

Step 6 — Add metadata for filtering

Attach arbitrary metadata to traces and spans to filter and debug in the dashboard:

trace = nexus.start_trace(
    name="research_task",
    metadata={
        "model": "claude-3-5-sonnet",
        "user_id": "usr_123",
        "session_id": "ses_abc",
        "environment": "production",
    },
)

span = trace.add_span(
    name="web_search",
    input={"query": "latest AI news", "max_results": 5},
)
results = search_web("latest AI news")
span.end(
    output={"count": len(results), "sources": [r["url"] for r in results]},
    status="ok",
)