### 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
```

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

### 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
```

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

### Initial Setup: Quick Generation Test

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

Perform a quick text generation test using a specified model. This is a simple way to verify model interaction after initial setup.

```bash
mix req_llm.gen "Hello, world!" --model openai:gpt-4o-mini
```

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

### Install Dependencies and Run Tests

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

Commands to install project dependencies, run tests with cached fixtures, perform quality checks, and generate 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
```

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

### End-to-End Text Generation with Tools

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

An example demonstrating text generation with a defined tool. It sets up a model, defines a tool for getting weather, creates a context, and then generates text, printing the answer and usage statistics. This example is provider-agnostic.

```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")
```

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

### Development Configuration Example

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

Example configuration for a development environment, setting shorter timeouts, enabling debug mode, and enabling dotenv loading.

```elixir
# config/dev.exs
config :req_llm,
  receive_timeout: 60_000,
  debug: true,
  load_dotenv: true
```

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

### Production Configuration Example

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

Example configuration for a production environment, setting timeouts, telemetry, disabling dotenv loading, and configuring Finch.

```elixir
# config/prod.exs
config :req_llm,
  receive_timeout: 120_000,
  stream_receive_timeout: 120_000,
  thinking_timeout: 300_000,
  metadata_timeout: 120_000,
  telemetry: [payloads: :none],
  load_dotenv: false,  # Use proper secrets management in production
  finch: [
    name: ReqLLM.Finch,
    pools: %{
      :default => [protocols: [:http1], size: 1, count: 16]
    }
  ]
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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?"
)
```

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

### Troubleshoot Model Not Found

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

Example error for a model not being found and how to list available models for a provider.

```bash
Error: Model 'gpt-invalid' not found
# List models: mix mc openai
```

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

### Get Dependencies

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

Run this command after updating `mix.exs` to fetch the new dependency.

```bash
mix deps.get
```

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

### Fixture State Tracking Example

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

Example JSON structure for `priv/supported_models.json`, which tracks the validation status and last checked time for each model.

```json
{
  "anthropic:claude-3-5-sonnet-20241022": {
    "status": "pass",
    "last_checked": "2025-01-29T10:30:00Z"
  },
  "openai:gpt-4o": {
    "status": "pass",
    "last_checked": "2025-01-29T10:30:15Z"
  },
  "xai:grok-vision-beta": {
    "status": "excluded",
    "last_checked": null
  }
}
```

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

### Troubleshoot Missing API Key

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

Example error message for a missing API key and how to set it using environment variables.

```bash
Error: API key not found for anthropic
# Set: export ANTHROPIC_API_KEY=sk-ant-...
```

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

### 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
```

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

### Define and Execute a ReqLLM Tool

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

Example of defining a new tool with a name, description, parameter schema, and callback, then executing 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"})
```

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

### Troubleshoot Fixture Mismatch

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

Example of a fixture mismatch failure and how to re-record the specific fixture.

```bash
FAIL anthropic:claude-3-5-sonnet
# Re-record: mix mc "anthropic:claude-3-5-sonnet" --record
```

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

### 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
```

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

### Comprehensive Test Macro Example

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

Example of how the Comprehensive test macro is used within a provider's test file.

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

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

### 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"
```

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

### Example Model Coverage Status Output

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

Example output format for the model coverage status report, showing pass/fail status for models within providers and overall coverage percentage.

```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%)
```

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

### 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
```

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

### ReqLLM Configuration Example

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

Shows how to set the default AI model in the application's configuration file (`config/config.exs`). This avoids repeatedly specifying the model in commands.

```elixir
config :req_llm, default_model: "openai:gpt-4o-mini"
```

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

### Troubleshoot Invalid Model Spec

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

Example error for an unknown provider and how to check available providers.

```bash
Error: Unknown provider 'invalid'
# Check: mix mc --available
```

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

### 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"
```

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

### Getting Usage Metadata: After

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

Illustrates concurrent metadata collection (usage, finish_reason) with the new API.

```elixir
{:ok, response} = ReqLLM.stream_text(model, messages)

# Stream tokens in real-time
tokens_task = Task.start(fn ->
  response
  |> ReqLLM.StreamResponse.tokens()
  |> Stream.each(&IO.write/1)
  |> Stream.run()
end)

# Collect metadata concurrently
usage = ReqLLM.StreamResponse.usage(response)
finish_reason = ReqLLM.StreamResponse.finish_reason(response)

IO.puts("\nUsage: #{inspect(usage)}")
IO.puts("Finish reason: #{finish_reason}")
```

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

### 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
```

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

### 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-...
```

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

### 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
```

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

### 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")
```

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

### Initiate a Streaming Text Operation

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

Example of initiating a streaming text generation request and obtaining a stream response handle.

```elixir
{:ok, sr} = ReqLLM.stream_text("anthropic:claude-haiku-4-5",
  [ReqLLM.Context.user("Tell me a story")]
)
```

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

### Generate Text with Tools

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

Generates text while enabling the model to use predefined tools. This example defines a 'get_weather' tool with its parameters and callback.

```elixir
{: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]}
    )
  ]
)
```

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

### Test Streaming Text (Before Migration)

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

Example of a test case for streaming text before migrating to the new API format. It asserts that all chunks are binaries.

```elixir
test "streams text" do
  chunks = ReqLLM.stream_text!("anthropic:claude-3-sonnet", "Hello") |> Enum.take(5)
  assert Enum.all?(chunks, &is_binary/1)
end
```

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

### 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
    }
  ]
)
```

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

### 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}
```

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

### Google Grounding Tool Usage

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

Example of making a text generation request with Google, enabling grounding features, and then inspecting the tool usage (queries) from the response.

```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"}
```

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

### 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
```

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

### Custom Response Format Configuration

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

Provide custom response format configuration using `response_format`. This example demonstrates setting up JSON schema for structured output.

```elixir
provider_options: [
  response_format: %{
    type: "json_schema",
    json_schema: %{
      name: "person",
      schema: %{type: "object", properties: %{name: %{type: "string"}}}
    }
  }
]
```

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

### Record initial fixtures for a new provider

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

Command to record initial fixtures for a newly implemented provider. Use the `--record` flag to capture live API responses.

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

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

### 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}")
```

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

### 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}
```

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

### API Key Configuration via .env Files

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

Recommended method for configuring API keys using a .env file. Supports multiple providers.

```bash
# .env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
```

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

### Getting Usage Metadata: Before

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

Shows that usage metadata was not available during streaming with the old API.

```elixir
# Usage was only available after completion via separate call
ReqLLM.stream_text!(model, messages) |> Stream.run()
# No way to get usage metadata for the stream
```

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

### Add New Provider: Record Initial Fixtures

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

After implementing a new provider module and test file, record initial fixtures for all its models. This step is crucial for establishing a baseline.

```bash
mix mc "newprovider:*" --record
```

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

### Add New Provider: Verify Tests Pass

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

After recording initial fixtures for a new provider, run the compatibility tests again to ensure all tests pass with the newly recorded fixtures.

```bash
mix mc "newprovider"
```

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

### 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)
```

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

### Context Redaction Example (Enabled)

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

When context redaction is enabled, inspect/2 shows only the message count.

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

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

### 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
```

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

### Configure Usage Reporting

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

Use `openrouter_usage` to configure usage reporting. The example shows how to include usage reporting.

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

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

### Setting API Keys via Environment Variables

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

Demonstrates how to set API keys for various AI providers using environment variables. This is a common method for securely providing credentials.

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...
export OPENROUTER_API_KEY=...
export XAI_API_KEY=...
```

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

### Context Redaction Example (Disabled)

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

When context redaction is disabled (default), inspect/2 shows the full message preview.

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

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

### 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"
)
```

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

### 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]
  )
```

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

### Set Top-A Sampling Parameter

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

Use `openrouter_top_a` to configure the top-a sampling parameter. An example value of 0.1 is provided.

```elixir
provider_options: [openrouter_top_a: 0.1]
```

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

### Set Repetition Penalty

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

Use `openrouter_repetition_penalty` to reduce repetitive text in the generated output. A value of 1.1 is provided as an example.

```elixir
provider_options: [openrouter_repetition_penalty: 1.1]
```

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

### 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)
```

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

### Show Models with Passing Fixtures

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

Run compatibility tests for models with passing fixtures. This is a quick way to verify the current state of tested models.

```bash
mix req_llm.model_compat
mix mc
```

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

### Connection Pool Configuration

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

Indicates that the new Finch-based system allows connection pool configuration. No code example provided in source.

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

### LiveView Integration: After

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

Shows how to integrate streaming responses with LiveView using the new API and `Task` for concurrent processing.

```elixir
def handle_info({:stream_text, model, messages}, socket) do
  case ReqLLM.stream_text(model, messages) do
    {:ok, response} ->
      # Stream tokens to the client
      parent = self()

      Task.start(fn ->
        try do
          response
          |> ReqLLM.StreamResponse.tokens()
          |> Stream.each(&send(parent, {:token, &1}))
          |> Stream.run()
        rescue
          e in ReqLLM.Error.API.Stream ->
            send(parent, {:stream_error, e})
        end
      end)

      # Handle metadata when available
      Task.start(fn ->
        usage = ReqLLM.StreamResponse.usage(response)
        send(self(), {:usage, usage})
      end)

      {:noreply, socket}

    {:error, reason} ->
      {:noreply, put_flash(socket, :error, "Stream failed: #{inspect(reason)}")}
  end
end

def handle_info({:token, token}, socket) do
  {:noreply, push_event(socket, "token", %{text: token})}
end

def handle_info({:usage, usage}, socket) do
  {:noreply, push_event(socket, "usage", usage)}
end
```

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

### Generate Text with OpenRouter Model

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

Example of generating text using a specified OpenRouter model and accessing cost information from the response.

```elixir
 {:ok, response} = ReqLLM.generate_text("openrouter:model", "Hello")
IO.puts("Cost: $#{response.usage.total_cost}")
```

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

### 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"]
  }
]
```

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

### Create Cached Binary Image ContentPart

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

Shows how to create a ContentPart for binary image data with ephemeral caching.

```elixir
cached_binary_image = ContentPart.image(
  image_data,
  "image/png",
  %{cache_control: %{type: "ephemeral"}}
)
```

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

### Per-Request Finch Callback

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

Pass an anonymous function to modify Finch requests on a per-call basis. This example adds a 'x-request-id' header.

```elixir
ReqLLM.stream_text("openai:gpt-4o", "Hello",
  on_finch_request: fn req ->
    %{req | headers: req.headers ++ [{"x-request-id", UUID.generate()}]}
  end
)
```

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

### Verbose fixture debugging

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

Enable verbose output for fixture debugging to get detailed logs during test execution. Useful for troubleshooting.

```bash
# Verbose fixture debugging
REQ_LLM_DEBUG=1 mix mc
```

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

### 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
```

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

### Create ReqLLM.Context with Messages

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

Initializes a ReqLLM.Context with a list of messages, including system prompts, user queries, and multimodal content. This demonstrates how to build a conversation history using the `Context.new` constructor and `ContentPart` for embedding files.

```elixir
import ReqLLM.Context
alias ReqLLM.Message.ContentPart

context = Context.new([
  system("You are a helpful assistant."),
  user("Summarize this document."),
  user([
    ContentPart.file(pdf_data, "report.pdf", "application/pdf")
  ])
])
```

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

### Basic Streaming: After

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

Shows the recommended `StreamResponse` API for basic streaming.

```elixir
{:ok, response} = ReqLLM.stream_text(model, "Tell me a story")
response
|> ReqLLM.StreamResponse.tokens()
|> Stream.each(&IO.write/1)
|> Stream.run()
```

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

### Sample N models per provider

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

Sample a specified number of models from each provider for testing. This is efficient for development and quick checks.

```bash
REQ_LLM_SAMPLE=2 mix mc
```

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

### Set Minimum Probability Threshold for Sampling

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

Use `openrouter_min_p` to set the minimum probability threshold for sampling. An example value of 0.05 is shown.

```elixir
provider_options: [openrouter_min_p: 0.05]
```

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

### Test all models from a provider

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

Use this command to test all available models from a specific provider. This is useful for comprehensive testing.

```bash
REQ_LLM_MODELS="anthropic:*" mix mc
```

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

### 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]
]
```

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

### Set API key in .env file

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

Configure API keys for providers by setting them in a `.env` file. This is necessary for tests that require live API access.

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

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

### 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
```

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

### ReqLLM StreamChunk Examples

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

Illustrates different types of stream chunks that can be received during a streaming operation, including content, tool calls, and metadata.

```elixir
%ReqLLM.StreamChunk{type: :content, text: "Hello"}
```

```elixir
%ReqLLM.StreamChunk{type: :tool_call, name: "get_weather", arguments: %{city: "NYC"}}
```

```elixir
%ReqLLM.StreamChunk{type: :meta, metadata: %{finish_reason: "stop"}}
```

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

### Implement Custom Finch Request Adapter

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

Provides an example implementation of the `ReqLLM.FinchRequestAdapter` behavior, adding a custom header to outgoing Finch requests.

```elixir
defmodule MyApp.TestFinchAdapter do
  @behaviour ReqLLM.FinchRequestAdapter

  @impl true
  def call(%Finch.Request{} = request) do
    %{request | headers: request.headers ++ [{"x-test-env", "true"}]}
  end
end
```

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

### 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"})
```

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

### Basic Text Generation with ReqLLM

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

Generates text from a prompt using the default model. Useful for quick tests and simple queries.

```bash
mix req_llm.gen "Explain how neural networks work"
```

```bash
mix req_llm.gen "What is 2+2?"
```

```bash
mix req_llm.gen "Explain quantum computing in simple terms"
```

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

### 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
```

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

### 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)
```

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

### 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)
```

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

### Custom ResponseBuilder Implementation

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

Example of a custom `ResponseBuilder` for a fictional 'Zephyr' provider. It delegates standard processing to the default builder and then 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
```

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

### Authentication with ReqLLM.Keys

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

Demonstrates the recommended way to retrieve API keys using `ReqLLM.Keys`, emphasizing not to read environment variables directly.

```elixir
api_key = ReqLLM.Keys.get!(model, opts)
```

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

### 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])
```

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

### Enable OpenRouter Plugins

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

Use `openrouter_plugins` to enable OpenRouter plugins, such as the web search plugin. The example shows how to enable a plugin with a specific ID.

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

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

### 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
```

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

### Configure Finch Request Adapter Module

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

Sets a module that implements the `ReqLLM.FinchRequestAdapter` behavior for modifying Finch requests before they are sent. This example is for test environments.

```elixir
config :req_llm, finch_request_adapter: MyApp.TestFinchAdapter
```

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

### Get Detailed Cost Breakdown

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

Accesses the detailed cost breakdown within the usage data. This map categorizes costs by tokens, tools, and images.

```elixir
response.usage.cost
#=> %{
#     tokens: 0.001,
#     tools: 0.02,
#     images: 0.04,
```

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

### 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
```

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

### Usage of Ollama Helper Module

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

Demonstrates how to use the custom `MyApp.Ollama` helper module for generating text with different models and options.

```elixir
# Usage
MyApp.Ollama.generate_text("llama3", "Explain pattern matching")
MyApp.Ollama.generate_text("gemma2", "Write a poem", temperature: 0.9)
```

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

### 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_...
```

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

### Error Handling: After

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

Demonstrates proper error handling using error tuples with the new API.

```elixir
case ReqLLM.stream_text(model, messages) do
  {:ok, response} ->
    response
    |> ReqLLM.StreamResponse.tokens()
    |> Stream.each(&IO.write/1)
    |> Stream.run()

  {:error, reason} ->
    handle_error(reason)
end
```

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

### 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
```

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

### Configure Sample Models in Config

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

Define sample models for testing in `config/config.exs`. This allows customization of which models are included in `--sample` tests.

```elixir
config :req_llm,
  sample_text_models: [
    "openai:gpt-4o-mini",
    "anthropic:claude-3-5-haiku-20241022"
  ],
  sample_embedding_models: [
    "openai:text-embedding-3-small"
  ]
```

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

### OAuth Credentials JSON Structure

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

Example of an OAuth JSON file structure for storing credentials, compatible with ReqLLM and pi-ai. This file can be referenced using `oauth_file`.

```json
{
  "openai-codex": {
    "type": "oauth",
    "access": "eyJ...",
    "refresh": "oai_rt_...",
    "expires": 1762857415123,
    "accountId": "user_123"
  }
}
```

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

### Set Number of Top Log Probabilities to Return

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

Use `openrouter_top_logprobs` to specify the number of top log probabilities to return. An example value of 5 is shown.

```elixir
provider_options: [openrouter_top_logprobs: 5]
```

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

### Fixture JSON format

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

Example of the JSON structure used for fixtures, capturing API response details. Includes metadata like model spec and scenario.

```json
{
  "captured_at": "2025-01-15T10:30:00Z",
  "model_spec": "anthropic:claude-3-5-sonnet-20241022",
  "scenario": "basic",
  "result": {
    "ok": true,
    "response": {
      "id": "msg_123",
      "model": "claude-3-5-sonnet-20241022",
      "message": {...},
      "usage": {...}
    }
  }
}
```

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

### 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
```