# Elixir SDK

Using SurrealDB Agent Memory from Elixir applications.

The SurrealDB Agent Memory client ships in the [`:surrealdb`](https://github.com/surrealdb/surrealdb.elixir) package on Hex as a typed REST client. It aims for feature parity with the JavaScript SDKs (`surrealdb` and `@surrealdb/spectron`).

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

## Installation

Add `:surrealdb` to your `mix.exs`:

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

## Client construction

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

```elixir
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

```elixir
{: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`:

```elixir
{: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:

```elixir
{: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:

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

## Errors

SurrealDB Agent Memory 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.