Python SDK reference

Item	Value
PyPI package	`surrealdb` (Spectron client bundled with the driver)
Install	`pip install surrealdb`
Import	`from surrealdb import Spectron, AsyncSpectron`
Submodule	`surrealdb.spectron` (models, namespaces, errors)

On PyPI, spectron is a different project. Install surrealdb for SurrealDB and Spectron — not pip install spectron.

Constructor

Spectron(context: str, endpoint: str, api_key: str,
    timeout: float = 30.0, max_retries: int = 3)
AsyncSpectron(...)  # same arguments; methods are async

Requests use Authorization: Bearer <api_key>. Optional on_behalf_of on every verb sets X-Spectron-On-Behalf-Of for delegation.

Memory verbs (REST mapping)

Method	HTTP
`remember(...)`	`POST /api/v1/{ctx}/facts`
`remember_many(...)`	`POST /api/v1/{ctx}/facts/batch`
`recall(...)`	`POST /api/v1/{ctx}/query`
`forget(...)`	`POST /api/v1/{ctx}/forget`
`chat(...)`	`POST /api/v1/{ctx}/chat` (SSE when `stream=True`)
`consolidate(...)`	`POST /api/v1/{ctx}/consolidate`
`reflect(...)`	`POST /api/v1/{ctx}/reflect`
`elaborate(...)`	`POST /api/v1/{ctx}/elaborate`
`query_context(...)`	`POST /api/v1/{ctx}/context`
`inspect(ref, ...)`	`GET /api/v1/{ctx}/inspect`
`state()`	`GET /api/v1/{ctx}/state`
`whoami()`	`GET /api/v1/{ctx}/me`
`profile()`	`GET /api/v1/{ctx}/profile`
`audit(...)`	`GET /api/v1/{ctx}/audit`
`health()`	`GET /api/v1/health` (not context-scoped)

Namespaces

Namespace	Methods
`documents`	`upload`, `get`, `delete`, `list`, `query`, `fetch_raw`, `reprocess`, `recompute_links`, `chunks`
`documents.keywords`	`list`, `get`, `search`, `for_document`
`sessions`	`create`, `delete`, `context`, `turns`
`entities`	`list`, `get`, `delete`, `history`
`scopes`	`register`, `list`, `delete`, `forget`
`principals`	`list`, `get`, `grant`, `revoke`, `effective`
`keys`	`create`, `list`, `delete`, `rotate`
`traces`	`list`, `get`, `stats`
`lifecycle`	`decay`, `expire`, `fsck`

Full REST tables: REST API.

Response models

Import from surrealdb.spectron:

Model	Used for
`RememberResponse`, `RememberBatchResponse`, `ExtractionResult`	Fact ingest
`RecallResponse`, `RecallHit`	Semantic recall
`ChatResponse`, `ChatChunk`	Chat (streaming chunks)
`ContextQueryResponse`	Composed context string
`StateResponse`	Working-memory snapshot
`UploadResponse`, `Document`, `DocumentPage`, `Chunk`, `ChunkPage`	Document corpus
`DocumentQueryResponse`, `DocumentQueryHit`	Document search
`Keyword`, `KeywordSearchResponse`, …	Keyword index
`Session`, `Turn`, `TurnListResponse`	Sessions
`EntityDetail`, `EntityListResponse`, …	Knowledge graph entities
`WhoamiResponse`, `ProfileResponse`	Caller identity
`TraceRecord`, `AuditResponse`, `FsckReport`	Observability / maintenance

Nested graph and extraction payloads may remain dict values where the server shape evolves (“slim model” convention).

Exceptions

Class	HTTP
`SpectronError`	Base
`SpectronAPIError`	Any non-2xx without a subclass (`status_code`, `message`, `trace_id`, `body`)
`SpectronAuthError`	401
`SpectronScopeError`	403
`SpectronNotFoundError`	404

→ Errors and retries

User guide

→ Python SDK