feat(api): add support for structured outputs beta

https://docs.claude.com/en/docs/build-with-claude/structured-outputs

Author: stainless-app[bot]

.inline-snapshot/external/.gitignore

@@ -0,0 +1,2 @@
+# ignore all snapshots which are not referred in the source
+*-new.*

.inline-snapshot/external/cd8d3d185e7a993935ab650e0e5c6a7970758bac7d0487f9b1afaad2cc095f3c.json

@@ -0,0 +1,4 @@
+[
+  "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"model\":\"claude-haiku-4-5-20251001\",\"id\":\"msg_01C63EzoQa1oa1eNn778a6ep\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":656,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":3,\"service_tier\":\"standard\"}}           }\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}    }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"I'll get\"}   }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" the weather for San Francisco for you.\"}  }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0         }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":1,\"content_block\":{\"type\":\"tool_use\",\"id\":\"toolu_011V184uLZKFsxYfCJSjiQ6q\",\"name\":\"get_weather\",\"input\":{}}    }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\"}               }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"loc\"}              }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"ati\"}         }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"on\\\": \\\"San Fr\"}   }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"anc\"}     }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"isc\"}           }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"o, CA\\\"\"}             }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\", \\\"units\\\"\"}      }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\": \\\"f\\\"}\"} }\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":1            }\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\",\"stop_sequence\":null},\"usage\":{\"input_tokens\":656,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"output_tokens\":85}   }\n\nevent: message_stop\ndata: {\"type\":\"message_stop\" }\n\n",
+  "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"model\":\"claude-haiku-4-5-20251001\",\"id\":\"msg_01Vm8Ddgc8qm4iuUSKbf6jku\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"stop_reason\":null,\"stop_sequence\":null,\"usage\":{\"input_tokens\":781,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":6,\"service_tier\":\"standard\"}}               }\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}            }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"The weather in San Francisco,\"}      }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" CA is currently **Sunny** with a temperature of **\"}}\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"68°F**.\"}    }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0          }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\",\"stop_sequence\":null},\"usage\":{\"input_tokens\":781,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"output_tokens\":25}            }\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"             }\n\n"
+]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 34
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic%2Fanthropic-5e665f72d2774cd751988ccc94f623f264d9358aa073289779de5815d36e89a3.yml
-openapi_spec_hash: c5f969a677c73796d192cf09dbb047f9
-config_hash: bbb07992b537724667f4589012714eb7
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic%2Fanthropic-2f35b2ff9174d526a6d35796d2703490bfa5692312af67cbdfa4500283dabe31.yml
+openapi_spec_hash: dc52b25c487e97d355ef645644aa13e7
+config_hash: 239752fc0713a82e121ea45f7e2ebbf6

api.md

@@ -263,6 +263,7 @@ from anthropic.types.beta import (
     BetaInputJSONDelta,
     BetaInputTokensClearAtLeast,
     BetaInputTokensTrigger,
+    BetaJSONOutputFormat,
     BetaMCPToolResultBlock,
     BetaMCPToolUseBlock,
     BetaMCPToolUseBlockParam,

examples/structured_outputs.py

@@ -0,0 +1,37 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = [
+#     "anthropic",
+# ]
+#
+# [tool.uv.sources]
+# anthropic = { path = "../", editable = true }
+# ///
+
+
+import pydantic
+
+import anthropic
+
+
+class Order(pydantic.BaseModel):
+    product_name: str
+    price: float
+    quantity: int
+
+
+client = anthropic.Anthropic()
+
+prompt = """
+Extract the product name, price, and quantity from this customer message:
+"Hi, I’d like to order 2 packs of Green Tea for 5.50 dollars each."
+"""
+
+parsed_message = client.beta.messages.parse(
+    model="claude-sonnet-4-5-20250929-structured-outputs",
+    messages=[{"role": "user", "content": prompt}],
+    max_tokens=1024,
+    output_format=Order,
+)
+
+print(parsed_message.parsed_output)  # Order(product_name='Green Tea', price=5.5, quantity=2)

examples/structured_outputs_streaming.py

@@ -0,0 +1,38 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = [
+#     "anthropic",
+# ]
+#
+# [tool.uv.sources]
+# anthropic = { path = "../", editable = true }
+# ///
+
+import pydantic
+
+import anthropic
+
+
+class Order(pydantic.BaseModel):
+    product_name: str
+    price: float
+    quantity: int
+
+
+client = anthropic.Anthropic()
+
+prompt = """
+Extract the product name, price, and quantity from this customer message:
+"Hi, I’d like to order 2 packs of Green Tea for 5.50 dollars each."
+"""
+
+with client.beta.messages.stream(
+    model="claude-sonnet-4-5-20250929-structured-outputs",
+    messages=[{"role": "user", "content": prompt}],
+    betas=["structured-outputs-2025-09-17"],
+    max_tokens=1024,
+    output_format=Order,
+) as stream:
+    for event in stream:
+        if event.type == "text":
+            print(event.parsed_snapshot())

pyproject.toml

@@ -160,7 +160,7 @@ show_error_codes = true
 #
 # We also exclude our `tests` as mypy doesn't always infer
 # types correctly and Pyright will still catch any type errors.
-exclude = ['src/anthropic/_files.py', '_dev/.*.py', 'tests/.*', 'examples/mcp_server_weather.py', 'examples/tools_with_mcp.py', 'examples/memory/basic.py']
+exclude = ['src/anthropic/_files.py', '_dev/.*.py', 'tests/.*', 'examples/mcp_server_weather.py', 'examples/tools_with_mcp.py', 'examples/memory/basic.py', 'src/anthropic/lib/_parse/_transform.py']
 
 strict_equality = true
 implicit_reexport = true

src/anthropic/__init__.py

@@ -44,6 +44,7 @@
 )
 from ._base_client import DefaultHttpxClient, DefaultAioHttpClient, DefaultAsyncHttpxClient
 from ._utils._logs import setup_logging as _setup_logging
+from .lib._parse._transform import transform_schema
 
 __all__ = [
     "types",
@@ -91,6 +92,7 @@
     "AI_PROMPT",
     "beta_tool",
     "beta_async_tool",
+    "transform_schema",
 ]
 
 if not _t.TYPE_CHECKING:

src/anthropic/_compat.py

@@ -131,6 +131,12 @@ def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str:
     return model.model_dump_json(indent=indent)
 
 
+def model_parse_json(model: type[_ModelT], data: str | bytes) -> _ModelT:
+    if PYDANTIC_V1:
+        return model.parse_raw(data)  # pyright: ignore[reportDeprecated]
+    return model.model_validate_json(data)
+
+
 def model_dump(
     model: pydantic.BaseModel,
     *,

src/anthropic/_models.py

@@ -774,7 +774,7 @@ class GenericModel(BaseGenericModel, BaseModel):
 
 
 if not PYDANTIC_V1:
-    from pydantic import TypeAdapter as _TypeAdapter
+    from pydantic import TypeAdapter as _TypeAdapter, computed_field as computed_field
 
     _CachedTypeAdapter = cast("TypeAdapter[object]", lru_cache(maxsize=None)(_TypeAdapter))
 
@@ -811,6 +811,18 @@ def _create_pydantic_model(type_: _T) -> Type[RootModel[_T]]:
     def TypeAdapter(*_args: Any, **_kwargs: Any) -> Any:
         raise RuntimeError("attempted to use TypeAdapter in pydantic v1")
 
+    def computed_field(func: Any | None = None, /, **__: Any) -> Any:
+        def _exc_func(*_: Any, **__: Any) -> Any:
+            raise RuntimeError("attempted to use computed_field in pydantic v1")
+
+        def _dec(*_: Any, **__: Any) -> Any:
+            return _exc_func
+
+        if func is not None:
+            return _dec(func)
+        else:
+            return _dec
+
 
 class FinalRequestOptionsInput(TypedDict, total=False):
     method: Required[str]