From 33ab92466ebc826e764ec62da2df0b2dd3f172b3 Mon Sep 17 00:00:00 2001 From: markstuart-oai <323302876+markstuart-oai@users.noreply.github.com> Date: Tue, 27 Oct 2026 20:01:19 +0000 Subject: [PATCH] feat(api): add typed references to Realtime response input Castiron-Internal-PR: https://github.com/openai/openai-python-internal/pull/349 Castiron-Source-SHA: 35d1417de7d2de0a22bd04c6226c703ca62e9f4e Castiron-Public-Base-SHA: 1b37b9a85e857a7ada4db661bf867bf680290ccf --- .castiron.stats.yml | 10 +- api_reference/openapi.transformed.yml | 23 ++++ scripts/castiron/generated-files.json | 22 +++- src/openai/resources/realtime/api.md | 1 + src/openai/resources/realtime/realtime.py | 56 +++++++-- src/openai/types/realtime/__init__.py | 8 ++ ...nse_create_params_with_references_param.py | 112 ++++++++++++++++++ ...onse_create_event_with_references_param.py | 48 ++++++++ .../types/realtime/response_item_reference.py | 21 ++++ .../realtime/response_item_reference_param.py | 21 ++++ 10 files changed, 302 insertions(+), 20 deletions(-) create mode 100644 src/openai/types/realtime/realtime_response_create_params_with_references_param.py create mode 100644 src/openai/types/realtime/response_create_event_with_references_param.py create mode 100644 src/openai/types/realtime/response_item_reference.py create mode 100644 src/openai/types/realtime/response_item_reference_param.py diff --git a/.castiron.stats.yml b/.castiron.stats.yml index 2686e266bf..588087b0f6 100644 --- a/.castiron.stats.yml +++ b/.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 diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index 7ecd7eae4a..bb5fc58114 100644 --- a/api_reference/openapi.transformed.yml +++ b/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. diff --git a/scripts/castiron/generated-files.json b/scripts/castiron/generated-files.json index c4bbbd2ffe..8b5deb9f70 100644 --- a/scripts/castiron/generated-files.json +++ b/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" diff --git a/src/openai/resources/realtime/api.md b/src/openai/resources/realtime/api.md index b4874ea226..d224be4f4f 100644 --- a/src/openai/resources/realtime/api.md +++ b/src/openai/resources/realtime/api.md @@ -106,6 +106,7 @@ from openai.types.realtime import ( ResponseDoneEvent, ResponseFunctionCallArgumentsDeltaEvent, ResponseFunctionCallArgumentsDoneEvent, + ResponseItemReference, ResponseMcpCallArgumentsDelta, ResponseMcpCallArgumentsDone, ResponseMcpCallCompleted, diff --git a/src/openai/resources/realtime/realtime.py b/src/openai/resources/realtime/realtime.py index 27fc71a5ba..44a95eeb0e 100644 --- a/src/openai/resources/realtime/realtime.py +++ b/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}), ) ) diff --git a/src/openai/types/realtime/__init__.py b/src/openai/types/realtime/__init__.py index d3071864bd..706ff185b0 100644 --- a/src/openai/types/realtime/__init__.py +++ b/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, ) diff --git a/src/openai/types/realtime/realtime_response_create_params_with_references_param.py b/src/openai/types/realtime/realtime_response_create_params_with_references_param.py new file mode 100644 index 0000000000..690adedf87 --- /dev/null +++ b/src/openai/types/realtime/realtime_response_create_params_with_references_param.py @@ -0,0 +1,112 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List, Union, Iterable, Optional +from typing_extensions import Literal, TypeAlias, TypedDict + +from ..shared_params.metadata import Metadata +from .conversation_item_param import ConversationItemParam +from .realtime_reasoning_param import RealtimeReasoningParam +from .realtime_function_tool_param import RealtimeFunctionToolParam +from .response_item_reference_param import ResponseItemReferenceParam +from ..responses.tool_choice_options import ToolChoiceOptions +from ..responses.response_prompt_param import ResponsePromptParam +from ..responses.tool_choice_mcp_param import ToolChoiceMcpParam +from ..responses.tool_choice_function_param import ToolChoiceFunctionParam +from .realtime_response_create_mcp_tool_param import RealtimeResponseCreateMcpToolParam +from .realtime_response_create_audio_output_param import RealtimeResponseCreateAudioOutputParam + +__all__ = ["RealtimeResponseCreateParamsWithReferencesParam", "ToolChoice", "Tool"] + +ToolChoice: TypeAlias = Union[ToolChoiceOptions, ToolChoiceFunctionParam, ToolChoiceMcpParam] + +Tool: TypeAlias = Union[RealtimeFunctionToolParam, RealtimeResponseCreateMcpToolParam] + + +class RealtimeResponseCreateParamsWithReferencesParam(TypedDict, total=False): + """Create a new Realtime response with these parameters""" + + audio: RealtimeResponseCreateAudioOutputParam + """Configuration for audio input and output.""" + + conversation: Union[str, Literal["auto", "none"]] + """Controls which conversation the response is added to. + + Currently supports `auto` and `none`, with `auto` as the default value. The + `auto` value means that the contents of the response will be added to the + default conversation. Set this to `none` to create an out-of-band response which + will not add items to default conversation. + """ + + input: Iterable[Union[ConversationItemParam, ResponseItemReferenceParam]] + """Input items to include in the prompt for the model. + + Using this field creates a new context for this Response instead of using the + default conversation. An empty array `[]` will clear the context for this + Response. Note that this can include references to items that previously + appeared in the session using their id. + """ + + instructions: str + """The default system instructions (i.e. + + system message) prepended to model calls. This field allows the client to guide + the model on desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here are examples of + good responses") and on audio behavior (e.g. "talk quickly", "inject emotion + into your voice", "laugh frequently"). The instructions are not guaranteed to be + followed by the model, but they provide guidance to the model on the desired + behavior. Note that the server sets default instructions which will be used if + this field is not set and are visible in the `session.created` event at the + start of the session. + """ + + max_output_tokens: Union[int, Literal["inf"]] + """ + Maximum number of output tokens for a single assistant response, inclusive of + tool calls. Provide an integer between 1 and 4096 to limit output tokens, or + `inf` for the maximum available tokens for a given model. Defaults to `inf`. + """ + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + output_modalities: List[Literal["text", "audio"]] + """ + The set of modalities the model used to respond, currently the only possible + values are `[\"audio\"]`, `[\"text\"]`. Audio output always include a text + transcript. Setting the output to mode `text` will disable audio output from the + model. + """ + + parallel_tool_calls: bool + """Whether the model may call multiple tools in parallel. + + Only supported by reasoning Realtime models such as `gpt-realtime-2`. + """ + + prompt: Optional[ResponsePromptParam] + """ + Reference to a prompt template and its variables. + [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code). + """ + + reasoning: RealtimeReasoningParam + """Configuration for reasoning-capable Realtime models such as `gpt-realtime-2`.""" + + tool_choice: ToolChoice + """How the model chooses tools. + + Provide one of the string modes or force a specific function/MCP tool. + """ + + tools: Iterable[Tool] + """Tools available to the model.""" diff --git a/src/openai/types/realtime/response_create_event_with_references_param.py b/src/openai/types/realtime/response_create_event_with_references_param.py new file mode 100644 index 0000000000..f385fe991c --- /dev/null +++ b/src/openai/types/realtime/response_create_event_with_references_param.py @@ -0,0 +1,48 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +from .realtime_response_create_params_with_references_param import RealtimeResponseCreateParamsWithReferencesParam + +__all__ = ["ResponseCreateEventWithReferencesParam"] + + +class ResponseCreateEventWithReferencesParam(TypedDict, total=False): + """ + This event instructs the server to create a Response, which means triggering + model inference. When in Server VAD mode, the server will create Responses + automatically. + + A Response will include at least one Item, and may have two, in which case + the second will be a function call. These Items will be appended to the + conversation history by default. + + The server will respond with a `response.created` event, events for Items + and content created, and finally a `response.done` event to indicate the + Response is complete. + + The `response.create` event includes inference configuration like + `instructions` and `tools`. If these are set, they will override the Session's + configuration for this Response only. + + Responses can be created out-of-band of the default Conversation, meaning that they can + have arbitrary input, and it's possible to disable writing the output to the Conversation. + Only one Response can write to the default Conversation at a time, but otherwise multiple + Responses can be created in parallel. The `metadata` field is a good way to disambiguate + multiple simultaneous Responses. + + Clients can set `conversation` to `none` to create a Response that does not write to the default + Conversation. Arbitrary input can be provided with the `input` field, which is an array accepting + raw Items and references to existing Items. + """ + + type: Required[Literal["response.create"]] + """The event type, must be `response.create`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" + + response: RealtimeResponseCreateParamsWithReferencesParam + """Create a new Realtime response with these parameters""" diff --git a/src/openai/types/realtime/response_item_reference.py b/src/openai/types/realtime/response_item_reference.py new file mode 100644 index 0000000000..00259fa0c8 --- /dev/null +++ b/src/openai/types/realtime/response_item_reference.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseItemReference"] + + +class ResponseItemReference(BaseModel): + """ + 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. + """ + + id: str + """The ID of an existing item in the same Realtime session.""" + + type: Literal["item_reference"] + """The type of this item. Always `item_reference`.""" diff --git a/src/openai/types/realtime/response_item_reference_param.py b/src/openai/types/realtime/response_item_reference_param.py new file mode 100644 index 0000000000..ea23fc0745 --- /dev/null +++ b/src/openai/types/realtime/response_item_reference_param.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseItemReferenceParam"] + + +class ResponseItemReferenceParam(TypedDict, total=False): + """ + 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. + """ + + id: Required[str] + """The ID of an existing item in the same Realtime session.""" + + type: Required[Literal["item_reference"]] + """The type of this item. Always `item_reference`."""