Create a btw-enhanced ellmer chat client

Creates an ellmer::Chat client, enhanced with the tools from btw_register_tools(). Use btw_client() to create the chat client for general or interactive use at the console, or btw_app() to create a chat client and launch a Shiny app for chatting with a btw-enhanced LLM in your local workspace.

Project Context

You can keep track of project-specific rules, guidance and context by adding a btw.md file in your project directory. Any time you start a chat client with btw_client() or launch a chat session with btw_app(), btw will automatically find and include the contents of the btw.md file in your chat.

Use btw.md to inform the LLM of your preferred code style, to provide domain-specific terminology or definitions, to establish project documentation, goals and constraints, to include reference materials such or technical specifications, or more. Storing this kind of information in btw.md may help you avoid repeating yourself and can be used to maintain coherence across many chat sessions.

The btw.md file, when present, is included as part of the system prompt for your chat conversation. You can structure the file in any way you wish.

You can also use the btw.md file to choose default chat settings for your project in a YAML block at the top of the file. In this YAML block you can choose the default provider, model and tools for btw_client() or btw_app(). provider chooses the ellmer::chat_*() function, e.g. provider: openai or provider: chat_openai to use ellmer::chat_openai(). tools chooses which btw tools are included in the chat, and all other values are passed to the ellmer::chat_*() constructor, e.g. model: gpt-4o, seed: 42, or `echo: all“.

Here's an example btw.md file:

---
provider: claude
model: claude-3-7-sonnet-20250219
tools: [data, docs, environment]
---

Follow these important style rules for any R code in this project:

* Prefer solutions that use {tidyverse}
* Always use `<-` for assignment
* Always use the native base-R pipe `|>` for piped expressions

Client Options

btw.client: The ellmer::Chat client to use as the basis for new btw_client() or btw_app() chats.
btw.tools: The btw tools to include by default when starting a new btw chat, see btw_register_tools() for details.

Usage

btw_client(..., client = NULL, tools = NULL, path_btw = NULL)

btw_app(..., client = NULL, tools = NULL, path_btw = NULL)

Arguments

...: Additional arguments are ignored. ... are included for future feature expansion.
client: An ellmer::Chat client, defaults to ellmer::chat_anthropic(). You can use the btw.client option to set a default client for new btw_client() calls, or use a btw.md project file for default chat client settings, like provider and model. We check the client argument, then the btw.client R option, and finally the btw.md project file, using only the client definition from the first of these that is available.
tools: Optional names of tools or tool groups to include in the chat client. By default, all btw tools are included. For example, use include = "docs" to include only the documentation related tools, or include = c("env", "docs"), etc. btw_client() also supports tools = FALSE to skip registering btw tools with the chat client.
path_btw: A path to a btw.md project context file. If NULL, btw will find a project-specific btw.md file in the parents of the current working directory.

Value

Returns an ellmer::Chat object with additional tools registered by btw_register_tools(). btw_app() returns the chat object invisibly, and the chat object with the messages added during the chat session.

Functions

btw_client(): Create a btw-enhanced ellmer::Chat client
btw_app(): Create a btw-enhanced client and launch a Shiny app to chat

Examples

if (interactive()) {
  withr::local_options(list(
    btw.client = ellmer::chat_ollama(model="llama3.1:8b")
  ))

  chat <- btw_client()
  chat$chat("How can I replace `stop()` calls with functions from the cli package?")
}