Chat {ellmer}R Documentation

A chat

Description

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

Public 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()

Register a callback for a tool request event.

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()

Register a callback for a tool result event.

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] Deprecated in favour of ⁠$chat_structured()⁠.

Usage
Chat$extract_data(...)
Arguments
...

See ⁠$chat_structured()⁠


Method extract_data_async()

[Deprecated]

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)
chat$chat("Tell me a funny joke")


[Package ellmer version 0.2.1 Index]