Python SDK | Spectron

The published package is surrealdb-spectron — a client generated from Spectron’s OpenAPI specification, wrapped with an ergonomic façade. Types such as MemoryCategory and graph edge kinds stay aligned with the server because both sides share the same spec.

Installation

pip install surrealdb-spectron

Python 3.10+ recommended. Regenerate from the repo spec with clients/python/generate.sh when developing Spectron itself.

Configuration

import os
from surrealdb_spectron import SpectronClient  # exact import may match generated module

client = SpectronClient(
    base_url=os.environ["SPECTRON_URL"],       # http://localhost:9090
    api_key=os.environ["SPECTRON_API_KEY"],
    context_id=os.environ["SPECTRON_CONTEXT_ID"],
)

Authentication uses the API-KEY header on every request (handled by the client). Do not prefix the key with Bearer.

Setting	Environment variable	Example
Server URL	`SPECTRON_URL`	`http://localhost:9090`
Context key	`SPECTRON_API_KEY`	from `spectrond bootstrap`
Context id	`SPECTRON_CONTEXT_ID`	`dev`

Remember (facts)

result = await client.facts.create(
    text="Alice was promoted to CTO.",
    infer="full",
    scope=["org=acme", "user=alice"],
)

Bulk conversation ingest:

result = await client.facts.create_batch(
    messages=[
        {"role": "user", "content": "I was promoted to CTO."},
        {"role": "assistant", "content": "Congratulations!"},
    ],
    scope=["org=acme", "user=alice"],
    idempotency_key="conv-01HF...",
)

Recall

hits = await client.query(
    query="What is Alice's role?",
    limit=10,
    scope=["org=acme", "user=alice"],
)

block = await client.context(
    query="What is Alice's role?",
    limit=10,
    scope=["org=acme", "user=alice"],
)

Documents

doc = await client.documents.upload(
    file_path="./policy.pdf",
    title="Returns policy",
)

Chat

reply = await client.chat(
    message="Summarise what you know about Alice",
    scope=["org=acme", "user=alice"],
)

Harness adapter (zero prompt change)

For LangChain-style apps that should auto-record every turn:

pip install spectron-langchain

See LangChain. The adapter posts to /facts/batch with platform-derived idempotency keys.

CLI alternative

The spectron binary exposes the same operations without installing the SDK:

spectron remember "Alice was promoted to CTO."
spectron recall "What is Alice's role?" --json

See CLI reference and REST API.

Method names on the generated client follow OpenAPI operation ids and may differ slightly from the examples above. When in doubt, run spectron-gen-spec and inspect doc/spec/ or use the CLI as the contract reference.