anthropic

Provides dual-track client classes (Anthropic for sync, AsyncAnthropic for async) that abstract HTTP transport, authentication, and request lifecycle management. Both clients inherit from a shared _BaseClient that handles connection pooling, retry logic with exponential backoff, and cloud provider routing (Vertex AI, AWS Bedrock). Clients are instantiated with API keys, base URLs, and timeout configurations, automatically managing session state and request signing.

Implements SSE (Server-Sent Events) streaming via httpx's streaming transport, with specialized stream managers that parse Claude's event format incrementally. The SDK decodes raw SSE bytes into typed event objects (content_block_start, content_block_delta, message_stop, etc.), supporting both synchronous and asynchronous iteration. Stream managers handle backpressure, error recovery, and automatic cleanup of connections.

Defines a hierarchy of exception types (APIError, APIConnectionError, RateLimitError, APIStatusError, etc.) that classify API failures by type and provide structured error information (status code, error message, request ID). The SDK catches HTTP errors and transforms them into typed exceptions, allowing developers to handle different failure modes (rate limits, auth failures, server errors) with specific catch blocks.

Provides helper utilities for common SDK operations: file handling (extracting file paths and MIME types), async utilities (running async code in sync contexts), string utilities (parsing, formatting), and type guards (checking if a value matches a type). These utilities reduce boilerplate in applications using the SDK and support common patterns like file uploads and type validation.

Manages the full HTTP request lifecycle including header injection, timeout configuration, and request signing. Developers can customize headers per request or per client, set connection/read/write timeouts, and configure request signing for cloud provider authentication. The SDK normalizes timeout configuration across sync and async transports.

Provides a declarative tool system where developers define tools via TypedDict or Pydantic models with JSON schema generation. The SDK validates tool definitions at request time, maps Claude's tool_use blocks to Python callables via a tool registry, and supports MCP (Model Context Protocol) integration for dynamic tool discovery. Tool runners execute functions with type-checked inputs and serialize outputs back to Claude.

Enables extraction of structured data (JSON, Pydantic models) from Claude's responses using the SDK's built-in parsing layer. For streaming responses, the SDK reconstructs partial JSON from content_block_delta events and validates against a provided schema. For non-streaming, it parses the final text block. The parser handles malformed JSON gracefully and supports both raw dict output and Pydantic model instantiation.

Implements transparent retry handling at the HTTP layer via the _BaseClient, automatically retrying transient failures (5xx errors, timeouts, rate limits) with exponential backoff and jitter. Retry configuration is customizable per client instance (max retries, backoff multiplier, initial delay). The SDK respects Retry-After headers from the API and integrates with httpx's retry transport.

Provides a dedicated Message Batches API that accepts multiple message requests in a single batch, processes them asynchronously on Anthropic's infrastructure, and returns results via polling or webhook callbacks. Batches are submitted as JSONL files containing individual message requests, processed with lower latency/cost than individual API calls, and results are retrieved via batch ID polling.

Defines all API request and response types using Pydantic BaseModel with runtime validation, supporting both Pydantic v1 and v2 simultaneously. Request types use TypedDict for flexibility, while responses use Pydantic models for validation and serialization. The SDK includes a compatibility layer that detects Pydantic version and uses appropriate validation/serialization methods, ensuring type safety across Python versions.

Abstracts authentication and endpoint routing for Anthropic's API, Google Vertex AI, and AWS Bedrock using a provider-agnostic client interface. The SDK detects the provider from environment variables or explicit configuration, applies provider-specific auth (API key, OAuth, AWS SigV4), and routes requests to the correct endpoint. Request/response formats are normalized across providers.

Provides a separate beta API client (BetaMessages) that exposes experimental Claude features before they're promoted to stable API. Beta features are versioned (e.g., web_search_tool_20250305) and may have different request/response schemas than stable APIs. The SDK maintains backward compatibility by keeping beta and stable APIs separate, allowing gradual migration as features stabilize.

Wraps paginated API responses (e.g., model listings) in response objects that provide iteration helpers and metadata. The SDK handles cursor-based pagination transparently, allowing developers to iterate over results without manually managing page tokens. Response wrappers include metadata (total count, pagination tokens) and support both synchronous and asynchronous iteration.