A chat

A Chat is a sequence of user and assistant Turns sent to a specific Provider. A Chat is a mutable R6 object that takes care of managing the state associated with the chat; i.e. it records the messages that you send to the server, and the messages that you receive back. If you register a tool (i.e. an R function that the assistant can call on your behalf), it also takes care of the tool loop.

You should generally not create this object yourself, but instead call chat_openai() or friends instead.

Value

A Chat object

Methods

Method `new()`

Usage

Chat$new(provider, system_prompt = NULL, echo = "none")

Arguments

provider

A provider object.

system_prompt

System prompt to start the conversation with.

echo

One of the following options:

none: don't emit any output (default when running in a function).
output: echo text and tool-calling output as it streams in (default when running at the console).
all: echo all input and output.

Note this only affects the chat() method.

Method `get_turns()`

Retrieve the turns that have been sent and received so far (optionally starting with the system prompt, if any).

Usage

Chat$get_turns(include_system_prompt = FALSE)

Arguments

include_system_prompt: Whether to include the system prompt in the turns (if any exists).

Method `set_turns()`

Replace existing turns with a new list.

Usage

Chat$set_turns(value)

Arguments

value: A list of Turns.

Method `add_turn()`

Add a pair of turns to the chat.

Usage

Chat$add_turn(user, system)

Arguments

user: The user Turn.
system: The system Turn.

Method `get_system_prompt()`

If set, the system prompt, it not, NULL.

Usage

Chat$get_system_prompt()

Method `get_model()`

Retrieve the model name

Usage

Chat$get_model()

Method `set_system_prompt()`

Update the system prompt

Usage

Chat$set_system_prompt(value)

Arguments

value: A character vector giving the new system prompt

Method `get_tokens()`

A data frame with a tokens column that proides the number of input tokens used by user turns and the number of output tokens used by assistant turns.

Usage

Chat$get_tokens(include_system_prompt = FALSE)

Arguments

include_system_prompt: Whether to include the system prompt in the turns (if any exists).

Method `get_cost()`

The cost of this chat

Usage

Chat$get_cost(include = c("all", "last"))

Arguments

include: The default, "all", gives the total cumulative cost of this chat. Alternatively, use "last" to get the cost of just the most recent turn.

Method `last_turn()`

The last turn returned by the assistant.

Usage

Chat$last_turn(role = c("assistant", "user", "system"))

Arguments

role: Optionally, specify a role to find the last turn with for the role.

Returns

Either a Turn or NULL, if no turns with the specified role have occurred.

Method `chat()`

Submit input to the chatbot, and return the response as a simple string (probably Markdown).

Usage

Chat$chat(..., echo = NULL)

Arguments

...: The input to send to the chatbot. Can be strings or images (see content_image_file() and content_image_url().
echo: Whether to emit the response to stdout as it is received. If NULL, then the value of echo set when the chat object was created will be used.

Method `chat_structured()`

Extract structured data

Usage

Chat$chat_structured(..., type, echo = "none", convert = TRUE)

Arguments

...: The input to send to the chatbot. Will typically include the phrase "extract structured data".
type: A type specification for the extracted data. Should be created with a type_() function.
echo: Whether to emit the response to stdout as it is received. Set to "text" to stream JSON data as it's generated (not supported by all providers).
convert: Automatically convert from JSON lists to R data types using the schema. For example, this will turn arrays of objects into data frames and arrays of strings into a character vector.

Method `chat_structured_async()`

Extract structured data, asynchronously. Returns a promise that resolves to an object matching the type specification.

Usage

Chat$chat_structured_async(..., type, echo = "none")

Arguments

...: The input to send to the chatbot. Will typically include the phrase "extract structured data".
type: A type specification for the extracted data. Should be created with a type_() function.
echo: Whether to emit the response to stdout as it is received. Set to "text" to stream JSON data as it's generated (not supported by all providers).

Method `chat_async()`

Submit input to the chatbot, and receive a promise that resolves with the response all at once. Returns a promise that resolves to a string (probably Markdown).

Usage

Chat$chat_async(..., tool_mode = c("concurrent", "sequential"))

Arguments

...: The input to send to the chatbot. Can be strings or images.
tool_mode: Whether tools should be invoked one-at-a-time ("sequential") or concurrently ("concurrent"). Sequential mode is best for interactive applications, especially when a tool may involve an interactive user interface. Concurrent mode is the default and is best suited for automated scripts or non-interactive applications.

Method `stream()`

Submit input to the chatbot, returning streaming results. Returns A coro generator that yields strings. While iterating, the generator will block while waiting for more content from the chatbot.

Usage

Chat$stream(..., stream = c("text", "content"))

Arguments

...: The input to send to the chatbot. Can be strings or images.
stream: Whether the stream should yield only "text" or ellmer's rich content types. When stream = "content", stream() yields Content objects.

Method `stream_async()`

Submit input to the chatbot, returning asynchronously streaming results. Returns a coro async generator that yields string promises.

Usage

Chat$stream_async(
  ...,
  tool_mode = c("concurrent", "sequential"),
  stream = c("text", "content")
)

Arguments

...: The input to send to the chatbot. Can be strings or images.
tool_mode: Whether tools should be invoked one-at-a-time ("sequential") or concurrently ("concurrent"). Sequential mode is best for interactive applications, especially when a tool may involve an interactive user interface. Concurrent mode is the default and is best suited for automated scripts or non-interactive applications.
stream: Whether the stream should yield only "text" or ellmer's rich content types. When stream = "content", stream() yields Content objects.

Method `register_tool()`

Register a tool (an R function) that the chatbot can use. If the chatbot decides to use the function, ellmer will automatically call it and submit the results back.

The return value of the function. Generally, this should either be a string, or a JSON-serializable value. If you must have more direct control of the structure of the JSON that's returned, you can return a JSON-serializable value wrapped in base::I(), which ellmer will leave alone until the entire request is JSON-serialized.

Usage

Chat$register_tool(tool_def)

Arguments

tool_def: Tool definition created by tool().

Method `get_provider()`

Get the underlying provider object. For expert use only.

Usage

Chat$get_provider()

Method `get_tools()`

Retrieve the list of registered tools.

Usage

Chat$get_tools()

Method `set_tools()`

Sets the available tools. For expert use only; most users should use register_tool().

Usage

Chat$set_tools(tools)

Arguments

tools: A list of tool definitions created with tool().

Method `on_tool_request()`

Usage

Chat$on_tool_request(callback)

Arguments

callback: A function to be called when a tool request event occurs, which must have request as its only argument.

Returns

A function that can be called to remove the callback.

Method `on_tool_result()`

Usage

Chat$on_tool_result(callback)

Arguments

callback: A function to be called when a tool result event occurs, which must have result as its only argument.

Returns

A function that can be called to remove the callback.

Method `extract_data()`

Deprecated in favour of $chat_structured().

Usage

Chat$extract_data(...)

Arguments

...: See $chat_structured()

Method `extract_data_async()`

Usage

Chat$extract_data_async(...)

Arguments

...: See $chat_structured_async()

Method `clone()`

The objects of this class are cloneable with this method.

Usage

Chat$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

chat <- chat_openai(echo = TRUE)
#> Using model = "gpt-4.1".
chat$chat("Tell me a funny joke")
#> Sure! Here you go:
#> 
#> Why did the scarecrow win an award?  
#> Because he was outstanding in his field! 🌾😄

Value

Methods

Public methods

Method new()

Usage

Arguments

Method get_turns()

Usage

Arguments

Method set_turns()

Usage

Arguments

Method add_turn()

Usage

Arguments

Method get_system_prompt()

Usage

Method get_model()

Usage

Method set_system_prompt()

Usage

Arguments

Method get_tokens()

Usage

Arguments

Method get_cost()

Usage

Arguments

Method last_turn()

Usage

Arguments

Returns

Method chat()

Usage

Arguments

Method chat_structured()

Usage

Arguments

Method chat_structured_async()

Usage

Arguments

Method chat_async()

Usage

Arguments

Method stream()

Usage

Arguments

Method stream_async()

Usage

Arguments

Method register_tool()

Usage

Arguments

Method get_provider()

Usage

Method get_tools()

Usage

Method set_tools()

Usage

Arguments

Method on_tool_request()

Usage

Arguments

Returns

Method on_tool_result()

Usage

Arguments

Returns

Method extract_data()

Usage

Arguments

Method extract_data_async()

Usage

Arguments

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `get_turns()`

Method `set_turns()`

Method `add_turn()`

Method `get_system_prompt()`

Method `get_model()`

Method `set_system_prompt()`

Method `get_tokens()`

Method `get_cost()`

Method `last_turn()`

Method `chat()`

Method `chat_structured()`

Method `chat_structured_async()`

Method `chat_async()`

Method `stream()`

Method `stream_async()`

Method `register_tool()`

Method `get_provider()`

Method `get_tools()`

Method `set_tools()`

Method `on_tool_request()`

Method `on_tool_result()`

Method `extract_data()`

Method `extract_data_async()`

Method `clone()`