### Check Model Installation for chat_ollama()

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-ollama.md

If a requested model is not installed locally, `chat_ollama()` will throw an error indicating the model's absence and provide instructions on how to install it using `ollama pull` or `ellmer::models_ollama()`.

```R
chat_ollama(model = "not-a-real-model")
```

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

### Streaming Responses with ellmer

Source: https://context7.com/tidyverse/ellmer/llms.txt

Shows how to use the $stream() method to receive response chunks as they arrive, allowing for fine-grained control over streaming content. Includes examples for basic iteration and using content objects.

```R
library(ellmer)

chat <- chat_openai()

# Basic streaming - iterate through chunks
stream <- chat$stream("Write a short poem about coding")
for (chunk in stream) {
  cat(chunk)
}
```

```R
stream <- chat$stream("Explain recursion", stream = "content")
for (content in stream) {
  if (inherits(content, "ContentText")) {
    cat(content@text)
  }
}
```

```R
controller <- stream_controller()
stream <- chat$stream("Write a very long story", controller = controller)

# In another context (e.g., button handler):
# controller$cancel()  # Stops the stream
```

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

### Replay Local Class Extending Ellmer Class

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/content-replay.md

Local classes that extend ellmer classes can be replayed. This example shows a successful test case for recording and replaying text content.

```R
test_record_replay(test_content("hello world"))
```

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

### Handle Unsupported Remote Images

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-aws.md

This example demonstrates an error when attempting to use a remote image with the chat function, as the current provider (AWS Bedrock) does not support it.

```R
. <- chat$chat("What's in this image?", image_remote)
```

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

### Chat with vLLM models

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `chat_vllm()` to interact with models served by vLLM. No specific setup is mentioned beyond having vLLM running.

```R
chat_vllm()
```

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

### Install ellmer Package

Source: https://github.com/tidyverse/ellmer/blob/main/README.md

Install the ellmer package from CRAN. This is the primary method for obtaining the package.

```r
install.packages("ellmer")
```

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

### Handling Deprecated Echo Argument in ellmer

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils.md

This example shows how ellmer warns users when a deprecated `echo` argument is used, suggesting the updated `echo = "output"` syntax. Use the recommended argument to avoid warnings and ensure future compatibility.

```R
expect_equal(check_echo("text"), "output")
```

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

### Get system prompt

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `Chat$get_system_prompt()` to retrieve the current system prompt. This replaces the older `Chat$system_prompt()` function.

```R
Chat$get_system_prompt()
```

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

### Basic Chat Operations in ellmer

Source: https://context7.com/tidyverse/ellmer/llms.txt

Demonstrates fundamental chat interactions, including getting responses, disabling echo for string-only output, managing multi-turn conversations, and accessing conversation history.

```R
chat$chat("Tell me a joke about statisticians")
```

```R
response <- chat$chat("What is 2 + 2?", echo = "none")
response
```

```R
chat$chat("Now multiply that by 10")
```

```R
chat$get_turns()
```

```R
chat$last_turn()
```

```R
chat$set_system_prompt("You are a pirate. Respond accordingly.")
chat$chat("What's the weather like?")
```

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

### Validate Tool Arguments Match Function Formals

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def.md

Checks if the names provided in the `arguments` list for `tool()` exactly match the formal arguments of the function. This example highlights missing and extra argument definitions.

```R
tool(fun, "", arguments = list(z = type_number()))
```

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

### Define and Use a Simple Tool

Source: https://context7.com/tidyverse/ellmer/llms.txt

Defines a tool named 'get_weather' that takes a city name and returns a weather description. Demonstrates calling the tool directly and registering it with a chat model.

```r
library(ellmer)

# Define a tool with the tool() function
get_weather <- tool(
  function(city) {
    # In real usage, this would call a weather API
    paste("The weather in", city, "is sunny and 72F")
  },
  name = "get_weather",
  description = "Get the current weather for a city",
  arguments = list(
    city = type_string("The city name")
  )
)

# Tools are callable functions
get_weather(city = "Paris")
#> [1] "The weather in Paris is sunny and 72F"

# Register tool with a chat
chat <- chat_openai()
chat$register_tool(get_weather)

# The LLM will automatically call the tool when needed
chat$chat("What's the weather like in Tokyo?")
#> [tool call] get_weather(city = "Tokyo")
#> The weather in Tokyo is sunny and 72F.
```

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

### Creating a UserTurn

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/turns.md

Instantiates a user turn with the provided content. The output shows a concise representation of the turn.

```R
UserTurn("hello")
```

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

### Warn about unsupported parameters during standardization

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/params.md

The `standardise_params` function issues a warning when it encounters unsupported parameters, such as 'top_p' in this example, and ignores them.

```R
. <- standardise_params(test_params, provider_params)
```

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

### Configure Azure OpenAI Client

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-azure.md

Instantiate the Azure OpenAI client with your endpoint and deployment ID. Defaults for api_version will be reported.

```R
. <- chat_azure_openai("endpoint", "deployment_id")
```

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

### Basic interpolate() usage

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/interpolate.md

Demonstrates the basic usage of the `interpolate()` function with a simple string prompt. The output shows the formatted prompt.

```R
interpolate("Hi!")
```

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

### Validate Tool Definition: Function Type

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def.md

Checks if the `fun` argument provided to `tool()` is a function. This example shows an error when a non-function is provided.

```R
tool(1)
```

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

### Use `credentials` instead of deprecated `api_key`

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-auth.md

The `api_key` argument is deprecated. Use the `credentials` argument for authentication.

```R
chat <- chat_openai_compatible_test(api_key = "abc")
```

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

### Validate Tool Definition: Name Type

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def.md

Verifies that the `name` argument for `tool()` is a single string or NULL. This example shows an error when a number is provided.

```R
tool(identity, "", name = 1)
```

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

### Initialize OpenAI Chat Object

Source: https://github.com/tidyverse/ellmer/blob/main/README.md

Load the ellmer library and create an OpenAI chat object. Specify the desired model for the conversation.

```r
library(ellmer)

chat <- chat_openai("Be terse", model = "gpt-4o-mini")
```

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

### as_json with .additional_properties for OpenAI

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-openai-compatible.md

This code demonstrates an attempt to use as_json with the .additional_properties argument set to TRUE for an OpenAI provider. This operation is not supported and will result in an error.

```R
as_json(stub, type_object(.additional_properties = TRUE))
```

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

### Initialize Cloudflare Chat with Defaults

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-cloudflare.md

This snippet shows how to initialize the Cloudflare chat client. It uses the default model, which is reported in the message.

```R
. <- chat_cloudflare()

```

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

### Validate Tool Argument Type Definition

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def.md

Ensures that each element within the `arguments` list for `tool()` is a valid type definition. This example shows an error when a number is provided for an argument type.

```R
tool(fun, "", arguments = list(x = type_number(), y = 1))
```

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

### Error in create_tool_def with Invalid Chat Argument

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def-auto.md

This example shows an error condition when using `create_tool_def` with an invalid type for the `chat` argument. The `chat` argument must be a `<Chat>` object or `NULL`.

```R
create_tool_def(print, chat = 1)
```

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

### Define a Tool with Deprecated Arguments

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def.md

Shows how to define a tool using deprecated arguments. This will trigger warnings indicating the preferred arguments to use instead.

```R
f <- tool(function(x) x * 2, .name = "double", .description = "double the input",
      x = type_number(), .convert = FALSE, .annotations = tool_annotations(title = "My Tool"))
```

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

### Add chat_portkey() and models_portkey() providers

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use these functions to integrate models hosted on Portkey AI.

```r
chat_portkey()
```

```r
models_portkey()
```

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

### Structured Data Extraction with ellmer

Source: https://context7.com/tidyverse/ellmer/llms.txt

Details the use of $chat_structured() for extracting structured data from text or images based on a provided type specification. Includes examples for simple field extraction and image analysis.

```R
library(ellmer)

chat <- chat_openai()

# Extract simple fields from text
data <- chat$chat_structured(
  "My name is Susan and I'm 13 years old",
  type = type_object(
    name = type_string(),
    age = type_number()
  )
)
data
```

```R
# Extract from image
data <- chat$chat_structured(
  content_image_url("https://www.r-project.org/Rlogo.png"),
  type = type_object(
    primary_shape = type_string(),
    primary_colour = type_string()
  )
)
```

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

### Load prompts from a file

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `prompt_file()` to load prompt templates from external files. This aids in organizing and managing complex prompts.

```R
prompt_file()
```

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

### Chat with a Provider using a String

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use the `chat()` function to interact with different LLM providers by specifying their name as a string. This simplifies the process of switching between providers like Anthropic or OpenAI.

```R
chat("anthropic")
chat("openai/gpt-4.1-nano")
```

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

### Configure Mock LLM Provider

Source: https://github.com/tidyverse/ellmer/blob/main/revdep/problems.md

Sets up a mock LLM provider for testing or development. It specifies the provider name, base URL, model, and parameters like seed. Note the unused 'api_key' argument.

```R
GitAI::set_llm(my_project)
       Backtrace:
           ▆
        1. ├─GitAI::set_prompt(set_llm(my_project), system_prompt = "You always return only 'Hi there!'") at test-set_llm.R:105:3
        2. └─GitAI::set_llm(my_project)
        3.   ├─rlang::exec(provider_method, !!!provider_args)
        4.   └─GitAI (local) `<fn>`(model = "gpt-4o-mini", params = NULL, echo = "none")
        5.     └─GitAI:::mock_chat_method(...) at ./setup.R:50:3
        6.       └─rlang::exec(provider_class, name = "mock", !!!provider_args) at ./setup.R:24:3
       
       [ FAIL 5 | WARN 0 | SKIP 5 | PASS 38 ]
       Error:
       ! Test failures.
       Execution halted
```

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

### Aggregate Column Descriptions for a Data Frame

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/schema.md

Use `df_schema()` to get a summary of columns in a data frame. It works on standard data frames and handles edge cases like empty data frames.

```R
df_schema(df)
```

```R
df_schema(data.frame())
```

```R
df_schema(data.frame(x = 1, y = "a"))
```

```R
df_schema(data.frame(x = 1:5))
```

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

### Get token usage data frame

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

The `Chat$tokens()` method has been renamed to `Chat$get_tokens()`. It now returns a data frame of tokens, correctly aligned to individual turns, which is used by the print method to display input/output token usage per turn.

```r
Chat$get_tokens()
```

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

### Registering and Replacing Tools

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `Chat$register_tool()` to add tools to a chat instance. A message is displayed if you are replacing an existing tool.

```R
chat_object$register_tool(my_new_tool)
```

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

### Error handling in as_user_turns()

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/turns.md

`as_user_turns()` expects a list or a prompt as input. Individual elements within the list must be strings or content objects.

```R
as_user_turns(1)
```

```R
as_user_turns(x)
```

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

### Initialize Hugging Face Chat Model

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-huggingface.md

Initializes the chat interface with a specified Hugging Face model. Ensure the model name is correct for intended functionality.

```R
. <- chat_huggingface()
Using model = "meta-llama/Llama-3.1-8B-Instruct".
```

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

### Initialize Deepseek Chat Model

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-deepseek.md

Initializes the deepseek-chat model. Ensure the model name is correctly specified.

```R
. <- chat_deepseek()
Message
  Using model = "deepseek-chat".
```

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

### Capture Sink with Custom Prefix and Newlines

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-cat.md

Demonstrates capturing output with a custom prefix ('Dickens&gt; ') and handling explicit newlines within the sink function. Shows how explicit newlines are preserved and the prefix is applied to each line.

```R
cat(capture_sink(prefix = "Dickens&gt; ", function(sink) {
  sink("It was the best of times,\nit was the worst of times,\n")
  sink("it was the age ")
  sink("of wisdom, it was the age of ")
  sink("foolishness,\nit was the epoch of belief")
  sink(", it was the epoch of incredulity, ")
  sink(paste(rep_len(" ", 200), collapse = ""))
  sink("it was the season of Light, it wa")
  sink("s the season of Darkness,\n\n\nit was the spring of hope,")
  sink(" it was the wint")
  sink("er of despair.")
}))
```

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

### Initialize Chat with Groq

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-groq.md

Initializes a chat session using the Groq API. The default model is automatically selected.

```R
. <- chat_groq()

```

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

### Initialize Databricks Chat Client

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-databricks.md

Use chat_databricks() to initialize the Databricks chat client. This sets the default model for subsequent interactions.

```R
. <- chat_databricks()
```

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

### Define a Tool with a Print Method

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def.md

Demonstrates defining a tool with a custom print method. The output shows the structure of the ToolDef object.

```R
f <- tool(function(x = 1, y = 2) {
    x + y
  }, name = "my_fun", description = "a simple function", convert = TRUE)
```

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

### Wrap Text with Prefix and Limited Width

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-cat.md

Captures and wraps text output with a '?&gt; ' prefix, limiting lines to 70 characters. Useful for formatted, paginated output.

```R
cat(capture_sink(prefix = "?&gt; ", width = 70, function(sink) {
  sink("It was the best of times, it was the worst of times, it was the age ")
  sink("of wisdom, it was the age of foolishness, it was the epoch of belief")
  sink(", it was the epoch of incredulity, it was the season of Light, it wa")
  sink("s the season of Darkness, it was the spring of hope, it was the wint")
  sink("er of despair.")
}))
```

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

### Create Local Ollama Chat Object

Source: https://context7.com/tidyverse/ellmer/llms.txt

Use `chat_ollama()` to connect to locally-running Ollama models. Specify the model name and optionally a custom `base_url` for remote servers. Use `models_ollama()` to list available models.

```R
library(ellmer)

# Connect to local Ollama (must have Ollama running)
chat <- chat_ollama(model = "llama3.1")
chat$chat("Hello! What can you help me with today?")

# With custom base URL for remote Ollama server
chat <- chat_ollama(
  model = "mistral",
  base_url = "http://my-server:11434",
  params = params(temperature = 0.5, top_k = 40)
)

# List available models
models_ollama()
#>          id                       name capabilities
#> 1  llama3.1 Meta Llama 3.1 8B Instruct         chat
#> 2   mistral          Mistral 7B v0.3    chat,tools
```

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

### Echoing Tool Requests and Results with invoke_tools_async

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/chat-tools.md

Similar to `invoke_tools`, `invoke_tools_async` can echo tool requests and results when `echo = "output"`. The output order may differ due to asynchronous execution.

```R
. <- sync(gen_async_promise_all(invoke_tools_async(turn, echo = "output")))
```

```R
. <- sync(coro::async_collect(invoke_tools_async(turn, echo = "output")))
```

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

### Initialize OpenAI Chat

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-openai.md

Initializes the OpenAI chat interface. The default model is reported upon successful initialization.

```R
`. <- chat_openai()`
```

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

### Replay Recorded Object

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/content-replay.md

Replaying a recorded object may fail if the required package, such as 'foo', is not found.

```R
contents_replay(recorded)
```

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

### Error handling in as_user_turn()

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/turns.md

`as_user_turn()` requires at least one input and expects all inputs to be unnamed. Inputs must be strings or content objects; other types will cause an error.

```R
as_user_turn(list())
```

```R
as_user_turn(list(x = 1))
```

```R
as_user_turn(1)
```

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

### Global Tool Approval Pattern

Source: https://context7.com/tidyverse/ellmer/llms.txt

Implements a global tool approval callback that prompts the user for permission before executing specific tools like 'delete_file' or 'write_file'.

```R
chat$on_tool_request(function(request) {
  if (request@name %in% c("delete_file", "write_file")) {
    answer <- utils::menu(
      c("Allow", "Deny"),
      title = paste("Allow tool", request@name, "?")
    )
    if (answer != 1) {
      tool_reject("User denied permission")
    }
  }
})
```

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

### Specify common model parameters

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use the `params` argument with the `params()` helper in `chat_anthropic()`, `chat_azure()`, `chat_openai()`, and `chat_gemini()` to specify common model parameters like `seed` and `temperature` across different providers.

```r
chat_anthropic(params = params(seed = 100, temperature = 0.5))
```

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

### Handle Unsupported Image Extensions with content_image_file

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/content-image.md

Provide image files with supported extensions to `content_image_file()`. This function errors for unsupported file types like '.r'.

```R
content_image_file(test_path("test-content.R"))
```

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

### Submit multiple chats to batched interfaces

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `batch_chat()` and `batch_chat_structured()` to submit multiple chats to OpenAI and Anthropic's batched interfaces. These services guarantee a response within 24 hours and are more cost-effective.

```r
batch_chat()
```

```r
batch_chat_structured()
```

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

### Check Recorded Object Structure

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/content-replay.md

Use `contents_replay` with a list that has 'version', 'class', and 'props' names. Errors occur if these are missing.

```R
contents_replay(bad_names)
```

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

### Record and Replay Chat Turns

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

The `contents_record()` and `contents_replay()` methods allow you to save and load the state of a `Chat` instance, useful for bookmarking conversations.

```R
contents_record(chat_object)
contents_replay(recorded_content)
```

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

### Define Type from JSON Schema

Source: https://context7.com/tidyverse/ellmer/llms.txt

Shows how to define types by loading an existing JSON schema from a file or directly from a JSON string.

```r
# Use existing JSON schema
type_from_schema(path = "schema.json")
type_from_schema(text = '{"type": "object", "properties": {...}}')
```

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

### Register tool request and result callbacks

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Implement custom logging or actions for tool requests and results using `$on_tool_request()` and `$on_tool_result()` methods without modifying tool functions.

```r
Chat$on_tool_request()
```

```r
Chat$on_tool_result()
```

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

### Interpolate from file with non-existent path

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/interpolate.md

Attempts to interpolate a prompt from a file that does not exist. This results in an error indicating that the specified path could not be found.

```R
interpolate_file("does-not-exist.md", x = 1)
```

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

### Create prompts with interpolation

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `interpolate()` to create prompts that mix static text with dynamic values. This simplifies prompt construction for varied inputs.

```R
interpolate()
```

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

### Error if both `credentials` and `api_key` are provided

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-auth.md

An error occurs if both `credentials` and `api_key` arguments are supplied simultaneously. Provide only one.

```R
chat_openai_compatible_test(credentials = "abc", api_key = "def")
```

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

### Working with PDFs in ellmer

Source: https://context7.com/tidyverse/ellmer/llms.txt

Explains how to process PDF documents with vision-capable models using content_pdf_file() and content_pdf_url(). Supports different models like Anthropic and OpenAI.

```R
library(ellmer)

# Claude handles PDFs natively
chat <- chat_anthropic()
chat$chat(
  "Summarize the key findings in this paper",
  content_pdf_file("research_paper.pdf")
)
```

```R
# PDF from URL
chat$chat(
  "What is this document about?",
  content_pdf_url("https://example.com/report.pdf")
)
```

```R
# OpenAI also supports PDFs
chat <- chat_openai()
chat$chat(
  "Extract the main data tables from this PDF",
  content_pdf_file("financial_report.pdf")
)
```

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

### Stream additional content types with Chat$stream() and Chat$stream_async()

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Enable streaming of additional content types, such as tool requests and results, by setting `stream = "content"`. This yields `Content` objects.

```r
Chat$stream(stream = "content")
```

```r
Chat$stream_async(stream = "content")
```

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

### Chat with AWS Bedrock models

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Initiate a chat session with AWS Bedrock models using `chat_bedrock()`. Ensure AWS credentials and region are configured.

```R
chat_bedrock()
```

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

### Print method with multi-line prompt

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/interpolate.md

Demonstrates the `print` method's handling of multi-line prompts when `max_lines` is set. The output is truncated to the specified number of lines, indicating additional content.

```R
print(ellmer_prompt("a\nb\nc\nd\ne"), max_lines = 3)
```

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

### Error: `credentials` must be a function or `NULL`

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-auth.md

The `credentials` argument must be a function or `NULL`. Providing a number will result in an error.

```R
chat_openai_test(credentials = 1)
```

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

### Improved Cost Estimates with LiteLLM

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Cost estimates are enhanced by capturing cached input tokens for providers like OpenAI and Gemini, and by using LiteLLM for a broader range of pricing data.

```R
chat_openai(..., cache_input_tokens = TRUE)
chat_google_gemini(..., cache_input_tokens = TRUE)
```

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

### Simplified Tool Specification

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

The `tool()` function now requires explicit `name`, `description`, and `arguments`. This change aims to make tool usage clearer and more consistent. Refer to `?tool` for a prompt to help convert older tool specifications.

```R
tool(
  name = "get_weather",
  description = "Get the current weather in a location",
  arguments = list(
    location = type_string("The city and country, e.g. San Francisco, US")
  )
)
```

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

### Live console interaction

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `live_console()` for interactive console sessions, replacing the older `chat_console()` function. This provides a direct interface for command-line interactions.

```R
live_console()
```

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

### Run Live Interactive Consoles

Source: https://context7.com/tidyverse/ellmer/llms.txt

Engage in interactive chat sessions using `live_console()` for terminal-based chat or `live_browser()` to open a Shiny app interface in your browser. The chat object maintains conversation history from these interactive sessions.

```r
library(ellmer)

chat <- chat_openai(
  system_prompt = "You are a helpful R programming assistant"
)

# Interactive console chat (in terminal)
live_console(chat)
#> Entering chat console. Use """ for multi-line input.
#> Press Ctrl+C to quit.
#> >>> How do I read a CSV file?
#> You can read a CSV file using `read.csv()`:
#> ```r
#> data <- read.csv("myfile.csv")
#> ```
#> >>>

# Interactive browser chat (opens Shiny app)
live_browser(chat)
# Opens a browser window with a chat interface

# The chat object retains history from interactive sessions
chat$get_turns()  # Shows conversation from live session
```

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

### Error Traceback in R Testing

Source: https://github.com/tidyverse/ellmer/blob/main/revdep/problems.md

This traceback indicates an error during the execution of an R script, specifically when setting up an LLM provider. The error occurs at line 24 of setup.R, involving rlang::exec and a ProviderOpenAICompatible object.

```r
...
   5.       └─rlang::exec(provider_class, name = "mock", !!!provider_args) at ./setup.R:24:3
  └─ Error ('test-set_llm.R:89:3'): setting LLM without system prompt 
       Error in `(structure(function (name = stop("Required"), model = stop("Required"), base_url = stop("Required"), params = list(), extra_args = list(), extra_headers = character(0), credentials = function() NULL, service_tier = character(0))  new_object(ProviderOpenAICompatible(name = name, model = model, base_url = base_url, params = params, extra_args = extra_args, extra_headers = extra_headers, credentials = credentials), service_tier = service_tier), name = "ProviderOpenAI", parent = structure(function (name = stop("Required"), model = stop("Required"), base_url = stop("Required"), params = list(), extra_args = list(), extra_headers = character(0), credentials = function() NULL)  new_object(Provider(name = name, model = model, base_url = base_url, params = params, extra_args = extra_args, extra_headers = extra_headers, credentials = credentials)), name = "ProviderOpenAICompatible", parent = structure(function (name = stop("Required"), model = stop("Required"), base_url = stop("Required"), params = list(), extra_args = list(), extra_headers = character(0), credentials = function() NULL)  {     name     model     base_url     params     extra_args     extra_headers     credentials     new_object(S7_object(), name = name, model = model, base_url = base_url, params = params, extra_args = extra_args, extra_headers = extra_headers, credentials = credentials) }, name = "Provider", parent = structure(function ()  {     .Call(S7_object_) }, name = "S7_object", properties = list(), abstract = FALSE, constructor = function ()  {     .Call(S7_object_) }, validator = function (self)  {     if (!is_S7_type(self)) {         "Underlying data is corrupt"     } }, class = c("S7_class", "S7_object")), package = "ellmer", properties = list(name = structure(list(name = "name", class = structure(list(class = "character", constructor_name = "character", constructor = function (.data = character(0))  .data, validator = function (object)  {     if (base_class(object) != name) {         sprintf("Underlying data must be <%%s> not <%%s>", name, base_class(object))     } }), class = "S7_base_class"), getter = NULL, setter = NULL, validator = function (value)  {     if (allow_null && is.null(value)) {         return()     }     if (length(value) != 1) {         paste0("must be a single string, not ", obj_type_friendly(value), ".")     }     else if (!allow_na && is.na(value)) {         "must not be missing."     } }, default = stop("Required")), class = "S7_property")), model = structure(list(name = "model", class = structure(list(class = "character", constructor_name = "character", constructor = function (.data = character(0))  .data, validator = function (object)  {     if (base_class(object) != name) {         sprintf("Underlying data must be <%%s> not <%%s>", name, base_class(object))     } }), class = "S7_base_class"), getter = NULL, setter = NULL, validator = function (value)  {     if (allow_null && is.null(value)) {         return()     }     if (length(value) != 1) {         paste0("must be a single string, not ", obj_type_friendly(value), ".")     }     else if (!allow_na && is.na(value)) {         "must not be missing."     } }, default = stop("Required")), class = "S7_property")), base_url = structure(list(name = "base_url", class = structure(list(class = "character", constructor_name = "character", constructor = function (.data = character(0))  .data, validator = function (object)  {     if (base_class(object) != name) {         sprintf("Underlying data must be <%%s> not <%%s>", name, base_class(object))     } }), class = "S7_base_class"), getter = NULL, setter = NULL, validator = function (value)  {     if (allow_null && is.null(value)) {         return()     }     if (length(value) != 1) {         paste0("must be a single string, not ", obj_type_friendly(value), ".")     }     else if (!allow_na && is.na(value)) {         "must not be missing."     } }, default = stop("Required")), class = "S7_property")), params = structure(list(name = "params", class = structure(list(class = "list", constructor_name = "list", constructor = function (.data = list())  .data, validator = function (object)  {     if (base_class(object) != name) {         sprintf("Underlying data must be <%%s> not <%%s>", name, base_class(object))     } }), class = "S7_base_class"), getter = NULL, setter = NULL, validator = NULL, default = NULL), class = "S7_property")), extra_args = structure(list(name = "extra_args", class = structure(list(class = "list", constructor_name = "list", constructor = function (.data = list())  .data, validator = function (object)  {     if (base_class(object) != name) {         sprintf("Underlying data must be <%%s> not <%%s>", name, base_class(object))     } }), class = "S7_base_class"),
```

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

### Portkey Chat with Virtual API Key

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

The `chat_portkey()` function is now functional and reads the virtual API key from the `PORTKEY_VIRTUAL_KEY` environment variable.

```R
Sys.setenv("PORTKEY_VIRTUAL_KEY" = "your_virtual_key")
chat_portkey()
```

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

### Display Thinking Process in HTML

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/content.md

Renders a thinking process as an HTML details element with a summary.

```R
cat(contents_html(ct))
```

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

### Prompt Interpolation

Source: https://context7.com/tidyverse/ellmer/llms.txt

Safely injects dynamic values into prompts using interpolate() and interpolate_file(). Supports basic, multiple, and vectorized variable substitution.

```R
library(ellmer)

# Basic interpolation with {{}} syntax
topic <- "machine learning"
prompt <- interpolate("Explain {{topic}} in simple terms")
prompt
#> [1] "Explain machine learning in simple terms"

# Multiple variables
template <- "Write a {{length}} story about {{subject}} in the style of {{author}}"
interpolate(template,
            length = "short",
            subject = "a robot",
            author = "Shakespeare")

# Vectorized for multiple prompts
countries <- c("USA", "Japan", "Brazil")
prompts <- interpolate("What is the population of {{country}}?",
                       country = countries)
prompts
#> [1] "What is the population of USA?"
#> [2] "What is the population of Japan?"
#> [3] "What is the population of Brazil?"

# Load prompt from file
# prompts/analysis.md:
# You are analyzing data about {{topic}}.
# Focus on: {{focus_areas}}
# Output format: {{format}}

prompt <- interpolate_file("prompts/analysis.md",
                          topic = "sales trends",
                          focus_areas = "seasonal patterns",
                          format = "bullet points")
```

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

### Error: `credentials` must not have arguments

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-auth.md

If `credentials` is a function, it must not accept any arguments. Functions with arguments will cause an error.

```R
chat_openai_test(credentials = function(a, b) a + b)
```

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

### Chat with Image Input

Source: https://github.com/tidyverse/ellmer/blob/main/README.md

Send an image along with a text prompt to the chat model. Use content_image_file() or content_image_url() for image input.

```r
chat$chat(
  content_image_url("https://www.r-project.org/Rlogo.png"),
  "Can you explain this logo?"
)
#> The logo consists of a stylized letter "R" in blue, surrounded by a gray oval 
#> shape. The design reflects the programming language R, which is widely used for
#> statistical computing and graphics. The color choice often symbolizes clarity 
#> and professionalism, aligning with R's use in data analysis and research. The 
#> logo encapsulates the language's focus on data visualization and statistical 
#> methods.
```

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

### Add .annotations argument to tool()

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use the `.annotations` argument with `tool_annotations()` to describe tools to clients, following the Model Context Protocol.

```r
tool(.annotations = tool_annotations())
```

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

### Compute Chat Costs

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/chat.md

The 'details' object provides a tibble showing input, output, cached input, cost, and a preview of the input text for each turn.

```R
details
```

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

### List GitHub Models

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `models_github()` to retrieve a list of available models for `chat_github()`.

```R
models_github()
```

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

### Create Google Gemini Chat Object

Source: https://context7.com/tidyverse/ellmer/llms.txt

Use `chat_google_gemini()` to connect to Google's Gemini API. Defaults to `gemini-2.5-flash`. Supports specific models and parameters like temperature. Automatic caching is also available.

```R
library(ellmer)

# Basic Gemini chat (defaults to gemini-2.5-flash)
chat <- chat_google_gemini()
chat$chat("Explain the tidyverse in 3 sentences.")

# With specific model and parameters
chat <- chat_google_gemini(
  system_prompt = "You are a data science tutor",
  model = "gemini-2.0-flash",
  params = params(temperature = 0.7)
)

# Gemini supports automatic caching too
response <- chat$chat("What's the best way to learn ggplot2?")
```

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

### Check Model Availability in chat_lmstudio

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-lmstudio.md

If a requested model is not loaded in LM Studio, `chat_lmstudio()` will throw an error indicating the model is unavailable and suggesting how to download it or list available models.

```R
chat_lmstudio(model = "not-a-real-model")
```

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

### Robust Model URL Generation

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Functions like `chat_aws_bedrock()`, `chat_google_gemini()`, `chat_ollama()`, and `chat_vllm()` now use a more robust method for generating model URLs from the provided `base_url`.

```R
chat_ollama(base_url = "http://localhost:11434")
```

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

### Tool Request and Result Callbacks

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/chat-tools.md

Callbacks can be set for tool requests and results. Ensure the callback function accepts the correct arguments ('request' or 'result'). Providing a callback with an incorrect argument signature, like 'data', will cause an error.

```R
. <- chat$chat("What are Joe and Hadley's favorite colors?")
```

```R
chat$on_tool_request(function(data) NULL)
```

```R
chat$on_tool_result(function(data) NULL)
```

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

### Live browser interaction

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `live_browser()` for interactive browser sessions, replacing the older `chat_browser()` function. This allows for real-time interaction with web content.

```R
live_browser()
```

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

### Register a tool for chat

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `chat$register_tool()` with an object created by `Tool()` to register tools for use in chat interactions. This simplifies tool definition reuse.

```R
chat$register_tool()
```

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

### Set system prompt

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `Chat$set_system_prompt()` to define the system prompt for a chat. This replaces the older `Chat$system_prompt()` function.

```R
Chat$set_system_prompt()
```

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

### Error: `credentials()` must return a string or named list

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-auth.md

The function provided to `credentials` must return a string or a named list. Returning a number will result in an error.

```R
chat_openai_test(credentials = function() 1)
```

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

### Initialize Anthropic Chat Model

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-claude.md

Initializes the Anthropic chat model. Ensure the 'claude-sonnet-4-5-20250929' model is available or specify a different one.

```R
. <- chat_anthropic()
```

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

### List available models for OpenAI

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `models_openai()` to list available models for OpenAI. The function is guaranteed to return a data frame with at least an `id` column, and may include token prices.

```r
models_openai()
```

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

### Set chat turns using Chat$set_turns()

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

The `turn` argument is no longer available in `chat_` functions. Use `Chat$set_turns()` to set the number of turns for a chat.

```r
Chat$set_turns(n_turns = 5)
```

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

### Generate JSON for Simple User Turn Expansion

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/chat-tools-content.md

Use this function to generate JSON output for a user turn with a simple expansion. This is useful for single tool calls or direct text responses.

```python
print_json(as_json(provider, UserTurn(expanded_simple)))
```

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

### Working with Images in ellmer

Source: https://context7.com/tidyverse/ellmer/llms.txt

Demonstrates how to send images to vision-capable models using various methods: from URLs, local files, or the current plot. Supports resizing and sending multiple images.

```R
library(ellmer)

chat <- chat_openai()

# Image from URL
chat$chat(
  "What do you see in this image?",
  content_image_url("https://www.r-project.org/Rlogo.png")
)
```

```R
# Image from local file
chat$chat(
  "Describe this chart",
  content_image_file("my_plot.png")
)
```

```R
# Capture and analyze current plot
plot(mtcars$mpg ~ mtcars$wt)
chat$chat(
  "Describe this scatter plot, suitable for alt-text",
  content_image_plot()
)
```

```R
# Image with resizing options
chat$chat(
  "What's in this photo?",
  content_image_file("large_photo.jpg", resize = "high")  # 2000x768 max
)
```

```R
# Multiple images in one message
chat$chat(
  "Compare these two images",
  content_image_url("https://example.com/image1.png"),
  content_image_file("local_image.png")
)
```

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

### Extract Signature with No Source File

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/tools-def-auto.md

Illustrates `extract_comments_and_signature` extracting a function signature and comments even when the source file is not available.

```R
extract_comments_and_signature(no_srcfile)
```

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

### Configure Request Retries and Timeout

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Control the number of request retries and the timeout duration using `options()`. The default timeout now applies to the initial connection phase, improving overall request success rates.

```R
options(ellmer_max_tries = 5)
options(ellmer_timeout_s = 60)
```

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

### Output Text with No Prefix and Limited Width

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/utils-cat.md

Captures and wraps text output with no prefix, limiting lines to 70 characters. Use when a clean, wrapped output without any markers is needed.

```R
cat(capture_sink(prefix = "", width = 70, function(sink) {
  sink("It was the best of times, it was the worst of times, it was the age ")
  sink("of wisdom, it was the age of foolishness, it was the epoch of belief")
  sink(", it was the epoch of incredulity, it was the season of Light, it wa")
  sink("s the season of Darkness, it was the spring of hope, it was the wint")
  sink("er of despair.")
}))
```

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

### Create OpenAI Chat Object

Source: https://context7.com/tidyverse/ellmer/llms.txt

Use `chat_openai()` to create a chat object for OpenAI's API. Supports custom system prompts, models, and parameters like temperature and max tokens. Inspect token usage and costs with `$get_tokens()` and `$get_cost()`.

```R
library(ellmer)

# Basic chat with default model (GPT-4.1)
chat <- chat_openai()
chat$chat("What is the capital of France?")
#> Paris is the capital of France.

# With a system prompt and specific model
chat <- chat_openai(
  system_prompt = "You are a helpful assistant that responds concisely.",
  model = "gpt-4.1-nano"
)
chat$chat("Explain quantum computing in one sentence.")
#> Quantum computing uses quantum mechanical phenomena like superposition and
#> entanglement to process information in ways classical computers cannot.

# With custom parameters
chat <- chat_openai(
  system_prompt = "Be creative and playful",
  model = "gpt-4.1",
  params = params(temperature = 0.9, max_tokens = 500)
)
response <- chat$chat("Write a haiku about R programming")

# Check token usage and cost
chat$get_tokens()
#>   input output cached_input    cost input_preview
#> 1    45    125            0   $0.00 Write a haiku about R programming
chat$get_cost()
#> $0.00
```

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

### as_chat() with Chat Object

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/chat-utils.md

Use this when you have an existing Chat object to pass to the as_chat() function.

```R
as_chat(chat)
```

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

### Define and Register a File Deletion Tool

Source: https://context7.com/tidyverse/ellmer/llms.txt

Defines a 'delete_file' tool that requires interactive confirmation before removing a file. It registers the tool with the chat object and sets up callbacks for logging tool requests and results.

```R
delete_file <- tool(
  function(path) {
    # Require confirmation in the tool itself
    if (!interactive()) {
      tool_reject("Cannot delete files in non-interactive mode")
    }

    confirm <- utils::askYesNo(paste("Delete", path, "?"))
    if (!isTRUE(confirm)) {
      tool_reject("User declined to delete the file")
    }

    file.remove(path)
    paste("Deleted", path)
  },
  name = "delete_file",
  description = "Delete a file from the filesystem",
  arguments = list(
    path = type_string("Path to the file to delete")
  )
)

chat$register_tool(delete_file)

# Register callbacks for logging/monitoring
chat$on_tool_request(function(request) {
  message("Tool requested: ", request@name)
  message("Arguments: ", deparse(request@arguments))
})

chat$on_tool_result(function(result) {
  message("Tool result: ", substr(tool_string(result), 1, 100))
})
```

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

### Ollama Models with Capabilities

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

The `models_ollama()` function now includes a `capabilities` column, providing a comma-separated list of each model's capabilities.

```R
models_ollama()
```

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

### List available models for VLLM

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Use `models_vllm()` to list available models for VLLM. The function is guaranteed to return a data frame with at least an `id` column.

```r
models_vllm()
```

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

### Overwriting an Existing Tool

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/chat-tools.md

Registering a tool with the same name as an existing one will result in a message indicating that the tool is being replaced.

```R
chat$register_tool(my_tool)
```

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

### Initialize Chat Snowflake

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-snowflake.md

Initializes the chat_snowflake function. This sets the default model for subsequent interactions.

```R
. <- chat_snowflake()
```

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

### Handle Mismatched Data with batch_chat_structured

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/batch-chat.md

Use `batch_chat_structured` for structured chat data. Similar to `batch_chat`, it checks for consistency in provider, prompts, and user turns. If a mismatch is found, you can select a new `path` or use `ignore_hash = TRUE`.

```R
batch_chat_structured(chat, prompts, path, type = type_string())
```

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

### Replay Object That Is Not an S7 Class

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/content-replay.md

The object specified for replay must be an S7 class. If it is a function, like `ellmer::chat_openai`, an error will be raised.

```R
contents_replay(not_s7)
```

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

### AWS Bedrock Chat with Custom Base URL

Source: https://github.com/tidyverse/ellmer/blob/main/NEWS.md

Configure a custom base URL for `chat_aws_bedrock()` to connect to specific AWS endpoints.

```R
chat_aws_bedrock(base_url = "https://my-custom-endpoint.amazonaws.com")
```

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

### Interactive Chat Method

Source: https://context7.com/tidyverse/ellmer/llms.txt

The `$chat()` method sends a message to the LLM and returns the response. It supports streaming output to the console by default when running interactively.

```R
library(ellmer)

chat <- chat_openai()
```

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

### Check Supported Version

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/content-replay.md

Ensure the recorded object's version is supported by `check_recorded`. Version 2 is shown as unsupported.

```R
contents_replay(bad_version)
```

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

### Using Deprecated virtual_key in chat_portkey

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/provider-portkey.md

This snippet demonstrates the usage of the deprecated `virtual_key` argument in the `chat_portkey` function. Users should transition to using the `model` argument instead.

```R
chat <- chat_portkey(model = "def", virtual_key = "abc")
```

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

### Define Tool with Multiple Arguments

Source: https://context7.com/tidyverse/ellmer/llms.txt

Defines a 'calculator' tool that performs basic arithmetic operations. It takes an operation type and two operands, returning the result.

```r
# Tool with multiple arguments
calculator <- tool(
  function(operation, x, y) {
    switch(operation,
      add = x + y,
      subtract = x - y,
      multiply = x * y,
      divide = x / y
    )
  },
  name = "calculator",
  description = "Perform basic arithmetic operations",
  arguments = list(
    operation = type_enum(c("add", "subtract", "multiply", "divide")),
    x = type_number("First operand"),
    y = type_number("Second operand")
  )
)

chat$register_tool(calculator)
chat$chat("What is 15 multiplied by 7?")
```

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

### Handle Unsupported Providers in batch_chat

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/batch-chat.md

The `batch_chat` function does not support batch requests for all providers. If the provider does not support batch requests, an error will be raised.

```R
batch_chat(chat_ollama)
```

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

### Define Array Types

Source: https://context7.com/tidyverse/ellmer/llms.txt

Demonstrates how to define array (vector) types for strings, integers, and nested arrays of numbers.

```r
# Arrays (vectors)
type_array(type_string())         # Character vector
type_array(type_integer())        # Integer vector
type_array(type_array(type_number()))  # List of numeric vectors
```

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

### Convert Data with Error Handling

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/parallel-chat.md

Use `multi_convert` to process turns and convert data. Errors during extraction will be reported as warnings, indicating the specific turns and reasons for failure.

```R
out <- multi_convert(provider, turns, type = type)
```

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

### Basic Chat Print Method

Source: https://github.com/tidyverse/ellmer/blob/main/tests/testthat/_snaps/chat.md

The print method for the chat object displays the model, turns, input/output tokens, and the conversation history including system, user, and assistant turns.

```R
chat
```