anthropic 0.76.0__py3-none-any.whl → 0.77.0__py3-none-any.whl

anthropic/resources/beta/messages/messages.py

@@ -40,12 +40,13 @@ from ....types.beta import (
     message_create_params,
     message_count_tokens_params,
 )
+from ...._exceptions import AnthropicError
 from ...._base_client import make_request_options
 from ...._utils._utils import is_dict
 from ....lib.streaming import BetaMessageStreamManager, BetaAsyncMessageStreamManager
 from ...messages.messages import DEPRECATED_MODELS
 from ....types.model_param import ModelParam
-from ....lib._parse._response import ResponseFormatT, parse_response
+from ....lib._parse._response import ResponseFormatT, parse_beta_response
 from ....lib._parse._transform import transform_schema
 from ....types.beta.beta_message import BetaMessage
 from ....lib.tools._beta_functions import (
@@ -233,10 +234,13 @@ class Messages(SyncAPIResource):
 
           metadata: An object describing metadata about the request.
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
 
-          output_format: A schema to specify Claude's output format in responses.
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
+
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           service_tier: Determines whether to use priority capacity (if available) or standard capacity
               for this request.
@@ -527,10 +531,13 @@ class Messages(SyncAPIResource):
 
           metadata: An object describing metadata about the request.
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
+
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
 
-          output_format: A schema to specify Claude's output format in responses.
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           service_tier: Determines whether to use priority capacity (if available) or standard capacity
               for this request.
@@ -817,10 +824,13 @@ class Messages(SyncAPIResource):
 
           metadata: An object describing metadata about the request.
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
+
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
 
-          output_format: A schema to specify Claude's output format in responses.
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           service_tier: Determines whether to use priority capacity (if available) or standard capacity
               for this request.
@@ -1004,6 +1014,8 @@ class Messages(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> BetaMessage | Stream[BetaRawMessageStreamEvent]:
         validate_output_format(output_format)
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
 
         if not stream and not is_given(timeout) and self._client.timeout == DEFAULT_TIMEOUT:
             timeout = self._client._calculate_nonstreaming_timeout(
@@ -1017,6 +1029,8 @@ class Messages(SyncAPIResource):
                 stacklevel=3,
             )
 
+        merged_output_config = _merge_output_configs(output_config, output_format)
+
         extra_headers = {
             **strip_not_given({"anthropic-beta": ",".join(str(e) for e in betas) if is_given(betas) else not_given}),
             **(extra_headers or {}),
@@ -1032,8 +1046,8 @@ class Messages(SyncAPIResource):
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
                     "metadata": metadata,
-                    "output_config": output_config,
-                    "output_format": output_format,
+                    "output_config": merged_output_config,
+                    "output_format": omit,
                     "service_tier": service_tier,
                     "stop_sequences": stop_sequences,
                     "stream": stream,
@@ -1087,6 +1101,9 @@ class Messages(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> ParsedBetaMessage[ResponseFormatT]:
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
         if not stream and not is_given(timeout) and self._client.timeout == DEFAULT_TIMEOUT:
             timeout = self._client._calculate_nonstreaming_timeout(
                 max_tokens, MODEL_NONSTREAMING_TOKENS.get(model, None)
@@ -1101,9 +1118,9 @@ class Messages(SyncAPIResource):
 
         betas = [beta for beta in betas] if is_given(betas) else []
 
-        if "structured-outputs-2025-11-13" not in betas:
+        if "structured-outputs-2025-12-15" not in betas and is_given(output_format):
             # Ensure structured outputs beta is included for parse method
-            betas.append("structured-outputs-2025-11-13")
+            betas.append("structured-outputs-2025-12-15")
 
         extra_headers = {
             "X-Stainless-Helper": "beta.messages.parse",
@@ -1111,26 +1128,28 @@ class Messages(SyncAPIResource):
             **(extra_headers or {}),
         }
 
-        transformed_output_format: Optional[message_create_params.OutputFormat] | NotGiven = NOT_GIVEN
-
         if is_given(output_format) and output_format is not None:
             adapted_type: TypeAdapter[ResponseFormatT] = TypeAdapter(output_format)
 
             try:
                 schema = adapted_type.json_schema()
-                transformed_output_format = message_create_params.OutputFormat(
+                transformed_output_format = BetaJSONOutputFormatParam(
                     schema=transform_schema(schema), type="json_schema"
                 )
             except pydantic.errors.PydanticSchemaGenerationError as e:
                 raise TypeError(
                     (
                         "Could not generate JSON schema for the given `output_format` type. "
-                        "Use a type that works with `pydanitc.TypeAdapter`"
+                        "Use a type that works with `pydantic.TypeAdapter`"
                     )
                 ) from e
 
+            merged_output_config = _merge_output_configs(output_config, transformed_output_format)
+        else:
+            merged_output_config = output_config
+
         def parser(response: BetaMessage) -> ParsedBetaMessage[ResponseFormatT]:
-            return parse_response(
+            return parse_beta_response(
                 response=response,
                 output_format=cast(
                     ResponseFormatT,
@@ -1149,8 +1168,8 @@ class Messages(SyncAPIResource):
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
                     "metadata": metadata,
-                    "output_config": output_config,
-                    "output_format": transformed_output_format,
+                    "output_config": merged_output_config,
+                    "output_format": omit,
                     "service_tier": service_tier,
                     "stop_sequences": stop_sequences,
                     "stream": stream,
@@ -1310,6 +1329,9 @@ class Messages(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> BetaStreamingToolRunner[ResponseFormatT] | BetaToolRunner[ResponseFormatT]:
         """Create a Message stream"""
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
         if model in DEPRECATED_MODELS:
             warnings.warn(
                 f"The model '{model}' is deprecated and will reach end-of-life on {DEPRECATED_MODELS[model]}.\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.",
@@ -1413,6 +1435,9 @@ class Messages(SyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> BetaMessageStreamManager[ResponseFormatT]:
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
         if model in DEPRECATED_MODELS:
             warnings.warn(
                 f"The model '{model}' is deprecated and will reach end-of-life on {DEPRECATED_MODELS[model]}.\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.",
@@ -1428,7 +1453,7 @@ class Messages(SyncAPIResource):
             **(extra_headers or {}),
         }
 
-        transformed_output_format: Optional[BetaJSONOutputFormatParam] | NotGiven = NOT_GIVEN
+        transformed_output_format: BetaJSONOutputFormatParam | Omit = omit
 
         if is_dict(output_format):
             transformed_output_format = cast(BetaJSONOutputFormatParam, output_format)
@@ -1444,9 +1469,12 @@ class Messages(SyncAPIResource):
                 raise TypeError(
                     (
                         "Could not generate JSON schema for the given `output_format` type. "
-                        "Use a type that works with `pydanitc.TypeAdapter`"
+                        "Use a type that works with `pydantic.TypeAdapter`"
                     )
                 ) from e
+
+        merged_output_config = _merge_output_configs(output_config, transformed_output_format)
+
         make_request = partial(
             self._post,
             "/v1/messages?beta=true",
@@ -1456,8 +1484,8 @@ class Messages(SyncAPIResource):
                     "messages": messages,
                     "model": model,
                     "metadata": metadata,
-                    "output_config": output_config,
-                    "output_format": transformed_output_format,
+                    "output_config": merged_output_config,
+                    "output_format": omit,
                     "container": container,
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
@@ -1594,10 +1622,13 @@ class Messages(SyncAPIResource):
 
           mcp_servers: MCP servers to be utilized in this request
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
+
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
 
-          output_format: A schema to specify Claude's output format in responses.
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           system: System prompt.
 
@@ -1704,6 +1735,11 @@ class Messages(SyncAPIResource):
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
+        merged_output_config = _merge_output_configs(output_config, output_format)
+
         extra_headers = {
             **strip_not_given(
                 {
@@ -1723,8 +1759,8 @@ class Messages(SyncAPIResource):
                     "model": model,
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
-                    "output_config": output_config,
-                    "output_format": output_format,
+                    "output_config": merged_output_config,
+                    "output_format": omit,
                     "system": system,
                     "thinking": thinking,
                     "tool_choice": tool_choice,
@@ -1894,10 +1930,13 @@ class AsyncMessages(AsyncAPIResource):
 
           metadata: An object describing metadata about the request.
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
 
-          output_format: A schema to specify Claude's output format in responses.
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
+
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           service_tier: Determines whether to use priority capacity (if available) or standard capacity
               for this request.
@@ -2188,10 +2227,13 @@ class AsyncMessages(AsyncAPIResource):
 
           metadata: An object describing metadata about the request.
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
+
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
 
-          output_format: A schema to specify Claude's output format in responses.
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           service_tier: Determines whether to use priority capacity (if available) or standard capacity
               for this request.
@@ -2478,10 +2520,13 @@ class AsyncMessages(AsyncAPIResource):
 
           metadata: An object describing metadata about the request.
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
 
-          output_format: A schema to specify Claude's output format in responses.
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
+
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           service_tier: Determines whether to use priority capacity (if available) or standard capacity
               for this request.
@@ -2665,6 +2710,8 @@ class AsyncMessages(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> BetaMessage | AsyncStream[BetaRawMessageStreamEvent]:
         validate_output_format(output_format)
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
 
         if not stream and not is_given(timeout) and self._client.timeout == DEFAULT_TIMEOUT:
             timeout = self._client._calculate_nonstreaming_timeout(
@@ -2678,6 +2725,8 @@ class AsyncMessages(AsyncAPIResource):
                 stacklevel=3,
             )
 
+        merged_output_config = _merge_output_configs(output_config, output_format)
+
         extra_headers = {
             **strip_not_given({"anthropic-beta": ",".join(str(e) for e in betas) if is_given(betas) else not_given}),
             **(extra_headers or {}),
@@ -2693,8 +2742,8 @@ class AsyncMessages(AsyncAPIResource):
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
                     "metadata": metadata,
-                    "output_config": output_config,
-                    "output_format": output_format,
+                    "output_config": merged_output_config,
+                    "output_format": omit,
                     "service_tier": service_tier,
                     "stop_sequences": stop_sequences,
                     "stream": stream,
@@ -2748,6 +2797,9 @@ class AsyncMessages(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> ParsedBetaMessage[ResponseFormatT]:
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
         if not stream and not is_given(timeout) and self._client.timeout == DEFAULT_TIMEOUT:
             timeout = self._client._calculate_nonstreaming_timeout(
                 max_tokens, MODEL_NONSTREAMING_TOKENS.get(model, None)
@@ -2761,9 +2813,9 @@ class AsyncMessages(AsyncAPIResource):
             )
         betas = [beta for beta in betas] if is_given(betas) else []
 
-        if "structured-outputs-2025-11-13" not in betas:
+        if "structured-outputs-2025-12-15" not in betas and is_given(output_format):
             # Ensure structured outputs beta is included for parse method
-            betas.append("structured-outputs-2025-11-13")
+            betas.append("structured-outputs-2025-12-15")
 
         extra_headers = {
             "X-Stainless-Helper": "beta.messages.parse",
@@ -2771,26 +2823,28 @@ class AsyncMessages(AsyncAPIResource):
             **(extra_headers or {}),
         }
 
-        transformed_output_format: Optional[message_create_params.OutputFormat] | NotGiven = NOT_GIVEN
-
         if is_given(output_format) and output_format is not None:
             adapted_type: TypeAdapter[ResponseFormatT] = TypeAdapter(output_format)
 
             try:
                 schema = adapted_type.json_schema()
-                transformed_output_format = message_create_params.OutputFormat(
+                transformed_output_format = BetaJSONOutputFormatParam(
                     schema=transform_schema(schema), type="json_schema"
                 )
             except pydantic.errors.PydanticSchemaGenerationError as e:
                 raise TypeError(
                     (
                         "Could not generate JSON schema for the given `output_format` type. "
-                        "Use a type that works with `pydanitc.TypeAdapter`"
+                        "Use a type that works with `pydantic.TypeAdapter`"
                     )
                 ) from e
 
+            merged_output_config = _merge_output_configs(output_config, transformed_output_format)
+        else:
+            merged_output_config = output_config
+
         def parser(response: BetaMessage) -> ParsedBetaMessage[ResponseFormatT]:
-            return parse_response(
+            return parse_beta_response(
                 response=response,
                 output_format=cast(
                     ResponseFormatT,
@@ -2808,9 +2862,9 @@ class AsyncMessages(AsyncAPIResource):
                     "container": container,
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
-                    "output_config": output_config,
+                    "output_config": merged_output_config,
                     "metadata": metadata,
-                    "output_format": transformed_output_format,
+                    "output_format": omit,
                     "service_tier": service_tier,
                     "stop_sequences": stop_sequences,
                     "stream": stream,
@@ -2970,6 +3024,9 @@ class AsyncMessages(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> BetaAsyncToolRunner[ResponseFormatT] | BetaAsyncStreamingToolRunner[ResponseFormatT]:
         """Create a Message stream"""
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
         if model in DEPRECATED_MODELS:
             warnings.warn(
                 f"The model '{model}' is deprecated and will reach end-of-life on {DEPRECATED_MODELS[model]}.\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.",
@@ -3073,6 +3130,9 @@ class AsyncMessages(AsyncAPIResource):
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> BetaAsyncMessageStreamManager[ResponseFormatT]:
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
         if model in DEPRECATED_MODELS:
             warnings.warn(
                 f"The model '{model}' is deprecated and will reach end-of-life on {DEPRECATED_MODELS[model]}.\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.",
@@ -3087,7 +3147,7 @@ class AsyncMessages(AsyncAPIResource):
             **(extra_headers or {}),
         }
 
-        transformed_output_format: Optional[BetaJSONOutputFormatParam] | NotGiven = NOT_GIVEN
+        transformed_output_format: BetaJSONOutputFormatParam | Omit = omit
 
         if is_dict(output_format):
             transformed_output_format = cast(BetaJSONOutputFormatParam, output_format)
@@ -3103,9 +3163,12 @@ class AsyncMessages(AsyncAPIResource):
                 raise TypeError(
                     (
                         "Could not generate JSON schema for the given `output_format` type. "
-                        "Use a type that works with `pydanitc.TypeAdapter`"
+                        "Use a type that works with `pydantic.TypeAdapter`"
                     )
                 ) from e
+
+        merged_output_config = _merge_output_configs(output_config, transformed_output_format)
+
         request = self._post(
             "/v1/messages?beta=true",
             body=maybe_transform(
@@ -3114,8 +3177,8 @@ class AsyncMessages(AsyncAPIResource):
                     "messages": messages,
                     "model": model,
                     "metadata": metadata,
-                    "output_config": output_config,
-                    "output_format": transformed_output_format,
+                    "output_config": merged_output_config,
+                    "output_format": omit,
                     "container": container,
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
@@ -3252,10 +3315,13 @@ class AsyncMessages(AsyncAPIResource):
 
           mcp_servers: MCP servers to be utilized in this request
 
-          output_config: Configuration options for the model's output. Controls aspects like how much
-              effort the model puts into its response.
+          output_config: Configuration options for the model's output, such as the output format.
 
-          output_format: A schema to specify Claude's output format in responses.
+          output_format: Deprecated: Use `output_config.format` instead. See
+              [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
+
+              A schema to specify Claude's output format in responses. This parameter will be
+              removed in a future release.
 
           system: System prompt.
 
@@ -3362,6 +3428,11 @@ class AsyncMessages(AsyncAPIResource):
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
+        _validate_output_config_conflict(output_config, output_format)
+        _warn_output_format_deprecated(output_format)
+
+        merged_output_config = _merge_output_configs(output_config, output_format)
+
         extra_headers = {
             **strip_not_given(
                 {
@@ -3381,8 +3452,8 @@ class AsyncMessages(AsyncAPIResource):
                     "model": model,
                     "context_management": context_management,
                     "mcp_servers": mcp_servers,
-                    "output_config": output_config,
-                    "output_format": output_format,
+                    "output_config": merged_output_config,
+                    "output_format": omit,
                     "system": system,
                     "thinking": thinking,
                     "tool_choice": tool_choice,
@@ -3404,6 +3475,9 @@ class MessagesWithRawResponse:
         self.create = _legacy_response.to_raw_response_wrapper(
             messages.create,
         )
+        self.parse = _legacy_response.to_raw_response_wrapper(
+            messages.parse,
+        )
         self.count_tokens = _legacy_response.to_raw_response_wrapper(
             messages.count_tokens,
         )
@@ -3420,6 +3494,9 @@ class AsyncMessagesWithRawResponse:
         self.create = _legacy_response.async_to_raw_response_wrapper(
             messages.create,
         )
+        self.parse = _legacy_response.async_to_raw_response_wrapper(
+            messages.parse,
+        )
         self.count_tokens = _legacy_response.async_to_raw_response_wrapper(
             messages.count_tokens,
         )
@@ -3466,3 +3543,37 @@ def validate_output_format(output_format: object) -> None:
         raise TypeError(
             "You tried to pass a `BaseModel` class to `beta.messages.create()`; You must use `beta.messages.parse()` instead"
         )
+
+
+def _validate_output_config_conflict(
+    output_config: BetaOutputConfigParam | Omit,
+    output_format: object,
+) -> None:
+    if is_given(output_format) and output_format is not None and is_given(output_config):
+        if "format" in output_config and output_config["format"] is not None:
+            raise AnthropicError(
+                "Both output_format and output_config.format were provided. "
+                "Please use only output_config.format (output_format is deprecated).",
+            )
+
+
+def _merge_output_configs(
+    output_config: BetaOutputConfigParam | Omit,
+    output_format: Optional[BetaJSONOutputFormatParam] | Omit,
+) -> BetaOutputConfigParam | Omit:
+    if is_given(output_format):
+        if is_given(output_config):
+            return {**output_config, "format": output_format}
+        else:
+            return {"format": output_format}
+    return output_config
+
+
+def _warn_output_format_deprecated(output_format: object) -> None:
+    """Emit deprecation warning if output_format is provided."""
+    if is_given(output_format) and output_format is not None:
+        warnings.warn(
+            "The 'output_format' parameter is deprecated. Please use 'output_config.format' instead.",
+            DeprecationWarning,
+            stacklevel=4,
+        )