DOCSEARCHbyAlgolia
Submit Docs

ellmer R Package

repository·main·Indexed 20 days ago

https://github.com/tidyverse/ellmer

An R package providing a unified interface for interacting with various Large Language Model (LLM) providers, including official providers like OpenAI, Anthropic, and Google Gemini, as well as community providers. It features stateful R6 chat objects, support for streaming, tool calling via the tool() function, structured data extraction, and image inputs. Users can interact with models programmatically through the $chat() method or via interactive consoles using live_console() and live_browser().

Tokens
2K
Snippets
10
Records
13
Agent score
70%

What's inside ellmer

  1. Control output streaming with echo

    main

    By default, ellmer streams output to the console. To capture the response as a string instead of streaming it, set the echo argument to "none". This can be done when creating the chat object or when calling the $chat() method.

    # Capture response as a string instead of streaming to console
my_function <- function() {
  chat <- chat_openai("Be terse", model = "gpt-4o-mini", echo = "none")
  chat$chat("What is 6 times 7?")
}

# Returns an 'ellmer_output' object containing the string
str(my_function())

  3. Authenticate with LLM providers

    main

    Authentication methods vary by provider:

    1. API Keys: For providers like OpenAI and Anthropic, it is recommended to save your API key in an environment variable rather than hardcoding it.
    2. Cloud Credentials: ellmer automatically detects OAuth or IAM-based credentials for major cloud providers, including chat_azure_openai(), chat_aws_bedrock(), chat_databricks(), and chat_snowflake(). This includes credentials managed via Posit Workbench and Posit Connect.

  4. How chat objects work in ellmer

    main

    To use ellmer, you first create a chat object using a provider-specific function (e.g., chat_openai()).

    Chat objects are stateful R6 objects. This means they retain the context of the conversation; every new query you send to the object builds upon the previous interactions. You interact with these objects using the $ operator to call their methods.

    library(ellmer)

# Create a stateful chat object
chat <- chat_openai("Be terse", model = "gpt-4o-mini")

  6. Chat with images

    main

    You can pass images to the chat$chat() method by using content_image_file() for local files or content_image_url() for web-hosted images.

    chat$chat(
  content_image_url("https://www.r-project.org/Rlogo.png"),
  "Can you explain this logo?"
)

  7. Define a tool call using the `tool()` function

    main

    To turn an R function into a tool that an LLM can call, use the tool() function. This function requires four main components:

    1. The function: The first argument (unnamed) is the R function itself.
    2. name: A string representing the name of the function.
    3. description: A brief description of what the function does (in the same language as the documentation).
    4. arguments: A named list where each element corresponds to a function argument. Each element must contain a type specification.

    If an argument cannot be easily represented by the supported types, assign it NULL to indicate it cannot be used by the LLM.

    tool(
  stats::median,
  name = "median",
  description = "Compute the median value",
  arguments = list(
     x = type_array("Input vector", items = type_number()),
     na.rm = type_boolean(
       "Should missing values be removed? Defaults to FALSE",
       required = FALSE
     ),
     ... = NULL
  )
)

  8. Specify argument types with `type_*` functions

    main

    When defining the arguments list for a tool(), use the following type specification functions. Each function takes a description string as its first argument.

    Scalar Types

    • type_string(description)
    • type_number(description)
    • type_integer(description)
    • type_boolean(description)

    Vector/Array Types

    • type_array(description, items = ...): Represents a vector. The items argument specifies the type of the elements within the array (e.g., type_array(description = "...", items = type_number()) for a numeric vector).

    Optional Arguments

    By default, all arguments are marked as required = TRUE. If the R function has a default value for an argument, set required = FALSE within the type function and describe the default behavior in the description field.

  9. Create a chat object

    main

    All interactions in ellmer begin by creating a chat object using a provider-specific function. Chat objects are stateful R6 objects that retain conversation context. You interact with them using the $ operator.

    library(ellmer)

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

  10. Available LLM providers in ellmer

    main

    ellmer supports various model providers categorized into Official and Community providers.

    Official Providers

    • Anthropic's Claude: chat_anthropic()
    • AWS Bedrock: chat_aws_bedrock()
    • Azure OpenAI: chat_azure_openai()
    • Databricks: chat_databricks()
    • DeepSeek: chat_deepseek()
    • Google Gemini/Vertex AI: chat_google_gemini(), chat_google_vertex()
    • Ollama: chat_ollama()
    • OpenAI: chat_openai()
    • Posit AI: chat_posit()
    • Snowflake Cortex: chat_snowflake(), chat_cortex_analyst()

    Community Providers

    • Cloudflare: chat_cloudflare()
    • Groq: chat_groq()
    • Hugging Face: chat_huggingface()
    • LM Studio: chat_lmstudio()
    • Mistral: chat_mistral()
    • OpenRouter: chat_openrouter()
    • perplexity.ai: chat_perplexity()
    • Portkey: chat_portkey()
    • VLLM: chat_vllm()

  11. Use the interactive chat console

    main

    For a highly interactive experience, you can launch a chat console directly in your R console or browser using live_console(chat) or live_browser().

    Because the chat object is stateful, any conversation held within the console will persist in the chat object even after you exit the console and return to the R prompt.

    # Enter an interactive console in the R terminal
live_console(chat)

# Or use a browser-based interface
live_browser()

  12. Call the chat method for interactive responses

    main

    You can interact with a chat object programmatically using the $chat() method.

    When called in the global environment, the response will stream to the console and is invisibly returned as a character vector once complete. You can also pass images to the chat using content_image_file() or content_image_url().

    # Basic chat call
chat$chat("What preceding languages most influenced R?")

# Chatting with an image
chat$chat(
  content_image_url("https://www.r-project.org/Rlogo.png"),
  "Can you explain this logo?"
)