refactor: openai:responses message construction logic

This refactors openai:responses message encoding so that when multiple
pieces of content may be organized into the same message (eg multiple
text pieces in one user message), they will be combined rather than
emitting separate messages for each content piece.

Due to limitations in the api design, this mostly applies to user
messages rather than assistant messages.

Author: teamdandelion

python/mirascope/llm/clients/openai/responses/_utils/encode.py

@@ -4,24 +4,24 @@
 from typing import TypedDict, cast
 
 from openai import NotGiven
-from openai.types import responses as openai_types
-from openai.types.responses import response_create_params
-from openai.types.responses.easy_input_message_param import EasyInputMessageParam
-from openai.types.responses.function_tool_param import FunctionToolParam
-from openai.types.responses.response_format_text_json_schema_config_param import (
+from openai.types.responses import (
+    FunctionToolParam,
     ResponseFormatTextJSONSchemaConfigParam,
-)
-from openai.types.responses.response_function_tool_call_param import (
     ResponseFunctionToolCallParam,
+    ResponseInputContentParam,
+    ResponseInputItemParam,
+    ResponseInputParam,
+    ResponseInputTextParam,
+    ResponseTextConfigParam,
+    ToolChoiceAllowedParam,
+    ToolChoiceFunctionParam,
+    response_create_params,
 )
+from openai.types.responses.easy_input_message_param import EasyInputMessageParam
 from openai.types.responses.response_input_param import (
     FunctionCallOutput,
-    ResponseInputItemParam,
-    ResponseInputParam,
+    Message as ResponseInputMessageParam,
 )
-from openai.types.responses.response_text_config_param import ResponseTextConfigParam
-from openai.types.responses.tool_choice_allowed_param import ToolChoiceAllowedParam
-from openai.types.responses.tool_choice_function_param import ToolChoiceFunctionParam
 from openai.types.shared_params import Reasoning
 from openai.types.shared_params.response_format_json_object import (
     ResponseFormatJSONObject,
@@ -34,7 +34,7 @@
     _utils as _formatting_utils,
     resolve_format,
 )
-from .....messages import Message
+from .....messages import AssistantMessage, Message, UserMessage
 from .....tools import FORMAT_TOOL_NAME, BaseToolkit, ToolSchema
 from ....base import Params, _utils as _base_utils
 from ...shared import _utils as _shared_utils
@@ -46,7 +46,7 @@ class ResponseCreateKwargs(TypedDict, total=False):
     """Kwargs to the OpenAI `client.responses.create` method."""
 
     model: ResponsesModel
-    input: str | openai_types.ResponseInputParam
+    input: str | ResponseInputParam
     instructions: str
     temperature: float
     max_output_tokens: int
@@ -57,6 +57,88 @@ class ResponseCreateKwargs(TypedDict, total=False):
     reasoning: Reasoning | NotGiven
 
 
+def _encode_user_message(
+    message: UserMessage,
+) -> ResponseInputParam:
+    current_content: list[ResponseInputContentParam] = []
+    result: ResponseInputParam = []
+
+    def flush_message_content() -> None:
+        nonlocal current_content
+        if current_content:
+            result.append(
+                ResponseInputMessageParam(
+                    content=current_content, role="user", type="message"
+                )
+            )
+            current_content = []
+
+    for part in message.content:
+        if part.type == "text":
+            current_content.append(
+                ResponseInputTextParam(text=part.text, type="input_text")
+            )
+        elif part.type == "tool_output":
+            flush_message_content()
+            result.append(
+                FunctionCallOutput(
+                    call_id=part.id,
+                    output=str(part.value),
+                    type="function_call_output",
+                )
+            )
+        else:
+            raise NotImplementedError(
+                f"Unsupported user content part type: {part.type}"
+            )
+    flush_message_content()
+
+    return result
+
+
+def _encode_assistant_message(
+    message: AssistantMessage, encode_thoughts: bool
+) -> ResponseInputParam:
+    result: ResponseInputParam = []
+
+    # Note: OpenAI does not provide any way to encode multiplie pieces of assistant-generated
+    # text as adjacent content within the same Message, except as part of
+    # ResponseOutputMessageParam which requires OpenAI-provided `id` and `status` on the message,
+    # and `annotations` and `logprobs` on the output text.
+    # Rather than generating a fake or nonexistent fields and triggering potentially undefined
+    # server-side behavior, we use `EasyInputMessageParam` for assistant generated text,
+    # with the caveat that assistant messages containing multiple text parts will be encoded
+    # as though they are separate messages.
+    # (It would seem as though the `Message` class in `response_input_param.py` would be suitable,
+    # especially as it supports the "assistant" role; however attempting to use it triggers a server
+    # error when text of type input_text is passed as part of an assistant message.)
+    for part in message.content:
+        if part.type == "text":
+            result.append(EasyInputMessageParam(content=part.text, role="assistant"))
+        elif part.type == "thought":
+            if encode_thoughts:
+                result.append(
+                    EasyInputMessageParam(
+                        content="**Thinking:** " + part.thought, role="assistant"
+                    )
+                )
+        elif part.type == "tool_call":
+            result.append(
+                ResponseFunctionToolCallParam(
+                    call_id=part.id,
+                    name=part.name,
+                    arguments=part.args,
+                    type="function_call",
+                )
+            )
+        else:
+            raise NotImplementedError(
+                f"Unsupported assistant content part type: {part.type}"
+            )
+
+    return result
+
+
 def _encode_message(
     message: Message, model_id: OpenAIResponsesModelId, encode_thoughts: bool
 ) -> ResponseInputParam:
@@ -81,39 +163,10 @@ def _encode_message(
     ):
         return cast(ResponseInputParam, message.raw_message)
 
-    result: ResponseInputParam = []
-
-    for part in message.content:
-        if part.type == "text":
-            result.append(EasyInputMessageParam(role=message.role, content=part.text))
-        elif part.type == "tool_call":
-            result.append(
-                ResponseFunctionToolCallParam(
-                    call_id=part.id,
-                    name=part.name,
-                    arguments=part.args,
-                    type="function_call",
-                )
-            )
-        elif part.type == "tool_output":
-            result.append(
-                FunctionCallOutput(
-                    call_id=part.id,
-                    output=str(part.value),
-                    type="function_call_output",
-                )
-            )
-        elif part.type == "thought":
-            if encode_thoughts:
-                result.append(
-                    EasyInputMessageParam(
-                        role=message.role, content="**Thinking:** " + part.thought
-                    )
-                )
-        else:
-            raise NotImplementedError(f"Unsupported content part type: {part.type}")
-
-    return result
+    if message.role == "assistant":
+        return _encode_assistant_message(message, encode_thoughts)
+    else:
+        return _encode_user_message(message)
 
 
 def _convert_tool_to_function_tool_param(tool: ToolSchema) -> FunctionToolParam:

python/tests/e2e/conftest.py

@@ -90,6 +90,7 @@ def vcr_config() -> VCRConfig:
             "x-api-key",  # Anthropic API keys
             "x-goog-api-key",  # Google/Gemini API keys
             "anthropic-organization-id",  # Anthropic org identifiers
+            "cookie",
         ],
         "filter_post_data_parameters": [],
     }

python/tests/e2e/input/cassettes/test_call_with_image_content/openai_responses_gpt_4o.yaml

@@ -259,19 +259,19 @@ interactions:
       access-control-allow-origin:
       - '*'
       age:
-      - '73020'
+      - '11350'
       cache-control:
       - max-age=31536000
       content-length:
       - '13444'
       content-type:
       - image/png
       date:
-      - Mon, 20 Oct 2025 06:12:10 GMT
+      - Tue, 21 Oct 2025 18:53:57 GMT
       etag:
       - '"3484-640857429fa00"'
       expires:
-      - Tue, 20 Oct 2026 06:12:10 GMT
+      - Wed, 21 Oct 2026 18:53:57 GMT
       last-modified:
       - Mon, 06 Oct 2025 23:03:04 GMT
       nel:
@@ -281,30 +281,30 @@ interactions:
       - '{ "group": "wm_nel", "max_age": 604800, "endpoints": [{ "url": "https://intake-logging.wikimedia.org/v1/events?stream=w3c.reportingapi.network_error&schema_uri=/w3c/reportingapi/network_error/1.0.0"
         }] }'
       server:
-      - mw-web.codfw.main-669ddffffc-bfhxz
+      - ATS/9.2.11
       server-timing:
-      - cache;desc="hit-front", host;desc="cp4039"
+      - cache;desc="hit-front", host;desc="cp4042"
       set-cookie:
       - WMF-Last-Access=21-Oct-2025;Path=/;HttpOnly;secure;Expires=Sat, 22 Nov 2025
-        00:00:00 GMT
+        12:00:00 GMT
       - WMF-Last-Access-Global=21-Oct-2025;Path=/;Domain=.wikipedia.org;HttpOnly;secure;Expires=Sat,
-        22 Nov 2025 00:00:00 GMT
-      - GeoIP=US:WA:Seattle:47.54:-122.28:v4; Path=/; secure; Domain=.wikipedia.org
+        22 Nov 2025 12:00:00 GMT
+      - GeoIP=US:WA:Seattle:47.61:-122.31:v4; Path=/; secure; Domain=.wikipedia.org
       - NetworkProbeLimit=0.001;Path=/;Secure;SameSite=None;Max-Age=3600
-      - WMF-Uniq=g7TMOqEykiGknMFmi6eiEQKTAAAAAFvda1aa2ybi2-E2wJcpJ3L6zlGePS86mcRW;Domain=.wikipedia.org;Path=/;HttpOnly;secure;SameSite=None;Expires=Wed,
+      - WMF-Uniq=mhGFDKvzLcvvOCABiElkSwKTAAAAAFvdc4GkylRfeUD2tDln_3nJKpCYUusFvDlM;Domain=.wikipedia.org;Path=/;HttpOnly;secure;SameSite=None;Expires=Wed,
         21 Oct 2026 00:00:00 GMT
       strict-transport-security:
       - max-age=106384710; includeSubDomains; preload
       x-analytics:
       - ''
       x-cache:
-      - cp4039 hit, cp4039 hit/170099
+      - cp4042 hit, cp4042 hit/72743
       x-cache-status:
       - hit-front
       x-client-ip:
-      - 97.113.225.86
+      - 71.212.69.193
       x-request-id:
-      - b401c304-7b09-420e-a31b-553a6665c11c
+      - c0af436a-410c-4eef-9504-92413ad66766
     status:
       code: 200
       message: OK

python/tests/e2e/input/cassettes/test_call_with_params/openai_responses_gpt_4o.yaml

@@ -1,6 +1,6 @@
 interactions:
 - request:
-    body: '{"input":[{"role":"user","content":"What is 4200 + 42?"}],"max_output_tokens":500,"model":"gpt-4o","temperature":0.7,"top_p":0.3}'
+    body: '{"input":[{"content":[{"text":"What is 4200 + 42?","type":"input_text"}],"role":"user","type":"message"}],"max_output_tokens":500,"model":"gpt-4o","temperature":0.7,"top_p":0.3}'
     headers:
       accept:
       - application/json
@@ -9,7 +9,7 @@ interactions:
       connection:
       - keep-alive
       content-length:
-      - '129'
+      - '177'
       content-type:
       - application/json
       host:
@@ -39,35 +39,35 @@ interactions:
   response:
     body:
       string: !!binary |
-        H4sIAAAAAAAAA3RU23KjMAx9z1d4/LpNxxDKJb/S2WGEEam3xnZtOdNMJ/++gwkk7LZvoCMdpHMk
-        vnaMcdXzI+Meg2tFX0KD0LwgNoeXrBSirIe8yQ9ZLUtZZ43o8qauqwybspF5Vwz8aaKw3R+UtNBY
-        E3COS49A2LcwYVlViiqvSpElLBBQDFONtKPTSNjPRR3I95O30Ux9DaADzmGltTInfmRfO8YY4w4u
-        6Kf6Hs+orUPPd4xdUzJ6byfMRK1TQJnlK22PBEqHLRrIR0nKmk18hM/WRnKRWrLvmMAXIVaMrNWt
-        BL1lG22Pemrs5Ghf2H0u8mIv6r0ob2olRn5kr2mQeZzViDGcfvYhP/SymHyAoj5kBVbQFfWha6rE
-        nFjo4jDxYAhwwjvwk+AJlNYQmntTj41taBc58JPW6pQAxliCRcLX3xtQ25PztvsGSURHxotcCPaL
-        FTnDjwg6sCIv8me+pl5vT2s191anjiAEFQgMzclTYkriDjxojXprE/k4L5TzeFY2hnbZ2TYZsNro
-        vB0dtRLkG7bveHnEPEKwZrOOOAzW00PSJHkcR/BL5bqdAQakS6t6NKQGhZtNDejPSmJLatnuAaKe
-        xeaBrMfHIQhHhx4oprB4rm7RJOqts8H6Ee7vD2amvFm1W8dn9J0Nii7zCvUqjvermnV8s0rOwkey
-        fAXu3nKyrn1wXKxBl3o8zO8+Gpn2JU2pAnR6+QXEtLnrAMpsLjArn/6PP5z1Omayrr8Xis2o/x52
-        ln0HfMe7uv8TNVkCfQfzapUwhq3bIxL0QDDRX3fXvwAAAP//AwAhbnZRkQUAAA==
+        H4sIAAAAAAAAA3RU0Y6jMAx871dEeb3tKVBKS39ldUJuYrq5DUkucaqtVv33E6FAudt9A4892DM2
+        nxvGuFb8xHjA6FshEZuqVDvcya5WeyHqY3cUu0JiqY7HoqnPRdPtm52UAg/NXhz4y0Dhzr9R0kTj
+        bMQxLgMCoWphwIpDXYhjVRybjEUCSnGoka73BgnVWHQG+X4JLtmhrw5MxDGsjdH2wk/sc8MYY9zD
+        DcNQr/CKxnkMfMPYPSdjCG7AbDImB7SdvtIqJNAmrtFIIUnSzq7iPXy0LpFP1JJ7xwzuhZgxcs60
+        EsyarXcKzdDYxdO2cttSlNVWHLeifqiVGfmJveZBxnFmI/p4+d4HBaoUDx8OZV3KfdE0u64Ypcss
+        dPOYeTBGuOACfCd4BqWzhHZp6rmxFe0kB37QXJ0TwFpHMEn4+msFGnfxwZ2/QDLRifGqFIL9YFXJ
+        8E8CE1lVVuVPPqfeH09zNQ/O5I4gRh0JLI3JQ2JO4h4CGINmbROFNC6UD3jVLsV22tk2GzDb6IPr
+        PbUS5Bu273h7xgJCdHa1jth1LtBT0iB56nsIU+W8nRE6pFurFVrSncbVpkYMVy2xJT1tdwfJjGLz
+        SC7g8xCEvccAlHJY/Dw8olnUR2edCz0s709m5rxRtUfHVwxnFzXdxhVSOvXLVY06vjktR+ETOT4D
+        i7ecnG+fHBdz0Oced+N7SFbmfclT6ghnM/0CUt7ceQBtVxdY1C//x5/Oeh4zW6eWQrEa9d/DLoqv
+        gK94Z/e/oyZHYBawPMwSprh2u0cCBQQD/X1z/wsAAP//AwC8YZJ4kQUAAA==
     headers:
       CF-RAY:
-      - 99020953cabc8061-SEA
+      - 99240b141983a384-SEA
       Connection:
       - keep-alive
       Content-Encoding:
       - gzip
       Content-Type:
       - application/json
       Date:
-      - Fri, 17 Oct 2025 19:00:02 GMT
+      - Tue, 21 Oct 2025 22:03:10 GMT
       Server:
       - cloudflare
       Set-Cookie:
-      - __cf_bm=evtYbxmnaQwi5afMTPErkZhDYDpvUkbeaPkpIcJTlWQ-1760727602-1.0.1.1-mqE3NlpND9CEorPhRmFwGKAGN2uqpv2Zbxmc_kHuDnBjmIsUnxQP43rssB88kkirLA50FdlWxO4ukB63YQyDgSOMXV9PUhlGVnT4lj3C36E;
-        path=/; expires=Fri, 17-Oct-25 19:30:02 GMT; domain=.api.openai.com; HttpOnly;
+      - __cf_bm=MRHkwPoUWvTHKkm_PjHwq14taZ9HbCNP_AFqmH6MrNs-1761084190-1.0.1.1-ZEXMfnVcFesGmZ_DLJdEgmuNoFWIVWYBus.zFUXsU0lP3bl0J.kz8FoaIoddl7CiEdecJ_oMN8zLy6xIk1Tn2IOW3UNb4KVXLNwCLOHd5yg;
+        path=/; expires=Tue, 21-Oct-25 22:33:10 GMT; domain=.api.openai.com; HttpOnly;
         Secure; SameSite=None
-      - _cfuvid=Jwpuea6eQDG6bp_P8Cf.nhKpa5JuxqGm5MlxgWVqYy4-1760727602448-0.0.1.1-604800000;
+      - _cfuvid=LtKS2w9Ws82f46SAMdIBbxU6h9Zs7uPwXvBw.h2gnP8-1761084190024-0.0.1.1-604800000;
         path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None
       Strict-Transport-Security:
       - max-age=31536000; includeSubDomains; preload
@@ -82,13 +82,13 @@ interactions:
       openai-organization:
       - sotai-i3ryiz
       openai-processing-ms:
-      - '880'
+      - '1121'
       openai-project:
       - proj_2kPLXdwNOjkHt3ifb0aZ4FwU
       openai-version:
       - '2020-10-01'
       x-envoy-upstream-service-time:
-      - '883'
+      - '1127'
       x-ratelimit-limit-requests:
       - '5000'
       x-ratelimit-limit-tokens:
@@ -102,7 +102,7 @@ interactions:
       x-ratelimit-reset-tokens:
       - 2ms
       x-request-id:
-      - req_421956d5955445a3ba608904b079e1ac
+      - req_d086ae6f912847cda68256eccc846101
     status:
       code: 200
       message: OK