# ExLLM Quick Start Guide
Get up and running with ExLLM in 5 minutes! This guide covers installation, basic configuration, and common usage patterns.
## Installation
Add ExLLM to your `mix.exs` dependencies:
```elixir
def deps do
[
{:ex_llm, "~> 0.7.0"}
]
end
```
Then run:
```bash
mix deps.get
```
## Configuration
### Environment Variables
Set API keys for the providers you want to use:
```bash
# Core providers
export ANTHROPIC_API_KEY="sk-ant-your-key"
export OPENAI_API_KEY="sk-your-key"
export GROQ_API_KEY="gsk_your-key"
# Additional providers (optional)
export GEMINI_API_KEY="your-gemini-key"
export MISTRAL_API_KEY="your-mistral-key"
export OPENROUTER_API_KEY="sk-or-your-key"
export PERPLEXITY_API_KEY="pplx-your-key"
```
### Application Configuration (Optional)
```elixir
# config/config.exs
config :ex_llm,
# Default provider
default_provider: :anthropic,
# Cost tracking
cost_tracking_enabled: true,
# Test caching (speeds up tests 25x)
test_cache: [
enabled: true,
cache_dir: "test/cache",
ttl: 604_800_000 # 7 days in milliseconds
]
```
## Basic Usage
### Simple Chat Completion
```elixir
# Start with a basic chat
{:ok, response} = ExLLM.chat(:anthropic, [
%{role: "user", content: "What is the capital of France?"}
])
IO.puts(response.content)
# => "The capital of France is Paris."
# Access additional metadata
IO.puts("Model: #{response.model}")
IO.puts("Cost: $#{response.cost}")
IO.puts("Tokens used: #{response.usage.total_tokens}")
```
### Different Providers
```elixir
# Try different providers
{:ok, response1} = ExLLM.chat(:openai, [
%{role: "user", content: "Explain quantum computing briefly"}
])
{:ok, response2} = ExLLM.chat(:groq, [
%{role: "user", content: "Write a haiku about coding"}
])
{:ok, response3} = ExLLM.chat(:gemini, [
%{role: "user", content: "What's 2+2?"}
])
```
### Streaming Responses
```elixir
# Stream responses in real-time
ExLLM.chat_stream(:openai, [
%{role: "user", content: "Write a short story about a robot"}
], fn chunk ->
IO.write(chunk.delta)
end)
```
### Session Management
```elixir
# Maintain conversation context
{:ok, session} = ExLLM.Session.new(:anthropic)
# First message
{:ok, session, response1} = ExLLM.Session.chat(session, "Hi, I'm learning Elixir")
IO.puts(response1.content)
# Continue the conversation
{:ok, session, response2} = ExLLM.Session.chat(session, "What are GenServers?")
IO.puts(response2.content)
# Session automatically tracks conversation history
IO.puts("Messages in session: #{length(session.messages)}")
IO.puts("Total cost: $#{session.total_cost}")
```
## Advanced Features
### Multimodal (Vision)
```elixir
# Analyze images (with Gemini or OpenAI)
image_data = File.read!("image.jpg") |> Base.encode64()
{:ok, response} = ExLLM.chat(:gemini, [
%{role: "user", content: [
%{type: "text", text: "What's in this image?"},
%{type: "image", image: %{
data: image_data,
media_type: "image/jpeg"
}}
]}
])
IO.puts(response.content)
```
### Function Calling
```elixir
# Define tools
tools = [
%{
type: "function",
function: %{
name: "get_weather",
description: "Get current weather for a location",
parameters: %{
type: "object",
properties: %{
location: %{type: "string", description: "City name"},
unit: %{type: "string", enum: ["celsius", "fahrenheit"]}
},
required: ["location"]
}
}
}
]
{:ok, response} = ExLLM.chat(:openai, [
%{role: "user", content: "What's the weather in Paris?"}
], tools: tools)
# Handle function calls
case response.function_calls do
[%{name: "get_weather", arguments: args}] ->
# Call your weather API here
weather_data = get_weather(args["location"])
# Continue conversation with function result
{:ok, final_response} = ExLLM.chat(:openai, [
%{role: "user", content: "What's the weather in Paris?"},
response.message,
%{role: "function", name: "get_weather", content: Jason.encode!(weather_data)}
])
_ ->
IO.puts(response.content)
end
```
### Model Discovery
```elixir
# List available models
{:ok, models} = ExLLM.list_models(:anthropic)
Enum.each(models, fn model ->
IO.puts("#{model.id} - Context: #{model.context_window} tokens")
end)
# Get specific model info
{:ok, model} = ExLLM.get_model(:openai, "gpt-4o")
IO.puts("Supports streaming: #{model.capabilities.supports_streaming}")
IO.puts("Supports vision: #{model.capabilities.supports_vision}")
```
## Testing
### Fast Testing with Caching
ExLLM includes intelligent test caching for 25x faster integration tests:
```bash
# Run tests with automatic caching
mix test
# Test specific providers
mix test.anthropic
mix test.openai --include live_api
# Manage cache
mix ex_llm.cache stats
mix ex_llm.cache clean --older-than 7d
```
### Writing Tests
```elixir
defmodule MyAppTest do
use ExUnit.Case
# Tag for automatic caching
@moduletag :live_api
@moduletag :requires_api_key
@moduletag provider: :anthropic
test "chat completion works" do
{:ok, response} = ExLLM.chat(:anthropic, [
%{role: "user", content: "Say hello"}
])
assert response.content =~ "hello"
assert response.cost > 0
end
end
```
## Local Models
### Ollama
```bash
# Start Ollama
ollama serve
# Pull a model
ollama pull llama3.2
```
```elixir
# Use local Ollama models
{:ok, response} = ExLLM.chat(:ollama, [
%{role: "user", content: "Hello!"}
], model: "llama3.2")
```
### LM Studio
```bash
# Start LM Studio server on localhost:1234
```
```elixir
# Use LM Studio models
{:ok, response} = ExLLM.chat(:lmstudio, [
%{role: "user", content: "Hello!"}
])
```
### Bumblebee (Elixir Native)
```elixir
# Add to deps for local inference
{:exla, "~> 0.7"} # For CPU/GPU acceleration
# Use Bumblebee models
{:ok, response} = ExLLM.chat(:bumblebee, [
%{role: "user", content: "Hello!"}
], model: "microsoft/DialoGPT-medium")
```
## Error Handling
```elixir
case ExLLM.chat(:anthropic, messages) do
{:ok, response} ->
IO.puts(response.content)
{:error, {:api_error, %{status: 401}}} ->
IO.puts("Invalid API key")
{:error, {:api_error, %{status: 429}}} ->
IO.puts("Rate limited - try again later")
{:error, {:api_error, %{status: 400, body: body}}} ->
IO.puts("Bad request: #{inspect(body)}")
{:error, {:network_error, reason}} ->
IO.puts("Network error: #{reason}")
{:error, reason} ->
IO.puts("Other error: #{inspect(reason)}")
end
```
## Environment-Specific Configuration
### Development
```elixir
# config/dev.exs
config :ex_llm,
log_level: :debug,
log_components: [:http_client, :streaming],
test_cache: [enabled: true]
```
### Test
```elixir
# config/test.exs
config :ex_llm,
log_level: :warn,
test_cache: [
enabled: true,
cache_dir: "test/cache",
ttl: 604_800_000 # 7 days
]
```
### Production
```elixir
# config/prod.exs
config :ex_llm,
log_level: :info,
log_redaction: true,
cost_tracking_enabled: true
```
## Next Steps
1. **Read the [User Guide](USER_GUIDE.md)** for comprehensive documentation
2. **Check [Provider Capabilities](PROVIDER_CAPABILITIES.md)** to compare features
3. **Review [Testing Guide](TESTING.md)** for advanced testing patterns and caching
## Common Issues
### "API key not found"
```bash
# Make sure you've set the environment variable
export ANTHROPIC_API_KEY="your-key"
```
### "Model not found"
```elixir
# Check available models
{:ok, models} = ExLLM.list_models(:anthropic)
```
### "Rate limited"
```elixir
# Use different providers or implement backoff
Process.sleep(1000)
{:ok, response} = ExLLM.chat(:groq, messages) # Try Groq for speed
```
### Tests running slowly
```bash
# Enable test caching
export EX_LLM_TEST_CACHE_ENABLED=true
mix test --include live_api
```
That's it! You're now ready to build amazing applications with ExLLM. 🚀
