Spectre is an Elixir framework for building agents that understand messages, use models and tools, and carry out work in supervised OTP processes. You choose the recognition strategies, model providers and capabilities your application needs.
Upgrading from 0.3? Spectre 0.4 introduces substantial changes to agent definitions, conversation ownership and tool execution. Follow the 0.3 → 0.4 migration guide before upgrading an existing application.
GAM stands for Governed Act Model. It defines how an agent's proposal becomes an authorized operation. Your application declares which operations are governed, who may authorize them and when human consent is required. Spectre checks that authority and records the decision before allowing execution, then tracks the observed result separately.
For example, an agent can prepare an email, but sending it must pass through the application's configured permissions and consent checks. Approval applies to the specific operation shown to the person, including its recipient and content.
Read the GAM manifesto for the model's principles and GAM in Spectre for their implementation.
- Stack installs the capabilities available to the application: models, browser access, memory and other tools.
- Agent declares the router, flows and intents that recognize input and select a route.
- Server implements the callbacks for those routes and manages the conversation's state, pending work and results inside an OTP process.
The Server can ask workers to generate a response or use a tool. Operations on the application's governed surface go through GAM before their effect adapter can execute them.
Requires Elixir ~> 1.19.
{:spectre, "~> 0.4.0"}Run mix deps.get and commit mix.lock. Installation
covers optional packages, source dependencies and supervision.
The code follows the diagram: first the Stack, then the Agent's router, then the
Server's callbacks. The router combines explicit regex rules, semantic similarity
through embeddings and a model that classifies input when earlier evidence is
insufficient. MyApp.Embeddings and MyApp.IntentModel are application-supplied
adapters: configure their models and credentials as described in
Routing and
Behaviours and adapters.
# 1. Stack: install any optional capabilities your application needs.
defmodule MyApp.AI do
use Spectre.Stack
end
# 2. Agent: recognize intent using patterns, embeddings or a classifier model.
defmodule MyApp.SupportAgent do
use Spectre.Agent, stack: MyApp.AI, server: MyApp.SupportServer
embedding MyApp.Embeddings
classifier :llm, MyApp.IntentModel, timeout: 8_000
router strategies: [:regex, :embedding, :llm_classifier]
flow :support do
on(:pricing,
regex: ~r/\b(price|pricing|cost)\b/i,
semantic_examples: ["How much does a subscription cost?"]
)
on :technical,
semantic_examples: ["My API key stopped working", "I cannot sign in"]
end
end
# 3. Server: handle the route selected by the Agent.
defmodule MyApp.SupportServer do
use Spectre.Server, tools: MyApp.AI
@impl true
def handle_flow({:support, :pricing}, _input, ctx),
do: respond(ctx, "Plans start at EUR 20 per month.")
def handle_flow({:support, :technical}, _input, ctx),
do: respond(ctx, "Tell me which error you see.")
def handle_flow(:unmatched, _input, ctx),
do: respond(ctx, "Ask me about pricing.")
end
{:ok, server} = Spectre.Server.start_link(agent: MyApp.SupportAgent, consumer: self())
{:ok, interaction} = Spectre.Server.input(server, "What is the price?")
receive do
{Spectre.Server, ^server, {:response, ^interaction, text, _metadata}} ->
IO.puts(text)
after
5_000 -> raise "No response from the agent"
endThe regex recognizes "What is the price?" directly. Other wording can match the
examples through vector similarity; when that evidence is insufficient, the
classifier model chooses among the declared intents. A selected route calls its
Server handler. input/3 returns an interaction ID; replies arrive asynchronously
at the consumer. A successful early match can avoid a model call.
For a complete first run without configured providers, use the model-free quickstart.
In an application, supervise the Server or use Spectre.summon/1
for per-subject ownership. Getting started covers
these next steps and the generator.
The Agent's router can combine several ways to recognize an intent. Choose the strategies that suit your application:
| Strategy | Recognizes input using | Requires |
|---|---|---|
:regex |
Explicit text patterns. | Route regex: patterns. |
:bag |
Character similarity to example phrases. | Route bag: examples. |
:jaro |
Spelling similarity to example phrases. | Route jaro: examples. |
:intent_dataset |
Reviewed exact examples and optional vector search. | Intent examples; an embedder for vector lookup. |
:embedding |
Meaning similarity to route examples. | An embedding adapter and semantic_examples:. |
:local_classifier |
A local intent classifier's prediction. | A configured local classifier. |
:llm_classifier |
A language model's choice among declared intents. | A configured intent model. |
The example above combines regex, semantic matching and model classification.
For a model-free router, select [:regex, :bag, :jaro] and declare bag: and
jaro: phrases on each route; see the local matching example.
For semantic and model-based recognition, configure the adapters in the Agent and select the corresponding strategies:
# Inside an Agent; these adapters are supplied by your application.
embedding MyApp.Embeddings
classifier :local, MyApp.IntentClassifier
classifier :llm, MyApp.IntentModel
router strategies: [
:regex, :intent_dataset, :bag, :jaro,
:embedding, :local_classifier, :llm_classifier
]The intent classifier and response model can be different models. You can also implement a custom router adapter, plug or arbitrator. Routing explains configuration, thresholds, fallbacks and complete examples; Behaviours and adapters explains the extension contracts.
All nine libraries are optional. Install only the capabilities your Stack needs.
| Library | Purpose |
|---|---|
| spectre_beam | Receive and deliver messages through external channels. |
| spectre_directive | Manage resumable missions, plans and their next steps. |
| spectre_kinetic | Turn model output into validated action proposals. |
| spectre_lab | Inspect agents and checkpoints; test and compare recorded runs. |
| spectre_ledger | Persist Server state and GAM history, with file and PostgreSQL storage. |
| spectre_lens | Browse websites, inspect pages and perform browser actions. |
| spectre_mnemonic | Store, search and recall agent memory. |
| spectre_prism | Select models for generation, classification and embeddings. |
| spectre_pulse | Exchange authenticated messages between agents across transports. |
Related tools: spectre_ecosystem runs compatibility checks across packages; spectre_studio provides a LiveView control panel for the retained Instance runtime.
Server helpers return commands in the Context. on_result: names the callback
continuation. Models, classifiers and tools run in workers; native OTP callbacks
remain available in the same conversation owner.
Configure permitted effects through gam: [operations: ...]. Confirmation,
when required, binds the human's decision to the exact presented operation.
Installing a tool or receiving a model proposal does not grant authority.
Mounted Skill servers have independent state and workers while sharing their
root AgentServer's GAM Domain and the mount's restrictions.
RAM-only operation is supported. Ledger can persist canonical GAM history, Server coordination and the Domain's historical projection in the application's PostgreSQL database. Application payload callbacks choose where content is stored and how it is protected.
Spectre.Server.reset(server) starts a fresh session, including mounted Skills,
while keeping the root PID. Use storage: :ephemeral to explicitly reset into RAM.
See Server lifecycle and
custom storage for reset semantics and the single
Spectre.Server.Store behaviour.
After registering the email effect, configure the operation on the root:
# Options for Spectre.Server.start_link/1; the application authenticates the user.
identity: %{subject: user.id},
consumer: chat_process,
gam: [operations: %{{:kinetic, :send_email} => [confirm: true]}]The business callback proposes the concrete draft instead of sending it directly:
def handle_flow({:mail, :send}, _input, ctx) do
propose(ctx, {:kinetic, :send_email},
%{"to" => ctx.assigns.recipient, "body" => ctx.assigns.draft},
on_result: :sent)
end
def handle_result(:sent, {:governed, %{outcome: %{status: :succeeded}}}, ctx),
do: respond(ctx, "The mail service confirmed the send operation.")These are application fragments: the effect registration, draft preparation and chat consumer are supplied by the host. The consumer displays the exact draft, acknowledges rendering and submits the human's separate confirm/reject decision. GAM checks that decision before execution. Managed GAM shows those calls; the full outreach source connects website inspection, drafting, refusal and failure handling.
| Goal | Start here |
|---|---|
| Build and run an agent | Getting started |
| Choose recognition strategies | Routing, Training |
| Implement custom adapters and behaviours | Behaviours and adapters |
| Understand processes, Context and continuations | Architecture, Server |
| Add models, browser, memory and other packages | Stack tools |
| Require local or external human consent | Managed GAM, external approval |
| Configure persistence and content storage | Domain storage, payload storage |
| Run parallel reusable capabilities | Skills |
| Run a complete website-to-email workflow | Examples, LiveView demo |
| Deploy, test or migrate | Production, Testing, Migration |
The documentation index links the full 0.4 reference. Earlier Instance/Run APIs remain supported through the compatibility reference.
Contributing · Security · Changelog · Application authoring reference