Principle:Anthropics Anthropic sdk python SDK Infrastructure

Knowledge Sources	Anthropic Python SDK Anthropic API Docs
Domains	SDK Architecture, HTTP Transport, Data Modeling
Last Updated	2026-02-15 00:00 GMT

Overview

The SDK Infrastructure principle describes the foundational layer of the Anthropic Python SDK: the HTTP client, response wrappers, data models, type system, and utilities that all higher-level features depend on. SyncAPIClient/AsyncAPIClient provide HTTP transport with retry and timeout logic. APIResponse wraps raw httpx responses with lazy deserialization. BaseModel extends Pydantic for recursive model construction. The _compat module bridges Pydantic v1/v2 differences. Core types define sentinel values (NOT_GIVEN, Omit) and transport types. Transform utilities handle TypedDict-to-JSON conversion with alias resolution.

Theoretical Basis

HTTP Client Layer

The base client classes (SyncAPIClient and AsyncAPIClient) serve as the SDK's HTTP transport backbone. They encapsulate:

Request construction -- Building HTTP requests with correct headers (anthropic-version, x-api-key, Authorization), query parameters, and JSON bodies.
Retry logic -- Automatic retries with exponential back-off for transient failures (connection errors, 429, 5xx). The retry count and back-off intervals are configurable at client construction time.
Timeout management -- Per-request and per-client timeout configurations using httpx.Timeout.
Response dispatch -- Routing raw responses to the appropriate deserialization path based on the expected return type (cast_to).

The client does not implement business logic; it is a generic HTTP client that API resource classes build upon.

Response Wrappers

The APIResponse class wraps the raw httpx.Response and provides lazy deserialization:

response = client.messages.create(...).with_raw_response()
response.status_code   # Access HTTP metadata immediately
response.parse()       # Deserialize JSON into the typed model on demand

This design avoids the cost of JSON parsing and Pydantic validation until the caller explicitly needs the parsed data. The LegacyAPIResponse class preserves backward compatibility with older SDK versions that returned pre-parsed models by default.

BaseModel and Pydantic Integration

The SDK's BaseModel extends Pydantic's BaseModel with additional capabilities for recursive model construction:

Recursive construction -- Nested dictionaries are automatically converted to the appropriate Pydantic model type based on field annotations.
Extra field tolerance -- Unknown fields in API responses are preserved rather than rejected, ensuring forward compatibility when the API adds new fields.
Custom serialization -- The model supports converting back to dictionaries and JSON with alias resolution for round-trip fidelity.

Pydantic v1/v2 Compatibility

The _compat module provides an abstraction layer that allows the SDK to work with both Pydantic v1 and v2. Key bridging functions include:

model_copy() -- Wraps .copy() (v1) or .model_copy() (v2).
model_json() -- Wraps .json() (v1) or .model_dump_json() (v2).
model_dump() -- Wraps .dict() (v1) or .model_dump() (v2).
Field validation decorators -- Unified field_get_default() that abstracts over schema differences.

This compatibility layer shields the rest of the SDK from Pydantic version differences, allowing users to run the SDK with either version installed.

Sentinel Types and Core Types

The SDK defines several sentinel types that serve as type-safe alternatives to None:

NOT_GIVEN -- A sentinel used for optional parameters to distinguish "not provided" from None. This allows the SDK to omit unset parameters from API requests rather than sending null.
Omit -- A sentinel that explicitly removes a field from the request body, even if a default is configured.

Core types also define transport-level constructs: RequestOptions for per-request timeout/header overrides, Headers and Query type aliases, and Body for request body payloads.

Transform Utilities

The transform module converts Python-native TypedDict instances into JSON-ready dictionaries for API requests. The transformation pipeline:

Resolves field aliases (e.g., Python max_tokens to JSON "max_tokens").
Strips NOT_GIVEN values so that unset optional parameters are omitted entirely.
Converts Python types to their JSON representations (e.g., datetime to ISO 8601 strings, Enum to string values).
Handles nested TypedDict structures recursively.

JSONL Decoding

The JSONLDecoder provides line-by-line parsing of newline-delimited JSON streams. This is used internally by streaming response handlers to incrementally parse server-sent events without buffering the entire response body.

General Utilities

The utility module provides cross-cutting helper functions:

is_given() -- Checks whether a value is not the NOT_GIVEN sentinel.
maybe_transform() -- Conditionally applies the transform pipeline.
flatten() -- Flattens nested iterables for batch operations.
lru_cache_none() -- A variant of functools.lru_cache that does not cache None results.

Design Constraints

The base client is transport-agnostic in design but concretely depends on httpx for HTTP communication.
APIResponse holds a reference to the raw httpx.Response, so the response body must remain available until parse() is called.
The Pydantic compatibility layer supports Pydantic v1 (>=1.9.0) and Pydantic v2 (>=2.0.0). Versions outside this range may not work correctly.
NOT_GIVEN is a singleton instance; identity checks (is NOT_GIVEN) are used rather than equality checks.
The package __init__.py re-exports all public types, client classes, and exceptions so that users can import directly from anthropic without navigating the internal module structure.

Related Pages

Implemented By

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment