claudio

# Claudio

An Elixir client library for the Anthropic API, providing a comprehensive interface for interacting with Claude models.

## Features

- **Messages API** with streaming support
- **Tool/Function calling** with structured schemas
- **Message Batches API** for large-scale async processing
- **Prompt caching** (up to 90% cost reduction)
- **Vision/image support** (base64, URL, Files API)
- **PDF/document support**
- **MCP (Model Context Protocol) servers**
- **Request building** with fluent API and validation
- **Structured response handling** with content block parsing
- **Token counting** for cost estimation
- **Cache metrics tracking**
- **Configurable timeouts** and retry logic

## Installation

Add `claudio` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:claudio, "~> 0.1.0"}
  ]
end
```

## Quick Start

```elixir
# Create a client
client = Claudio.Client.new(%{
  token: System.get_env("ANTHROPIC_API_KEY"),
  version: "2023-06-01"
})

# Simple message
{:ok, response} = Claudio.Messages.create(client, %{
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 1024,
  messages: [
    %{role: "user", content: "Hello, Claude!"}
  ]
})

IO.puts(response.content |> hd() |> Map.get(:text))
```

## Configuration

### API Client

```elixir
# config/config.exs
config :claudio,
  default_api_version: "2023-06-01",
  default_beta_features: ["prompt-caching-2024-07-31"]
```

### Timeout Configuration

Configure connection and receive timeouts (important for streaming):

```elixir
# config/config.exs
config :claudio, Claudio.Client,
  timeout: 60_000,        # Connection timeout in ms (default: 60s)
  recv_timeout: 120_000   # Receive timeout in ms (default: 120s)
```

**For long-running streaming operations:**

```elixir
config :claudio, Claudio.Client,
  timeout: 60_000,
  recv_timeout: 600_000   # 10 minutes for long streams
```

**For production environments:**

```elixir
# config/prod.exs
config :claudio, Claudio.Client,
  timeout: 30_000,
  recv_timeout: 180_000,
  retry: true  # Enable automatic retries
```

### Retry Configuration

Enable automatic retries for transient failures:

```elixir
config :claudio, Claudio.Client,
  retry: true  # Uses default retry strategy

# Or customize:
config :claudio, Claudio.Client,
  retry: [
    delay: 1000,
    max_retries: 3,
    max_delay: 10_000
  ]
```

## Usage

### Request Builder API (Recommended)

Use the fluent request builder for type-safe requests:

```elixir
alias Claudio.Messages.Request

request =
  Request.new("claude-3-5-sonnet-20241022")
  |> Request.add_message(:user, "What is the capital of France?")
  |> Request.set_max_tokens(1024)
  |> Request.set_temperature(0.7)

{:ok, response} = Claudio.Messages.create(client, request)
```

### Streaming Responses

Stream responses for real-time output:

```elixir
alias Claudio.Messages.{Request, Stream}

request =
  Request.new("claude-3-5-sonnet-20241022")
  |> Request.add_message(:user, "Write a short story")
  |> Request.set_max_tokens(1024)
  |> Request.enable_streaming()

{:ok, stream_response} = Claudio.Messages.create(client, request)

# Parse and accumulate text
text =
  stream_response.body
  |> Stream.parse_events()
  |> Stream.accumulate_text()

IO.puts(text)
```

### Prompt Caching

Reduce costs by caching large contexts:

```elixir
request =
  Request.new("claude-3-5-sonnet-20241022")
  |> Request.set_system_with_cache("""
    You are an expert on Shakespeare's works.
    Here is the full text of Hamlet...
    [large context that will be cached]
    """, ttl: "5m")
  |> Request.add_message(:user, "Analyze Hamlet's soliloquy")
  |> Request.set_max_tokens(2048)

{:ok, response} = Claudio.Messages.create(client, request)

# Check cache metrics
IO.inspect(response.usage.cache_creation_input_tokens)
IO.inspect(response.usage.cache_read_input_tokens)
```

### Vision/Image Support

Send images for analysis:

```elixir
# From base64
image_data = File.read!("image.jpg") |> Base.encode64()

request =
  Request.new("claude-3-5-sonnet-20241022")
  |> Request.add_message_with_image(:user, "Describe this image", image_data, "image/jpeg")
  |> Request.set_max_tokens(1024)
```

### Tool/Function Calling

Define and use tools:

```elixir
alias Claudio.Tools

# Define a tool
weather_tool = Tools.define_tool(
  "get_weather",
  "Get the current weather in a location",
  %{
    type: "object",
    properties: %{
      location: %{type: "string", description: "City name"},
      unit: %{type: "string", enum: ["celsius", "fahrenheit"]}
    },
    required: ["location"]
  }
)

# Create request with tool
request =
  Request.new("claude-3-5-sonnet-20241022")
  |> Request.add_message(:user, "What's the weather in Paris?")
  |> Request.add_tool(weather_tool)
  |> Request.set_max_tokens(1024)

{:ok, response} = Claudio.Messages.create(client, request)

# Extract and handle tool uses
if Tools.has_tool_uses?(response) do
  tool_uses = Tools.extract_tool_uses(response)
  # Execute your tools and continue conversation...
end
```

### Message Batches API

Process large volumes of requests asynchronously:

```elixir
# Create a batch of requests
requests = [
  %{
    custom_id: "req-1",
    params: %{
      model: "claude-3-5-sonnet-20241022",
      max_tokens: 1024,
      messages: [%{role: "user", content: "Hello"}]
    }
  }
]

# Submit batch (up to 100,000 requests)
{:ok, batch} = Claudio.Batches.create(client, requests)

# Wait for completion with progress callback
{:ok, completed_batch} = Claudio.Batches.wait_for_completion(
  client,
  batch["id"],
  fn status ->
    IO.puts("Progress: #{status["request_counts"]["succeeded"]}")
  end
)

# Get results
{:ok, results} = Claudio.Batches.get_results(client, batch["id"])
```

## Error Handling

All API calls return structured errors:

```elixir
case Claudio.Messages.create(client, request) do
  {:ok, response} ->
    # Handle success
    IO.puts("Success!")

  {:error, %Claudio.APIError{} = error} ->
    # Handle API errors
    IO.puts("Error #{error.status}: #{error.message}")
    IO.inspect(error.type)  # :rate_limit_error, :authentication_error, etc.

  {:error, reason} ->
    # Handle other errors (network, timeout, etc.)
    IO.inspect(reason)
end
```

## Testing

```bash
# Unit tests only
mix test

# Include integration tests (requires ANTHROPIC_API_KEY)
mix test --include integration
```

## Documentation

Generate documentation:

```bash
mix docs
open doc/index.html
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Anthropic API Documentation](https://docs.anthropic.com/)
- [GitHub Repository](https://github.com/thetonymaster/claudio)