Skip to content
elchemistaPublic

About

Supervised Process Event Controller for Transition and Reasoning with Elixir. (S.P.E.C.T.R.E)

Topics

Resources

Contributing

Security policy

Stars

13 stars

Watchers

1 watching

Forks

Repository files navigation

Spectre

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.

What is GAM?

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 → Agent → Server

Spectre: From conversation to governed work

Diagram source.

  • 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.

Install

Requires Elixir ~> 1.19.

{:spectre, "~> 0.4.0"}

Run mix deps.get and commit mix.lock. Installation covers optional packages, source dependencies and supervision.

Build an agent

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"
end

The 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.

Routing strategies

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.

Satellite libraries

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.

From conversation to governed work

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.

Example: ask before sending an email

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.

Guides

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

About

Supervised Process Event Controller for Transition and Reasoning with Elixir. (S.P.E.C.T.R.E)

Topics

Resources

Contributing

Security policy

Stars

13 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages