feat(api): add typed references to Realtime response input

Castiron-Internal-PR: openai/openai-python-internal#349
Castiron-Source-SHA: 35d1417de7d2de0a22bd04c6226c703ca62e9f4e
Castiron-Public-Base-SHA: 1b37b9a

Author: markstuart-oai

.castiron.stats.yml

@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: 3979ac4c-7176-4e6d-9fde-1b9fa94dca0e
+generation_id: 66c33b8f-b104-40d5-882f-9e511b4c0f84
 openapi_spec_hash: 2c78c708cab402e8904f555026c78020
-openapi_transformed_spec_hash: e513b495f24d8119b952521ffc783d86
-config_hash: e8e4d0a0f7d89bb89f18f5ed789c0ac6
-codegen_sha: 47c0bc8105b4986bef09e3e9e43ab8a26cd882c9
-codegen_hash: a0d517f4d93e3430ed6dbcf2dfb9aeba57e563f1b7348a093d149c3d6c20ea77
+openapi_transformed_spec_hash: 078e0a8b0fbf06b663d2a310567695ce
+config_hash: e901e1843aa6ac7c3816ad65338289ac
+codegen_sha: 3f98cde2ae19fc412a1425b432a34c789a42f3cc
+codegen_hash: 1408cfa777ed0a695f6a9a7585f15457a30078e5a4518b18e7589f59e81153a2

api_reference/openapi.transformed.yml

@@ -58291,6 +58291,7 @@ components:
       - $ref: '#/components/schemas/RealtimeMCPListTools'
       - $ref: '#/components/schemas/RealtimeMCPToolCall'
       - $ref: '#/components/schemas/RealtimeMCPApprovalRequest'
+      - $ref: '#/components/schemas/RealtimeResponseItemReference'
       discriminator:
         propertyName: type
     RealtimeConversationItemFunctionCall:
@@ -111167,6 +111168,28 @@ components:
       - type
       - server_label
       - name
+    RealtimeResponseItemReference:
+      type: object
+      description: |
+        Reference an existing item in this Realtime session as response.create input.
+        Item references are only accepted in the response input array, not as new
+        conversation items.
+      properties:
+        type:
+          type: string
+          enum:
+          - item_reference
+          x-stainless-const: true
+          description: The type of this item. Always `item_reference`.
+        id:
+          type: string
+          minLength: 1
+          maxLength: 32
+          pattern: ^[a-zA-Z0-9_-]+$
+          description: The ID of an existing item in the same Realtime session.
+      required:
+      - type
+      - id
   responses:
     TooManyRequests:
       description: The request was rejected because a rate limit was exceeded.

scripts/castiron/generated-files.json

@@ -583,7 +583,7 @@
     },
     "src/openai/resources/realtime/api.md": {
       "mode": "100644",
-      "sha256": "f977c3b6d8ac7161eeb7025492ac820fc4a17465a54dbec223359b8d72ec6346"
+      "sha256": "eead2cb85c18f8618053945184022e68166bee967e60078cc0c8b3ef8be3fc34"
     },
     "src/openai/resources/realtime/calls.py": {
       "mode": "100644",
@@ -595,7 +595,7 @@
     },
     "src/openai/resources/realtime/realtime.py": {
       "mode": "100644",
-      "sha256": "0285ac5edb9b8b17f296b2d513068cb35c3413895e35424221765cc4a15c8592"
+      "sha256": "0bfb331a5a3b95022b8d93532b05f906279d38f52b7dd1d3d455207039b6847f"
     },
     "src/openai/resources/realtime/translations/__init__.py": {
       "mode": "100644",
@@ -5119,7 +5119,7 @@
     },
     "src/openai/types/realtime/__init__.py": {
       "mode": "100644",
-      "sha256": "261c144fdf20c27eb36a7d231089412a837f0e4c515fdc32a25cd7e856ab166e"
+      "sha256": "9666db4186bc43fb9172e062757c6fd9f80a602243e9bb887453843ae705e187"
     },
     "src/openai/types/realtime/audio_transcription.py": {
       "mode": "100644",
@@ -5521,6 +5521,10 @@
       "mode": "100644",
       "sha256": "d8b30f5cf2b34637790ca055cf95e50391346dcf72e5ff009f6b44afc4bcb547"
     },
+    "src/openai/types/realtime/realtime_response_create_params_with_references_param.py": {
+      "mode": "100644",
+      "sha256": "e497ef7761e669350ca27b7083e6435c41f4864b0bd5bbfd5c3c204b35d2f883"
+    },
     "src/openai/types/realtime/realtime_response_status.py": {
       "mode": "100644",
       "sha256": "b00b75118e8e7d2c42fcf4fbdb15e4018c572f1c371af7d86b89015dc4c08156"
@@ -5761,6 +5765,10 @@
       "mode": "100644",
       "sha256": "5ca62450179ad1415d9c4057d8aa8850463a346d7541c1f5cf4cd1cc4373ab03"
     },
+    "src/openai/types/realtime/response_create_event_with_references_param.py": {
+      "mode": "100644",
+      "sha256": "447311a4c3fcc158d048b7a661f8c3839a889a05f7bde833f35c883ea1a8e1c1"
+    },
     "src/openai/types/realtime/response_created_event.py": {
       "mode": "100644",
       "sha256": "36bf360cb5d65a600e0580a6cf6887a229a03607d96218f400c4903b49ea5728"
@@ -5777,6 +5785,14 @@
       "mode": "100644",
       "sha256": "75586fb8816948a71e001c78c0a8f3ac2ab821a878f2f9b58a4f137867ec05cb"
     },
+    "src/openai/types/realtime/response_item_reference.py": {
+      "mode": "100644",
+      "sha256": "bbd4ddcfc8a99940f161eed062552d3f7e70f40042824948bad7ab80022ebc57"
+    },
+    "src/openai/types/realtime/response_item_reference_param.py": {
+      "mode": "100644",
+      "sha256": "06d0f4594d15309a190f72098cfb0970a49ca8da14214c2ca8fbc27ab9e142be"
+    },
     "src/openai/types/realtime/response_mcp_call_arguments_delta.py": {
       "mode": "100644",
       "sha256": "59af6b127685ea447c94ee2577aab8509adf0fa6f74efa45706aabbebc0b41d4"

src/openai/resources/realtime/api.md

@@ -106,6 +106,7 @@ from openai.types.realtime import (
     ResponseDoneEvent,
     ResponseFunctionCallArgumentsDeltaEvent,
     ResponseFunctionCallArgumentsDoneEvent,
+    ResponseItemReference,
     ResponseMcpCallArgumentsDelta,
     ResponseMcpCallArgumentsDone,
     ResponseMcpCallCompleted,

src/openai/resources/realtime/realtime.py

@@ -62,6 +62,10 @@
 from ...types.realtime.conversation_item_param import ConversationItemParam
 from ...types.realtime.realtime_client_event_param import RealtimeClientEventParam
 from ...types.realtime.realtime_response_create_params_param import RealtimeResponseCreateParamsParam
+from ...types.realtime.response_create_event_with_references_param import ResponseCreateEventWithReferencesParam
+from ...types.realtime.realtime_response_create_params_with_references_param import (
+    RealtimeResponseCreateParamsWithReferencesParam,
+)
 
 if TYPE_CHECKING:
     from websockets.sync.client import ClientConnection as WebSocketConnection
@@ -395,11 +399,17 @@ async def recv_bytes(self) -> bytes:
                 self._reconnect_attempt = 0
         return message
 
-    async def send(self, event: RealtimeClientEvent | RealtimeClientEventParam) -> None:
+    async def send(
+        self, event: RealtimeClientEvent | Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam]
+    ) -> None:
         data = (
             event.to_json(use_api_names=True, exclude_unset=True)
             if isinstance(event, BaseModel)
-            else json.dumps(await async_maybe_transform(event, RealtimeClientEventParam))
+            else json.dumps(
+                await async_maybe_transform(
+                    event, Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam]
+                )
+            )
         )
         if self._is_reconnecting:
             self._send_queue.enqueue(data)
@@ -546,7 +556,9 @@ def __init__(
         self.__send_queue = SendQueue(max_bytes=max_queue_size)
         self.__event_handler_registry = EventHandlerRegistry(use_lock=False)
 
-    def send(self, event: RealtimeClientEvent | RealtimeClientEventParam) -> None:
+    def send(
+        self, event: RealtimeClientEvent | Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam]
+    ) -> None:
         """Queue a message to be sent when the connection is established.
 
         This can be called before entering the context manager. Queued messages
@@ -555,7 +567,9 @@ def send(self, event: RealtimeClientEvent | RealtimeClientEventParam) -> None:
         data = (
             event.to_json(use_api_names=True, exclude_unset=True)
             if isinstance(event, BaseModel)
-            else json.dumps(maybe_transform(event, RealtimeClientEventParam))
+            else json.dumps(
+                maybe_transform(event, Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam])
+            )
         )
         self.__send_queue.enqueue(data)
 
@@ -840,11 +854,15 @@ def recv_bytes(self) -> bytes:
                 self._reconnect_attempt = 0
         return message
 
-    def send(self, event: RealtimeClientEvent | RealtimeClientEventParam) -> None:
+    def send(
+        self, event: RealtimeClientEvent | Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam]
+    ) -> None:
         data = (
             event.to_json(use_api_names=True, exclude_unset=True)
             if isinstance(event, BaseModel)
-            else json.dumps(maybe_transform(event, RealtimeClientEventParam))
+            else json.dumps(
+                maybe_transform(event, Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam])
+            )
         )
         if self._is_reconnecting:
             self._send_queue.enqueue(data)
@@ -985,7 +1003,9 @@ def __init__(
         self.__send_queue = SendQueue(max_bytes=max_queue_size)
         self.__event_handler_registry = EventHandlerRegistry(use_lock=True)
 
-    def send(self, event: RealtimeClientEvent | RealtimeClientEventParam) -> None:
+    def send(
+        self, event: RealtimeClientEvent | Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam]
+    ) -> None:
         """Queue a message to be sent when the connection is established.
 
         This can be called before entering the context manager. Queued messages
@@ -994,7 +1014,9 @@ def send(self, event: RealtimeClientEvent | RealtimeClientEventParam) -> None:
         data = (
             event.to_json(use_api_names=True, exclude_unset=True)
             if isinstance(event, BaseModel)
-            else json.dumps(maybe_transform(event, RealtimeClientEventParam))
+            else json.dumps(
+                maybe_transform(event, Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam])
+            )
         )
         self.__send_queue.enqueue(data)
 
@@ -1206,7 +1228,13 @@ def update(self, *, session: session_update_event_param.Session, event_id: str |
 
 
 class RealtimeResponseResource(BaseRealtimeConnectionResource):
-    def create(self, *, event_id: str | Omit = omit, response: RealtimeResponseCreateParamsParam | Omit = omit) -> None:
+    def create(
+        self,
+        *,
+        event_id: str | Omit = omit,
+        response: Union[RealtimeResponseCreateParamsParam, RealtimeResponseCreateParamsWithReferencesParam]
+        | Omit = omit,
+    ) -> None:
         """
         This event instructs the server to create a Response, which means triggering
         model inference. When in Server VAD mode, the server will create Responses
@@ -1236,7 +1264,7 @@ def create(self, *, event_id: str | Omit = omit, response: RealtimeResponseCreat
         """
         self._connection.send(
             cast(
-                RealtimeClientEventParam,
+                Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam],
                 strip_not_given({"type": "response.create", "event_id": event_id, "response": response}),
             )
         )
@@ -1450,7 +1478,11 @@ async def update(self, *, session: session_update_event_param.Session, event_id:
 
 class AsyncRealtimeResponseResource(BaseAsyncRealtimeConnectionResource):
     async def create(
-        self, *, event_id: str | Omit = omit, response: RealtimeResponseCreateParamsParam | Omit = omit
+        self,
+        *,
+        event_id: str | Omit = omit,
+        response: Union[RealtimeResponseCreateParamsParam, RealtimeResponseCreateParamsWithReferencesParam]
+        | Omit = omit,
     ) -> None:
         """
         This event instructs the server to create a Response, which means triggering
@@ -1481,7 +1513,7 @@ async def create(
         """
         await self._connection.send(
             cast(
-                RealtimeClientEventParam,
+                Union[RealtimeClientEventParam, ResponseCreateEventWithReferencesParam],
                 strip_not_given({"type": "response.create", "event_id": event_id, "response": response}),
             )
         )

src/openai/types/realtime/__init__.py

@@ -38,6 +38,7 @@
 from .realtime_mcp_list_tools import RealtimeMcpListTools as RealtimeMcpListTools
 from .realtime_response_usage import RealtimeResponseUsage as RealtimeResponseUsage
 from .realtime_tracing_config import RealtimeTracingConfig as RealtimeTracingConfig
+from .response_item_reference import ResponseItemReference as ResponseItemReference
 from .mcp_list_tools_completed import McpListToolsCompleted as McpListToolsCompleted
 from .realtime_reasoning_param import RealtimeReasoningParam as RealtimeReasoningParam
 from .realtime_response_status import RealtimeResponseStatus as RealtimeResponseStatus
@@ -75,6 +76,7 @@
 from .realtime_mcp_approval_request import RealtimeMcpApprovalRequest as RealtimeMcpApprovalRequest
 from .realtime_mcp_list_tools_param import RealtimeMcpListToolsParam as RealtimeMcpListToolsParam
 from .realtime_tracing_config_param import RealtimeTracingConfigParam as RealtimeTracingConfigParam
+from .response_item_reference_param import ResponseItemReferenceParam as ResponseItemReferenceParam
 from .response_mcp_call_in_progress import ResponseMcpCallInProgress as ResponseMcpCallInProgress
 from .conversation_item_create_event import ConversationItemCreateEvent as ConversationItemCreateEvent
 from .conversation_item_delete_event import ConversationItemDeleteEvent as ConversationItemDeleteEvent
@@ -199,6 +201,9 @@
 from .realtime_translation_session_update_request import (
     RealtimeTranslationSessionUpdateRequest as RealtimeTranslationSessionUpdateRequest,
 )
+from .response_create_event_with_references_param import (
+    ResponseCreateEventWithReferencesParam as ResponseCreateEventWithReferencesParam,
+)
 from .response_function_call_arguments_done_event import (
     ResponseFunctionCallArgumentsDoneEvent as ResponseFunctionCallArgumentsDoneEvent,
 )
@@ -277,6 +282,9 @@
 from .realtime_conversation_item_function_call_output_param import (
     RealtimeConversationItemFunctionCallOutputParam as RealtimeConversationItemFunctionCallOutputParam,
 )
+from .realtime_response_create_params_with_references_param import (
+    RealtimeResponseCreateParamsWithReferencesParam as RealtimeResponseCreateParamsWithReferencesParam,
+)
 from .conversation_item_input_audio_transcription_delta_event import (
     ConversationItemInputAudioTranscriptionDeltaEvent as ConversationItemInputAudioTranscriptionDeltaEvent,
 )