Language models

API providers

Obtain a key from the provider, then put it in the environment of your R process or an existing private .env file. gptr_env() loads that file, registers values for redaction and reports names and fingerprints. It leaves an existing environment variable alone unless override = TRUE. Keep the file out of version control.

library(gptr)
gptr_env("~/keys/models.env")
gptr_config(model = "openai/gpt-6-sol", .scope = "user")
session = peter("Explain the relationship between mpg and wt.", mtcars)
session$text

At first interactive use of a remote route, gptr asks you to acknowledge the data sent to it. For unattended jobs, acknowledge the specific provider beforehand at user scope:

gptr_config(egress = utils::modifyList(gptr_config()$egress, list(openai = "ack")),
            .scope = "user")

This covers automatic context; it does not pre-approve tool actions. Read ?gptr_egress for the request contents and ?gptr_security before using sensitive data. gptr_login("openrouter") offers an interactive login; gptr_login("anthropic", method = "key") offers masked key entry. These credentials are separate from a command-line tool’s sign-in.

An OpenAI-compatible service can use the existing completions adapter. Register its endpoint, credential variable and the model metadata supplied by your service:

off = gptr_register(gptr_provider(
  "work", api = "openai-completions", base_url = "https://llm.example.org/v1",
  auth = "WORK_API_KEY",
  models = list(list(id = "work-model", context = 32000, max_output = 4000,
                     tool_call = TRUE))
))
peter("Summarize these data.", mtcars, model = "work/work-model")
off()  # remove this process-lifetime provider registration

Declare features only when your service supports them. Endpoint compatibility alone does not establish tool, image or reasoning support. More built-in compatible routes appear in gptr_providers(); ?gptr_provider documents registration and compatibility fields.

Azure OpenAI and Amazon Bedrock

The built-in Azure route reads AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT. Give the resource endpoint, such as https://your-resource.openai.azure.com; gptr adds /openai/v1 and sends the key in the api-key header. The model sent to Azure is your deployment name. Declare that deployment and its real capacities in provider settings:

gptr_env("~/keys/azure.env")  # AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT
azure_model = list(id = "analysis-chat", context = 32000, max_output = 4000,
                   tool_call = TRUE)
gptr_config(
  providers = list(azure = list(models = list(azure_model))),
  .scope = "session"
)
session = peter("Summarize these data.", mtcars, model = "azure/analysis-chat")

Replace analysis-chat and the limits with your deployment’s metadata; declare tool_call only when supported. Alternatively, AZURE_OPENAI_DEPLOYMENT_NAME_MAP maps a declared model id to its deployment using model-id=deployment-name pairs separated by commas.

The built-in Bedrock route uses AWS_BEARER_TOKEN_BEDROCK with the runtime’s OpenAI-compatible API. AWS_REGION, then AWS_DEFAULT_REGION, selects the region; the default is us-east-1. Its endpoint is https://bedrock-runtime.<region>.amazonaws.com/openai/v1. Choose a model your account can use through that API and declare its id and capacities:

gptr_env("~/keys/bedrock.env")  # AWS_BEARER_TOKEN_BEDROCK and AWS_REGION
bedrock_model = list(id = "your-bedrock-model-id", context = 32000, max_output = 4000,
                     tool_call = TRUE)
gptr_config(
  providers = list(bedrock = list(models = list(bedrock_model))),
  .scope = "session"
)
session = peter("Summarize these data.", mtcars,
                model = "bedrock/your-bedrock-model-id")

Replace the illustrative metadata with your service’s values. This built-in route does not implement AWS SigV4 signing, AWS profile credentials or the general Bedrock Converse API. An AWS credentials file alone therefore does not authenticate it, and the route does not imply support for every Bedrock model. These remote providers need the egress acknowledgment described above, using provider ids azure and bedrock.

Subscription command-line tools

Install and sign in to the claude or codex tool outside gptr, following that tool’s own setup. The executable must be on PATH, or you can give its path with the gptr.cli_path option. Then choose model = "claude-cli" (alias claude_code) or model = "codex".

options(gptr.cli_path = list(claude = "/path/to/claude", codex = "/path/to/codex"))
gptr_providers(check = TRUE)
session = peter("Inspect the columns of mtcars.", mtcars, model = "codex")

These calls run a child process. The built-in claude-cli route uses the Claude Code CLI’s signed-in plan/OAuth authentication and refuses API-key billing. For API-key use, explicitly choose the direct anthropic provider. The Codex route uses the CLI’s active authentication and billing. Live R access goes through gptr’s MCP permission gate; the Codex route needs the suggested packages httpuv, later and openssl. First use asks for an acknowledgment. gptr checks required CLI flags and rejects incompatible versions. The Claude plan route is experimental and opt-in; review ?gptr_security and the provider’s terms before choosing it.

Local Ollama models

Run Ollama separately and install the model you intend to use. Discover the installed models, then copy a returned reference into the call:

local_models = gptr_models(provider = "ollama", refresh = TRUE)
local_models
session = peter("Inspect mtcars and suggest a plot.", mtcars,
                model = "ollama/qwen3:1.7b")

The default server is http://127.0.0.1:11434/v1. For another local endpoint, configure its base_url explicitly with gptr_config(providers = list(ollama = list(base_url = ...)), .scope = "user"). gptr verifies installed-model capabilities and inference locality. Its default local_only = TRUE rejects cloud selectors, remote markers and ambiguous locality; it does not install, start or update Ollama, pull models or fall back to a cloud route.

Conversational models return sessions. Clef and Clef Flash are native decision models, require Ollama 0.35.1 or later, and return logical, choice or score vectors. Their calls do not run an agent conversation. See System 1 decisions. A local model does not keep a later cloud call or network tool local.