From 829f97f41e82beab7c826c0b3ee00e34a84da5b8 Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Wed, 6 Aug 2025 08:03:58 +0200 Subject: [PATCH] LCORE-390: description for all QueryRequest fields --- docs/openapi.json | 65 ++++++++++++++++++++++++++++++++++----- docs/openapi.md | 16 +++++----- docs/output.md | 16 +++++----- src/models/requests.py | 70 +++++++++++++++++++++++++++++++++++++----- 4 files changed, 135 insertions(+), 32 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index cddb29b3a..cc9c7f467 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -1406,7 +1406,11 @@ "properties": { "query": { "type": "string", - "title": "Query" + "title": "Query", + "description": "The query string", + "examples": [ + "What is Kubernetes?" + ] }, "conversation_id": { "anyOf": [ @@ -1417,7 +1421,11 @@ "type": "null" } ], - "title": "Conversation Id" + "title": "Conversation Id", + "description": "The optional conversation ID (UUID)", + "examples": [ + "c5260aec-4d82-4370-9fdf-05cf908b3f16" + ] }, "provider": { "anyOf": [ @@ -1428,7 +1436,12 @@ "type": "null" } ], - "title": "Provider" + "title": "Provider", + "description": "The optional provider", + "examples": [ + "openai", + "watsonx" + ] }, "model": { "anyOf": [ @@ -1439,7 +1452,11 @@ "type": "null" } ], - "title": "Model" + "title": "Model", + "description": "The optional model", + "examples": [ + "gpt4mini" + ] }, "system_prompt": { "anyOf": [ @@ -1450,7 +1467,12 @@ "type": "null" } ], - "title": "System Prompt" + "title": "System Prompt", + "description": "The optional system prompt.", + "examples": [ + "You are OpenShift assistant.", + "You are Ansible assistant." + ] }, "attachments": { "anyOf": [ @@ -1464,7 +1486,25 @@ "type": "null" } ], - "title": "Attachments" + "title": "Attachments", + "description": "The optional list of attachments.", + "examples": [ + { + "attachment_type": "log", + "content": "this is attachment", + "content_type": "text/plain" + }, + { + "attachment_type": "configuration", + "content": "kind: Pod\n metadata:\n name: private-reg", + "content_type": "application/yaml" + }, + { + "attachment_type": "configuration", + "content": "foo: bar", + "content_type": "application/yaml" + } + ] }, "no_tools": { "anyOf": [ @@ -1476,7 +1516,12 @@ } ], "title": "No Tools", - "default": false + "description": "Whether to bypass all tools and MCP servers", + "default": false, + "examples": [ + true, + false + ] }, "media_type": { "anyOf": [ @@ -1487,7 +1532,11 @@ "type": "null" } ], - "title": "Media Type" + "title": "Media Type", + "description": "Media type (used just to enable compatibility)", + "examples": [ + "application/json" + ] } }, "additionalProperties": false, diff --git a/docs/openapi.md b/docs/openapi.md index 2799067dc..350c4d394 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -737,14 +737,14 @@ Example: | Field | Type | Description | |-------|------|-------------| -| query | string | | -| conversation_id | | | -| provider | | | -| model | | | -| system_prompt | | | -| attachments | | | -| no_tools | | | -| media_type | | | +| query | string | The query string | +| conversation_id | | The optional conversation ID (UUID) | +| provider | | The optional provider | +| model | | The optional model | +| system_prompt | | The optional system prompt. | +| attachments | | The optional list of attachments. | +| no_tools | | Whether to bypass all tools and MCP servers | +| media_type | | Media type (used just to enable compatibility) | ## QueryResponse diff --git a/docs/output.md b/docs/output.md index 937a4ab8a..ae3a6144c 100644 --- a/docs/output.md +++ b/docs/output.md @@ -719,14 +719,14 @@ Example: | Field | Type | Description | |-------|------|-------------| -| query | string | | -| conversation_id | | | -| provider | | | -| model | | | -| system_prompt | | | -| attachments | | | -| no_tools | | | -| media_type | | | +| query | string | The query string | +| conversation_id | | The optional conversation ID (UUID) | +| provider | | The optional provider | +| model | | The optional model | +| system_prompt | | The optional system prompt. | +| attachments | | The optional list of attachments. | +| no_tools | | Whether to bypass all tools and MCP servers | +| media_type | | Media type (used just to enable compatibility) | ## QueryResponse diff --git a/src/models/requests.py b/src/models/requests.py index 860bec321..03c819a35 100644 --- a/src/models/requests.py +++ b/src/models/requests.py @@ -85,16 +85,70 @@ class QueryRequest(BaseModel): ``` """ - query: str - conversation_id: Optional[str] = None - provider: Optional[str] = None - model: Optional[str] = None - system_prompt: Optional[str] = None - attachments: Optional[list[Attachment]] = None - no_tools: Optional[bool] = False + query: str = Field( + description="The query string", + examples=["What is Kubernetes?"], + ) + + conversation_id: Optional[str] = Field( + None, + description="The optional conversation ID (UUID)", + examples=["c5260aec-4d82-4370-9fdf-05cf908b3f16"], + ) + + provider: Optional[str] = Field( + None, + description="The optional provider", + examples=["openai", "watsonx"], + ) + + model: Optional[str] = Field( + None, + description="The optional model", + examples=["gpt4mini"], + ) + + system_prompt: Optional[str] = Field( + None, + description="The optional system prompt.", + examples=["You are OpenShift assistant.", "You are Ansible assistant."], + ) + + attachments: Optional[list[Attachment]] = Field( + None, + description="The optional list of attachments.", + examples=[ + { + "attachment_type": "log", + "content_type": "text/plain", + "content": "this is attachment", + }, + { + "attachment_type": "configuration", + "content_type": "application/yaml", + "content": "kind: Pod\n metadata:\n name: private-reg", + }, + { + "attachment_type": "configuration", + "content_type": "application/yaml", + "content": "foo: bar", + }, + ], + ) + + no_tools: Optional[bool] = Field( + False, + description="Whether to bypass all tools and MCP servers", + examples=[True, False], + ) + # media_type is not used in 'lightspeed-stack' that only supports application/json. # the field is kept here to enable compatibility with 'road-core' clients. - media_type: Optional[str] = None + media_type: Optional[str] = Field( + None, + description="Media type (used just to enable compatibility)", + examples=["application/json"], + ) # provides examples for /docs endpoint model_config = {