Version 0.2 • artclaude

artclaude 0.2.0 (2025-12-26)

Major Features - Complete Claude API Feature Parity

This release achieves complete feature parity with the Claude API, adding support for all current beta features and advanced capabilities.

Effort Control (Opus 4.5)

New effort parameter in claude_new() controls token consumption while maintaining quality (#1)
- Three levels: “low”, “medium”, “high”
- Medium effort: 76% fewer tokens, matches Sonnet 4.5 quality
- Automatically validates Opus 4.5 requirement
- Auto-adds effort-2025-11-24 beta header

Example:

chat <- claude_new(effort = "medium")
chat$chat("Explain quantum computing")

Files API

New file management functions for persistent storage across conversations:
- claude_file_upload() - Upload files to Anthropic storage (500MB max, 100GB org limit)
- claude_file_list() - List all uploaded files
- claude_file_delete() - Delete uploaded files
- claude_file_get() - Get file metadata
- claude_file_download() - Download file content
- claude_file_content() - Create file content blocks for messages
Supports PDFs, images (JPEG, PNG, GIF, WebP), and plain text
Files persist until explicitly deleted

Example:

file <- claude_file_upload("report.pdf")
chat1 <- claude_new()
chat1$chat(claude_file_content(file$id), "Summarize")
# Reuse in another conversation
chat2 <- claude_new()
chat2$chat(claude_file_content(file$id), "Extract metrics")
claude_file_delete(file$id)

Citations API

New claude_doc_cite() function enables precise source attribution
- Supports inline documents (base64-encoded) and uploaded files
- Citations include page numbers, character offsets, or content block indices
- Eliminates hallucinations with verifiable sources
Internal .detect_mime() helper for automatic MIME type detection
New vignette("citations") with comprehensive examples

Example:

chat <- claude_new()
chat$chat(
  claude_doc_cite("contract.pdf", title = "Service Agreement"),
  "What are the termination conditions? Cite specific clauses."
)

Long-Running Agents

Memory Tool

New claude_memory() enables persistent agent memory across sessions
- File-based storage with automatic directory creation
- Claude manages memory files (create, read, update, delete)
- Knowledge persists between R sessions
- Requires beta_headers$BETA_CONTEXT_MGMT

Example:

memory_dir <- tempfile("agent_memory_")
chat <- claude_new(
  tools = list(claude_memory(memory_dir)),
  beta = beta_headers$BETA_CONTEXT_MGMT
)
chat$chat("Remember my favorite color is blue")
# New session
chat2 <- claude_new(
  tools = list(claude_memory(memory_dir)),
  beta = beta_headers$BETA_CONTEXT_MGMT
)
chat2$chat("What is my favorite color?")  # Returns "blue"

Context Editing

New claude_context_edit() automatically manages context in long sessions
- Clears stale tool results while preserving conversation flow
- 84% token reduction in 100-turn sessions
- Configurable thresholds and tool exclusions
New context_edit parameter in claude_new()
- Passed via api_args$context_management

Example:

chat <- claude_new(
  tools = list(claude_web_search()),
  context_edit = claude_context_edit(
    trigger_tokens = 30000L,
    keep_tool_uses = 5L,
    exclude_tools = c("memory")
  ),
  beta = beta_headers$BETA_CONTEXT_MGMT
)
# Can run 100+ searches without hitting context limits

Advanced Tool Features

Web Fetch Tool

New claude_web_fetch() enables reading specific URLs
- Wraps ellmer::claude_tool_web_fetch()
- Complements web search for targeted content retrieval

Text Editor Tools

New claude_text_editor() provides structured file editing
- Two types: “basic” (text_editor_20250124) and “advanced” (text_editor_20250728)
- String replacement operations for file manipulation

Token-Efficient Tools

New token_efficient parameter in claude_new()
- Reduces tool response tokens by up to 70% (average 14%)
- Auto-adds token-efficient-tools-2025-02-19 beta header

Tool Search

New claude_tool_defer() enables dynamic tool discovery
- Load only needed tools from collections of 100+
- Prevents context exhaustion with large tool sets
- Requires beta_headers$BETA_TOOL_SEARCH

Example:

tools <- lapply(1:100, function(i) {
  claude_tool_defer(claude_tool(
    fn = function() paste("Tool", i),
    name = paste0("tool_", i),
    desc = paste("Tool number", i)
  ))
})
chat <- claude_new(tools = tools, beta = beta_headers$BETA_TOOL_SEARCH)
chat$chat("Use tool_42")  # Only loads tool_42

Programmatic Tool Calling

New claude_tool_programmatic() enables code-based tool orchestration
- Claude writes Python to batch multiple tool calls
- 37%+ token reduction vs individual API calls
- Filtered/aggregated results
- Requires code execution tool + beta_headers$BETA_ADVANCED_TOOLS

Example:

search_tool <- claude_tool_programmatic(claude_tool(
  fn = function(query) search_db(query),
  name = "search",
  desc = "Search database"
))
chat <- claude_new(
  tools = list(search_tool, claude_code_exec(type = "python")),
  beta = c(beta_headers$BETA_ADVANCED_TOOLS, beta_headers$BETA_CODE_EXEC_PYTHON)
)
chat$chat("Search for 'art', 'music', 'dance' and combine results")

Agent Skills

New skills parameter in claude_new() for specialized tasks
Four new functions for skill management:
- claude_skill() - Reference by ID (pre-built or uploaded)
- claude_skill_local() - Load from local directory
- claude_skill_upload() - Upload to /v1/skills API endpoint
- claude_skill_list() - List available skills

Pre-built Skills

pptx - Create/modify PowerPoint presentations
xlsx - Create/modify Excel spreadsheets
docx - Create/modify Word documents
pdf - Extract/process PDF content

Example:

chat <- claude_new(
  skills = list(claude_skill("pptx")),
  tools = list(claude_code_exec()),
  beta = c(beta_headers$BETA_SKILLS, beta_headers$BETA_CODE_EXEC_BASH)
)
chat$chat("Create a presentation about R packages")

Custom Skills

Load from local directories (agentskills.io spec)
Upload to API for organization-wide sharing
Support templates, scripts, and resource files
YAML frontmatter with name and description

Example:

# Load local skill
chat <- claude_new(
  skills = list(claude_skill_local("~/skills/my_skill")),
  tools = list(claude_code_exec()),
  beta = c(beta_headers$BETA_SKILLS, beta_headers$BETA_CODE_EXEC_BASH)
)

# Upload for persistent use
result <- claude_skill_upload("~/skills/my_skill")
chat <- claude_new(
  skills = list(claude_skill(result$id)),
  tools = list(claude_code_exec()),
  beta = c(beta_headers$BETA_SKILLS, beta_headers$BETA_CODE_EXEC_BASH)
)

Beta Headers

Updated beta_headers from 7 to 13 entries:
- BETA_EFFORT - Token efficiency control
- BETA_SKILLS - Agent Skills
- BETA_CONTEXT_MGMT - Memory and context editing
- BETA_TOOL_SEARCH - Dynamic tool discovery
- BETA_ADVANCED_TOOLS - Programmatic tool calling
- BETA_TOKEN_EFFICIENT - Token-efficient tool responses

Documentation

New Vignettes

vignette("files-citations") - Files API and Citations usage with multi-document examples
vignette("long-running-agents") - Memory tool and context editing for extended sessions
vignette("advanced-tools") - Tool search, programmatic calling, token efficiency
vignette("agent-skills") - Pre-built and custom skills with real-world examples

Updated Documentation

README.md expanded with all new features and comprehensive examples
All 17 new functions fully documented with roxygen2
43 API reference links throughout package documentation
Every function has @family tags for pkgdown organization

Testing

Test Infrastructure

New httptest2-based testing infrastructure for offline API testing
- Fixtures recorded once, tests run offline
- No API key required for CI
- Redactors protect sensitive data
- Block external requests globally

Test Coverage

110 total tests (87 new)
- test-effort.R - 14 tests
- test-files.R - 18 tests
- test-citations.R - 13 tests
- test-memory.R - 24 tests
- test-skills.R - 33 tests
- test-health-check.R - 8 tests
57.04% package coverage (new code >85%)
- claude-skills.R: 92.41%
- claude-files.R: 87.50%
- claude-tools.R: 71.43%
- claude-api.R: 71.19%

Bug Fixes

Skills API Implementation

BREAKING: Pre-built skill IDs corrected to match API:
- ~~"powerpoint"~~ → "pptx"
- ~~"excel"~~ → "xlsx"
- ~~"word"~~ → "docx"
- "pdf" (unchanged)
Fixed claude_skill_upload() to use multipart/form-data instead of JSON
- Folder name in filenames must match skill name from SKILL.md
- All files sent via files[] array
- Uses display_title field for skill name
Fixed claude_skill_list() response parsing
- Use skills_data$data instead of skills_data$skills
- Use s$display_title instead of s$name
- Handle empty response correctly

API Integration

Added api_args parameter to ellmer::chat_anthropic() call
- Required for effort, context_edit, and skills parameters
- Dynamically builds request body extensions

Dependencies

Added to Imports

base64enc - Base64 encoding for inline documents
fs - File system operations for memory tool
yaml - YAML parsing for SKILL.md files
httr2 - HTTP client for Skills API
curl - Multipart form uploads
data.table - Moved from Suggests for skills list operations

Added to Suggests

httptest2 - HTTP testing infrastructure
jsonlite, reticulate, screenshot - Vignette dependencies

Internal Changes

Improved comment quality in R/claude-api.R explaining design decisions
Added .detect_mime() internal helper for file type detection
Test helper functions path_mocks() and path_extra() in tests/testthat/setup.R
httptest2 redactors for API keys and base64 data

Validation

R CMD check: 0 errors, 0 warnings, 3 notes (expected)
All 110 tests passing
All 9 vignettes building successfully
Complete API documentation with verified links