feat(responses): type file results properly (#3117)

Another thing our tests implicitly depended on.

docs/_static/llama-stack-spec.html

@@ -8293,28 +8293,60 @@
                         "type": "array",
                         "items": {
                             "type": "object",
-                            "additionalProperties": {
+                            "properties": {
-                                "oneOf": [
+                                "attributes": {
-                                    {
+                                    "type": "object",
-                                        "type": "null"
+                                    "additionalProperties": {
+                                        "oneOf": [
+                                            {
+                                                "type": "null"
+                                            },
+                                            {
+                                                "type": "boolean"
+                                            },
+                                            {
+                                                "type": "number"
+                                            },
+                                            {
+                                                "type": "string"
+                                            },
+                                            {
+                                                "type": "array"
+                                            },
+                                            {
+                                                "type": "object"
+                                            }
+                                        ]
                                     },
-                                    {
+                                    "description": "(Optional) Key-value attributes associated with the file"
-                                        "type": "boolean"
+                                },
-                                    },
+                                "file_id": {
-                                    {
+                                    "type": "string",
-                                        "type": "number"
+                                    "description": "Unique identifier of the file containing the result"
-                                    },
+                                },
-                                    {
+                                "filename": {
-                                        "type": "string"
+                                    "type": "string",
-                                    },
+                                    "description": "Name of the file containing the result"
-                                    {
+                                },
-                                        "type": "array"
+                                "score": {
-                                    },
+                                    "type": "number",
-                                    {
+                                    "description": "Relevance score for this search result (between 0 and 1)"
-                                        "type": "object"
+                                },
-                                    }
+                                "text": {
-                                ]
+                                    "type": "string",
-                            }
+                                    "description": "Text content of the search result"
+                                }
+                            },
+                            "additionalProperties": false,
+                            "required": [
+                                "attributes",
+                                "file_id",
+                                "filename",
+                                "score",
+                                "text"
+                            ],
+                            "title": "OpenAIResponseOutputMessageFileSearchToolCallResults",
+                            "description": "Search results returned by the file search operation."
                         },
                         "description": "(Optional) Search results returned by the file search operation"
                     }

docs/_static/llama-stack-spec.yaml

@@ -6021,14 +6021,44 @@ components:
           type: array
           items:
             type: object
-            additionalProperties:
+            properties:
-              oneOf:
+              attributes:
-                - type: 'null'
+                type: object
-                - type: boolean
+                additionalProperties:
-                - type: number
+                  oneOf:
-                - type: string
+                    - type: 'null'
-                - type: array
+                    - type: boolean
-                - type: object
+                    - type: number
+                    - type: string
+                    - type: array
+                    - type: object
+                description: >-
+                  (Optional) Key-value attributes associated with the file
+              file_id:
+                type: string
+                description: >-
+                  Unique identifier of the file containing the result
+              filename:
+                type: string
+                description: Name of the file containing the result
+              score:
+                type: number
+                description: >-
+                  Relevance score for this search result (between 0 and 1)
+              text:
+                type: string
+                description: Text content of the search result
+            additionalProperties: false
+            required:
+              - attributes
+              - file_id
+              - filename
+              - score
+              - text
+            title: >-
+              OpenAIResponseOutputMessageFileSearchToolCallResults
+            description: >-
+              Search results returned by the file search operation.
           description: >-
             (Optional) Search results returned by the file search operation
       additionalProperties: false

llama_stack/apis/agents/openai_responses.py

@@ -170,6 +170,23 @@ class OpenAIResponseOutputMessageWebSearchToolCall(BaseModel):
     type: Literal["web_search_call"] = "web_search_call"
 
 
+class OpenAIResponseOutputMessageFileSearchToolCallResults(BaseModel):
+    """Search results returned by the file search operation.
+
+    :param attributes: (Optional) Key-value attributes associated with the file
+    :param file_id: Unique identifier of the file containing the result
+    :param filename: Name of the file containing the result
+    :param score: Relevance score for this search result (between 0 and 1)
+    :param text: Text content of the search result
+    """
+
+    attributes: dict[str, Any]
+    file_id: str
+    filename: str
+    score: float
+    text: str
+
+
 @json_schema_type
 class OpenAIResponseOutputMessageFileSearchToolCall(BaseModel):
     """File search tool call output message for OpenAI responses.
@@ -185,7 +202,7 @@ class OpenAIResponseOutputMessageFileSearchToolCall(BaseModel):
     queries: list[str]
     status: str
     type: Literal["file_search_call"] = "file_search_call"
-    results: list[dict[str, Any]] | None = None
+    results: list[OpenAIResponseOutputMessageFileSearchToolCallResults] | None = None
 
 
 @json_schema_type

llama_stack/providers/inline/agents/meta_reference/openai_responses.py

@@ -38,6 +38,7 @@ from llama_stack.apis.agents.openai_responses import (
     OpenAIResponseOutputMessageContent,
     OpenAIResponseOutputMessageContentOutputText,
     OpenAIResponseOutputMessageFileSearchToolCall,
+    OpenAIResponseOutputMessageFileSearchToolCallResults,
     OpenAIResponseOutputMessageFunctionToolCall,
     OpenAIResponseOutputMessageMCPListTools,
     OpenAIResponseOutputMessageWebSearchToolCall,
@@ -827,12 +828,13 @@ class OpenAIResponsesImpl:
                         text = result.metadata["chunks"][i] if "chunks" in result.metadata else None
                         score = result.metadata["scores"][i] if "scores" in result.metadata else None
                         message.results.append(
-                            {
+                            OpenAIResponseOutputMessageFileSearchToolCallResults(
-                                "file_id": doc_id,
+                                file_id=doc_id,
-                                "filename": doc_id,
+                                filename=doc_id,
-                                "text": text,
+                                text=text,
-                                "score": score,
+                                score=score,
-                            }
+                                attributes={},
+                            )
                         )
                 if error_exc or (result.error_code and result.error_code > 0) or result.error_message:
                     message.status = "failed"