Getting started with pal • pal

Pals are persistent, ergonomic LLM assistants designed to help you complete repetitive, hard-to-automate tasks quickly.

library(pal)

The pal package ships with a number of pre-engineered “roles.” A pal role is a keyword that succinctly describes what the pal is intended to do and serves as an identifier to match the pal with its prompt and interface. A pal’s prompt is just a markdown file with enough context and examples to teach a model to carry out a given task well. A pal’s interface determines whether it replaces, prefixes, or suffixes the selected code. For example:

The "testthat" pal helps you transition your R package’s unit tests to the third edition of testthat. Its prompt shows the model how to convert to snapshot tests, disentangle nested expectations, and transition from deprecated functions. It replaces the selected code.
The "roxygen" pal helps you quickly template out royxgen documentation for a function. Its prompt shows the model how to write high-quality stub @param and @returns entries that can be later extended by the developer. It prefixes the selected code.

Choosing a model

Under the hood, pals are driven by Large Language Models (LLMs). To use pals, you will need an API key for a commercial model or a connection to a locally hosted model.

Pals use the elmer package to interface with LLMs. Any model supported by elmer is supported by pal.

As of October 2024, we highly recommend Anthropic’s Claude Sonnet 3.5 as the model to power your pals. Compared to other models we’ve tried, Claude is most likely to generate syntactically valid code that aligns with the pal’s prompt well. As such, Claude is the default model used by pal. If you want to use Claude with pal, the only additional setup step you need is to set an ANTHROPIC_API_KEY in your .Renviron—you might use usethis::edit_r_environ() to open the file, and then set:

ANTHROPIC_API_KEY=your.key.here

To use another model to power your pals, use the .pal_fn and .pal_args options. .pal_fn is the name of a chat_*() function from elmer, and .pal_args is a list of any non-default arguments you’d like to supply to that function. For example, to use models from OpenAI, you might write:

options(
  .pal_fn = "chat_openai"
)

Or, to use GPT 4o mini specifically, you might write:

options(
  .pal_fn = "chat_openai",
  .pal_args = list(model = "gpt-4o-mini")
)

To use a local model with ollama, you might write:

options(
  .pal_fn = "chat_ollama",
  .pal_args = list(model = "qwen2.5-coder:14b")
)

You’ll probably want pal to always use whichever model you’re configuring with this option. To make this selection persist across sessions, add that options() code to your .Rprofile. You might use usethis::edit_r_profile() to open the file. After making those changes and restarting R, your pal will use the new model.

The pal addin

Rather than through package functions directly, pals are interfaced with via the pal addin. Once you have a default model set up, you’re ready to use the package in any RStudio session (even if you haven’t loaded the package yet).

Just:

Select some code.
Trigger the pal addin.
Type in a pal “role.” Once it’s autocompleted, press Enter.
Watch your code be rewritten.

Pals are interfaced with the via the pal addin. For easiest access, we recommend registering the pal addin to a keyboard shortcut.

In RStudio, navigate to Tools > Modify Keyboard Shortcuts > Search "Pal"—we suggest Ctrl+Alt+P (or Ctrl+Cmd+P on macOS).

In Positron, you’ll need to open the command palette, run “Open Keyboard Shortcuts (JSON)”, and paste the following into your keybindings.json():

    {
        "key": "Ctrl+Cmd+P",
        "command": "workbench.action.executeCode.console",
        "when": "editorTextFocus",
        "args": {
            "langId": "r",
            "code": "pal::.init_addin()",
            "focus": true
        }
    }

The analogous keybinding on non-macOS is Ctrl+Alt+P. That said, change the "key" entry to any keybinding you wish!

Once those steps are completed, you’re ready to use pals with a keyboard shortcut.

Adding custom pals

While the pal package comes with three pals for package development, one can use pals for all sorts of coding tasks in R, from interactive data analysis to authoring with Quarto, or even for coding tasks in languages other than R! All you need to set up your own pal is a markdown file.

To learn more about adding custom pals as well as how to share them with others, see the “Custom pals” vignette with vignette("custom", package = "pal").