Chat: A chat
In ellmer: Chat with Large Language Models
Chat R Documentation
A chat
Description
A Chat is an sequence of 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, turns, seed = NULL, echo = "none")
Arguments
providerA provider object.
turnsAn unnamed list of turns to start the chat with (i.e.,
continuing a previous conversation). If NULL or zero-length list, the
conversation begins from scratch.
seedOptional integer seed that ChatGPT uses to try and make output
more reproducible.
echoOne of the following options:
-
none: don't emit any output (default when running in a function).
-
text: echo text 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_promptWhether 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
valueA list of Turns.
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
valueA string giving the new system prompt
Method tokens()
List the number of tokens consumed by each assistant turn.
Currently tokens are recorded for assistant turns only; so user
turns will have zeros.
Usage
Chat$tokens()
Method last_turn()
The last turn returned by the assistant.
Usage
Chat$last_turn(role = c("assistant", "user", "system"))
Arguments
roleOptionally, 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().
echoWhether 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 extract_data()
Extract structured data
Usage
Chat$extract_data(..., type, echo = "none", convert = TRUE)
Arguments
...The input to send to the chatbot. Will typically include
the phrase "extract structured data".
typeA type specification for the extracted data. Should be
created with a type_() function.
echoWhether 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).
convertAutomatically 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 extract_data_async()
Extract structured data, asynchronously. Returns a promise
that resolves to an object matching the type specification.
Usage
Chat$extract_data_async(..., type, echo = "none")
Arguments
...The input to send to the chatbot. Will typically include
the phrase "extract structured data".
typeA type specification for the extracted data. Should be
created with a type_() function.
echoWhether 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(...)
Arguments
...The input to send to the chatbot. Can be strings or images.
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(...)
Arguments
...The input to send to the chatbot. Can be strings or images.
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(...)
Arguments
...The input to send to the chatbot. Can be strings or images.
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_defTool definition created by tool().
Method clone()
The objects of this class are cloneable with this method.
Usage
Chat$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
chat <- chat_openai(echo = TRUE)
chat$chat("Tell me a funny joke")
ellmer documentation built on April 4, 2025, 3:53 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Chat | R Documentation |
A chat
Description
A Chat is an sequence of 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, turns, seed = NULL, echo = "none")
Arguments
providerA provider object.
turnsAn unnamed list of turns to start the chat with (i.e., continuing a previous conversation). If
NULLor zero-length list, the conversation begins from scratch.seedOptional integer seed that ChatGPT uses to try and make output more reproducible.
echoOne of the following options:
-
none: don't emit any output (default when running in a function). -
text: echo text 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_promptWhether 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
valueA list of Turns.
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
valueA string giving the new system prompt
Method tokens()
List the number of tokens consumed by each assistant turn. Currently tokens are recorded for assistant turns only; so user turns will have zeros.
Usage
Chat$tokens()
Method last_turn()
The last turn returned by the assistant.
Usage
Chat$last_turn(role = c("assistant", "user", "system"))Arguments
roleOptionally, 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()andcontent_image_url().echoWhether to emit the response to stdout as it is received. If
NULL, then the value ofechoset when the chat object was created will be used.
Method extract_data()
Extract structured data
Usage
Chat$extract_data(..., type, echo = "none", convert = TRUE)
Arguments
...The input to send to the chatbot. Will typically include the phrase "extract structured data".
typeA type specification for the extracted data. Should be created with a
type_()function.echoWhether 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).
convertAutomatically 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 extract_data_async()
Extract structured data, asynchronously. Returns a promise that resolves to an object matching the type specification.
Usage
Chat$extract_data_async(..., type, echo = "none")
Arguments
...The input to send to the chatbot. Will typically include the phrase "extract structured data".
typeA type specification for the extracted data. Should be created with a
type_()function.echoWhether 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(...)
Arguments
...The input to send to the chatbot. Can be strings or images.
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(...)
Arguments
...The input to send to the chatbot. Can be strings or images.
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(...)
Arguments
...The input to send to the chatbot. Can be strings or images.
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_defTool definition created by
tool().
Method clone()
The objects of this class are cloneable with this method.
Usage
Chat$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
chat <- chat_openai(echo = TRUE)
chat$chat("Tell me a funny joke")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.