1. Self return type on validate_image_attachment

  2. XOR-style consistency check merging two if-blocks
  3. image_attachments field removed from ResponsesApiParams
  4. Image attachments threaded as explicit parameters through handlers instead
  of via ResponsesApiParams

Signed-off-by: Lucas <lyoon@redhat.com>

Author: JslYoon

src/app/endpoints/query.py

@@ -23,7 +23,7 @@
 from authorization.middleware import authorize
 from client import AsyncLlamaStackClientHolder
 from configuration import configuration
-from constants import ENDPOINT_PATH_QUERY
+from constants import ENDPOINT_PATH_QUERY, IMAGE_CONTENT_TYPES
 from log import get_logger
 from models.api.requests import QueryRequest
 from models.api.responses.constants import UNAUTHORIZED_OPENAPI_EXAMPLES_WITH_MCP_OAUTH
@@ -227,6 +227,13 @@ async def query_endpoint_handler(
     ):
         client = await AsyncLlamaStackClientHolder().update_azure_token()
 
+    # Extract image attachments for multimodal support
+    image_attachments = [
+        a
+        for a in (query_request.attachments or [])
+        if a.content_type in IMAGE_CONTENT_TYPES
+    ] or None
+
     # Retrieve response using Responses API
     turn_summary = await retrieve_agent_response(
         client,
@@ -235,6 +242,7 @@ async def query_endpoint_handler(
         endpoint_path,
         compaction.original_input if compaction.compacted else None,
         no_tools=bool(query_request.no_tools),
+        image_attachments=image_attachments,
     )
 
     if moderation_result.decision == "passed":

src/app/endpoints/streaming_query.py

@@ -46,6 +46,7 @@
 from configuration import configuration
 from constants import (
     ENDPOINT_PATH_STREAMING_QUERY,
+    IMAGE_CONTENT_TYPES,
     LLM_TOKEN_EVENT,
     LLM_TOOL_CALL_EVENT,
     LLM_TOOL_RESULT_EVENT,
@@ -69,6 +70,7 @@
     UnprocessableEntityResponse,
 )
 from models.api.responses.successful import StreamingQueryResponse
+from models.common.query import Attachment
 from models.common.responses.contexts import ResponseGeneratorContext
 from models.common.responses.responses_api_params import ResponsesApiParams
 from models.common.responses.types import ResponseInput
@@ -307,6 +309,13 @@ async def streaming_query_endpoint_handler(  # pylint: disable=too-many-locals
     )
     recording.record_llm_call(provider_id, model_id, endpoint_path)
 
+    # Extract image attachments for multimodal support
+    image_attachments = [
+        a
+        for a in (query_request.attachments or [])
+        if a.content_type in IMAGE_CONTENT_TYPES
+    ] or None
+
     response_media_type = (
         MEDIA_TYPE_TEXT
         if query_request.media_type == MEDIA_TYPE_TEXT
@@ -330,6 +339,7 @@ async def streaming_query_endpoint_handler(  # pylint: disable=too-many-locals
                 context=context,
                 responses_params=responses_params,
                 endpoint_path=endpoint_path,
+                image_attachments=image_attachments,
             ),
             media_type=response_media_type,
         )
@@ -339,6 +349,7 @@ async def streaming_query_endpoint_handler(  # pylint: disable=too-many-locals
         context=context,
         endpoint_path=endpoint_path,
         no_tools=bool(query_request.no_tools),
+        image_attachments=image_attachments,
     )
 
     # Combine inline RAG results (BYOK + Solr) with tool-based results
@@ -461,6 +472,7 @@ async def generate_response_with_compaction(
     context: ResponseGeneratorContext,
     responses_params: ResponsesApiParams,
     endpoint_path: str,
+    image_attachments: Optional[list[Attachment]] = None,
 ) -> AsyncIterator[str]:
     """Stream a response for a conversation that requires compaction.
 
@@ -475,6 +487,7 @@ async def generate_response_with_compaction(
         context: The response generator context.
         responses_params: The base Responses API parameters.
         endpoint_path: API endpoint path used for metric labeling.
+        image_attachments: Image attachments for multimodal prompt construction.
 
     Yields:
         SSE-formatted strings.
@@ -507,6 +520,7 @@ async def generate_response_with_compaction(
             responses_params=responses_params,
             context=context,
             endpoint_path=endpoint_path,
+            image_attachments=image_attachments,
         )
     except HTTPException as e:
         yield http_exception_stream_event(e)

src/models/common/query.py

@@ -2,7 +2,7 @@
 
 import base64
 import binascii
-from typing import Any, Literal, Optional
+from typing import Any, Literal, Optional, Self
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
@@ -41,30 +41,25 @@ class Attachment(BaseModel):
     )
 
     @model_validator(mode="after")
-    def validate_image_attachment(self) -> "Attachment":
+    def validate_image_attachment(self) -> Self:
         """Validate consistency between attachment_type and content_type for images.
 
         Returns:
             Self: The validated Attachment instance.
 
         Raises:
-            ValueError: If image content_type is used without attachment_type='image',
-                if attachment_type='image' is used without an image content_type,
+            ValueError: If attachment_type and content_type are inconsistent
+                (one indicates an image while the other does not),
                 if image content is not valid base64, or if decoded size exceeds the limit.
         """
         is_image_content_type = self.content_type in IMAGE_CONTENT_TYPES
         is_image_attachment_type = self.attachment_type == "image"
 
-        if is_image_content_type and not is_image_attachment_type:
+        if is_image_content_type != is_image_attachment_type:
             raise ValueError(
-                f"attachment_type must be 'image' when content_type is "
-                f"'{self.content_type}'"
-            )
-
-        if is_image_attachment_type and not is_image_content_type:
-            raise ValueError(
-                f"content_type must be 'image/jpeg' or 'image/png' when "
-                f"attachment_type is 'image', got '{self.content_type}'"
+                f"attachment_type and content_type are inconsistent: "
+                f"attachment_type='{self.attachment_type}', "
+                f"content_type='{self.content_type}'"
             )
 
         if is_image_content_type:

src/models/common/responses/responses_api_params.py

@@ -20,7 +20,6 @@
 )
 from pydantic import BaseModel, Field
 
-from models.common.query import Attachment
 from models.common.responses.types import IncludeParameter, InputTool, ResponseInput
 from utils.tool_formatter import translate_vector_store_ids_to_user_facing
 
@@ -131,12 +130,6 @@ class ResponsesApiParams(BaseModel):
         "compacted, lightspeed-stack supplies explicit input and must not let "
         "Llama Stack reload the full history via the conversation parameter.",
     )
-    image_attachments: Optional[list[Attachment]] = Field(
-        default=None,
-        exclude=True,
-        description="Image attachments from the query request. Excluded from the "
-        "API request body — used by agent runners to build multimodal prompts.",
-    )
 
     def model_dump(self, *args: Any, **kwargs: Any) -> dict[str, Any]:
         """Serialize to a request body dict.

src/utils/agents/query.py

@@ -32,6 +32,7 @@
 )
 from models.common.agents import AgentTurnAccumulator
 from models.common.moderation import ShieldModerationResult
+from models.common.query import Attachment
 from models.common.responses.responses_api_params import ResponsesApiParams
 from models.common.responses.types import ResponseInput
 from models.common.turn_summary import TurnSummary
@@ -285,6 +286,7 @@ async def retrieve_agent_response(
     endpoint_path: str,
     _original_input: Optional[ResponseInput] = None,
     no_tools: bool = False,
+    image_attachments: Optional[list[Attachment]] = None,
 ) -> TurnSummary:
     """Retrieve a turn summary from a blocking agent run.
 
@@ -297,6 +299,7 @@ async def retrieve_agent_response(
         endpoint_path: Endpoint path used for metric labeling.
         _original_input: Original user input before the explicit-input rewrite.
         no_tools: Whether to skip tool processing.
+        image_attachments: Image attachments for multimodal prompt construction.
     Returns:
         Turn summary for the completed agent run.
 
@@ -319,10 +322,10 @@ async def retrieve_agent_response(
             client, responses_params, configuration.skills, no_tools=no_tools
         )
         logger.debug("Starting agent non-streaming response processing")
-        if responses_params.image_attachments:
+        if image_attachments:
             prompt = build_multimodal_input(
                 cast(str, responses_params.input),
-                responses_params.image_attachments,
+                image_attachments,
             )
         else:
             prompt = cast(str, responses_params.input)

src/utils/agents/streaming.py

@@ -39,6 +39,7 @@
     ToolResultStreamPayload,
     TurnCompleteStreamPayload,
 )
+from models.common.query import Attachment
 from models.common.responses import ResponseInput
 from models.common.responses.contexts import ResponseGeneratorContext
 from models.common.responses.responses_api_params import ResponsesApiParams
@@ -90,6 +91,7 @@ async def retrieve_agent_response_generator(
     context: ResponseGeneratorContext,
     endpoint_path: str,
     no_tools: bool = False,
+    image_attachments: Optional[list[Attachment]] = None,
 ) -> tuple[AsyncIterator[str], TurnSummary]:
     """Return the SSE generator and mutable turn summary for an agent run.
 
@@ -98,6 +100,7 @@ async def retrieve_agent_response_generator(
         context: Streaming request context and moderation result.
         endpoint_path: Endpoint path used for metric labeling.
         no_tools: Whether to skip tool processing.
+        image_attachments: Image attachments for multimodal prompt construction.
 
     Returns:
         Tuple of SSE async iterator and mutable turn summary.
@@ -135,6 +138,7 @@ async def retrieve_agent_response_generator(
                 context,
                 turn_summary,
                 endpoint_path,
+                image_attachments=image_attachments,
             ),
             turn_summary,
         )
@@ -301,6 +305,7 @@ async def agent_response_generator(
     context: ResponseGeneratorContext,
     turn_summary: TurnSummary,
     endpoint_path: str,
+    image_attachments: Optional[list[Attachment]] = None,
 ) -> AsyncIterator[str]:
     """Stream SSE events from an agent run and update the turn summary.
 
@@ -310,6 +315,7 @@ async def agent_response_generator(
         context: Streaming request context.
         turn_summary: Mutable summary to fill while streaming.
         endpoint_path: Endpoint path used for metric labeling.
+        image_attachments: Image attachments for multimodal prompt construction.
 
     Yields:
         Serialized SSE event strings.
@@ -320,10 +326,10 @@ async def agent_response_generator(
         rag_id_mapping=context.rag_id_mapping,
         turn_summary=turn_summary,
     )
-    if responses_params.image_attachments:
+    if image_attachments:
         prompt = build_multimodal_input(
             cast(str, responses_params.input),
-            responses_params.image_attachments,
+            image_attachments,
         )
     else:
         prompt = cast(str, responses_params.input)

src/utils/responses.py

@@ -93,7 +93,6 @@
     NotFoundResponse,
     ServiceUnavailableResponse,
 )
-from models.common.query import Attachment
 from models.common.responses.responses_api_params import ResponsesApiParams
 from models.common.responses.types import (
     InputTool,
@@ -388,17 +387,6 @@ async def prepare_responses_params(  # pylint: disable=too-many-arguments,too-ma
     # Adds inline RAG context and text attachments (images are excluded)
     input_text = prepare_input(query_request, inline_rag_context)
 
-    # Extract image attachments for multimodal support
-    image_attachments: Optional[list[Attachment]] = None
-    if query_request.attachments:
-        images = [
-            a
-            for a in query_request.attachments
-            if a.content_type in constants.IMAGE_CONTENT_TYPES
-        ]
-        if images:
-            image_attachments = images
-
     # Handle conversation ID for Responses API
     conversation_id = query_request.conversation_id
     if conversation_id:
@@ -443,7 +431,6 @@ async def prepare_responses_params(  # pylint: disable=too-many-arguments,too-ma
         extra_headers=extra_headers,
         max_infer_iters=configuration.inference.max_infer_iters,
         max_tool_calls=configuration.inference.max_tool_calls,
-        image_attachments=image_attachments,
     )
 
 

tests/unit/models/requests/test_attachment.py

@@ -67,7 +67,9 @@ def test_valid_image_attachment_png(self) -> None:
     def test_image_content_type_requires_image_attachment_type(self) -> None:
         """Test that image content_type requires attachment_type='image'."""
         image_data = base64.b64encode(b"\xff\xd8\xff\xe0").decode()
-        with pytest.raises(ValidationError, match="attachment_type must be 'image'"):
+        with pytest.raises(
+            ValidationError, match="attachment_type and content_type are inconsistent"
+        ):
             Attachment(
                 attachment_type="log",
                 content_type="image/jpeg",
@@ -77,7 +79,7 @@ def test_image_content_type_requires_image_attachment_type(self) -> None:
     def test_image_attachment_type_requires_image_content_type(self) -> None:
         """Test that attachment_type='image' requires an image content_type."""
         with pytest.raises(
-            ValidationError, match="content_type must be 'image/jpeg' or 'image/png'"
+            ValidationError, match="attachment_type and content_type are inconsistent"
         ):
             Attachment(
                 attachment_type="image",

tests/unit/utils/agents/test_query.py

@@ -461,13 +461,13 @@ async def test_success_with_image_attachments_sends_multimodal_prompt(
             content_type="image/jpeg",
         )
         params = make_responses_params(input_text="describe this")
-        params.image_attachments = [image_attachment]
 
         summary = await retrieve_agent_response(
             client=mocker.AsyncMock(),
             responses_params=params,
             moderation_result=ShieldModerationPassed(),
             endpoint_path=ENDPOINT_PATH_QUERY,
+            image_attachments=[image_attachment],
         )
 
         prompt_arg = mock_agent.run.call_args[0][0]

tests/unit/utils/agents/test_streaming.py

@@ -594,6 +594,7 @@ async def test_success_returns_agent_generator(
             context,
             turn_summary,
             ENDPOINT_PATH_STREAMING_QUERY,
+            image_attachments=None,
         )
 
     @pytest.mark.asyncio
@@ -935,7 +936,6 @@ async def test_streams_with_image_attachments_passes_multimodal_prompt(
             content_type="image/jpeg",
         )
         params = make_responses_params(input_text="describe this")
-        params.image_attachments = [image_attachment]
 
         _ = [
             event
@@ -945,6 +945,7 @@ async def test_streams_with_image_attachments_passes_multimodal_prompt(
                 context,
                 turn_summary,
                 ENDPOINT_PATH_STREAMING_QUERY,
+                image_attachments=[image_attachment],
             )
         ]