# `ElixirLLM`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L1)

A unified Elixir API for LLMs.

ElixirLLM provides one beautiful interface for OpenAI, Anthropic, Ollama, and more.
Inspired by RubyLLM.

## Quick Start

    # Simple chat
    {:ok, response} = ElixirLLM.chat("What is Elixir?")

    # With configuration
    {:ok, response, chat} =
      ElixirLLM.new()
      |> ElixirLLM.model("claude-sonnet-4-5")
      |> ElixirLLM.temperature(0.7)
      |> ElixirLLM.ask("Explain OTP in simple terms")

    # With streaming
    ElixirLLM.new()
    |> ElixirLLM.model("gpt-4o")
    |> ElixirLLM.ask("Write a haiku", stream: fn chunk ->
      IO.write(chunk.content || "")
    end)

## Tools

    defmodule MyApp.Tools.Calculator do
      use ElixirLLM.Tool

      @impl true
      def name, do: "calculator"

      @impl true
      def description, do: "Performs basic math calculations"

      @impl true
      def parameters do
        %{
          expression: [type: :string, description: "Math expression to evaluate"]
        }
      end

      @impl true
      def execute(%{expression: expr}) do
        # Safe evaluation...
        {:ok, 42}
      end
    end

    {:ok, response, chat} =
      ElixirLLM.new()
      |> ElixirLLM.tool(MyApp.Tools.Calculator)
      |> ElixirLLM.ask("What is 6 * 7?")

## Configuration

Configure API keys in your `config/config.exs`:

    config :elixir_llm,
      default_model: "gpt-4o",

      openai: [
        api_key: System.get_env("OPENAI_API_KEY")
      ],

      anthropic: [
        api_key: System.get_env("ANTHROPIC_API_KEY")
      ],

      ollama: [
        base_url: "http://localhost:11434"
      ]

# `ask`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L160)

```elixir
@spec ask(ElixirLLM.Chat.t(), String.t(), keyword()) ::
  {:ok, ElixirLLM.Response.t(), ElixirLLM.Chat.t()} | {:error, Exception.t()}
```

Sends a message and returns the assistant's response.

Maintains conversation history in the returned chat.

## Options

  * `:stream` - A callback function `(Chunk.t() -> any())` for streaming responses
  * `:with` - File path(s) to include with the message (not yet implemented)

## Examples

    # Simple ask
    {:ok, response, chat} = ElixirLLM.ask(chat, "Hello!")

    # Continue the conversation
    {:ok, response, chat} = ElixirLLM.ask(chat, "Tell me more")

    # With streaming
    {:ok, response, chat} = ElixirLLM.ask(chat, "Write a story", stream: fn chunk ->
      IO.write(chunk.content || "")
    end)

# `audio`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L442)

Creates audio content from a file path.

# `chat`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L129)

```elixir
@spec chat(
  String.t(),
  keyword()
) :: {:ok, ElixirLLM.Response.t()} | {:error, Exception.t()}
```

Simple one-shot chat completion.

## Examples

    {:ok, response} = ElixirLLM.chat("What is Elixir?")
    {:ok, response} = ElixirLLM.chat("Explain OTP", model: "claude-sonnet-4-5")

# `embed`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L419)

Generates embeddings for the given text(s).

## Options

  * `:model` - The embedding model to use (default: "text-embedding-3-small")
  * `:dimensions` - Number of dimensions (for models that support it)

## Examples

    {:ok, embedding} = ElixirLLM.embed("Hello, world!")
    {:ok, embeddings} = ElixirLLM.embed(["Hello", "World"])

# `image`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L433)

Creates an image content for multi-modal messages.

## Examples

    content = ElixirLLM.image("photo.jpg")
    {:ok, response, chat} = ElixirLLM.ask(chat, "What's in this image?", with: content)

# `image_base64`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L439)

Creates image content from base64 data.

# `image_url`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L436)

Creates image content from a URL.

# `instructions`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L84)

# `max_tokens`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L83)

# `model`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L80)

# `new`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L111)

```elixir
@spec new(keyword()) :: ElixirLLM.Chat.t()
```

Creates a new chat instance.

## Options

  * `:model` - The model to use (e.g., "gpt-4o", "claude-sonnet-4-5")

## Examples

    chat = ElixirLLM.new()
    chat = ElixirLLM.new(model: "claude-sonnet-4-5")

# `on_tool_call`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L88)

# `on_tool_result`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L89)

# `params`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L90)

# `pdf`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L445)

Creates PDF content from a file path.

# `provider`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L81)

# `schema`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L87)

# `stream`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L187)

```elixir
@spec stream(ElixirLLM.Chat.t(), String.t()) :: Enumerable.t()
```

Returns a stream of chunks for the given message.

## Examples

    ElixirLLM.new()
    |> ElixirLLM.model("gpt-4o")
    |> ElixirLLM.stream("Write a poem")
    |> Stream.each(fn chunk -> IO.write(chunk.content || "") end)
    |> Stream.run()

# `temperature`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L82)

# `tool`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L85)

# `tools`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L86)

# `with_cache`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L94)

# `with_circuit_breaker`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L96)

# `with_rate_limiting`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L95)

# `with_retry`
[🔗](https://github.com/khasinski/elixir_llm/blob/v0.3.0/lib/elixir_llm.ex#L93)

---

*Consult [api-reference.md](api-reference.md) for complete listing*
