Extract documentation from a function

This function extracts documentation from a help file (if available, i.e., when the function is part of a package) or from documentation added by add_tools_add_documentation(). The extracted documentation includes the function's name, description, arguments, and return value. This information is used to provide an LLM with information about the functions, so that the LLM can call R functions.

Usage

add_tools_get_documentation(func, name = NULL)

Arguments

func: A function object. The function should belong to a package and have documentation available in a help file, or it should have documentation added by add_tools_add_documentation()
name: The name of the function if already known (optional). If not provided it will be extracted from the documentation or the function object's name

Value

A list with the following elements:

name: The name of the function
description: A description of the function
arguments: A named list of arguments with descriptions
return_value: A description of the return value

Details

This function will prioritize documentation added by add_tools_add_documentation() over documentation from a help file. Thus, it is possible to override the help file documentation by adding custom documentation

Examples

# Example fake weather function to add to the prompt:
temperature_in_location <- function(
    location = c("Amsterdam", "Utrecht", "Enschede"),
    unit = c("Celcius", "Fahrenheit")
) {
  location <- match.arg(location)
  unit <- match.arg(unit)

  temperature_celcius <- switch(
    location,
    "Amsterdam" = 32.5,
    "Utrecht" = 19.8,
    "Enschede" = 22.7
  )

  if (unit == "Celcius") {
    return(temperature_celcius)
  } else {
    return(temperature_celcius * 9/5 + 32)
  }
}

# Add documentation to a function:
temperature_in_location <- add_tools_add_documentation(
  temperature_in_location,
  description = "Get the temperature in a location",
  arguments = list(
    location = "Location, must be one of: 'Amsterdam', 'Utrecht', 'Enschede'",
    unit = "Unit, must be one of: 'Celcius', 'Fahrenheit'"
  ),
  return_value = "The temperature in the specified location and unit"
)

# Attempt to extract documentation as it is extracted by add_tools():
add_tools_get_documentation(temperature_in_location)
#> $name
#> [1] "temperature_in_location"
#> 
#> $description
#> [1] "Get the temperature in a location"
#> 
#> $arguments
#> $arguments$location
#> [1] "Location, must be one of: 'Amsterdam', 'Utrecht', 'Enschede'"
#> 
#> $arguments$unit
#> [1] "Unit, must be one of: 'Celcius', 'Fahrenheit'"
#> 
#> 
#> $return_value
#> [1] "The temperature in the specified location and unit"
#> 

# You can also pass functions which are included in packages;
#   documentation is then extracted from help files
#   (so you don't need to manually add documentation):
add_tools_get_documentation(list.files)
#> $name
#> [1] "list.files"
#> 
#> $description
#> [1] "List the Files in a Directory/Folder: These functions produce a character vector of the names of files\nor directories in the named directory."
#> 
#> $arguments
#> $arguments$path
#> [1] "a character vector of full path names; the default corresponds to the working directory, ‘getwd()’.  Tilde expansion (see ‘path.expand’) is performed.  Missing values will be ignored.  Elements with a marked encoding will be converted to the native encoding (and if that fails, considered non-existent)."
#> 
#> $arguments$pattern
#> [1] "an optional regular expression.  Only file names which match the regular expression will be returned."
#> 
#> $arguments$all.files
#> [1] "a logical value.  If ‘FALSE’, only the names of visible files are returned (following Unix-style visibility, that is files whose name does not start with a dot).  If ‘TRUE’, all file names will be returned."
#> 
#> $arguments$full.names
#> [1] "a logical value.  If ‘TRUE’, the directory path is prepended to the file names to give a relative file path.  If ‘FALSE’, the file names (rather than paths) are returned."
#> 
#> $arguments$recursive
#> [1] "logical.  Should the listing recurse into directories?"
#> 
#> $arguments$ignore.case
#> [1] "logical.  Should pattern-matching be case-insensitive?"
#> 
#> $arguments$include.dirs
#> [1] "logical.  Should subdirectory names be included in recursive listings?  (They always are in non-recursive ones)."
#> 
#> $arguments$no..
#> [1] "logical.  Should both ‘\".\"’ and ‘\"..\"’ be excluded also from non-recursive listings?"
#> 
#> 
#> $return_value
#> [1] "A character vector containing the names of the files in the\nspecified directories (empty if there were no files).  If a path\ndoes not exist or is not a directory or is unreadable it is\nskipped.\nThe files are sorted in alphabetical order, on the full path if\n‘full.names = TRUE’.\n‘list.dirs’ implicitly has ‘all.files = TRUE’, and if ‘recursive =\nTRUE’, the answer includes ‘path’ itself (provided it is a\nreadable directory).\n‘dir’ is an alias for ‘list.files’."
#> 

# Example usage:
prompt1 <- "Hi, what is the weather in Enschede? Give me Celcius degrees" |>
  add_tools(temperature_in_location)

prompt2 <- "What are the files in my current directory?" |>
  add_tools(list.files)

if (FALSE) { # \dontrun{
  prompt1 |>
    send_prompt(llm_provider_ollama())
  #   --- Sending request to LLM provider (llama3.1:8b): ---
  #     Hi, what is the weather in Enschede? Give me Celcius degrees
  #
  #     If you need more information, you can call functions to help you.
  #     To call a function, output a JSON object with the following format:
  #
  #       {
  #         "function": "<function name>",
  #         "arguments": {
  #           "<argument_name>": <argument_value>,
  #           ...
  #         }
  #       }
  #
  #     (Note: you cannot call other functions within arguments.)
  #
  #     The following functions are available:
  #
  #       function name: temperature_in_location
  #     description: Get the temperature in a location
  #     arguments:
  #       - location: Location, must be one of: 'Amsterdam', 'Utrecht', 'Enschede'
  #     - unit: Unit, must be one of: 'Celcius', 'Fahrenheit'
  #     return value: The temperature in the specified location and unit
  #
  #     After you call a function, wait until you receive more information.
  #     Use the information to decide your next steps or provide a final response.
  #   --- Receiving response from LLM provider: ---
  #     To get the weather in Enschede, I'll need to call the
  #     `temperature_in_location` function.
  #
  #   Here's my JSON object:
  #   ```
  #     {
  #       "function": "temperature_in_location",
  #       "arguments": {
  #         "location": "Enschede",
  #         "unit": "Celcius"
  #       }
  #     }
  #   ```
  #
  #   I'll wait for your response...
  # --- Sending request to LLM provider (llama3.1:8b): ---
  #   function called: temperature_in_location
  #   arguments used: location = Enschede, unit = Celcius
  #   result: 22.7
  # --- Receiving response from LLM provider: ---
  #   The current temperature in Enschede is 22.7°C.
  #
  #   So, the final answer is:
  #   **22.7°C**
  #
  #   Is there anything else I can help you with?
  # [1] "The current temperature in Enschede is 22.7°C.\n\nSo, the final answer
  # is:\n**22.7°C**\n\nIs there anything else I can help you with?"

  prompt2 |>
    send_prompt(llm_provider_ollama())
  # ...
} # }

Usage

Arguments

Value

Details

See also

Examples