Getting started

Copy Markdown View Source

This guide takes you from zero to a running ExAthena call in under five minutes.

Install

mix igniter.install ex_athena

The installer:

  • Adds {:ex_athena, "~> 0.1"} to your deps.
  • Writes config :ex_athena, default_provider: :ollama (and per-provider defaults) to config/config.exs.
  • Is idempotent — re-running preserves whatever you've already configured.

Alternatively, add the dep manually:

def deps do
  [
    {:ex_athena, "~> 0.1"},
    {:claude_code, "~> 0.36"}  # only needed for the :claude provider
  ]
end

…then run mix ex_athena.install once to wire up defaults.

Pick a provider

Ollama (local, free)

ollama pull llama3.1
ollama serve

config :ex_athena, default_provider: :ollama
config :ex_athena, :ollama, base_url: "http://localhost:11434", model: "llama3.1"

OpenAI / OpenAI-compatible

config :ex_athena, default_provider: :openai_compatible
config :ex_athena, :openai_compatible,
  base_url: "https://api.openai.com/v1",
  api_key: System.get_env("OPENAI_API_KEY"),
  model: "gpt-4o-mini"

Swap base_url for any OpenAI-compatible endpoint (OpenRouter, LM Studio, Groq, Together, vLLM, llama.cpp in server mode).

Anthropic Claude

config :ex_athena, default_provider: :claude
config :ex_athena, :claude,
  api_key: System.get_env("ANTHROPIC_API_KEY"),
  model: "claude-opus-4-5"

Make a call

{:ok, response} = ExAthena.query("What is 2+2?")
IO.puts(response.text)

response is an %ExAthena.Response{} with:

  • :text — concatenated assistant text
  • :tool_calls — any tool calls the model wants the runtime to execute (empty in Phase 1)

  • :finish_reason — :stop | :length | :tool_calls | :content_filter | :error

  • :usage — token accounting when the provider reports it
  • :model, :provider, :raw

Stream the response

ExAthena.stream("Explain quantum computing in plain English", fn event ->
  case event.type do
    :text_delta -> IO.write(event.data)
    :stop -> IO.puts("\n[done]")
    _ -> :ok
  end
end)

The callback runs on every delta — keep it fast. If you need to do expensive work per-delta, hand off to a Task.

Next steps