# ExAthena v0.3.0 - Table of Contents

Provider-agnostic agent loop for Elixir. Drop-in replacement for the Claude
Code SDK that runs on Ollama, OpenAI-compatible endpoints, llama.cpp, or
Anthropic itself — same tools, hooks, permissions, and streaming across all
providers. Includes a full Igniter installer.

## Pages

- [ExAthena](readme.md)
- [Changelog](changelog.md)
- [LICENSE](license.md)

- Guides
  - [Getting started](getting_started.md)
  - [Providers](providers.md)
  - [Tool calls](tool_calls.md)
  - [Tools](tools.md)
  - [The agent loop](agent_loop.md)

## Modules

- [ExAthena.Compactor](ExAthena.Compactor.md): Behaviour for context-window compaction.
- [ExAthena.Compactors.Summary](ExAthena.Compactors.Summary.md): Default `ExAthena.Compactor` — replaces the middle of message history
with a short LLM-generated summary.
- [ExAthena.Telemetry](ExAthena.Telemetry.md): Telemetry emission for ExAthena, shaped to the OpenTelemetry GenAI
semantic conventions so consumers can plug directly into OTel without
a translation layer.

- Core API
  - [ExAthena](ExAthena.md): Provider-agnostic agent loop for Elixir.
  - [ExAthena.Config](ExAthena.Config.md): Resolves the provider and per-call options for an ExAthena request.
  - [ExAthena.Request](ExAthena.Request.md): A normalised inference request.
  - [ExAthena.Response](ExAthena.Response.md): A normalised inference response.
  - [ExAthena.Result](ExAthena.Result.md): Canonical run outcome returned by `ExAthena.run/2` and
`ExAthena.Loop.run/2`.

- Agent loop
  - [ExAthena.Budget](ExAthena.Budget.md): Usage + cost accounting and budget checks for agent runs.
  - [ExAthena.Loop](ExAthena.Loop.md): Agent-loop kernel. Dispatches to a `ExAthena.Loop.Mode` implementation
and handles everything around it: caps, budget, hooks, counters, events,
and termination accounting.
  - [ExAthena.Loop.Events](ExAthena.Loop.Events.md): Flat, pattern-matchable event tuples the loop emits to `:on_event`.
  - [ExAthena.Loop.Mode](ExAthena.Loop.Mode.md): Pluggable control-flow strategy for the agent loop.
  - [ExAthena.Loop.Parallel](ExAthena.Loop.Parallel.md): Parallel tool-call dispatcher.
  - [ExAthena.Loop.State](ExAthena.Loop.State.md): Internal state of a running agent loop.
  - [ExAthena.Loop.Terminations](ExAthena.Loop.Terminations.md): Typed termination subtypes for agent-loop runs.
  - [ExAthena.Session](ExAthena.Session.md): GenServer that owns a multi-turn conversation.
  - [ExAthena.Structured](ExAthena.Structured.md): One-shot structured extraction backed by a JSON schema.

- Modes
  - [ExAthena.Modes.PlanAndSolve](ExAthena.Modes.PlanAndSolve.md): Plan-and-Solve mode.
  - [ExAthena.Modes.ReAct](ExAthena.Modes.ReAct.md): Default mode: Reason-Act cycle.
  - [ExAthena.Modes.Reflexion](ExAthena.Modes.Reflexion.md): Reflexion mode: after each ReAct iteration, insert a short self-critique
pass before the next turn.

- Messages
  - [ExAthena.Messages](ExAthena.Messages.md): Canonical in-memory representation of a conversation.
  - [ExAthena.Messages.Message](ExAthena.Messages.Message.md): A single turn in the conversation.
  - [ExAthena.Messages.ToolCall](ExAthena.Messages.ToolCall.md): A tool call the model wants the runtime to execute.
  - [ExAthena.Messages.ToolResult](ExAthena.Messages.ToolResult.md): The outcome of a tool execution, replayed back to the model.

- Provider contract
  - [ExAthena.Capabilities](ExAthena.Capabilities.md): Provider-capability map shape.
  - [ExAthena.Provider](ExAthena.Provider.md): Behaviour every provider must implement.

- Providers
  - [ExAthena.Providers.Mock](ExAthena.Providers.Mock.md): In-memory provider for tests.
  - [ExAthena.Providers.ReqLLM](ExAthena.Providers.ReqLLM.md): Delegating provider that runs requests through the `req_llm` library.

- Tool calls
  - [ExAthena.ToolCalls](ExAthena.ToolCalls.md): Extracts tool calls from a provider response.
  - [ExAthena.ToolCalls.Native](ExAthena.ToolCalls.Native.md): Parses native tool-call structures from provider responses.
  - [ExAthena.ToolCalls.TextTagged](ExAthena.ToolCalls.TextTagged.md): Parses `~~~tool_call` fenced blocks out of assistant text.

- Tool contract
  - [ExAthena.Tool](ExAthena.Tool.md): Behaviour every tool must implement.
  - [ExAthena.ToolContext](ExAthena.ToolContext.md): Context handed to every tool execution.
  - [ExAthena.Tools](ExAthena.Tools.md): Resolves tool modules into the shape the provider + loop expect.

- Builtin tools
  - [ExAthena.Tools.Bash](ExAthena.Tools.Bash.md): Executes a shell command via `/bin/sh -c` with a configurable timeout.
  - [ExAthena.Tools.Edit](ExAthena.Tools.Edit.md): Exact-string replacement in a file.
  - [ExAthena.Tools.Glob](ExAthena.Tools.Glob.md): Finds files matching a glob pattern, relative to `ctx.cwd`.
  - [ExAthena.Tools.Grep](ExAthena.Tools.Grep.md): Search file contents with a regex under `ctx.cwd`.
  - [ExAthena.Tools.PlanMode](ExAthena.Tools.PlanMode.md): Toggle the loop's permission phase.
  - [ExAthena.Tools.Read](ExAthena.Tools.Read.md): Reads a file from the filesystem.
  - [ExAthena.Tools.SpawnAgent](ExAthena.Tools.SpawnAgent.md): Synchronously run a sub-agent-loop with its own prompt, tools, and budget.
  - [ExAthena.Tools.TodoWrite](ExAthena.Tools.TodoWrite.md): Writes the agent's todo list.
  - [ExAthena.Tools.WebFetch](ExAthena.Tools.WebFetch.md): HTTP GET via `Req`, returning the body as text.
  - [ExAthena.Tools.Write](ExAthena.Tools.Write.md): Creates or overwrites a file with the given content.

- Permissions + hooks
  - [ExAthena.Hooks](ExAthena.Hooks.md): Lifecycle hooks the loop fires at key transitions.
  - [ExAthena.Permissions](ExAthena.Permissions.md): Decides whether a tool call is allowed.

- Streaming
  - [ExAthena.Streaming](ExAthena.Streaming.md): Canonical streaming event types and the broadcaster helper.
  - [ExAthena.Streaming.Event](ExAthena.Streaming.Event.md): A single streaming event.

- Errors
  - [ExAthena.Error](ExAthena.Error.md): Canonical error surface across providers.

## Mix Tasks

- [mix ex_athena.install](Mix.Tasks.ExAthena.Install.md): Installs ExAthena into your project.

