### Setup and Run Quick Start

Source: https://github.com/agentjido/req_llm/blob/main/examples/README.md

Instructions for setting up and running the ReqLLM examples from the repository root or directly within the examples directory.

```bash
cp examples/.env.example examples/.env
cd examples
mix deps.get
mix run demo.exs
```

```bash
cp .env.example .env
mix deps.get
mix run demo.exs
```

--------------------------------

### Quick Start Examples

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Run these commands from the `examples/` project root after adding a working key to `.env`. These examples cover basic text generation, streaming text, object generation, and image analysis.

```bash
cp .env.example .env
mix deps.get

# Text generation
mix run scripts/text_generate.exs "Explain functional programming"

# Streaming text
mix run scripts/text_stream.exs "Write a haiku about code"

# Object generation (use Anthropic for best results)
mix run scripts/object_generate.exs "Create a profile for Alice" -m anthropic:claude-3-5-haiku-20241022

# Image analysis
mix run scripts/multimodal_image_analysis.exs "What's in this image?" --file priv/examples/test.jpg
```

--------------------------------

### Quick Start Examples

Source: https://github.com/agentjido/req_llm/blob/main/README.md

Basic usage examples for text generation, structured output, and image generation.

```elixir
# Keys are picked up from .env files or environment variables - see `ReqLLM.Keys`
model = "anthropic:claude-haiku-4-5"

ReqLLM.generate_text!(model, "Hello world")
#=> "Hello! How can I assist you today?"

schema = [name: [type: :string, required: true], age: [type: :pos_integer]]
person = ReqLLM.generate_object!(model, "Generate a person", schema)
#=> %{name: "John Doe", age: 30}

output = ReqLLM.Output.array([name: [type: :string, required: true]])
{:ok, response} = ReqLLM.generate_text(model, "Generate three people", output: output)
ReqLLM.Response.output(response, output)
#=> [%{"name" => "Ada"}, %{"name" => "Grace"}, %{"name" => "Linus"}]

result = ReqLLM.Response.output_result(response, output)
result.valid?       #=> true
result.raw          # retained text or tool-call arguments
result.repairs      # visible legacy or callback repair attempts

{:ok, strict_response} = ReqLLM.generate_text(
  model,
  "Generate three people",
  output: output,
  output_validation: :strict
)

{:ok, image_response} = ReqLLM.generate_image("openai:gpt-image-1.5", "A simple red square")
image_bytes = ReqLLM.Response.image_data(image_response)
File.write!("red_square.png", image_bytes)
```

--------------------------------

### Verify Development Setup

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Run these commands to verify that your development setup is correct and all tests pass.

```bash
# Verify setup
mix test
mix quality
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Follow these steps to clone the ReqLLM repository and install project dependencies.

```bash
# Clone the repository
git clone https://github.com/agentjido/req_llm.git
cd req_llm

# Install dependencies
mix deps.get
```

--------------------------------

### Manual Dependency Installation

Source: https://github.com/agentjido/req_llm/blob/main/README.md

Add the dependency to your mix.exs file and fetch it.

```elixir
def deps do
  [
    {:req_llm, "~> 1.6"}
  ]
end
```

```bash
mix deps.get
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Copy the example environment file and edit it to include your API keys.

```bash
# Set up API keys (copy and configure)
cp .env.example .env
# Edit .env with your API keys
```

--------------------------------

### Perform Initial Setup and Testing

Source: https://github.com/agentjido/req_llm/blob/main/guides/mix-tasks.md

Validate sample models and perform a quick generation test to verify the environment.

```bash
# 1. Validate sample models
mix mc --sample

# 2. Test a quick generation
mix req_llm.gen "Hello, world!" --model openai:gpt-4o-mini
```

--------------------------------

### Install ReqLLM with Igniter

Source: https://github.com/agentjido/req_llm/blob/main/guides/getting-started.md

Use this command to install ReqLLM if your project has Igniter available.

```bash
mix igniter.install req_llm
```

--------------------------------

### Basic Text Generation Example

Source: https://github.com/agentjido/req_llm/blob/main/guides/zenmux.md

A simple example demonstrating text generation for a query. The response is captured in an {:ok, response} tuple.

```elixir
{:ok, response} = ReqLLM.generate_text(
  "zenmux:openai/gpt-4o",
  "What is the capital of France?"
)
```

--------------------------------

### Install Git Hooks

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Install git hooks to enforce code formatting and other checks before pushing.

```bash
# Install git hooks (recommended)
mix git_hooks.install
```

--------------------------------

### Generate Object Profile Script Example

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Run the object generation script to create a structured profile. This example demonstrates generating a software engineer profile with specific model and log level settings.

```bash
mix run scripts/object_generate.exs \
  "Create a software engineer profile" \
  -m anthropic:claude-3-5-haiku-20241022 \
  -l warning
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/agentjido/req_llm/blob/main/README.md

Standard commands for installing dependencies, running tests, performing quality checks, and generating documentation.

```bash
# Install dependencies
mix deps.get

# Run tests with cached fixtures
mix test

# Run quality checks
mix quality  # format, compile, credo --strict, dialyzer

# Generate documentation
mix docs
```

--------------------------------

### Example provider drift output

Source: https://github.com/agentjido/req_llm/blob/main/guides/mix-tasks.md

Sample output showing model coverage status.

```text
----------------------------------------------------
Model Coverage Status
----------------------------------------------------

Anthropic
  ✓ claude-3-5-sonnet-20241022 (flagship)
  ✓ claude-3-5-haiku-20241022 (fast)
  ✗ claude-3-opus-20240229 (flagship)
  2 pass, 1 fail, 0 excluded, 0 untested | 66.7% coverage

OpenAI
  ✓ gpt-4o (flagship)
  ✓ gpt-4o-mini (fast)
  ✓ gpt-3.5-turbo (fast)
  3 pass, 0 fail, 0 excluded, 0 untested | 100.0% coverage

Overall Coverage: 5/6 models validated (83.3%)
```

--------------------------------

### Reasoning Token Usage Example

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Demonstrates extended thinking with reasoning-capable models. Use this to explore complex problems requiring multi-step reasoning.

```bash
mix run scripts/reasoning_tokens.exs "Your prompt here" [options]
```

```bash
# Basic reasoning
mix run scripts/reasoning_tokens.exs \
  "Explain quantum entanglement"
```

```bash
# High effort with token budget
mix run scripts/reasoning_tokens.exs \
  "Solve this complex logic puzzle" \
  --reasoning-effort high \
  --reasoning-token-budget 1000
```

```bash
# Control thinking visibility
mix run scripts/reasoning_tokens.exs \
  "Analyze this algorithm" \
  --thinking-visibility hidden
```

--------------------------------

### Image Generation Prompt Examples

Source: https://github.com/agentjido/req_llm/blob/main/guides/image-generation.md

Examples of less effective prompt patterns for generating multiple images. For reliable multi-image workflows, consider making multiple API calls or using a numbered list format.

```elixir
"Generate two images of cats"
"Create 2 pictures of a banana"
```

```elixir
"Create two DISTINCT and SEPARATE images"
```

--------------------------------

### Basic Text Generation Example

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Demonstrates non-streaming text generation with full response metadata. Use this for standard text completion tasks.

```bash
mix run scripts/text_generate.exs "Your prompt here" [options]
```

```bash
# Basic usage
mix run scripts/text_generate.exs "Explain neural networks"
```

```bash
# With system message
mix run scripts/text_generate.exs "Hello" -s "You are a pirate"
```

```bash
# Different model with parameters
mix run scripts/text_generate.exs "Tell a joke" \
  -m anthropic:claude-3-5-haiku-20241022 \
  --temperature 0.9 \
  --max-tokens 100
```

--------------------------------

### JSON Schema Generation Examples

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Demonstrates various JSON schema patterns and object generation capabilities. Supports different models for schema generation.

```bash
mix run scripts/json_schema_examples.exs [options]
```

```bash
# Run all three examples with OpenAI
mix run scripts/json_schema_examples.exs

```

```bash
# Or with Anthropic
mix run scripts/json_schema_examples.exs \
  -m anthropic:claude-3-5-haiku-20241022
```

--------------------------------

### Install Git Hooks with git_hooks Package

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Install git hooks using the `git_hooks` Elixir package. This typically sets up a pre-push hook to check code formatting.

```bash
mix git_hooks.install
```

--------------------------------

### Advanced Generation and Tooling

Source: https://github.com/agentjido/req_llm/blob/main/README.md

Examples for context-aware generation, tool definitions, and streaming responses.

```elixir
{:ok, response} = ReqLLM.generate_text(
  model,
  ReqLLM.Context.new([
    ReqLLM.Context.system("You are a helpful coding assistant"),
    ReqLLM.Context.user("Explain recursion in Elixir")
  ]),
  temperature: 0.7,
  max_tokens: 200
)


{:ok, response} = ReqLLM.generate_text(
  model,
  "What's the weather in Paris?",
  tools: [
    ReqLLM.tool(
      name: "get_weather",
      description: "Get current weather for a location",
      parameter_schema: [
        location: [type: :string, required: true, doc: "City name"]
      ],
      callback: {Weather, :fetch_weather, [:extra, :args]}
    )
  ]
)

# Streaming text generation
{:ok, response} = ReqLLM.stream_text(model, "Write a short story")
ReqLLM.StreamResponse.tokens(response)
|> Stream.each(&IO.write/1)
|> Stream.run()

# Access usage metadata after streaming
usage = ReqLLM.StreamResponse.usage(response)
```

--------------------------------

### Streaming Text Generation Example

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Shows real-time token streaming as the model generates text. Ideal for interactive applications where immediate feedback is desired.

```bash
mix run scripts/text_stream.exs "Your prompt here" [options]
```

```bash
# Watch tokens appear in real-time
mix run scripts/text_stream.exs "Write a story about a robot"
```

```bash
# With creative parameters
mix run scripts/text_stream.exs "Compose a poem" \
  --temperature 1.2 \
  -s "You are a romantic poet"
```

--------------------------------

### Common ReqLLM Commands

Source: https://github.com/agentjido/req_llm/blob/main/examples/README.md

A collection of common commands to run different ReqLLM examples, including interactive demos, text generation, streaming, and the local playground.

```bash
mix run demo.exs
```

```bash
mix run scripts/text_generate.exs "Explain functional programming"
```

```bash
mix run scripts/text_stream.exs "Write a haiku about code"
```

```bash
./scripts/run_all.sh
```

```bash
mix run playground.exs
```

--------------------------------

### Streaming Object Generation Example

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Generates objects with real-time updates. This script is similar to `object_generate.exs` but provides streaming capabilities.

```bash
mix run scripts/object_stream.exs "Your prompt here" [options]
```

```bash
mix run scripts/object_stream.exs \
  "Create a character profile" \
  -m anthropic:claude-3-5-haiku-20241022
```

--------------------------------

### Configure Web Search Options

Source: https://github.com/agentjido/req_llm/blob/main/guides/anthropic.md

Examples of configuring web search parameters such as usage limits, domain filtering, and user location.

```elixir
# Basic web search with usage limit
provider_options: [web_search: %{max_uses: 5}]

# Web search with domain filtering
provider_options: [
  web_search: %{
    max_uses: 3,
    allowed_domains: ["wikipedia.org", "britannica.com"]
  }
]

# Web search with blocked domains
provider_options: [
  web_search: %{
    blocked_domains: ["untrustedsource.com"]
  }
]

# Web search with user location for localized results
provider_options: [
  web_search: %{
    max_uses: 5,
    user_location: %{
      type: "approximate",
      city: "San Francisco",
      region: "California",
      country: "US",
      timezone: "America/Los_Angeles"
    }
  }
]

# Combine with regular tools
ReqLLM.chat(
  "What's the weather in NYC and latest tech news?",
  model: "anthropic:claude-sonnet-4-5",
  tools: [my_weather_tool],
  provider_options: [web_search: %{max_uses: 3}]
)
```

--------------------------------

### Set XAI API Key

Source: https://github.com/agentjido/req_llm/blob/main/guides/xai.md

Set the XAI_API_KEY environment variable to authenticate with xAI services. This is a required setup step.

```bash
XAI_API_KEY=xai-...
```

--------------------------------

### Listing and Validating Image Models

Source: https://github.com/agentjido/req_llm/blob/main/guides/image-generation.md

Provides examples for discovering which image generation models are available through ReqLLM and how to validate a specific model's configuration. This is useful for selecting the appropriate model for your needs.

```elixir
# List all models that support image generation
ReqLLM.Images.supported_models()
# => ["openai:gpt-image-1", "openai:dall-e-3", "google:gemini-2.5-flash-image", ...]

# Validate a specific model
{:ok, model} = ReqLLM.Images.validate_model("openai:gpt-image-1")
```

--------------------------------

### Web Search Integration for Real-time Data

Source: https://github.com/agentjido/req_llm/blob/main/guides/zenmux.md

Enable web search to fetch up-to-date information for LLM prompts. This example configures web search to be enabled with a limit of 10 results.

```elixir
{:ok, response} = ReqLLM.generate_text(
  "zenmux:openai/gpt-4o",
  "What are the latest AI developments in 2026?",
  provider_options: [
    web_search_options: %{
      enabled: true,
      max_results: 10
    }
  ]
)
```

--------------------------------

### Implement a custom ResponseBuilder

Source: https://github.com/agentjido/req_llm/blob/main/guides/adding_a_provider.md

Example of a custom provider builder that delegates to the default implementation and applies provider-specific post-processing.

```elixir
defmodule ReqLLM.Providers.Zephyr.ResponseBuilder do
  @moduledoc "Custom ResponseBuilder for Zephyr provider."

  @behaviour ReqLLM.Provider.ResponseBuilder

  alias ReqLLM.Provider.Defaults.ResponseBuilder, as: DefaultBuilder

  @impl true
  def build_response(chunks, metadata, opts) do
    # Delegate to default builder for standard processing
    with {:ok, response} <- DefaultBuilder.build_response(chunks, metadata, opts) do
      # Apply provider-specific post-processing
      response = apply_zephyr_quirks(response, metadata)
      {:ok, response}
    end
  end

  defp apply_zephyr_quirks(response, metadata) do
    # Example: Zephyr includes session_id in metadata
    case metadata[:session_id] do
      nil -> response
      sid -> %{response | provider_meta: Map.put(response.provider_meta, :session_id, sid)}
    end
  end
end
```

--------------------------------

### Generate Image with Descriptive Prompt (OpenAI)

Source: https://github.com/agentjido/req_llm/blob/main/guides/image-generation.md

Use a descriptive prompt for best results when generating images with OpenAI models. This example uses the gpt-image-1 model.

```elixir
 {:ok, response} = ReqLLM.generate_image(
  "openai:gpt-image-1",
  "A cozy coffee shop interior with warm lighting, exposed brick walls,
   vintage furniture, and steam rising from ceramic cups on wooden tables"
)
```

--------------------------------

### Basic Image Generation (Google Gemini)

Source: https://github.com/agentjido/req_llm/blob/main/guides/image-generation.md

Generate an image using Google's Gemini models. This example uses `gemini-2.5-flash-image` and specifies the `aspect_ratio`.

```elixir
{:ok, response} = ReqLLM.generate_image(
  "google:gemini-2.5-flash-image",
  "A futuristic cityscape with flying cars and neon lights",
  aspect_ratio: "16:9"
)
```

--------------------------------

### Track Grounding Cost and Usage

Source: https://github.com/agentjido/req_llm/blob/main/guides/google.md

Example of generating text with Google Search grounding and accessing the usage details for web search queries and overall cost.

```elixir
{:ok, response} = ReqLLM.generate_text(
  "google:gemini-3-flash-preview",
  "What are the latest developments in quantum computing?",
  provider_options: [google_grounding: %{enable: true}]
)

# Access grounding/search usage
response.usage.tool_usage.web_search
#=> %{count: 3, unit: "query"}

# Access cost breakdown
response.usage.cost
#=> %{tokens: 0.001, tools: 0.015, images: 0.0, total: 0.016}
```

--------------------------------

### Basic Text Generation and Usage Metrics

Source: https://github.com/agentjido/req_llm/blob/main/guides/zenmux.md

A fundamental example of generating text and accessing usage metrics like total cost and tokens. This is useful for basic API interaction and cost tracking.

```elixir
{:ok, response} = ReqLLM.generate_text("zenmux:openai/gpt-4o", "Hello")
IO.puts("Cost: $#{response.usage.total_cost}")
IO.puts("Tokens: #{response.usage.total_tokens}")
```

--------------------------------

### Update Key Lookup Aliases

Source: https://github.com/agentjido/req_llm/blob/main/guides/v2-migration-audit.md

Rename fetch and fetch! functions to get and get! for key lookups.

```elixir
ReqLLM.Keys.fetch(:openai)
ReqLLM.Keys.fetch!(:openai)
```

```elixir
ReqLLM.Keys.get(:openai)
ReqLLM.Keys.get!(:openai)
```

--------------------------------

### Function Calling with Tools

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Demonstrates how to use tools and function calling capabilities with different models. Supports single and multi-tool calls.

```bash
mix run scripts/tools_function_calling.exs "Your prompt here" [options]
```

```bash
# Single tool call
mix run scripts/tools_function_calling.exs \
  "What's the weather in Paris in Celsius?"

```

```bash
# Multi-tool call (uses default prompt)
mix run scripts/tools_function_calling.exs

```

```bash
# With Anthropic
mix run scripts/tools_function_calling.exs \
  "Tell me a joke about programming" \
  -m anthropic:claude-3-5-haiku-20241022
```

--------------------------------

### Add a new provider

Source: https://github.com/agentjido/req_llm/blob/main/guides/mix-tasks.md

Workflow steps for implementing and recording fixtures for a new provider.

```bash
# 1. Implement provider module
# 2. Create test file using Comprehensive macro
# 3. Record initial fixtures
mix mc "newprovider:*" --record

# 4. Verify all tests pass
mix mc "newprovider"
```

--------------------------------

### Constructing LLMDB.Model instances

Source: https://github.com/agentjido/req_llm/blob/main/guides/data-structures.md

Demonstrates various ways to instantiate a model, including using the helper functions or direct struct creation.

```elixir
{:ok, model} = ReqLLM.model("anthropic:claude-haiku-4-5")

model =
  ReqLLM.model!(%{
    provider: :openai,
    id: "gpt-6-mini",
    base_url: "http://localhost:8000/v1"
  })

# Direct struct creation if you need full control
model = LLMDB.Model.new!(%{
  provider: :anthropic,
  id: "claude-3-5-sonnet-20241022",
  capabilities: %{tool_call: true},
  modalities: %{input: [:text, :image], output: [:text]},
  cost: %{input: 3.0, output: 15.0}
})
```

--------------------------------

### Sample testing configuration

Source: https://github.com/agentjido/req_llm/blob/main/guides/mix-tasks.md

Commands to run sample tests and the corresponding configuration structure in config.exs.

```bash
# Test sample subset (uses config/config.exs)
mix mc --sample

# Test sample for specific provider
mix mc "anthropic:*" --sample
```

```elixir
# Configure samples in config/config.exs
config :req_llm,
  sample_text_models: [
    "openai:gpt-4o-mini",
    "anthropic:claude-3-5-haiku-20241022"
  ],
  sample_embedding_models: [
    "openai:text-embedding-3-small"
  ]
```

--------------------------------

### Inspect unredacted context

Source: https://github.com/agentjido/req_llm/blob/main/guides/configuration.md

Example output when context redaction is disabled.

```elixir
inspect(context)
#=> "#Context<2 msgs: system:\"You are a helpful assistant\", user:\"Hello\">"
```

--------------------------------

### Add New Provider Commands

Source: https://github.com/agentjido/req_llm/blob/main/guides/fixture-testing.md

Commands to record initial fixtures and verify tests for a new provider.

```bash
mix mc "<provider>:*" --record
```

```bash
mix mc "<provider>"
```

--------------------------------

### Inspect redacted context

Source: https://github.com/agentjido/req_llm/blob/main/guides/configuration.md

Example output when context redaction is enabled.

```elixir
inspect(context)
#=> "#Context<4 messages [REDACTED]>"
```

--------------------------------

### Implement provider-agnostic end-to-end flow

Source: https://github.com/agentjido/req_llm/blob/main/guides/data-structures.md

Demonstrates a complete workflow including model initialization, tool definition, context creation, and text generation without provider-specific branching.

```elixir
alias ReqLLM.Message.ContentPart

{:ok, model} = ReqLLM.model("anthropic:claude-haiku-4-5")

{:ok, tool} = ReqLLM.Tool.new(
  name: "get_weather",
  description: "Gets weather by city",
  parameter_schema: [city: [type: :string, required: true]],
  callback: fn %{city: city} -> {:ok, "Weather in #{city}: sunny"} end
)

context = ReqLLM.Context.new([
  ReqLLM.Context.system("You are a helpful assistant."),
  ReqLLM.Context.user([
    ContentPart.text("What is the weather in NYC today?")
  ])
])

{:ok, response} = ReqLLM.generate_text(model, context, tools: [tool])

IO.puts("Answer: " <> ReqLLM.Response.text(response))
IO.inspect(ReqLLM.Response.usage(response), label: "Usage")
```

--------------------------------

### Google Grounding Usage

Source: https://github.com/agentjido/req_llm/blob/main/guides/usage-and-billing.md

Example of tracking grounding query usage when using Google models.

```elixir
{:ok, response} = ReqLLM.generate_text(
  "google:gemini-3-flash-preview",
  "Current stock market trends",
  provider_options: [google_grounding: %{enable: true}]
)

response.usage.tool_usage.web_search
#=> %{count: 2, unit: "query"}
```

--------------------------------

### Basic Image Generation and Saving

Source: https://github.com/agentjido/req_llm/blob/main/guides/image-generation.md

Demonstrates how to generate an image from a text prompt using ReqLLM and save the resulting binary data to a file. Ensure the ReqLLM library and necessary image models are configured.

```elixir
 {:ok, response} = ReqLLM.generate_image(
  "openai:gpt-image-1",
  "A serene Japanese garden with cherry blossoms"
)

# Extract the image binary data
image_data = ReqLLM.Response.image_data(response)

# Save to file
File.write!("garden.png", image_data)
```

--------------------------------

### Define Comprehensive Provider Test

Source: https://github.com/agentjido/req_llm/blob/main/guides/fixture-testing.md

Example of a provider-specific test file using the ReqLLM.ProviderTest.Comprehensive macro.

```elixir
defmodule ReqLLM.Coverage.Anthropic.ComprehensiveTest do
  use ReqLLM.ProviderTest.Comprehensive, provider: :anthropic
end
```

--------------------------------

### Replace full Finch pool configuration

Source: https://github.com/agentjido/req_llm/blob/main/guides/configuration.md

Overrides the entire Finch pool setup for origin-specific settings.

```elixir
config :req_llm,
  finch: [
    name: ReqLLM.Finch,
    pools: %{
      :default => [protocols: [:http1], size: 1, count: 32]
    }
  ]
```

--------------------------------

### Test Image Generation with Fixtures

Source: https://github.com/agentjido/req_llm/blob/main/guides/image-generation.md

Shows how to use fixtures to simulate image generation responses for testing purposes without making actual API calls. Requires the 'image_basic' fixture to be set up.

```elixir
{:ok, response} = ReqLLM.generate_image(
  "openai:gpt-image-1",
  "A test prompt",
  fixture: "image_basic"
)
```

--------------------------------

### xAI Web Search Usage

Source: https://github.com/agentjido/req_llm/blob/main/guides/usage-and-billing.md

Example of tracking web search usage when using xAI models.

```elixir
{:ok, response} = ReqLLM.generate_text(
  "xai:grok-4-1-fast-reasoning",
  "Latest tech news",
  xai_tools: [%{type: "web_search"}]
)

response.usage.tool_usage.web_search
#=> %{count: 5, unit: "call"}
```

--------------------------------

### Anthropic Web Search Usage

Source: https://github.com/agentjido/req_llm/blob/main/guides/usage-and-billing.md

Example of tracking web search usage when using Anthropic models.

```elixir
{:ok, response} = ReqLLM.generate_text(
  "anthropic:claude-sonnet-4-5",
  "What's happening in AI today?",
  provider_options: [web_search: %{max_uses: 5}]
)

response.usage.tool_usage.web_search
#=> %{count: 3, unit: "call"}
```

--------------------------------

### Configure provider options using flat and namespaced shapes

Source: https://github.com/agentjido/req_llm/blob/main/guides/configuration.md

Demonstrates legacy flat provider options and the newer provider-keyed namespace approach for configuration.

```elixir
ReqLLM.generate_text(
  "openai:gpt-5",
  "Solve this carefully",
  provider_options: [reasoning_summary: "auto"]
)
```

```elixir
ReqLLM.generate_text(
  "openai:gpt-5",
  "Solve this carefully",
  provider_options: [
    openai: [reasoning_summary: "auto"]
  ]
)
```

```elixir
provider_options: %{
  openai: %{reasoning_summary: "auto"}
}
```

--------------------------------

### Configure Application Default Credentials

Source: https://github.com/agentjido/req_llm/blob/main/guides/google_vertex.md

Set up local development environment variables for Google Cloud authentication.

```bash
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_REGION="global"
```

--------------------------------

### Define ReqLLM.StreamChunk payloads

Source: https://github.com/agentjido/req_llm/blob/main/guides/data-structures.md

Examples of different StreamChunk types used for content, tool calls, and metadata.

```elixir
%ReqLLM.StreamChunk{type: :content, text: "Hello"}
%ReqLLM.StreamChunk{type: :tool_call, name: "get_weather", arguments: %{city: "NYC"}}
%ReqLLM.StreamChunk{type: :meta, metadata: %{finish_reason: "stop"}}
```

--------------------------------

### Define and Use Tools for LLM Calls

Source: https://github.com/agentjido/req_llm/blob/main/guides/core-concepts.md

Illustrates how to define a tool with a name, description, parameter schema, and callback function using `ReqLLM.Tool.new/1`. It then shows how to invoke a text generation request that can utilize this tool.

```elixir
 {:ok, tool} = ReqLLM.Tool.new(
  name: "get_weather",
  description: "Gets weather by city",
  parameter_schema: [city: [type: :string, required: true]],
  callback: fn %{city: city} -> {:ok, "Weather in #{city}: sunny"} end
)

 {:ok, response} =
  ReqLLM.generate_text("anthropic:claude-haiku-4-5",
    ReqLLM.Context.new([ReqLLM.Context.user("Weather in NYC today? ")]),
    tools: [tool]
  )
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Before starting development, create a new branch for your feature using Git.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Context and Messages for Generation

Source: https://github.com/agentjido/req_llm/blob/main/usage-rules.md

Construct a context using `ReqLLM.Context.new/1` with system and user messages to guide the AI's response.

```elixir
context = ReqLLM.Context.new([
  ReqLLM.Context.system("You are a helpful coding assistant"),
  ReqLLM.Context.user("Explain recursion in Elixir")
])

{:ok, response} = ReqLLM.generate_text("anthropic:claude-haiku-4-5", context)
```

--------------------------------

### Configure Usage and Plugins

Source: https://github.com/agentjido/req_llm/blob/main/guides/openrouter.md

Enable usage reporting and OpenRouter plugins.

```elixir
provider_options: [openrouter_usage: %{include: true}]
```

```elixir
provider_options: [openrouter_plugins: [%{id: "web"}]]
```

--------------------------------

### Example Telemetry Metadata Payload

Source: https://github.com/agentjido/req_llm/blob/main/guides/telemetry.md

A representative map structure containing the base keys and streaming-specific fields for a typical ReqLLM request.

```elixir
%{
  request_id: "2184",
  operation: :chat,
  mode: :stream,
  provider: :anthropic,
  model: %LLMDB.Model{},
  transport: :finch,
  reasoning: %{
    supported?: true,
    requested?: true,
    effective?: true,
    requested_mode: :enabled,
    requested_effort: :medium,
    requested_budget_tokens: 4096,
    effective_mode: :enabled,
    effective_effort: :medium,
    effective_budget_tokens: 4096,
    returned_content?: true,
    reasoning_tokens: 812,
    content_bytes: 1432,
    channel: :content_and_usage
  },
  request_summary: %{
    message_count: 1,
    text_bytes: 42,
    image_part_count: 0,
    tool_call_count: 0
  },
  response_summary: %{
    text_bytes: 318,
    thinking_bytes: 1432,
    tool_call_count: 0,
    image_count: 0,
    object?: false
  },
  http_status: 200,
  finish_reason: :stop,
  usage: %{
    input_tokens: 24,
    output_tokens: 133,
    total_tokens: 157,
    reasoning_tokens: 812
  },
  request_options: %{
    temperature: 0.7,
    max_tokens: 1024,
    stream?: true,
    conversation_id: "thread-42"
  },
  server: %{
    address: "api.anthropic.com",
    port: 443,
    path: "/v1/messages"
  },
  streaming: %{
    first_chunk_at: -576_460_751_000_000_000,
    time_to_first_chunk: 412_300_000
  }
}
```

--------------------------------

### Configure Service Account via Environment Variables

Source: https://github.com/agentjido/req_llm/blob/main/guides/google_vertex.md

Set environment variables to authenticate using a service account JSON file.

```bash
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
GOOGLE_CLOUD_PROJECT="your-project-id"
GOOGLE_CLOUD_REGION="global"
```

--------------------------------

### Configure Groq Web Search Settings

Source: https://github.com/agentjido/req_llm/blob/main/guides/groq.md

Enable web search capabilities by configuring `search_settings`, including specifying domains to include or exclude.

```elixir
provider_options: [
  search_settings: %{
    include_domains: ["techcrunch.com", "arstechnica.com"],
    exclude_domains: ["spam.com"]
  }
]
```

--------------------------------

### ReqLLM doctor JSON output schema

Source: https://github.com/agentjido/req_llm/blob/main/guides/mix-tasks.md

Example of the machine-readable JSON output returned when using the --format json flag.

```json
{
  "schema_version": 1,
  "status": "ok",
  "checks": [
    {
      "id": "runtime.application",
      "layer": "runtime",
      "status": "ok",
      "message": "ReqLLM and its supervision tree are running.",
      "remediation": null,
      "details": {}
    }
  ]
}
```

--------------------------------

### Structure of the usage field

Source: https://github.com/agentjido/req_llm/blob/main/guides/data-structures.md

Example of the normalized usage data map containing token counts, cost breakdowns, and tool/image usage.

```elixir
%{
  # Token counts
  input_tokens: 150,
  output_tokens: 200,
  total_tokens: 350,
  reasoning_tokens: 0,        # For reasoning models (o1, o3, gpt-5)
  cached_tokens: 100,         # Cached input tokens
  cache_creation_tokens: 0,   # Tokens used to create cache

  # Cost breakdown (USD)
  input_cost: 0.00045,
  output_cost: 0.0006,
  total_cost: 0.00105,

  # Detailed cost by category
  cost: %{
    tokens: 0.00105,
    tools: 0.02,              # Web search, function calls
    images: 0.0,              # Image generation
    total: 0.02105,
    line_items: [...]         # Per-component cost details
  },

  # Tool usage (web search, etc.)
  tool_usage: %{
    web_search: %{count: 2, unit: "call"}
  },

  # Image usage (for image generation)
  image_usage: %{
    generated: %{count: 1, size_class: "1024x1024"}
  }
}
```

--------------------------------

### Select Models for Testing

Source: https://github.com/agentjido/req_llm/blob/main/guides/fixture-testing.md

Configure which models to test using environment variables for selection, sampling, or exclusion.

```bash
# Test all available models
REQ_LLM_MODELS="all" mix mc

# Test all models from a provider
REQ_LLM_MODELS="anthropic:*" mix mc

# Test specific models (comma-separated)
REQ_LLM_MODELS="openai:gpt-4o,anthropic:claude-3-5-sonnet" mix mc

# Sample N models per provider
REQ_LLM_SAMPLE=2 mix mc

# Exclude specific models
REQ_LLM_EXCLUDE="gpt-4o-mini,gpt-3.5-turbo" mix mc
```

--------------------------------

### Migration audit JSON report schema

Source: https://github.com/agentjido/req_llm/blob/main/guides/v2-migration-audit.md

Example of the JSON schema returned by the migration audit, containing scan summaries and specific findings.

```json
{
  "schema_version": 1,
  "status": "findings",
  "summary": {
    "files_scanned": 12,
    "actionable": 1,
    "advisory": 0,
    "errors": 0
  },
  "findings": [
    {
      "id": "req_llm.stream_text_bang",
      "category": "deprecated_api",
      "actionable": true,
      "file": "lib/client.ex",
      "line": 12,
      "column": 5,
      "contract": "ReqLLM.stream_text!/2",
      "owner": "ReqLLM core maintainers",
      "message": "ReqLLM.stream_text!/3 is deprecated.",
      "replacement": "ReqLLM.stream_text/3 and a ReqLLM.StreamResponse projection",
      "guide": "https://hexdocs.pm/req_llm/v2-migration-audit.html#bang-streaming-apis"
    }
  ],
  "errors": []
}
```

--------------------------------

### Run All Tests

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Execute all tests in the project, using cached fixtures by default.

```bash
# Run all tests with cached fixtures
mix test
```

--------------------------------

### List Available Models (Bash)

Source: https://github.com/agentjido/req_llm/blob/main/guides/nearai.md

Fetch the list of available models from the NEAR AI Cloud public catalog using curl.

```bash
curl https://cloud-api.near.ai/v1/model/list
```

--------------------------------

### Incorrect Schema Definition for OpenAI

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

An example of a schema definition that may fail with OpenAI due to missing `required: true` flags on fields.

```elixir
# ❌ May fail with OpenAI - missing required flags
schema = [
  name: [type: :string],
  age: [type: :integer]
]
```

--------------------------------

### Run Smoke Test

Source: https://github.com/agentjido/req_llm/blob/main/guides/adding_a_provider.md

Verify the provider integration using the CLI.

```bash
export ACME_API_KEY=sk-...
mix req_llm.gen "Hello" --model acme:acme-chat-mini
```

--------------------------------

### Specify Models for Generation

Source: https://github.com/agentjido/req_llm/blob/main/guides/getting-started.md

Models can be specified as strings, tuples, structs, or map specs. Refer to the Model Specs guide for a full workflow.

```elixir
"anthropic:claude-haiku-4-5"
{:anthropic, "claude-3-sonnet-20240229", temperature: 0.7}
ReqLLM.model!(%{provider: :openai, id: "gpt-6-mini", base_url: "http://localhost:8000/v1"})
```

--------------------------------

### Execute ReqLLM Fixture Commands

Source: https://github.com/agentjido/req_llm/blob/main/guides/fixture-testing.md

Use these commands to validate models against fixtures or record live API calls for specific providers.

```bash
# Validation (using fixtures)
mix mc                          # All models with passing fixtures
mix mc anthropic                # All Anthropic models
mix mc "openai:gpt-4o"          # Specific model
mix mc --sample                 # Sample models per provider
mix mc --available              # List all registry models

# Recording (live API calls)
mix mc --record                 # Re-record passing models
mix mc "xai:*" --record         # Re-record xAI models
mix mc "<provider>:*" --record  # Re-record specific provider

# Environment variables
REQ_LLM_FIXTURES_MODE=record    # Force recording
REQ_LLM_MODELS="pattern"        # Model selection pattern
REQ_LLM_SAMPLE=N                # Sample N per provider
REQ_LLM_EXCLUDE="model1,model2" # Exclude models
REQ_LLM_DEBUG=1                 # Verbose output
```

--------------------------------

### Generation with System Context

Source: https://github.com/agentjido/req_llm/blob/main/guides/deepseek.md

Provide system context to guide the model's behavior. This is useful for setting up specific roles or instructions for the AI.

```elixir
context = ReqLLM.Context.new([
  ReqLLM.Context.system("You are a helpful coding assistant."),
  ReqLLM.Context.user("How do I parse JSON in Elixir?")
])

model = ReqLLM.model!(%{provider: :deepseek, id: "deepseek-reasoner"})

{:ok, response} = ReqLLM.generate_text(model, context)
```

--------------------------------

### Test model subsets

Source: https://github.com/agentjido/req_llm/blob/main/guides/fixture-testing.md

Runs tests against a predefined sample list configured in config/config.exs.

```bash
# Test sample models per provider (uses config/config.exs sample list)
mix mc --sample

# Test specific provider samples
mix mc --sample anthropic
```

--------------------------------

### Run All Tests

Source: https://github.com/agentjido/req_llm/blob/main/AGENTS.md

Execute all tests in the project using cached fixtures.

```shell
mix test
```

--------------------------------

### OpenAI Image Editing with Source Image

Source: https://github.com/agentjido/req_llm/blob/main/guides/image-generation.md

Demonstrates how to perform image editing using OpenAI models by providing a source image. This allows for reference-based generation or modifications like applying a style. Ensure the source image is read into binary data.

```elixir
source_image = File.read!("source.png")

{:ok, response} = ReqLLM.generate_image(
  "openai:gpt-image-1.5",
  "Create a polished product hero image using this as reference",
  source_image: source_image,
  source_image_media_type: "image/png",
  output_format: :png
)

image_data = ReqLLM.Response.image_data(response)
```

--------------------------------

### Configure Fireworks API Key (Bash)

Source: https://github.com/agentjido/req_llm/blob/main/guides/fireworks_ai.md

Set your Fireworks API key as an environment variable for authentication. This is a common setup step before making API calls.

```bash
FIREWORKS_API_KEY=fw_...
```

--------------------------------

### Configure Meta Model API Key

Source: https://github.com/agentjido/req_llm/blob/main/guides/meta.md

Set the environment variable to authenticate with the Meta Model API.

```bash
MODEL_API_KEY=your-api-key
```

--------------------------------

### Add a New Model Provider

Source: https://github.com/agentjido/req_llm/blob/main/guides/mix-tasks.md

Register a new provider by creating a JSON patch file, testing the model, and recording fixtures.

```bash
# 1. Add models to local patch
cat > priv/models_local/newprovider.json <<EOF
{
  "provider": {
    "id": "newprovider",
    "name": "New Provider"
  },
  "models": [
    {
      "id": "model-v1",
      "name": "Model v1",
      "type": "chat"
    }
  ]
}
EOF

# 2. Test the model
mix req_llm.gen "Hello" --model newprovider:model-v1

# 3. Record fixtures
mix mc "newprovider:*" --record
```

--------------------------------

### Structured Object Generation Example

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Generates validated JSON objects matching a schema. Ensure all schema fields have `required: true` for OpenAI strict mode.

```bash
mix run scripts/object_generate.exs "Your prompt here" [options]
```

```bash
# Generate person profile
mix run scripts/object_generate.exs \
  "Create a profile for a software engineer named Alice" \
  -m anthropic:claude-3-5-haiku-20241022
```

```bash
# Extract structured data from text
mix run scripts/object_generate.exs \
  "Extract info: John Smith, 35, lawyer in Boston" \
  -m anthropic:claude-sonnet-4-5-20250929
```

--------------------------------

### Using Tools for Generation

Source: https://github.com/agentjido/req_llm/blob/main/usage-rules.md

Define tools with descriptions and parameter schemas, then pass them to `generate_text/4` to allow the model to use them.

```elixir
weather_tool = ReqLLM.tool(
  name: "get_weather",
  description: "Get current weather for a location",
  parameter_schema: [location: [type: :string, required: true]],
  callback: {WeatherAPI, :fetch_weather}
)

ReqLLM.generate_text("openai:gpt-4", "What's the weather in Paris?", tools: [weather_tool])
```

--------------------------------

### Configure API Keys

Source: https://github.com/agentjido/req_llm/blob/main/guides/fixture-testing.md

Define API keys in the .env file to ensure tests can execute against live APIs.

```bash
# Set in .env file
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
```

--------------------------------

### Generate Text with Web Search and Access Usage

Source: https://github.com/agentjido/req_llm/blob/main/guides/xai.md

Example of generating text using a Grok model with web search enabled, and then accessing the tool usage and cost breakdown from the response.

```elixir
{:ok, response} = ReqLLM.generate_text(
  "xai:grok-4-1-fast-reasoning",
  "What are the latest news about AI?",
  xai_tools: [%{type: "web_search"}]
)

# Access web search usage
response.usage.tool_usage.web_search
#=> %{count: 3, unit: "call"}

# Access cost breakdown
response.usage.cost
#=> %{tokens: 0.002, tools: 0.03, images: 0.0, total: 0.032}
```

--------------------------------

### Basic Text Generation Test with Live Fixture

Source: https://github.com/agentjido/req_llm/blob/main/AGENTS.md

Demonstrates a basic happy-path test for text generation using ReqLLM. The test utilizes a live fixture to abstract response handling and asserts that the generated text contains the expected content.

```elixir
defmodule CoreTest do
  use ReqLLM.Test.LiveFixture, provider: :openai
  use ExUnit.Case, async: true

  describe "generate_text/3" do
    test "basic happy-path" do
      {:ok, text} =
        use_fixture(:provider, "core-basic", fn ->
          ReqLLM.generate_text!("openai:gpt-4o", "Hello!")
        end)

      assert text =~ "Hello"
    end
  end
end
```

--------------------------------

### Run Tests Against Live APIs

Source: https://github.com/agentjido/req_llm/blob/main/CONTRIBUTING.md

Run tests against live APIs and regenerate fixtures by setting the `LIVE` environment variable to `true`.

```bash
# Run tests against live APIs (regenerate fixtures)
LIVE=true mix test
```

--------------------------------

### List Available Models

Source: https://github.com/agentjido/req_llm/blob/main/AGENTS.md

List all models available in the model registry.

```shell
mix mc --available
```

--------------------------------

### Execute Provider Drift Anchors

Source: https://github.com/agentjido/req_llm/blob/main/guides/fixture-testing.md

Runs the provider drift anchors for all providers or a specific selected provider.

```bash
mix req_llm.provider_drift
```

```bash
mix req_llm.provider_drift --provider openai
```

--------------------------------

### Extract Specific Information from PDF

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Extract specific information from a PDF document using the multimodal PDF QA script. This example shows how to list all mentioned dates and limit the response tokens.

```bash
mix run scripts/multimodal_pdf_qa.exs \
  "List all mentioned dates" \
  --file report.pdf \
  --max-tokens 500
```

--------------------------------

### Define and execute a ReqLLM tool

Source: https://github.com/agentjido/req_llm/blob/main/guides/data-structures.md

Create a tool with a schema for argument validation and execute it locally.

```elixir
{:ok, tool} = ReqLLM.Tool.new(
  name: "get_weather",
  description: "Gets weather by city",
  parameter_schema: [city: [type: :string, required: true]],
  callback: fn %{city: city} -> {:ok, "Weather in #{city}: sunny"} end
)

# Execute locally (e.g., after a model issues a tool_call)
{:ok, result} = ReqLLM.Tool.execute(tool, %{"city" => "NYC"})
```

--------------------------------

### Generate Text with Fireworks AI Model

Source: https://github.com/agentjido/req_llm/blob/main/guides/fireworks_ai.md

Generate text using a specified Fireworks AI model ID. This example shows how to use an exact model ID from LLMDB or a custom model ID.

```elixir
ReqLLM.generate_text(
  "fireworks_ai:accounts/fireworks/models/kimi-k2p5",
  "Hello!"
)
```

```elixir
# Or inline for models not yet in LLMDB:
model = ReqLLM.model!(
  provider: :fireworks_ai,
  id: "accounts/fireworks/models/some-new-model"
)
ReqLLM.generate_text(model, "Hello!")
```

--------------------------------

### Create Simple PDF using ps2pdf

Source: https://github.com/agentjido/req_llm/blob/main/examples/scripts/README.md

Create a basic PDF file from standard input using the `ps2pdf` command. This is useful for generating test PDF documents.

```bash
echo "Test document content" | ps2pdf - priv/examples/my_doc.pdf
```

--------------------------------

### Generate Text with Bedrock using API Key

Source: https://github.com/agentjido/req_llm/blob/main/guides/amazon_bedrock.md

Example of generating text with an Anthropic Claude model via Amazon Bedrock using an API key for authentication. Ensure the model ID is correct and the API key is valid.

```elixir
ReqLLM.generate_text(
  "amazon_bedrock:anthropic.claude-3-sonnet-20240229-v1:0",
  "Hello",
  provider_options: [api_key: "your-api-key", region: "us-east-1"]
)
```

--------------------------------

### Record Fixtures and Validate Coverage

Source: https://github.com/agentjido/req_llm/blob/main/guides/adding_a_provider.md

Commands for recording live test fixtures and validating model compatibility.

```bash
# Record fixtures during live test runs
LIVE=true mix test --only provider:acme

# Or use model compatibility tool
mix mc "acme:*" --record
```

```bash
# Quick validation
mix mc

# Sample models during development
mix mc --sample
```

--------------------------------

### Implement a minimal OpenAI-compatible provider

Source: https://github.com/agentjido/req_llm/blob/main/guides/adding_a_provider.md

Use this structure to create a provider that reuses default ReqLLM functionality while adding custom headers.

```elixir
defmodule ReqLLM.Providers.Acme do
  @moduledoc "Acme – OpenAI-compatible chat API."

  use ReqLLM.Provider,
    id: :acme,
    default_base_url: "https://api.acme.ai/v1",
    default_env_key: "ACME_API_KEY"

  use ReqLLM.Provider.Defaults

  @provider_schema [
    organization: [type: :string, doc: "Tenant/Org header"]
  ]

  @impl ReqLLM.Provider
  def attach(request, model_input, user_opts) do
    request = super(request, model_input, user_opts)
    provider_opts = user_opts[:provider_options] || []
    org = provider_opts[:organization]
    
    case org do
      nil -> request
      _ -> Req.Request.put_header(request, "x-acme-organization", org)
    end
  end
end
```