Principle:Anthropics Anthropic sdk python Beta Type System

Knowledge Sources	Anthropic Python SDK Anthropic API Docs
Domains	SDK Architecture, Type System, Beta Features
Last Updated	2026-02-15 00:00 GMT

Overview

The Beta Type System principle describes how the Anthropic Python SDK defines and organizes types, response models, and parameter types for experimental API features. Beta types mirror their stable counterparts (BetaMessage corresponds to Message, BetaUsage corresponds to Usage) but include additional experimental fields such as cache_creation_input_tokens. The Beta namespace re-exports all beta types for clean imports. ParsedBetaMessage adds generic typed output parsing for structured extraction workflows.

Theoretical Basis

Parallel Type Hierarchies

The SDK maintains two parallel type hierarchies -- stable and beta -- that share the same structural patterns but differ in their field sets:

Stable                          Beta
──────                          ────
Message                  ↔      BetaMessage
Usage                    ↔      BetaUsage
ContentBlock             ↔      BetaContentBlock
ContentBlockParam        ↔      BetaContentBlockParam
TextBlock                ↔      BetaTextBlock
ToolUseBlock             ↔      BetaToolUseBlock

This parallel structure ensures that:

Stable types are never polluted -- Experimental fields do not appear on stable types, preserving API contract stability for production users.
Beta types are self-contained -- Code using beta features can import from the beta namespace without mixing stable and experimental field sets.
Migration is straightforward -- When a beta feature graduates to stable, the corresponding beta type's additional fields are merged into the stable type, and the beta type becomes an alias.

The Beta Namespace

The Beta namespace module re-exports all beta types from a single import location:

from anthropic.types.beta import (
    BetaMessage,
    BetaUsage,
    BetaContentBlock,
    BetaContentBlockParam,
    BetaTextBlock,
    BetaToolUseBlock,
)

This follows the facade pattern: rather than requiring callers to know the internal module structure (e.g., anthropic.types.beta.beta_message), the namespace module provides a flat, discoverable surface. The namespace also serves as documentation -- the set of re-exported names defines the complete public API for beta features.

Additional Experimental Fields

Beta types extend stable types with fields that are under active development:

BetaUsage.cache_creation_input_tokens -- Tracks tokens used to create prompt cache entries. This field is absent from the stable Usage type when caching is not a generally available feature.
BetaUsage.cache_read_input_tokens -- Tracks tokens read from existing cache entries.
Additional content block types -- Beta content blocks may include experimental block types not yet available in the stable API.

These fields are typically Optional in the beta types, reflecting the fact that they may or may not be present depending on the API version and feature flags in effect.

ParsedBetaMessage and Generic Output Typing

ParsedBetaMessage extends BetaMessage with a generic type parameter for structured output parsing:

class ParsedBetaMessage(BetaMessage, Generic[OutputT]):
    parsed: Optional[OutputT]

This allows the SDK's structured output helpers to return a message whose parsed field is typed to the caller's output schema. For example, if the caller requests extraction into a UserProfile Pydantic model, the return type is ParsedBetaMessage[UserProfile], providing full type safety from API response to application domain object.

Beta Resource Methods

The beta type system supports beta resource classes (e.g., client.beta.messages) that accept beta parameter types and return beta response types. This resource-level separation ensures that beta API endpoints -- which may have different request/response schemas -- are accessed through a distinct namespace, preventing accidental use of beta features in production code paths.

Skill-Specific Response Types

Some beta features introduce entirely new response types that have no stable counterpart. For example, SkillCreateResponse represents the result of creating an experimental skill resource. These types are defined exclusively in the beta namespace and will either graduate to stable or be removed when the experiment concludes.

Design Constraints

Beta types follow the same Pydantic model patterns as stable types (discriminated unions, nested composition, optional fields with None defaults).
The beta namespace must be explicitly imported; beta types are not available from the top-level anthropic package to prevent accidental usage.
Beta type names are always prefixed with Beta to make them visually distinguishable from stable types in code.
When a beta feature is removed, its corresponding types are deprecated and eventually deleted. The SDK's changelog documents these removals.

Related Pages

Implemented By

Page Connections

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

Principle

Implementation

Heuristic

Environment