Respan | Spectron

Respan is an LLM engineering platform: tracing, evals, and a gateway across many model providers. It is complementary to Spectron: Respan observes and evaluates your agent, while Spectron gives it memory. This guide runs the two together with the Python SDK (surrealdb).

Note

This is an integration guide. Respan and Spectron are separate services; the code shows how they sit side by side in one request.

Installation

pip install surrealdb openai

export SPECTRON_ENDPOINT="https://api.spectron.example"
export SPECTRON_CONTEXT="acme-prod"
export SPECTRON_API_KEY="sk-spec-..."
export RESPAN_API_KEY="..."

Route model calls through Respan, memory through Spectron

Point your model client's base URL at the Respan gateway so every call is traced and cost-attributed, and use the Spectron client for recall and storage. Check the Respan docs for the current gateway base URL:

import os
from openai import OpenAI
from surrealdb import Spectron

# Model calls flow through Respan (traced, logged, cost-attributed).
llm = OpenAI(
    base_url="https://gateway.respan.ai/v1",  # see Respan docs for the exact URL
    api_key=os.environ["RESPAN_API_KEY"],
)

# Memory is handled by Spectron.
memory = Spectron(
    endpoint=os.environ["SPECTRON_ENDPOINT"],
    context=os.environ["SPECTRON_CONTEXT"],
    api_key=os.environ["SPECTRON_API_KEY"],
)
scope = ["org/acme/user/alice"]

def answer(user_message: str) -> str:
    block = memory.query_context(user_message, k=8, scope=scope)

    completion = llm.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"You are a helpful assistant.\n\n## Memory\n{block}"},
            {"role": "user", "content": user_message},
        ],
    )
    reply = completion.choices[0].message.content

    memory.remember_many(
        [{"role": "user", "content": user_message}, {"role": "assistant", "content": reply}],
        scope=scope,
    )
    return reply

The recall and storage calls appear in Respan's trace tree alongside the model call, so you can see the memory operations and their latency for each turn.

Scope per user

Pass a scope on every Spectron call to isolate memory. A scope is a slash path or an array of paths, for example ["org/acme/user/alice"]. Register paths with spectron scopes create before first use.

Next steps

Python SDK: the full client surface
Traces: Spectron's own decision traces, correlated by traceId