Add Form() annotations and fix OpenAPI generation for multipart params

- Add Form() annotations to purpose and expires_after parameters in file upload endpoints
- Add support for optional multipart form parameters in OpenAPI generator
- Generated spec now properly mirrors OpenAI format with schema refs

docs/static/llama-stack-spec.yaml

@@ -4393,8 +4393,13 @@ paths:
                 file:
                   type: string
                   format: binary
+                purpose:
+                  $ref: '#/components/schemas/OpenAIFilePurpose'
+                expires_after:
+                  $ref: '#/components/schemas/ExpiresAfter'
               required:
                 - file
+                - purpose
         required: true
   /v1/openai/v1/files:
     get:
@@ -4499,8 +4504,13 @@ paths:
                 file:
                   type: string
                   format: binary
+                purpose:
+                  $ref: '#/components/schemas/OpenAIFilePurpose'
+                expires_after:
+                  $ref: '#/components/schemas/ExpiresAfter'
               required:
                 - file
+                - purpose
         required: true
   /v1/openai/v1/models:
     get:
@@ -5733,7 +5743,16 @@ components:
       type: object
       properties:
         strategy:
-          $ref: '#/components/schemas/SamplingStrategy'
+          oneOf:
+            - $ref: '#/components/schemas/GreedySamplingStrategy'
+            - $ref: '#/components/schemas/TopPSamplingStrategy'
+            - $ref: '#/components/schemas/TopKSamplingStrategy'
+          discriminator:
+            propertyName: type
+            mapping:
+              greedy: '#/components/schemas/GreedySamplingStrategy'
+              top_p: '#/components/schemas/TopPSamplingStrategy'
+              top_k: '#/components/schemas/TopKSamplingStrategy'
           description: The sampling strategy.
         max_tokens:
           type: integer
@@ -5761,17 +5780,6 @@ components:
         - strategy
       title: SamplingParams
       description: Sampling parameters.
-    SamplingStrategy:
-      oneOf:
-        - $ref: '#/components/schemas/GreedySamplingStrategy'
-        - $ref: '#/components/schemas/TopPSamplingStrategy'
-        - $ref: '#/components/schemas/TopKSamplingStrategy'
-      discriminator:
-        propertyName: type
-        mapping:
-          greedy: '#/components/schemas/GreedySamplingStrategy'
-          top_p: '#/components/schemas/TopPSamplingStrategy'
-          top_k: '#/components/schemas/TopKSamplingStrategy'
     SystemMessage:
       type: object
       properties:
@@ -6218,7 +6226,16 @@ components:
             - progress
           description: Type of the event
         delta:
-          $ref: '#/components/schemas/ContentDelta'
+          oneOf:
+            - $ref: '#/components/schemas/TextDelta'
+            - $ref: '#/components/schemas/ImageDelta'
+            - $ref: '#/components/schemas/ToolCallDelta'
+          discriminator:
+            propertyName: type
+            mapping:
+              text: '#/components/schemas/TextDelta'
+              image: '#/components/schemas/ImageDelta'
+              tool_call: '#/components/schemas/ToolCallDelta'
           description: >-
             Content generated since last event. This can be one or more tokens, or
             a tool call.
@@ -6261,17 +6278,6 @@ components:
       title: ChatCompletionResponseStreamChunk
       description: >-
         A chunk of a streamed chat completion response.
-    ContentDelta:
-      oneOf:
-        - $ref: '#/components/schemas/TextDelta'
-        - $ref: '#/components/schemas/ImageDelta'
-        - $ref: '#/components/schemas/ToolCallDelta'
-      discriminator:
-        propertyName: type
-        mapping:
-          text: '#/components/schemas/TextDelta'
-          image: '#/components/schemas/ImageDelta'
-          tool_call: '#/components/schemas/ToolCallDelta'
     ImageDelta:
       type: object
       properties:
@@ -6953,7 +6959,22 @@ components:
       type: object
       properties:
         payload:
-          $ref: '#/components/schemas/AgentTurnResponseEventPayload'
+          oneOf:
+            - $ref: '#/components/schemas/AgentTurnResponseStepStartPayload'
+            - $ref: '#/components/schemas/AgentTurnResponseStepProgressPayload'
+            - $ref: '#/components/schemas/AgentTurnResponseStepCompletePayload'
+            - $ref: '#/components/schemas/AgentTurnResponseTurnStartPayload'
+            - $ref: '#/components/schemas/AgentTurnResponseTurnCompletePayload'
+            - $ref: '#/components/schemas/AgentTurnResponseTurnAwaitingInputPayload'
+          discriminator:
+            propertyName: event_type
+            mapping:
+              step_start: '#/components/schemas/AgentTurnResponseStepStartPayload'
+              step_progress: '#/components/schemas/AgentTurnResponseStepProgressPayload'
+              step_complete: '#/components/schemas/AgentTurnResponseStepCompletePayload'
+              turn_start: '#/components/schemas/AgentTurnResponseTurnStartPayload'
+              turn_complete: '#/components/schemas/AgentTurnResponseTurnCompletePayload'
+              turn_awaiting_input: '#/components/schemas/AgentTurnResponseTurnAwaitingInputPayload'
           description: >-
             Event-specific payload containing event data
       additionalProperties: false
@@ -6962,23 +6983,6 @@ components:
       title: AgentTurnResponseEvent
       description: >-
         An event in an agent turn response stream.
-    AgentTurnResponseEventPayload:
-      oneOf:
-        - $ref: '#/components/schemas/AgentTurnResponseStepStartPayload'
-        - $ref: '#/components/schemas/AgentTurnResponseStepProgressPayload'
-        - $ref: '#/components/schemas/AgentTurnResponseStepCompletePayload'
-        - $ref: '#/components/schemas/AgentTurnResponseTurnStartPayload'
-        - $ref: '#/components/schemas/AgentTurnResponseTurnCompletePayload'
-        - $ref: '#/components/schemas/AgentTurnResponseTurnAwaitingInputPayload'
-      discriminator:
-        propertyName: event_type
-        mapping:
-          step_start: '#/components/schemas/AgentTurnResponseStepStartPayload'
-          step_progress: '#/components/schemas/AgentTurnResponseStepProgressPayload'
-          step_complete: '#/components/schemas/AgentTurnResponseStepCompletePayload'
-          turn_start: '#/components/schemas/AgentTurnResponseTurnStartPayload'
-          turn_complete: '#/components/schemas/AgentTurnResponseTurnCompletePayload'
-          turn_awaiting_input: '#/components/schemas/AgentTurnResponseTurnAwaitingInputPayload'
     AgentTurnResponseStepCompletePayload:
       type: object
       properties:
@@ -7057,7 +7061,16 @@ components:
           description: >-
             Unique identifier for the step within a turn
         delta:
-          $ref: '#/components/schemas/ContentDelta'
+          oneOf:
+            - $ref: '#/components/schemas/TextDelta'
+            - $ref: '#/components/schemas/ImageDelta'
+            - $ref: '#/components/schemas/ToolCallDelta'
+          discriminator:
+            propertyName: type
+            mapping:
+              text: '#/components/schemas/TextDelta'
+              image: '#/components/schemas/ImageDelta'
+              tool_call: '#/components/schemas/ToolCallDelta'
           description: >-
             Incremental content changes during step execution
       additionalProperties: false
@@ -8126,15 +8139,6 @@ components:
       title: OpenAIResponseOutputMessageMCPListTools
       description: >-
         MCP list tools output message containing available tools from an MCP server.
-    OpenAIResponseContentPart:
-      oneOf:
-        - $ref: '#/components/schemas/OpenAIResponseContentPartOutputText'
-        - $ref: '#/components/schemas/OpenAIResponseContentPartRefusal'
-      discriminator:
-        propertyName: type
-        mapping:
-          output_text: '#/components/schemas/OpenAIResponseContentPartOutputText'
-          refusal: '#/components/schemas/OpenAIResponseContentPartRefusal'
     OpenAIResponseContentPartOutputText:
       type: object
       properties:
@@ -8242,7 +8246,14 @@ components:
           description: >-
             Unique identifier of the output item containing this content part
         part:
-          $ref: '#/components/schemas/OpenAIResponseContentPart'
+          oneOf:
+            - $ref: '#/components/schemas/OpenAIResponseContentPartOutputText'
+            - $ref: '#/components/schemas/OpenAIResponseContentPartRefusal'
+          discriminator:
+            propertyName: type
+            mapping:
+              output_text: '#/components/schemas/OpenAIResponseContentPartOutputText'
+              refusal: '#/components/schemas/OpenAIResponseContentPartRefusal'
           description: The content part that was added
         sequence_number:
           type: integer
@@ -8277,7 +8288,14 @@ components:
           description: >-
             Unique identifier of the output item containing this content part
         part:
-          $ref: '#/components/schemas/OpenAIResponseContentPart'
+          oneOf:
+            - $ref: '#/components/schemas/OpenAIResponseContentPartOutputText'
+            - $ref: '#/components/schemas/OpenAIResponseContentPartRefusal'
+          discriminator:
+            propertyName: type
+            mapping:
+              output_text: '#/components/schemas/OpenAIResponseContentPartOutputText'
+              refusal: '#/components/schemas/OpenAIResponseContentPartRefusal'
           description: The completed content part
         sequence_number:
           type: integer
@@ -8563,7 +8581,22 @@ components:
           description: >-
             Unique identifier of the response containing this output
         item:
-          $ref: '#/components/schemas/OpenAIResponseOutput'
+          oneOf:
+            - $ref: '#/components/schemas/OpenAIResponseMessage'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageFileSearchToolCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageFunctionToolCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageMCPCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageMCPListTools'
+          discriminator:
+            propertyName: type
+            mapping:
+              message: '#/components/schemas/OpenAIResponseMessage'
+              web_search_call: '#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall'
+              file_search_call: '#/components/schemas/OpenAIResponseOutputMessageFileSearchToolCall'
+              function_call: '#/components/schemas/OpenAIResponseOutputMessageFunctionToolCall'
+              mcp_call: '#/components/schemas/OpenAIResponseOutputMessageMCPCall'
+              mcp_list_tools: '#/components/schemas/OpenAIResponseOutputMessageMCPListTools'
           description: >-
             The output item that was added (message, tool call, etc.)
         output_index:
@@ -8599,7 +8632,22 @@ components:
           description: >-
             Unique identifier of the response containing this output
         item:
-          $ref: '#/components/schemas/OpenAIResponseOutput'
+          oneOf:
+            - $ref: '#/components/schemas/OpenAIResponseMessage'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageFileSearchToolCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageFunctionToolCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageMCPCall'
+            - $ref: '#/components/schemas/OpenAIResponseOutputMessageMCPListTools'
+          discriminator:
+            propertyName: type
+            mapping:
+              message: '#/components/schemas/OpenAIResponseMessage'
+              web_search_call: '#/components/schemas/OpenAIResponseOutputMessageWebSearchToolCall'
+              file_search_call: '#/components/schemas/OpenAIResponseOutputMessageFileSearchToolCall'
+              function_call: '#/components/schemas/OpenAIResponseOutputMessageFunctionToolCall'
+              mcp_call: '#/components/schemas/OpenAIResponseOutputMessageMCPCall'
+              mcp_list_tools: '#/components/schemas/OpenAIResponseOutputMessageMCPListTools'
           description: >-
             The completed output item (message, tool call, etc.)
         output_index:
@@ -8922,7 +8970,14 @@ components:
       type: object
       properties:
         eval_candidate:
-          $ref: '#/components/schemas/EvalCandidate'
+          oneOf:
+            - $ref: '#/components/schemas/ModelCandidate'
+            - $ref: '#/components/schemas/AgentCandidate'
+          discriminator:
+            propertyName: type
+            mapping:
+              model: '#/components/schemas/ModelCandidate'
+              agent: '#/components/schemas/AgentCandidate'
           description: The candidate to evaluate.
         scoring_params:
           type: object
@@ -8943,15 +8998,6 @@ components:
       title: BenchmarkConfig
       description: >-
         A benchmark configuration for evaluation.
-    EvalCandidate:
-      oneOf:
-        - $ref: '#/components/schemas/ModelCandidate'
-        - $ref: '#/components/schemas/AgentCandidate'
-      discriminator:
-        propertyName: type
-        mapping:
-          model: '#/components/schemas/ModelCandidate'
-          agent: '#/components/schemas/AgentCandidate'
     LLMAsJudgeScoringFnParams:
       type: object
       properties:
@@ -9415,7 +9461,20 @@ components:
       type: object
       properties:
         message:
-          $ref: '#/components/schemas/OpenAIMessageParam'
+          oneOf:
+            - $ref: '#/components/schemas/OpenAIUserMessageParam'
+            - $ref: '#/components/schemas/OpenAISystemMessageParam'
+            - $ref: '#/components/schemas/OpenAIAssistantMessageParam'
+            - $ref: '#/components/schemas/OpenAIToolMessageParam'
+            - $ref: '#/components/schemas/OpenAIDeveloperMessageParam'
+          discriminator:
+            propertyName: role
+            mapping:
+              user: '#/components/schemas/OpenAIUserMessageParam'
+              system: '#/components/schemas/OpenAISystemMessageParam'
+              assistant: '#/components/schemas/OpenAIAssistantMessageParam'
+              tool: '#/components/schemas/OpenAIToolMessageParam'
+              developer: '#/components/schemas/OpenAIDeveloperMessageParam'
           description: The message from the model
         finish_reason:
           type: string
@@ -9708,15 +9767,6 @@ components:
         - model
         - input_messages
       title: OpenAICompletionWithInputMessages
-    DataSource:
-      oneOf:
-        - $ref: '#/components/schemas/URIDataSource'
-        - $ref: '#/components/schemas/RowsDataSource'
-      discriminator:
-        propertyName: type
-        mapping:
-          uri: '#/components/schemas/URIDataSource'
-          rows: '#/components/schemas/RowsDataSource'
     Dataset:
       type: object
       properties:
@@ -9751,7 +9801,14 @@ components:
           description: >-
             Purpose of the dataset indicating its intended use
         source:
-          $ref: '#/components/schemas/DataSource'
+          oneOf:
+            - $ref: '#/components/schemas/URIDataSource'
+            - $ref: '#/components/schemas/RowsDataSource'
+          discriminator:
+            propertyName: type
+            mapping:
+              uri: '#/components/schemas/URIDataSource'
+              rows: '#/components/schemas/RowsDataSource'
           description: >-
             Data source configuration for the dataset
         metadata:
@@ -9997,31 +10054,6 @@ components:
         - type
       title: ObjectType
       description: Parameter type for object values.
-    ParamType:
-      oneOf:
-        - $ref: '#/components/schemas/StringType'
-        - $ref: '#/components/schemas/NumberType'
-        - $ref: '#/components/schemas/BooleanType'
-        - $ref: '#/components/schemas/ArrayType'
-        - $ref: '#/components/schemas/ObjectType'
-        - $ref: '#/components/schemas/JsonType'
-        - $ref: '#/components/schemas/UnionType'
-        - $ref: '#/components/schemas/ChatCompletionInputType'
-        - $ref: '#/components/schemas/CompletionInputType'
-        - $ref: '#/components/schemas/AgentTurnInputType'
-      discriminator:
-        propertyName: type
-        mapping:
-          string: '#/components/schemas/StringType'
-          number: '#/components/schemas/NumberType'
-          boolean: '#/components/schemas/BooleanType'
-          array: '#/components/schemas/ArrayType'
-          object: '#/components/schemas/ObjectType'
-          json: '#/components/schemas/JsonType'
-          union: '#/components/schemas/UnionType'
-          chat_completion_input: '#/components/schemas/ChatCompletionInputType'
-          completion_input: '#/components/schemas/CompletionInputType'
-          agent_turn_input: '#/components/schemas/AgentTurnInputType'
     ScoringFn:
       type: object
       properties:
@@ -10060,7 +10092,30 @@ components:
               - type: array
               - type: object
         return_type:
-          $ref: '#/components/schemas/ParamType'
+          oneOf:
+            - $ref: '#/components/schemas/StringType'
+            - $ref: '#/components/schemas/NumberType'
+            - $ref: '#/components/schemas/BooleanType'
+            - $ref: '#/components/schemas/ArrayType'
+            - $ref: '#/components/schemas/ObjectType'
+            - $ref: '#/components/schemas/JsonType'
+            - $ref: '#/components/schemas/UnionType'
+            - $ref: '#/components/schemas/ChatCompletionInputType'
+            - $ref: '#/components/schemas/CompletionInputType'
+            - $ref: '#/components/schemas/AgentTurnInputType'
+          discriminator:
+            propertyName: type
+            mapping:
+              string: '#/components/schemas/StringType'
+              number: '#/components/schemas/NumberType'
+              boolean: '#/components/schemas/BooleanType'
+              array: '#/components/schemas/ArrayType'
+              object: '#/components/schemas/ObjectType'
+              json: '#/components/schemas/JsonType'
+              union: '#/components/schemas/UnionType'
+              chat_completion_input: '#/components/schemas/ChatCompletionInputType'
+              completion_input: '#/components/schemas/CompletionInputType'
+              agent_turn_input: '#/components/schemas/AgentTurnInputType'
         params:
           $ref: '#/components/schemas/ScoringFnParams'
       additionalProperties: false
@@ -11512,7 +11567,14 @@ components:
           description: >-
             Event type identifier set to STRUCTURED_LOG
         payload:
-          $ref: '#/components/schemas/StructuredLogPayload'
+          oneOf:
+            - $ref: '#/components/schemas/SpanStartPayload'
+            - $ref: '#/components/schemas/SpanEndPayload'
+          discriminator:
+            propertyName: type
+            mapping:
+              span_start: '#/components/schemas/SpanStartPayload'
+              span_end: '#/components/schemas/SpanEndPayload'
           description: >-
             The structured payload data for the log event
       additionalProperties: false
@@ -11525,15 +11587,6 @@ components:
       title: StructuredLogEvent
       description: >-
         A structured log event containing typed payload data.
-    StructuredLogPayload:
-      oneOf:
-        - $ref: '#/components/schemas/SpanStartPayload'
-        - $ref: '#/components/schemas/SpanEndPayload'
-      discriminator:
-        propertyName: type
-        mapping:
-          span_start: '#/components/schemas/SpanStartPayload'
-          span_end: '#/components/schemas/SpanEndPayload'
     StructuredLogType:
       type: string
       enum:
@@ -11742,7 +11795,14 @@ components:
           description: >-
             Key-value attributes associated with the file
         chunking_strategy:
-          $ref: '#/components/schemas/VectorStoreChunkingStrategy'
+          oneOf:
+            - $ref: '#/components/schemas/VectorStoreChunkingStrategyAuto'
+            - $ref: '#/components/schemas/VectorStoreChunkingStrategyStatic'
+          discriminator:
+            propertyName: type
+            mapping:
+              auto: '#/components/schemas/VectorStoreChunkingStrategyAuto'
+              static: '#/components/schemas/VectorStoreChunkingStrategyStatic'
           description: >-
             Strategy used for splitting the file into chunks
         created_at:
@@ -13054,6 +13114,25 @@ components:
       required:
         - attributes
       title: OpenaiUpdateVectorStoreFileRequest
+    ExpiresAfter:
+      type: object
+      properties:
+        anchor:
+          type: string
+          const: created_at
+        seconds:
+          type: integer
+      additionalProperties: false
+      required:
+        - anchor
+        - seconds
+      title: ExpiresAfter
+      description: >-
+        Control expiration of uploaded files.
+
+        Params:
+         - anchor, must be "created_at"
+         - seconds, must be int between 3600 and 2592000 (1 hour to 30 days)
     DPOAlignmentConfig:
       type: object
       properties:
@@ -13339,7 +13418,14 @@ components:
       type: object
       properties:
         query_generator_config:
-          $ref: '#/components/schemas/RAGQueryGeneratorConfig'
+          oneOf:
+            - $ref: '#/components/schemas/DefaultRAGQueryGeneratorConfig'
+            - $ref: '#/components/schemas/LLMRAGQueryGeneratorConfig'
+          discriminator:
+            propertyName: type
+            mapping:
+              default: '#/components/schemas/DefaultRAGQueryGeneratorConfig'
+              llm: '#/components/schemas/LLMRAGQueryGeneratorConfig'
           description: Configuration for the query generator.
         max_tokens_in_context:
           type: integer
@@ -13382,15 +13468,6 @@ components:
       title: RAGQueryConfig
       description: >-
         Configuration for the RAG query generation.
-    RAGQueryGeneratorConfig:
-      oneOf:
-        - $ref: '#/components/schemas/DefaultRAGQueryGeneratorConfig'
-        - $ref: '#/components/schemas/LLMRAGQueryGeneratorConfig'
-      discriminator:
-        propertyName: type
-        mapping:
-          default: '#/components/schemas/DefaultRAGQueryGeneratorConfig'
-          llm: '#/components/schemas/LLMRAGQueryGeneratorConfig'
     RAGSearchMode:
       type: string
       enum:
@@ -13826,6 +13903,15 @@ components:
         - dataset_id
         - scoring_functions
       title: RegisterBenchmarkRequest
+    DataSource:
+      oneOf:
+        - $ref: '#/components/schemas/URIDataSource'
+        - $ref: '#/components/schemas/RowsDataSource'
+      discriminator:
+        propertyName: type
+        mapping:
+          uri: '#/components/schemas/URIDataSource'
+          rows: '#/components/schemas/RowsDataSource'
     RegisterDatasetRequest:
       type: object
       properties:
@@ -13910,6 +13996,31 @@ components:
       required:
         - model_id
       title: RegisterModelRequest
+    ParamType:
+      oneOf:
+        - $ref: '#/components/schemas/StringType'
+        - $ref: '#/components/schemas/NumberType'
+        - $ref: '#/components/schemas/BooleanType'
+        - $ref: '#/components/schemas/ArrayType'
+        - $ref: '#/components/schemas/ObjectType'
+        - $ref: '#/components/schemas/JsonType'
+        - $ref: '#/components/schemas/UnionType'
+        - $ref: '#/components/schemas/ChatCompletionInputType'
+        - $ref: '#/components/schemas/CompletionInputType'
+        - $ref: '#/components/schemas/AgentTurnInputType'
+      discriminator:
+        propertyName: type
+        mapping:
+          string: '#/components/schemas/StringType'
+          number: '#/components/schemas/NumberType'
+          boolean: '#/components/schemas/BooleanType'
+          array: '#/components/schemas/ArrayType'
+          object: '#/components/schemas/ObjectType'
+          json: '#/components/schemas/JsonType'
+          union: '#/components/schemas/UnionType'
+          chat_completion_input: '#/components/schemas/ChatCompletionInputType'
+          completion_input: '#/components/schemas/CompletionInputType'
+          agent_turn_input: '#/components/schemas/AgentTurnInputType'
     RegisterScoringFunctionRequest:
       type: object
       properties: