anthropic-tools 1.0.1

A Rust library for interacting with the Anthropic API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

A Rust library (`anthropic-tools`) for interacting with the Anthropic API. Provides a builder-pattern API client for Claude models with support for tool calling, vision/multimodal, prompt caching, extended thinking, and SSE streaming.

## Build & Test Commands

```bash
# Build
cargo build
cargo build --release

# Run unit tests with nextest
cargo nextest run
cargo make nextest

# Run API integration tests (requires ANTHROPIC_API_KEY)
cargo make test-api

# Run all tests (unit + API integration + doc tests)
cargo make test-all

# Run a single test
cargo nextest run <test_name>

# Run doc tests only
cargo test --doc

# Format and lint
cargo make format-all

# Generate documentation
cargo doc --open
```

## Architecture

### Module Structure

- **`common/`** - Shared types
  - `errors.rs` - `AnthropicToolError` enum and `Result` type alias
  - `tool.rs` - `Tool`, `JsonSchema`, `PropertyDef` for function calling
  - `usage.rs` - Token usage tracking

- **`messages/`** - Messages API implementation
  - `request/mod.rs` - `Messages` client with builder pattern
  - `request/body.rs` - Request body structure, `ThinkingConfig`, and validation
  - `request/content.rs` - `ContentBlock` enum (text, image, tool_use, tool_result, thinking, document)
  - `request/message.rs` - `Message` and `SystemPrompt` types
  - `request/model.rs` - `Model` enum for type-safe model selection
  - `response.rs` - `Response` struct with helper methods
  - `streaming.rs` - SSE event types and `StreamAccumulator`

### Key Patterns

1. **Builder Pattern**: The `Messages` client uses method chaining:
   ```rust
   let mut client = Messages::new();
   // Using Model enum (recommended)
   client.model(Model::Sonnet4).max_tokens(1024).user("Hello");
   // Or using string (backward compatible)
   client.model("claude-sonnet-4-20250514").max_tokens(1024).user("Hello");
   ```

   With extended thinking:
   ```rust
   client.model(Model::Sonnet4).max_tokens(16000).thinking(10000).user("Complex problem");
   ```

2. **Model Enum**: Type-safe model selection with `Model` enum:
   - `Model::Opus4`, `Model::Sonnet4` - Claude 4 family
   - `Model::Sonnet35`, `Model::Haiku35` - Claude 3.5 family
   - `Model::Opus3`, `Model::Sonnet3`, `Model::Haiku3` - Claude 3 family
   - `Model::Other(String)` - Custom/future models
   - Default: `Model::Sonnet4`
   - Helper: `model.supports_thinking()` checks extended thinking capability

3. **Tagged Union Serialization**: `ContentBlock` uses `#[serde(tag = "type")]` for Anthropic API compliance.

4. **Prelude Module**: Import `anthropic_tools::prelude::*` for all commonly used types.

## Environment

- Requires `ANTHROPIC_API_KEY` for API calls
- Supports both environment variable and `.env` file:
  ```bash
  # Option 1: Environment variable
  export ANTHROPIC_API_KEY="sk-ant-..."

  # Option 2: .env file in project root
  echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
  ```
- Priority: Environment variable > `.env` file > `with_api_key()`