AGENTS.md

# AGENTS.md

This file provides guidance to agents or humans when working with code in this repository.

## Architecture Overview

This is an Anthropic Claude API client library written in Rust, designed with a modular architecture that separates concerns between the client and API endpoint managers. The library implements a chain-style API pattern similar to modern cloud SDKs.

### Core Structure

```
anthropic-rust/src/
├── lib.rs                 # Library entry point with re-exports
├── client.rs              # Main Client with builder pattern, HTTP handling
├── message.rs             # Message API manager (create, stream, count_tokens)
├── batch.rs               # Message Batches API manager
├── model.rs               # Models API manager
└── types/                 # Type definitions
    ├── mod.rs             # Module exports
    ├── messages.rs        # Messages API types (requests, responses, content blocks)
    ├── batches.rs         # Batch API types
    └── models.rs          # Models API types
```

**Key Design Patterns:**
- **Manager-style API**: `client.messages().create(request).await`
- **Builder pattern**: `Client::builder().api_key(key).build()?`
- **Request builders**: `CreateMessageRequest::builder().model("...").build()?`

### Client

The `Client` struct is the primary entry point:
- Manages HTTP client, API key, base URL, and API version
- Provides manager accessor methods: `messages()`, `batches()`, `models()`
- Supports custom configuration via `ClientBuilder`
- Handles request/response serialization and error handling
- Supports beta feature flags via `beta()` method

### Message (API Manager)

`Message` provides access to the Messages API:
- `create()` - send a message and get a complete response
- `create_stream()` - SSE streaming for incremental responses
- `count_tokens()` - pre-flight token estimation

### Batch (API Manager)

`Batch` provides access to the Message Batches API:
- `create()` - create a new batch of message requests
- `get()` - retrieve batch status
- `list()` - list all batches
- `cancel()` - cancel a processing batch
- `delete()` - delete a completed batch

### Model (API Manager)

`Model` provides access to the Models API:
- `list()` - list available models
- `get()` - get details for a specific model

### Type System

- All types are exported from `types::*`
- Request/response types mirror the Anthropic API structure
- Content blocks support: text, image, document, tool_use, tool_result, thinking, redacted_thinking
- Stream types use `async-stream` for Server-Sent Events parsing
- Full support for tool use, extended thinking, and caching

## Development Commands

### Building and Testing
```bash
# Build the library
cargo build

# Check compilation (faster)
cargo check

# Run tests
cargo test
```

### Running Examples
```bash
# Basic message example
cargo run --example messages

# Streaming example
cargo run --example streaming

# Batches example
cargo run --example batches

# Models example
cargo run --example models
```

### Workspace Structure
This is a Cargo workspace with:
- Main library: `anthropic-rust/`
- Examples: `examples/*/` (each is its own crate)

## Development Rules

**Core Reference Materials:**
- [Anthropic Claude API documentation](https://platform.claude.com/docs/en/api/overview) (primary reference)
- Official Anthropic API specifications

**Development Workflow:**
1. **Compilation**: Always compile after code changes with `cargo check` or `cargo build`
2. **Testing**: Write unit tests for new functionality, run with `cargo test`
3. **Examples**: Create examples for each API capability in `examples/[name]/`
4. **Documentation**: Keep docs concise and current

**Environment Variables:**

Examples expect:
- `ANTHROPIC_API_KEY` - API key for Anthropic Claude API
- `ANTHROPIC_BASE_URL` - Optional base URL override

Load via `.env` file using `dotenvy::dotenv()`.

### Adding New API Endpoints

1. Add type definitions in `types/[name].rs` if needed
2. Add API manager struct in `[name].rs` with methods
3. Add manager accessor to `Client` in `client.rs`
4. Update `types/mod.rs` and `lib.rs` to export new types
5. Create example in `examples/[name]/`
6. Update documentation

### API Coverage Status

Currently implemented:
- Messages API (`/v1/messages`)
- Streaming Messages API (SSE)
- Token Counting API (`/v1/messages/count_tokens`)
- Message Batches API (`/v1/messages/batches`)
- Models API (`/v1/models`)

Features supported:
- Text generation
- Vision (images)
- Documents (PDF, text)
- Tool use (function calling)
- Extended thinking
- Prompt caching
- Server-side tools (web search)