Crate api_claude

Source

Expand description

§api_claude

Comprehensive Rust client for Anthropic’s Claude API with enterprise reliability features.

§🎯 Architecture: Stateless HTTP Client

This API crate is designed as a stateless HTTP client with zero persistence requirements. It provides:

Direct HTTP calls to the Anthropic Claude API
In-memory operation state only (resets on restart)
No external storage dependencies (databases, files, caches)
No configuration persistence beyond environment variables

This ensures lightweight, containerized deployments and eliminates operational complexity.

§🏛️ Governing Principle: “Thin Client, Rich API”

Expose all server-side functionality transparently while maintaining zero client-side intelligence or automatic behaviors.

Key principles:

API Transparency: One-to-one mapping with Claude API endpoints
Zero Automatic Behavior: No implicit decision-making or magic thresholds
Explicit Control: Developer decides when, how, and why operations occur
Configurable Reliability: Enterprise features available through explicit configuration

§Scope

§In Scope

Messages API (conversational interface)
Server-Sent Events streaming
Tool/function calling
Vision support (image analysis)
Prompt caching (~90% cost savings)
Token counting
System prompts and safety settings
Enterprise reliability (retry, circuit breaker, rate limiting, failover, health checks)
Synchronous API wrapper
Batch operations

§Out of Scope

Embeddings (not offered by Anthropic)
Audio processing (not available in Claude API)
WebSocket streaming (Claude uses SSE only)
Model tuning/deployment (managed service only)

§Features

Core Capabilities:

Messages API with full conversational support
SSE streaming responses with tool calling integration
Complete function/tool calling with validation
Vision support for image analysis
Prompt caching for cost optimization

Enterprise Reliability:

Retry logic with exponential backoff and jitter
Circuit breaker for failure threshold management
Rate limiting with token bucket algorithm
Multi-endpoint failover (4 strategies)
Health checks with endpoint monitoring

Client Enhancements:

Sync API wrapper for blocking operations
CURL diagnostics for debugging
Dynamic configuration with file watching
Enterprise quota management
HTTP compression support

§Installation

Add to your Cargo.toml:

[dependencies]
api_claude = { version = "0.1.0", features = ["full"] }

§Quick Start

§Basic Usage

use api_claude::{ Client, Secret, CreateMessageRequest, Message, Role, Content };

#[ tokio::main ]
async fn main() -> Result< (), Box< dyn std::error::Error > >
{
  let secret = Secret::new( "sk-ant-api03-your-key-here".to_string() )?;
  let client = Client::new( secret );

  let request = CreateMessageRequest::builder()
    .model( "claude-sonnet-4-5-20250929".to_string() )
    .max_tokens( 1000 )
    .messages( vec![
      Message
      {
        role : Role::User,
        content : vec![ Content::Text
        {
          r#type : "text".to_string(),
          text : "Hello, Claude!".to_string(),
        } ],
        cache_control : None,
      }
    ] )
    .build();

  let response = client.create_message( request ).await?;
  println!( "Claude: {:?}", response.content );

  Ok( () )
}

§Streaming Response

use api_claude::{ Client, Secret, CreateMessageRequest, Message, Role, Content };
use futures_util::StreamExt;

#[ tokio::main ]
async fn main() -> Result< (), Box< dyn std::error::Error > >
{
  let client = Client::from_workspace()?;

  let request = CreateMessageRequest::builder()
    .model( "claude-sonnet-4-5-20250929".to_string() )
    .max_tokens( 1000 )
    .stream( true )
    .messages( vec![ Message::user( "Tell me a story" ) ] )
    .build();

  let mut stream = client.create_message_stream( request ).await?;

  while let Some( event ) = stream.next().await
  {
    let event = event?;
    if let Some( text ) = event.delta_text()
    {
      print!( "{}", text );
    }
  }

  Ok( () )
}

§Authentication

§Option 1: Workspace Secret (Recommended)

Create secret/-secrets.sh in your workspace root:

#!/bin/bash
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

use api_claude::Client;

let client = Client::from_workspace()?;

§Option 2: Environment Variable

export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"

use api_claude::Client;

let client = Client::from_env()?;

§Option 3: Direct Configuration

use api_claude::{ Client, Secret };

let secret = Secret::new( "sk-ant-api03-your-key-here".to_string() )?;
let client = Client::new( secret );

See Secret Loading Guide for complete authentication options.

§Feature Flags

§Core Features

enabled - Master switch for core functionality
streaming - SSE streaming support
tools - Function calling and tools
vision - Image understanding capabilities

§Enterprise Reliability

retry-logic - Exponential backoff retry
circuit-breaker - Circuit breaker pattern
rate-limiting - Token bucket rate limiting
failover - Multi-endpoint failover
health-checks - Health monitoring

§Client Enhancements

sync-api - Synchronous wrappers
curl-diagnostics - Debug utilities
compression - HTTP compression
enterprise-quota - Usage tracking
dynamic-config - Runtime configuration

§Presets

full - All features enabled

§Testing

§Test Coverage

435 tests passing (100%)
Real API integration tests
No-mockup policy: all integration tests use real API calls

§Supported Models

Model	Context Window	Capabilities
claude-sonnet-4-5-20250929	200k tokens	Full capabilities
claude-3-5-sonnet-latest	200k tokens	Fast, cost-effective
claude-3-opus-latest	200k tokens	Highest capability
claude-3-haiku-latest	200k tokens	Fastest

§Documentation

API Reference - Complete API documentation
Examples - Real-world usage examples
Secret Loading - Authentication and secret management
Testing Guide - Testing organization and NO MOCKING policy
Specification - Detailed project specification

§Dependencies

reqwest: HTTP client with async support
tokio: Async runtime
serde: Serialization/deserialization
workspace_tools: Secret management
error_tools: Unified error handling
secrecy: Secure credential handling

All dependencies workspace-managed for consistency.

§Contributing

Follow established patterns in existing code
Use 2-space indentation consistently
Add tests for new functionality
Update documentation for public APIs
Ensure zero clippy warnings: cargo clippy -- -D warnings
Follow zero-tolerance mock policy (real API integration only)
Follow the “Thin Client, Rich API” principle

§License

MIT

§Links

Anthropic Console - Get your API key
Claude API Documentation - Official API docs
Examples - Comprehensive usage examples
Specification - Technical specification Anthropic API client for Rust

This crate provides a comprehensive HTTP client for interacting with Anthropic’s Claude API. It handles authentication, request/response serialization, and streaming support.

§Governing Principle : “Thin Client, Rich API”

This library follows the principle of “Thin Client, Rich API” - exposing all server-side functionality transparently while maintaining zero client-side intelligence or automatic behaviors.

Key Distinction: The principle prohibits automatic/implicit behaviors but explicitly allows and encourages explicit/configurable enterprise reliability features.

§Core Principles

API Transparency: One-to-one mapping with Anthropic Claude API endpoints
Zero Automatic Behavior: No implicit decision-making or magic thresholds
Explicit Control: Developer decides when, how, and why operations occur
Information vs Action: Clear separation between data retrieval and state changes
Configurable Reliability: Enterprise features available through explicit configuration

§Enterprise Reliability Features

The following enterprise reliability features are explicitly allowed when implemented with explicit configuration and transparent operation:

Configurable Retry Logic: Exponential backoff with explicit configuration
Circuit Breaker Pattern: Failure threshold management with transparent state
Rate Limiting: Request throttling with explicit rate configuration
Failover Support: Multi-endpoint configuration and automatic switching
Health Checks: Periodic endpoint health verification and monitoring

§State Management Policy

✅ ALLOWED: Runtime-Stateful, Process-Stateless

Connection pools, circuit breaker state, rate limiting buckets
Retry logic state, failover state, health check state
Runtime state that dies with the process
No persistent storage or cross-process state

❌ PROHIBITED: Process-Persistent State

File storage, databases, configuration accumulation
State that survives process restarts

Implementation Requirements:

Feature gating behind cargo features (retry, circuit_breaker, rate_limiting, failover, health_checks)
Explicit configuration required (no automatic enabling)
Transparent method naming (e.g., execute_with_retries(), execute_with_circuit_breaker())
Zero overhead when features disabled

§Examples

use api_claude::{ Client, Secret, CreateMessageRequest, Message, Role, Content };

// Create a client
let secret = Secret::new( "sk-ant-api03-your-key-here".to_string() )?;
let client = Client::new( secret );

// Create a simple message
let request = CreateMessageRequest::builder()
  .model( "claude-sonnet-4-5-20250929".to_string() )
  .max_tokens( 1000 )
  .messages( vec![
    Message {
      role : Role::User,
      content : vec![ Content::Text {
        r#type : "text".to_string(),
        text : "Hello, Claude! How are you?".to_string()
      } ],
      cache_control : None,
    }
  ] )
  .build();

// Send the request
let response = client.create_message( request ).await?;
println!( "Claude responded : {:?}", response.content );

Modules§

authentication: Advanced authentication functionality for Anthropic API
batch: Batch Messages API
buffered_streaming: Buffered Streaming for Smoother UX
circuit_breaker: Circuit breaker implementation for the Anthropic API client
client: Anthropic API client implementation
compression: HTTP Compression Support
content_generation: Content generation functionality for Anthropic API
curl_diagnostics: CURL diagnostics functionality for Anthropic API client
dynamic_config: Dynamic Configuration with Hot-Reloading
embeddings: Text embedding functionality for Anthropic API client
enhanced_function_calling: Enhanced function calling with type-safe execution and validation
enterprise_config: Enterprise Configuration Module
enterprise_quota: Enterprise Quota Management
environment: Environment configuration and secret validation for Anthropic API
error: Error handling for the Anthropic API client
error_tools: Error-related exports.
exposed: Exposed namespace of the module.
failover: Failover Module
general_diagnostics: General diagnostics functionality for Anthropic API client
health_checks: Health Check Module
input_validation: Input validation module for Claude API requests
messages: Message types for Anthropic API
model_comparison: Model Comparison for A/B Testing
model_management: Model management functionality for Anthropic API
orphan: Orphan namespace of the module.
own: Own namespace of the module.
prelude: Prelude to use essentials: use my_module ::prelude :: *.
rate_limiting: Rate limiting implementation for Anthropic Claude API
request_caching: Request caching implementation for Anthropic Claude API
request_templates: Request Templates for Common Use Cases
retry_logic: Retry logic implementation for the Anthropic API client
secret: Secret management for Anthropic API
ser: Serde-related exports.
streaming: Server-Sent Events streaming support for Anthropic API
streaming_control: Streaming control for pause/resume/cancel operations
sync_api: Synchronous API functionality for Anthropic Claude API
validators: Reusable validation functions for Claude API parameters

Structs§

ActionableError: Actionable error with remediation steps
AdaptiveRateLimiter: Adaptive rate limiter that adjusts based on API responses
AdaptiveRateLimiterConfig: Configuration for adaptive rate limiting
AggregatedMetrics: Aggregated metrics data
Alert: Alert generated by the monitoring system
AlertingSystem: Alerting system
AnthropicApiError: Anthropic API error response structure
AnthropicRateLimitInfo: Rate limit information from Anthropic API response headers
ApiErrorWrap: Wrapper for API error responses
AuditLog: Audit log entry
AuthMetrics: Authentication metrics
AuthPerformanceMonitor: Authentication performance monitor
AuthenticationAuditLogger: Authentication audit logger
AuthenticationError: Enhanced authentication error
BackoffCalculator: Backoff calculator for rate limiting
BackoffStrategyDetails: Backoff strategy details
BackoffStrategyDetails: Detailed backoff strategy information
BatchError: Batch error aggregation
BatchListResponse: Batch list response
BatchRequestItem: Request item for batch processing
BatchResponse: Batch response from API
BatchResult: Individual batch result from JSONL file
BatchResultError: Error information in batch result
BufferConfig: Configuration for buffered streaming
BufferedStream: Buffered stream wrapper
CacheConfig: Configuration for request caching
CacheControl: Cache control configuration for prompt caching
CacheMetrics: Cache metrics for monitoring
ChainedError: Chained error result
CircuitBreaker: Circuit breaker implementation
CircuitBreakerConfig: Circuit breaker configuration
CircuitBreakerMetrics: Circuit breaker metrics
Client: Anthropic API client
ClientConfig: Configuration for Anthropic API client
ClientConfigBuilder: Builder for client configuration requiring explicit values
ComparisonResults: Results from comparing multiple models
CompressionConfig: Compression configuration
ConfigWatcher: Configuration watcher for hot-reloading
ContentGenerationRequest: Content generation configuration and parameters
ContentGenerationRequestBuilder: Builder for content generation requests
ContentGenerationResponse: Content generation response with additional metadata
ContentGenerator: Content generator with advanced capabilities
ContextWindowDetails: Context window details with token breakdown
ControlledStream: Controlled stream wrapper
CorrelationSummary: Correlation summary
CorrelationTracker: Correlation tracker for cross-request errors
CostCalculator: Cost calculator for Claude models (cost per million tokens)
CostComparison: Cost comparison between models
CostEstimate: Cost estimation result
CountMessageTokensRequest: Request to count tokens in a message
CountMessageTokensResponse: Response from token counting endpoint
CreateBatchRequest: Batch creation request
CreateMessageRequest: Request to create a message
CreateMessageRequestBuilder: Builder for CreateMessageRequest
CreateMessageResponse: Response from create message API
CredentialHintGenerator: Credential hint generator
CredentialHints: Credential hints for authentication errors
CredentialValidationInfo: Credential validation information
CurlBuilder: Helper for building cURL commands
CustomError: Custom error type for domain-specific errors
DiagnosticsAggregator: Diagnostics aggregator for comprehensive reporting
DiagnosticsCollector: Diagnostics collector integrating with CURL diagnostics
DiagnosticsContext: Diagnostics context for correlation
DiagnosticsData: Diagnostics data structure
DiagnosticsExporter: Mock exporter for testing
DiagnosticsSummary: Summary of diagnostic information
EmbeddingData: Individual embedding data point
EmbeddingRequest: Embedding request structure for future Anthropic embedding models
EmbeddingResponse: Response from embedding API
EmbeddingUsage: Usage statistics for embedding requests
EnhancedAnthropicError: Enhanced error with context and classification
EnhancedModelCapabilities: Enhanced model capabilities with detailed information
EnhancedModelDetails: Enhanced model details with comprehensive metadata
EnterpriseConfig: Enterprise configuration combining all reliability features
EnterpriseConfigBuilder: Builder for enterprise configuration
Environment: Environment configuration for Anthropic API
EnvironmentCredentials: Environment-specific credentials
ErrorAnalyzer: Error analysis and categorization
ErrorCategory: Error category containing related errors
ErrorChain: Error chain for cause relationships
ErrorClassifier: Error classifier for categorization
ErrorContext: Error context information
ErrorLocalizer: Error localizer for multi-language support
ErrorLogger: Error logger with structured data
ErrorMapper: Error mapper for HTTP status codes
ErrorMetrics: Error metrics reporter
ErrorParser: Error parser for API responses
ErrorRecovery: Error recovery strategy analyzer
ErrorSerializer: Error serializer
ErrorSummary: Summary of all errors across categories
EstimatedUsage: Cost estimation request
ExpirationStatus: Credential expiration status
ExplicitRetryBuilder: Zero Magic: No automatic retry decisions or hidden retry logicTransparent Control: Every retry parameter is visible and configurableInformation vs Action: Provides retry information without making retry decisions
FailoverConfig: Failover configuration and policy
FailoverContext: Failover context representing the current state of a failover attempt
FailoverEndpoint: Endpoint configuration for failover
FailoverManager: Failover manager for endpoint selection and health tracking
FeatureCompatibility: Feature compatibility information
FeatureCompatibilityMatrix: Feature compatibility matrix
FeatureTimelineEntry: Feature timeline entry
FilteredModel: Filtered model result
GenerationMetadata: Metadata about content generation
GenerationSettings: Advanced content generation settings
HealthCheckConfig: Configuration for health checks
HealthCheckResult: Health check result for a single endpoint
HealthChecker: Stateless health check utilities
HealthMetrics: Health metrics aggregator for multiple check results
HealthStatus: Health status information for explicit monitoring
HttpError: Structured HTTP error information
ImageContent: Image content for vision support (requires vision feature)
ImageSource: Image source specification (requires vision feature)
LoadTestResults: Results from a load test
LoadTester: Load testing integration
LocalizedError: Localized error message
LogEntry: Log entry with structured data
Message: Message in conversation
MessageBuilder: Builder for constructing messages with multiple content types
MigrationPath: Migration path for deprecated models
ModelAvailability: Model availability information
ModelCapabilities: Model capabilities structure
ModelComparator: Model comparator for A/B testing
ModelComparison: Model comparison functionality
ModelComparisonResult: Result from comparing a single model
ModelDetailsCache: Model details cache
ModelFilter: Model filtering criteria
ModelFilterBuilder: Builder for model filter
ModelInfo: Model information structure
ModelLifecycle: Model lifecycle information
ModelLimits: Model limits and constraints
ModelManager: Model management system
ModelPerformance: Model performance metrics
ModelPricing: Model pricing information
ModelRecommendation: Model recommendation result
ModelRequirements: Model requirements for selection
ModelRequirementsBuilder: Builder for model requirements
ModelSearchResult: Model search result
ModelStatus: Model status information
MonitoringStatus: Status information for monitoring
NetworkError: Network error details
NetworkErrorClassification: Network error classification
NetworkErrorClassifier: Network error classifier
OperationMetrics: Metrics for operations of a specific type
OperationStats: Statistics for a specific operation type
PerformanceComparison: Performance comparison between models
PerformanceMetrics: Performance metrics collection
PerformanceMonitor: Performance monitor for tracking API and operation performance
PerformanceProfile: Performance profile for a model
QuotaConfig: Quota limits configuration
QuotaExceededError: Quota violation error
QuotaManager: Quota manager for tracking and enforcing usage limits
RateLimitError: Rate limiting error with Anthropic API headers
RateLimitInfo: Rate limit information
RateLimitInfo: Rate limit information for explicit control
RateLimiter: Token bucket rate limiter
RateLimiterConfig: Configuration for rate limiting
RateLimiterMetrics: Rate limiter metrics
RateLimits: Rate limiting information
RealtimeMonitor: Real-time monitoring capabilities
RecoveryStrategy: Recovery strategy information
RequestCache: Request cache implementation
RequestContext: Request context for operations
RequestCounts: Request counts for batch status
RequestTemplate: Request template for common use cases
RequestTracker: Request lifecycle tracker
ResponseContent: Content in response
RetryConfig: Configuration for retry behavior
RetryExecutor: Retry executor for running operations with retry logic
RetryMetrics: Metrics tracking for retry attempts
RetryStrategy: Retry strategy implementation
RuntimeConfig: Runtime configuration that can be hot-reloaded
Secret: Anthropic API key secret
SecurityEvent: Security event
SecurityMonitor: Security monitor for credential transmission
StreamControl: Handle for controlling stream operations
StreamMessage: Stream message structure for streaming responses
StructuredLogger: Structured logger for detailed observability
SyncClient: Synchronous client wrapper around the async Client
SyncClientBuilder: Builder for configuring synchronous clients
SyncRuntime: Runtime manager for synchronous operations
SyncStreamIterator: Synchronous iterator wrapper around async EventStream
SystemContent: System content block for count tokens endpoint
SystemInstructions: Builder for composing multi-part system instructions
SystemPrompt: System prompt with optional cache control
TemperatureRange: Temperature range
TimeoutClassification: Timeout error classifier
TimeoutError: Timeout error details
TokenBreakdown: Token allocation breakdown
ToolDefinition: Tool definition for function calling
ToolRegistry: Registry for managing and executing tools
ToolResultContent: Tool result content in user messages
ToolUseContent: Tool use content in assistant messages
Usage: Usage statistics
UsageMetrics: Usage metrics for a specific time period
ValidationError: Validation error with detailed failure information
VersionCompatibility: Version compatibility information

Enums§

AnthropicError: Anthropic API error types
BackoffStrategy: Backoff strategy types
BackoffStrategyType: Backoff strategy types for error handling
BackoffType: Backoff types for rate limiting
BatchProcessingStatus: Batch processing status
CircuitState: Circuit breaker states
CodeComplexity: Code complexity levels
Content: Content block in a message
ContentLength: Content length categories
EmbeddingInput: Input for embedding requests - can be single text or batch
EndpointHealth: Endpoint health status
EndpointHealthStatus: Health status for an endpoint
ErrorClass: Error classification categories
ErrorSeverity: Error severity levels
ErrorType: Specific error types for detailed classification
FailoverStrategy: Failover strategy for selecting endpoints
HealthCheckStrategy: Health check strategy
LogLevel: Log level for structured logging
LogSeverity: Log severity levels
NetworkErrorType: Network error types
RequestResult: Request result enumeration
RequestStatus: Request status enumeration
RetryStrategyType: Types of retry strategies
Role: Message role in conversation
StreamContentBlock: Content block in streaming response
StreamDelta: Delta updates for streaming content
StreamEvent: Streaming events from Server-Sent Events
StreamState: State of a controlled stream
TimeoutType: Timeout error types
ToolChoice: Choice for how the model should use tools
UseCase: Use case definitions for model recommendations
WritingTone: Writing tone styles

Constants§

ANTHROPIC_API_BASE_URL: Standard base URL for Anthropic API (no longer a magic default)
ANTHROPIC_API_VERSION: Standard API version header value (no longer a magic default)
RECOMMENDED_MODEL: Current recommended model (no longer a magic default)

Traits§

AsCurl: Trait for converting API requests to equivalent cURL commands
AsCurlClient: Trait for client-level cURL generation with authentication
StreamBufferExt: Extension trait for streams
ToolExecutor: Trait for executable tools with type-safe parameter handling
Validate: Trait for validating request parameters

Functions§

add_compression_headers: Add compression headers to request
compress: Compress data using gzip
create_parameter_schema: Helper for creating a parameter schema
create_tool_definition: Helper for creating a simple tool definition
decompress: Decompress gzip-compressed data
is_gzip: Check if data appears to be gzip-compressed
map_deserialization_error: Map deserialization error to AnthropicError
parse_sse_events: Parse Server-Sent Events data into stream events
secret_diagnostic_info: Get diagnostic information about secret loading configuration
validate_anthropic_secret: Validate that required secrets are available for API operations
validate_workspace_structure: Check if workspace secrets directory exists and is properly configured

Type Aliases§

AnthropicResult: Result type for Anthropic API operations
EventStream: Stream of Server-Sent Events
ToolResult: Result type for tool execution

Crate api_claude

Crate api_claude Copy item path

§api_claude

§🎯 Architecture: Stateless HTTP Client

§🏛️ Governing Principle: “Thin Client, Rich API”

§Scope

§In Scope

§Out of Scope

§Features

§Installation

§Quick Start

§Basic Usage

§Streaming Response

§Authentication

§Option 1: Workspace Secret (Recommended)

§Option 2: Environment Variable

§Option 3: Direct Configuration

§Feature Flags

§Core Features

§Enterprise Reliability

§Client Enhancements

§Presets

§Testing

§Test Coverage

§Supported Models

§Documentation

§Dependencies

§Contributing

§License

§Links

§Governing Principle : “Thin Client, Rich API”

§Core Principles

§Enterprise Reliability Features

§State Management Policy

§Examples

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate api_claude