anthropic Extension

This extension allows rill scripts to access Anthropic’s Claude API. The host binds it to a namespace with prefixFunctions('llm', ext), and scripts call llm::message(), llm::embed(), and so on. Switching to OpenAI or Google means changing one line of host config. Scripts stay identical.

Five functions cover the core LLM operations. message sends a single prompt. messages continues a multi-turn conversation. embed and embed_batch generate vector embeddings. tool_loop runs an agentic loop where the model calls rill closures as tools. All return the same dict shape (content, model, usage, stop_reason, id, messages), so scripts work across providers without changes.

The host sets API key, model, and temperature at creation time — scripts never handle credentials. Each call emits a structured event (anthropic:message, anthropic:tool_call) for host-side logging and metrics.

Quick Start

import { createRuntimeContext, prefixFunctions } from '@rcrsr/rill';
import { createAnthropicExtension } from '@rcrsr/rill-ext-anthropic';

const ext = createAnthropicExtension({
  api_key: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-5-20250929',
});
const functions = prefixFunctions('anthropic', ext);
const ctx = createRuntimeContext({ functions });

// Script: anthropic::message("Explain TCP handshakes")

Configuration

const ext = createAnthropicExtension({
  api_key: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-5-20250929',
  temperature: 0.7,
  max_tokens: 4096,
  system: 'You are a helpful assistant.',
  embed_model: 'voyage-3',
  base_url: 'https://custom-endpoint.example.com',
  max_retries: 3,
  timeout: 30000,
});

Functions

message(text, options?) — Send a single prompt:

anthropic::message("Explain TCP handshakes") => $result
$result.content      # Response text
$result.model        # Model used
$result.usage.input  # Input tokens
$result.usage.output # Output tokens

messages(messages, options?) — Multi-turn conversation:

[
  [role: "user", content: "What is rill?"],
  [role: "assistant", content: "A scripting language."],
  [role: "user", content: "Tell me more."],
] -> anthropic::messages => $result
$result.content   # Latest response
$result.messages  # Full conversation history

embed(text) — Generate text embedding:

anthropic::embed("sample text") => $vec
$vec -> .dimensions  # Vector size
$vec.model           # Embedding model used

embed_batch(texts) — Batch embeddings:

["first text", "second text"] -> anthropic::embed_batch => $vectors
$vectors.len  # Number of vectors

tool_loop(prompt, options?) — Agentic tool-use loop:

tool("get_weather", "Get current weather", [city: "string"], {
  "Weather in {$city}: 72F sunny"
}) => $weather_tool

anthropic::tool_loop("What's the weather in Paris?", [
  tools: [$weather_tool],
  max_turns: 5,
]) => $result
$result.content  # Final response
$result.turns    # Number of LLM round-trips

Per-Call Options

Result Dict

All functions except embed and embed_batch return:

The tool_loop result adds turns (number of LLM round-trips).

Error Behavior

Validation errors (before API call):

• Empty prompt → RuntimeError RILL-R004: prompt text cannot be empty
• Missing role → RuntimeError RILL-R004: message missing required 'role' field
• Invalid role → RuntimeError RILL-R004: invalid role '{value}'
• Missing content → RuntimeError RILL-R004: {role} message requires 'content'
• No embed_model → RuntimeError RILL-R004: embed_model not configured
• Missing tools → RuntimeError RILL-R004: tool_loop requires 'tools' option

API errors (from provider):

• Rate limit → RuntimeError RILL-R004: Anthropic: rate limit
• Auth failure → RuntimeError RILL-R004: Anthropic: authentication failed (401)
• Timeout → RuntimeError RILL-R004: Anthropic: request timeout
• Other → RuntimeError RILL-R004: Anthropic: {detail} ({status})

Tool loop errors:

• Unknown tool → RuntimeError RILL-R004: unknown tool '{name}'
• Error limit → RuntimeError RILL-R004: tool loop aborted after {n} consecutive errors

Events

Test Host

A runnable example at packages/ext/anthropic/examples/test-host.ts demonstrates integration:

# Set API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Built-in demo
pnpm exec tsx examples/test-host.ts

# Inline expression
pnpm exec tsx examples/test-host.ts -e 'llm::message("Tell me a joke") -> $.content -> log'

# Script file
pnpm exec tsx examples/test-host.ts script.rill

Override model or endpoint with ANTHROPIC_MODEL and ANTHROPIC_BASE_URL.

See Also

• Bundled Extensions — All shipped extensions
• Developing Extensions — Writing custom extensions
• Host Integration — Embedding API
• Reference — Language specification