feat(api): support response format updates and local output types

Castiron-Internal-PR: openai/openai-python-internal#365
Castiron-Source-SHA: 2d22a5018f49c135bb0ee85d0b8db74f1b52f5f3
Castiron-Public-Base-SHA: 68b962c

Author: markstuart-oai

.castiron.stats.yml

@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: e511c488-31b9-4833-baf5-cfb49bbba7ac
-openapi_spec_hash: d57efec7c76a156447c9ab739b446dc1
-openapi_transformed_spec_hash: b34c897c8cec867ec4ac8e22727c5975
-config_hash: 8da38e8d8f706786c2d8586691168746
-codegen_sha: e46410d5a9751f068b9afce57ecf25abda75de09
-codegen_hash: 33536449fa4898b45941d5fa4b5a958f88e2701a4b85fae21c372b75614198cd
+generation_id: 7b7feee1-6807-4c20-98e0-610aab05b2da
+openapi_spec_hash: 51b199ef7fd5542bc4910765f9becd60
+openapi_transformed_spec_hash: 73822d924c15a6ed58dcfe8f616bd4be
+config_hash: b707b209c892562880c415693d111ad6
+codegen_sha: e1054c07fb03a8025411f0ff6ee0a5ff17e09109
+codegen_hash: 73c66bd2bff47ee2bbd2d04a174184dec767ebe300a3bd41443938d914013ef0

api_reference/openapi.transformed.yml

@@ -65425,8 +65425,8 @@ components:
     ResponseConfigurationUpdate:
       type: object
       description: |
-        A configuration update that applies to subsequent responses until it is
-        replaced by another configuration update.
+        A configuration update for subsequent responses. Each setting stays in effect
+        until a later update replaces that setting.
       properties:
         id:
           type: string
@@ -65448,15 +65448,27 @@ components:
               description: |
                 The reasoning effort used for subsequent responses until another
                 configuration update replaces it.
+        text:
+          type: object
+          description: The text output configuration for subsequent responses.
+          properties:
+            format:
+              description: Use a JSON schema for structured output or text to return to plain text.
+              discriminator:
+                propertyName: type
+              anyOf:
+              - $ref: '#/components/schemas/ResponseFormatText'
+              - $ref: '#/components/schemas/TextResponseFormatJsonSchema'
+          required:
+          - format
       required:
       - id
       - type
     ResponseConfigurationUpdateItemParam:
       type: object
       description: |
-        An update to the conversation's response configuration. The configuration
-        remains in effect for subsequent responses until it is replaced by another
-        configuration update.
+        An update to the conversation's response configuration. Supply reasoning,
+        text, or both. Each setting stays in effect until a later update replaces it.
       properties:
         id:
           anyOf:
@@ -65480,6 +65492,19 @@ components:
               description: |
                 The reasoning effort to use for subsequent responses until another
                 configuration update replaces it.
+        text:
+          type: object
+          description: The text output configuration for subsequent responses.
+          properties:
+            format:
+              description: Use a JSON schema for structured output or text to return to plain text.
+              discriminator:
+                propertyName: type
+              anyOf:
+              - $ref: '#/components/schemas/ResponseFormatText'
+              - $ref: '#/components/schemas/TextResponseFormatJsonSchema'
+          required:
+          - format
       required:
       - type
     ResponseContentPartAddedEvent:
@@ -71066,13 +71091,13 @@ components:
         Setting to `{ "type": "json_object" }` enables the older JSON mode, which
         ensures the message the model generates is valid JSON. Using `json_schema`
         is preferred for models that support it.
+      discriminator:
+        propertyName: type
       anyOf:
       - $ref: '#/components/schemas/ResponseFormatText'
       - $ref: '#/components/schemas/TextResponseFormatJsonSchema'
         x-openai-ruby-json-schema-input: true
       - $ref: '#/components/schemas/ResponseFormatJsonObject'
-      discriminator:
-        propertyName: type
     TextResponseFormatJsonSchema:
       x-openai-structured-output: json_schema_default_strict
       type: object
@@ -99478,12 +99503,12 @@ components:
         Setting to `{ "type": "json_object" }` enables the older JSON mode, which
         ensures the message the model generates is valid JSON. Using `json_schema`
         is preferred for models that support it.
+      discriminator:
+        propertyName: type
       anyOf:
       - $ref: '#/components/schemas/BetaResponseFormatText'
       - $ref: '#/components/schemas/BetaTextResponseFormatJsonSchema'
       - $ref: '#/components/schemas/BetaResponseFormatJsonObject'
-      discriminator:
-        propertyName: type
     BetaResponseFormatJsonObject:
       type: object
       title: JSON object
@@ -102546,9 +102571,8 @@ components:
     BetaResponseConfigurationUpdateItemParam:
       type: object
       description: |
-        An update to the conversation's response configuration. The configuration
-        remains in effect for subsequent responses until it is replaced by another
-        configuration update.
+        An update to the conversation's response configuration. Supply reasoning,
+        text, or both. Each setting stays in effect until a later update replaces it.
       properties:
         agent:
           anyOf:
@@ -102577,6 +102601,19 @@ components:
               description: |
                 The reasoning effort to use for subsequent responses until another
                 configuration update replaces it.
+        text:
+          type: object
+          description: The text output configuration for subsequent responses.
+          properties:
+            format:
+              description: Use a JSON schema for structured output or text to return to plain text.
+              discriminator:
+                propertyName: type
+              anyOf:
+              - $ref: '#/components/schemas/BetaResponseFormatText'
+              - $ref: '#/components/schemas/BetaTextResponseFormatJsonSchema'
+          required:
+          - format
       required:
       - type
     BetaAdditionalToolsItemParam:
@@ -105303,8 +105340,8 @@ components:
     BetaResponseConfigurationUpdate:
       type: object
       description: |
-        A configuration update that applies to subsequent responses until it is
-        replaced by another configuration update.
+        A configuration update for subsequent responses. Each setting stays in effect
+        until a later update replaces that setting.
       properties:
         agent:
           $ref: '#/components/schemas/BetaAgentTag'
@@ -105329,6 +105366,19 @@ components:
               description: |
                 The reasoning effort used for subsequent responses until another
                 configuration update replaces it.
+        text:
+          type: object
+          description: The text output configuration for subsequent responses.
+          properties:
+            format:
+              description: Use a JSON schema for structured output or text to return to plain text.
+              discriminator:
+                propertyName: type
+              anyOf:
+              - $ref: '#/components/schemas/BetaResponseFormatText'
+              - $ref: '#/components/schemas/BetaTextResponseFormatJsonSchema'
+          required:
+          - format
       required:
       - id
       - type

helpers.md

@@ -63,6 +63,41 @@ output into a Pydantic model. The same parsing rules apply to
 Use `output_parsed` for the structured result and retain `output` when replaying
 messages so their phases are preserved.
 
+When the output schema changes during a conversation, pass `parse_as` to
+`client.responses.parse()` to select the local output type. For example, if a
+previous turn switched to `DetailedAnswer`, continue with this call.
+
+```py
+response = client.responses.parse(
+    model=model,
+    previous_response_id=previous.id,
+    input="Explain the evidence.",
+    parse_as=DetailedAnswer,
+)
+```
+
+The SDK parses the answer as `DetailedAnswer`. The request inherits its output
+format from the previous turn. If you also pass `text_format=ShortAnswer`,
+the request sends that class's schema as the top-level format. Pass
+`parse_as=None` to read unparsed text when the previous turn reset the format.
+You can also pass a format update directly in `input`. For example, given a
+JSON schema format named `detailed_format`:
+
+```py
+response = client.responses.parse(
+    model=model,
+    input=[
+        {"type": "configuration_update", "text": {"format": detailed_format}},
+        {"role": "user", "content": "Explain the evidence."},
+    ],
+    parse_as=DetailedAnswer,
+)
+```
+
+To switch back to plain text, send `{"type": "text"}` as the update's format.
+A reasoning-only update keeps the active format. Retrieved configuration items
+include `item.text.format` when the input supplied it.
+
 ## Auto-parsing function tool calls
 
 The `.parse()` method will also automatically parse `function` tool calls if:

scripts/castiron/generated-files.json

@@ -379,7 +379,7 @@
     },
     "src/openai/resources/beta/responses/responses.py": {
       "mode": "100644",
-      "sha256": "043ff25a6a7f078bb0b11f6368ee136d7f3bb371c65360c8eb608afaf86de023"
+      "sha256": "effa8db6d9a676f1f264f0b6acb3252d8dcd5f75db251bfd8b5d45ea49f0f533"
     },
     "src/openai/resources/beta/threads/__init__.py": {
       "mode": "100644",
@@ -559,19 +559,19 @@
     },
     "src/openai/resources/live/forks.py": {
       "mode": "100644",
-      "sha256": "eda42fc4ed92675d23eb62905f154a5b115567c158dd4b0fe5cf3d0824e2bd9d"
+      "sha256": "7fe78c144680df54628773683f9dd5b06c5241d0218b4f4c745890ddae225c92"
     },
     "src/openai/resources/live/live.py": {
       "mode": "100644",
-      "sha256": "a42b9133f64a4421eafbb1d0d10a9cddcefdc872270518f7bdf61ce192265985"
+      "sha256": "86be3e074d011a750fa52a4d216a7e87ee5c8e82f6ccec00102c03a539199882"
     },
     "src/openai/resources/live/sessions.py": {
       "mode": "100644",
       "sha256": "9ba2d59d9c7498c96ac2e7e48660c91468e0eeb5df881e77f123ee37985c3dfd"
     },
     "src/openai/resources/live/sideband.py": {
       "mode": "100644",
-      "sha256": "7ed377e577ce3b229692bd112059914700741cbff042a7a92cc2a581ec2ac1f8"
+      "sha256": "d19149c042afcd8c8efca3d7794092acc1c2f76a4bcb4f6f620547314a78e59b"
     },
     "src/openai/resources/models.py": {
       "mode": "100644",
@@ -599,7 +599,7 @@
     },
     "src/openai/resources/realtime/realtime.py": {
       "mode": "100644",
-      "sha256": "563d955afa8c0b023f4fcb353565db0b4348394f36e6a02659db6c2885286149"
+      "sha256": "d45ef5f2d1e25e6f8761592a9fb5739d7a344c6e64a4e7a4006418c16f05a540"
     },
     "src/openai/resources/realtime/translations/__init__.py": {
       "mode": "100644",
@@ -611,15 +611,15 @@
     },
     "src/openai/resources/realtime/translations/translations.py": {
       "mode": "100644",
-      "sha256": "8f45807c74c477a1d13df9979c6274a089c380004b943fcb6d9342b1a7ac3ef1"
+      "sha256": "4a6f072cea78d5afab3fe1c995b939ff8c79f449665346c729abb5c516c53f21"
     },
     "src/openai/resources/responses/__init__.py": {
       "mode": "100644",
       "sha256": "70034ef169af2cd1991aaaed26fb565d2a2d5a5b6b14309a72ab1f483f0aba15"
     },
     "src/openai/resources/responses/api.md": {
       "mode": "100644",
-      "sha256": "e7815b1278aa2780bb885ac5a249fe00859dff67d3899b708d25d2968e734785"
+      "sha256": "b635f37005fb7126cc69a7b69e3f14a9df135d9523271cc4407b1ffcb9bd5c8c"
     },
     "src/openai/resources/responses/input_items.py": {
       "mode": "100644",
@@ -631,7 +631,7 @@
     },
     "src/openai/resources/responses/responses.py": {
       "mode": "100644",
-      "sha256": "6e536e48d77d9ed583bd0c86a4f189b664e8636ae46a52a1c80fac28ffc3b4ec"
+      "sha256": "f844db6ec37b49de883ab2c507570b94c29e8c2609ee93cf45c0aec19fd671d3"
     },
     "src/openai/resources/safety/__init__.py": {
       "mode": "100644",
@@ -2523,15 +2523,15 @@
     },
     "src/openai/types/beta/beta_response_configuration_update_item.py": {
       "mode": "100644",
-      "sha256": "4bd97e32e710edbd688bf8c6eac0dd8f24d1d0a64da60efda522ffefa0790046"
+      "sha256": "eebab46ab26a7650a94cf353d3b98c86fc12378284a9431cd4379808515ba6b0"
     },
     "src/openai/types/beta/beta_response_configuration_update_item_param.py": {
       "mode": "100644",
-      "sha256": "eb06f107b27ef1fa3a9266bfaf8921b68384faf7c0dd0d300e554767bb7aed30"
+      "sha256": "c10511a06c2bd67530ce2f6ab2e94b63e49602e4e29df8cfb64e4bb73359e3a9"
     },
     "src/openai/types/beta/beta_response_configuration_update_item_param_param.py": {
       "mode": "100644",
-      "sha256": "3c9bcd2d7e730b102b0674424e56cbd35e6bed0664a58acc1830466eea28d2be"
+      "sha256": "269015eac1b4dd3a8bfbd1053218e64c9a2fd3cac4b50db961089f3813c6bbd0"
     },
     "src/openai/types/beta/beta_response_container_reference.py": {
       "mode": "100644",
@@ -6167,15 +6167,15 @@
     },
     "src/openai/types/responses/response_configuration_update_item.py": {
       "mode": "100644",
-      "sha256": "4d07aca0f5dbb6f87f1db31fc16dbba2e4a49d0670edbd46256907066605a703"
+      "sha256": "89a39d84322be94f3805145e1ca70bae0c2b0500f89102ea93918700ecc65a02"
     },
     "src/openai/types/responses/response_configuration_update_item_param.py": {
       "mode": "100644",
-      "sha256": "c8eb1b18f489c4d820bc17c10e505e97a4da8059592e903882aae5ed3ca919ad"
+      "sha256": "fb7a2cb3b72d2a5dd73fc78ad6194bce51eb4e1b805d9ccc85c2725e3c0bab3f"
     },
     "src/openai/types/responses/response_configuration_update_item_param_param.py": {
       "mode": "100644",
-      "sha256": "8e177dbfa309934a8aedbc5bd278b48bddfa3365a42cfb661ead8677aa924a9b"
+      "sha256": "d7e43648f155a90a35d2f57d31e8f8481c463ada28805dd810d17db00304ce23"
     },
     "src/openai/types/responses/response_container_reference.py": {
       "mode": "100644",