Elixir SDK | Spectron

The Spectron client ships in the :surrealdb package on Hex, as a typed REST client for agent memory. It aims for feature parity with the JavaScript SDKs (surrealdb and @surrealdb/spectron).

Installation

Add :surrealdb to your mix.exs:

def deps do
  [
    {:surrealdb, "~> 0.1"}
  ]
end

Client construction

Create a client pinned to one context and pass it to every call:

client =
  SurrealDB.Spectron.new(
    endpoint: System.fetch_env!("SPECTRON_ENDPOINT"),
    context: "acme-prod",
    api_key: System.fetch_env!("SPECTRON_API_KEY")
  )

Remember, recall, and chat

{:ok, _} = SurrealDB.Spectron.remember(client, "I just got promoted to CTO", scopes: "user/tobie")
{:ok, hits} = SurrealDB.Spectron.recall(client, "What is Tobie's role?", k: 10)
{:ok, %{"reply" => reply}} = SurrealDB.Spectron.chat(client, "What do you know about me?")

Stream the chat loop with stream: true:

{:ok, stream} = SurrealDB.Spectron.chat(client, "Tell me a story", stream: true)

for chunk <- stream do
  IO.write(chunk["delta"])
end

Namespaces

Grouped operations live in dedicated modules, each taking the client first:

{:ok, doc} = SurrealDB.Spectron.Documents.upload(client, title: "Handbook", file: "handbook.pdf")
{:ok, session} = SurrealDB.Spectron.Sessions.create(client)
{:ok, minted} = SurrealDB.Spectron.Keys.create(client, name: "ci", ttl_seconds: 3600)

The available namespaces are Documents, Entities, Sessions, Lifecycle, Traces, Principals, Scopes, and Keys.

Delegation

on_behalf_of/2 returns a new client whose requests carry the X-Spectron-On-Behalf-Of header; the original client is unchanged:

as_alex = SurrealDB.Spectron.on_behalf_of(client, "principal:alex")
{:ok, _} = SurrealDB.Spectron.remember(as_alex, "Reviewed the Q3 plan")

Errors

Spectron calls return {:error, %SurrealDB.Spectron.Error{}} whose kind is one of :auth, :validation, :not_found, :rate_limit, :scope, :server, or :connection. Each error carries the response trace_id when the server provided one.