Spectre

An OTP-native Elixir runtime for building agents whose routing, state, policies, and side effects stay explicit.

Spectre treats an agent the way OTP treats a system: a supervised set of processes with one canonical owner for every piece of state, explicit messages at every boundary, and recovery designed in from the start. If you know GenServer, supervision trees, and "let it crash", you already have the mental model - Spectre applies it to conversations, model calls, and tool execution.

A Spectre agent should read like a map, not a magic trick.

Philosophy

Three ideas define Spectre. Everything else in the library is a consequence of them.

1. The model proposes. It never executes.

Every side effect crosses a fixed safety boundary:

• models and routes may propose work;
• protected work must pass a deterministic policy;
• approval changes state — it does not run anything;
• execution happens only through an explicit host call;
• every outcome is returned as plain data.

No model output can skip a policy, invent a route, or trigger a side effect on its own. Your application keeps owning business rules, permissions, storage, and the actual operations. The whole lifecycle at a glance:

input
  -> normalize
  -> restore state and memory
  -> resolve an open policy, or route the turn
  -> run handler
       -> reply / no response
       -> stage effect
            -> unprotected: pending -> execute -> completed / failed
            -> protected: waiting_policy
                 -> accepted -> approved -> execute -> completed / failed
                 -> rejected / attempts exceeded -> cancelled

2. Routing is a dial, not a dogma.

The lifecycle around a decision is always deterministic. How the agent decides — which route handles this input — is exactly as deterministic as you configure it to be:

router(via: [:regex])                                # fully deterministic
router(via: [:regex, :embedding, :classifier])       # hybrid: patterns win, semantics cover paraphrases
router(via: [:regex, :embedding, :classifier,
             :semantic_cache, :llm_classifier])      # model-in-the-loop

With :llm_classifier in the chain, routing is genuinely model-driven — but only between routes the agent declares, only after cheaper evidence was not decisive, and always inside the same deterministic lifecycle. A refunds bot can run pure regex; an open-ended assistant can lean on the LLM; both get the same guarantees. See Routing.

3. Everything durable is data — and data never becomes code.

Agents compile to canonical, content-addressed Definitions. Runtime-authored behavior (skills, work programs, change proposals) is portable data that can only reference operations the host already registered — never callbacks, never executable templates. An agent can even propose changes to itself, but only through the same governance every change passes: evaluation, review, explicit approval, activation, and rollback. See Governance and the Reflective Runtime.

Installation

def deps do
  [
    {:spectre, "~> 0.3.0"}
  ]
end

See Installation for release verification, snapshot pinning, and the optional SpectreKinetic and ExFastembed integrations. The complete API reference is published on HexDocs. Spectre is 0.x: documented APIs may still evolve in minor releases; the normative compatibility surface is the public API manifest.

A Small Agent

One readable module declares the stable shape of the agent. The DSL covers the repetitive structure; normal Elixir modules still own the business logic.

defmodule MyApp.SupportAgent do
  use Spectre.Agent, prompt_root: "priv/agents/support/prompts"

  model(MyApp.LLM, purpose: :smart)

  router(via: [:regex, :embedding, :classifier])

  actions MyApp.SupportActions do
    protect(:delete_account, with: :delete_account_confirmation)
  end

  policy :delete_account_confirmation do
    request(:confirm_delete_account)
    accept(:confirmed_delete, regex: ~r/^yes, delete it$/i)
    reject(:cancel_delete, regex: ~r/^(no|cancel)$/i)
    otherwise(ask: :confirm_delete_account_retry)
    attempts(3, then: :cancel_pending)
  end

  interrupt :HELP, regex: ~r/^(help|menu)$/i do
    reply(:help)
  end

  flow :support do
    on :PRICING,
      regex: ~r/\b(price|pricing|cost)\b/i,
      embedding: ["how much does it cost?", "pricing plans"] do
      reply(:pricing)
    end

    on :DELETE_ACCOUNT, regex: ~r/\bdelete my account\b/i do
      action(:delete_account)
    end
  end
end

Spectre.turn/3 is the host boundary. Every turn returns one decision as data:

{:ok, turn} =
  Spectre.turn(MyApp.SupportAgent, "How much does it cost?",
    conversation_id: "chat-123"
  )

case turn.decision do
  {:reply, result} -> deliver(result.reply_text)
  {:awaiting, awaitable, result} -> present_policy(awaitable, result)
  {:needs, effect, result} -> enqueue_or_execute(effect, result)
  {:completed, completion, result} -> deliver_completion(completion, result)
  {:no_response, _result} -> :ok
end

The safety boundary in action — starting a protected action never executes it:

# The model/route proposes; the effect waits for the policy.
{:ok, awaiting} = Spectre.turn(MyApp.SupportAgent, "delete my account")
{:awaiting, %Spectre.Awaitable{status: :open}, result} = awaiting.decision

# Approval changes state — still nothing has run.
{:ok, approved} =
  Spectre.turn(MyApp.SupportAgent, "yes, delete it", state: result.state)
{:needs, %Spectre.Effect{status: :approved}, approved_result} = approved.decision

# Only the host executes, explicitly.
{:ok, executed} =
  Spectre.execute(approved_result.state, %{
    agent: MyApp.SupportAgent,
    input: approved_result.input,
    state: approved_result.state,
    opts: [user_id: user.id]
  })

A full walkthrough — approval, rejection, retries, sessions, persistence — is in Getting Started.

Core Concepts

Documentation

Start here

• Guide for LLMs and coding agents — machine-oriented contracts, safe usage patterns, and documentation routing for Spectre 0.3.0.
• Getting Started — a complete agent and host lifecycle.
• Two Realistic Agents — database Q&A with Kinetic, browse-and-answer with Lens.
• Architecture — ownership, lifecycle, trust, and host boundaries.
• System Overview — small core, explicit satellite packages, design rationale.
• DSL — agent macros, flows, handlers, policies, actions, prompts.

Build

• Routing · Routing Evaluation · Training
• Actions · Skills · Memory
• Agent Instances and Subjects · Resumable Runs
• Stack · Integration Boundaries

Operate

• Production Operations — persistence, idempotency, supervision, deployment checklist.
• Journal · Provider Resilience · Testing

The reflective runtime

• Work, Vigil, and the Operational Runtime
• Runtime Skills · Data-driven Execution
• Governed Definition Changes · Reflective Runtime
• Skill State · Event Lifecycle · Identity and Activation
• Definition Store · Foundation Conformance
• Public API Manifest — the exact normative compatibility surface.

Releases

• Changelog — release notes and compatibility changes.
• Roadmap — architectural hardening and package direction.
• Migration guides are versioned with the package; start with Migrating to 0.3.0.

License

Spectre is released under the Apache License 2.0.