From 053090b1dc7a8a3c5a18b677eb15775847b3fea5 Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Thu, 14 Aug 2025 08:47:10 +0200 Subject: [PATCH 1/2] Fields for ModelResponse, QueryResponse, InfoResponse, and ErrorResponse --- src/models/responses.py | 68 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 6 deletions(-) diff --git a/src/models/responses.py b/src/models/responses.py index 5d037a77a..a1204dfbd 100644 --- a/src/models/responses.py +++ b/src/models/responses.py @@ -8,7 +8,30 @@ class ModelsResponse(BaseModel): """Model representing a response to models request.""" - models: list[dict[str, Any]] + models: list[dict[str, Any]] = Field( + ..., + description="List of models available", + examples=[ + { + "identifier": "openai/gpt-4-turbo", + "metadata": {}, + "api_model_type": "llm", + "provider_id": "openai", + "type": "model", + "provider_resource_id": "gpt-4-turbo", + "model_type": "llm", + }, + { + "identifier": "openai/gpt-3.5-turbo-0125", + "metadata": {}, + "api_model_type": "llm", + "provider_id": "openai", + "type": "model", + "provider_resource_id": "gpt-3.5-turbo-0125", + "model_type": "llm", + }, + ], + ) # TODO(lucasagomes): a lot of fields to add to QueryResponse. For now @@ -30,8 +53,18 @@ class QueryResponse(BaseModel): response: The response. """ - conversation_id: Optional[str] = None - response: str + conversation_id: Optional[str] = Field( + None, + description="The optional conversation ID (UUID)", + examples=["c5260aec-4d82-4370-9fdf-05cf908b3f16"], + ) + + response: str = Field( + description="Response from LLM", + examples=[ + "Kubernetes is an open-source container orchestration system for automating ..." + ], + ) # provides examples for /docs endpoint model_config = { @@ -62,8 +95,15 @@ class InfoResponse(BaseModel): ``` """ - name: str - version: str + name: str = Field( + description="Service name", + examples=["Lightspeed Stack"], + ) + + version: str = Field( + description="Service version", + examples=["0.1.0", "0.2.0", "1.0.0"], + ) # provides examples for /docs endpoint model_config = { @@ -483,7 +523,23 @@ class ConversationsListResponse(BaseModel): class ErrorResponse(BaseModel): """Model representing error response for query endpoint.""" - detail: dict[str, str] + detail: dict[str, str] = Field( + description="Error details", + examples=[ + { + "detail": { + "response": "Error while validation question", + "cause": "Failed to handle request to https://bam-api.res.ibm.com/v2/text", + }, + }, + { + "detail": { + "response": "Error retrieving conversation history", + "cause": "Invalid conversation ID 1237-e89b-12d3-a456-426614174000", + }, + }, + ], + ) model_config = { "json_schema_extra": { From 6421f351a7d574746d769b120be80d7e5aec4567 Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Thu, 14 Aug 2025 08:47:27 +0200 Subject: [PATCH 2/2] Regenerated OpenAPI specification --- docs/openapi.json | 121 ++++++++++++++++++++++++---------------- docs/openapi.md | 46 +++++++++++---- docs/output.md | 114 ++++++++++++++++++++++--------------- src/models/responses.py | 12 ++-- 4 files changed, 179 insertions(+), 114 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index bd1137dab..26d57d5d0 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -74,7 +74,7 @@ "models" ], "summary": "Models Endpoint Handler", - "description": "Handle requests to the /models endpoint.", + "description": "Handle requests to the /models endpoint.\n\nProcess GET requests to the /models endpoint, returning a list of available\nmodels from the Llama Stack service.\n\nRaises:\n HTTPException: If unable to connect to the Llama Stack server or if\n model retrieval fails for any reason.\n\nReturns:\n ModelsResponse: An object containing the list of available models.", "operationId": "models_endpoint_handler_v1_models_get", "responses": { "200": { @@ -300,7 +300,7 @@ "feedback" ], "summary": "Feedback Endpoint Handler", - "description": "Handle feedback requests.\n\nArgs:\n feedback_request: The request containing feedback information.\n ensure_feedback_enabled: The feedback handler (FastAPI Depends) that\n will handle feedback status checks.\n auth: The Authentication handler (FastAPI Depends) that will\n handle authentication Logic.\n\nReturns:\n Response indicating the status of the feedback storage request.", + "description": "Handle feedback requests.\n\nProcesses a user feedback submission, storing the feedback and\nreturning a confirmation response.\n\nArgs:\n feedback_request: The request containing feedback information.\n ensure_feedback_enabled: The feedback handler (FastAPI Depends) that\n will handle feedback status checks.\n auth: The Authentication handler (FastAPI Depends) that will\n handle authentication Logic.\n\nReturns:\n Response indicating the status of the feedback storage request.\n\nRaises:\n HTTPException: Returns HTTP 500 if feedback storage fails.", "operationId": "feedback_endpoint_handler_v1_feedback_post", "requestBody": { "content": { @@ -372,7 +372,7 @@ "feedback" ], "summary": "Feedback Status", - "description": "Handle feedback status requests.\n\nReturns:\n Response indicating the status of the feedback.", + "description": "Handle feedback status requests.\n\nReturn the current enabled status of the feedback\nfunctionality.\n\nReturns:\n StatusResponse: Indicates whether feedback collection is enabled.", "operationId": "feedback_status_v1_feedback_status_get", "responses": { "200": { @@ -441,7 +441,7 @@ "conversations" ], "summary": "Get Conversation Endpoint Handler", - "description": "Handle request to retrieve a conversation by ID.", + "description": "Handle request to retrieve a conversation by ID.\n\nRetrieve a conversation's chat history by its ID. Then fetches\nthe conversation session from the Llama Stack backend,\nsimplifies the session data to essential chat history, and\nreturns it in a structured response. Raises HTTP 400 for\ninvalid IDs, 404 if not found, 503 if the backend is\nunavailable, and 500 for unexpected errors.\n\nParameters:\n conversation_id (str): Unique identifier of the conversation to retrieve.\n\nReturns:\n ConversationResponse: Structured response containing the conversation\n ID and simplified chat history.", "operationId": "get_conversation_endpoint_handler_v1_conversations__conversation_id__get", "parameters": [ { @@ -513,7 +513,7 @@ "conversations" ], "summary": "Delete Conversation Endpoint Handler", - "description": "Handle request to delete a conversation by ID.", + "description": "Handle request to delete a conversation by ID.\n\nValidates the conversation ID format and attempts to delete the\ncorresponding session from the Llama Stack backend. Raises HTTP\nerrors for invalid IDs, not found conversations, connection\nissues, or unexpected failures.\n\nReturns:\n ConversationDeleteResponse: Response indicating the result of the deletion operation.", "operationId": "delete_conversation_endpoint_handler_v1_conversations__conversation_id__delete", "parameters": [ { @@ -807,11 +807,20 @@ "properties": { "user_id": { "type": "string", - "title": "User Id" + "title": "User Id", + "description": "User ID, for example UUID", + "examples": [ + "c5260aec-4d82-4370-9fdf-05cf908b3f16" + ] }, "username": { "type": "string", - "title": "Username" + "title": "Username", + "description": "User name", + "examples": [ + "John Doe", + "Adam Smith" + ] } }, "type": "object", @@ -860,14 +869,7 @@ "default": [] }, "authentication": { - "anyOf": [ - { - "$ref": "#/components/schemas/AuthenticationConfiguration" - }, - { - "type": "null" - } - ], + "$ref": "#/components/schemas/AuthenticationConfiguration", "default": { "module": "noop", "skip_tls_verification": false @@ -1140,33 +1142,6 @@ "title": "DatabaseConfiguration", "description": "Database configuration." }, - "DatabaseConfiguration": { - "properties": { - "sqlite": { - "anyOf": [ - { - "$ref": "#/components/schemas/SQLiteDatabaseConfiguration" - }, - { - "type": "null" - } - ] - }, - "postgres": { - "anyOf": [ - { - "$ref": "#/components/schemas/PostgreSQLDatabaseConfiguration" - }, - { - "type": "null" - } - ] - } - }, - "type": "object", - "title": "DatabaseConfiguration", - "description": "Database configuration." - }, "ErrorResponse": { "properties": { "detail": { @@ -1174,7 +1149,18 @@ "type": "string" }, "type": "object", - "title": "Detail" + "title": "Detail", + "description": "Error details", + "examples": [ + { + "cause": "Failed to handle request to https://bam-api.res.ibm.com/v2/text", + "response": "Error while validation question" + }, + { + "cause": "Invalid conversation ID 1237-e89b-12d3-a456-426614174000", + "response": "Error retrieving conversation history" + } + ] } }, "type": "object", @@ -1413,11 +1399,21 @@ "properties": { "name": { "type": "string", - "title": "Name" + "title": "Name", + "description": "Service name", + "examples": [ + "Lightspeed Stack" + ] }, "version": { "type": "string", - "title": "Version" + "title": "Version", + "description": "Service version", + "examples": [ + "0.1.0", + "0.2.0", + "1.0.0" + ] } }, "type": "object", @@ -1576,7 +1572,28 @@ "type": "object" }, "type": "array", - "title": "Models" + "title": "Models", + "description": "List of models available", + "examples": [ + { + "api_model_type": "llm", + "identifier": "openai/gpt-4-turbo", + "metadata": {}, + "model_type": "llm", + "provider_id": "openai", + "provider_resource_id": "gpt-4-turbo", + "type": "model" + }, + { + "api_model_type": "llm", + "identifier": "openai/gpt-3.5-turbo-0125", + "metadata": {}, + "model_type": "llm", + "provider_id": "openai", + "provider_resource_id": "gpt-3.5-turbo-0125", + "type": "model" + } + ] } }, "type": "object", @@ -1867,11 +1884,19 @@ "type": "null" } ], - "title": "Conversation Id" + "title": "Conversation Id", + "description": "The optional conversation ID (UUID)", + "examples": [ + "c5260aec-4d82-4370-9fdf-05cf908b3f16" + ] }, "response": { "type": "string", - "title": "Response" + "title": "Response", + "description": "Response from LLM", + "examples": [ + "Kubernetes is an open-source container orchestration system for automating ..." + ] } }, "type": "object", diff --git a/docs/openapi.md b/docs/openapi.md index 914499719..eaefd3683 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -171,8 +171,11 @@ Returns: Handle feedback status requests. +Return the current enabled status of the feedback +functionality. + Returns: - Response indicating the status of the feedback. + StatusResponse: Indicates whether feedback collection is enabled. @@ -205,6 +208,20 @@ Handle request to retrieve all conversations for the authenticated user. Handle request to retrieve a conversation by ID. +Retrieve a conversation's chat history by its ID. Then fetches +the conversation session from the Llama Stack backend, +simplifies the session data to essential chat history, and +returns it in a structured response. Raises HTTP 400 for +invalid IDs, 404 if not found, 503 if the backend is +unavailable, and 500 for unexpected errors. + +Parameters: + conversation_id (str): Unique identifier of the conversation to retrieve. + +Returns: + ConversationResponse: Structured response containing the conversation + ID and simplified chat history. + ### 🔗 Parameters @@ -228,6 +245,14 @@ Handle request to retrieve a conversation by ID. Handle request to delete a conversation by ID. +Validates the conversation ID format and attempts to delete the +corresponding session from the Llama Stack backend. Raises HTTP +errors for invalid IDs, not found conversations, connection +issues, or unexpected failures. + +Returns: + ConversationDeleteResponse: Response indicating the result of the deletion operation. + ### 🔗 Parameters @@ -391,8 +416,8 @@ Attributes: | Field | Type | Description | |-------|------|-------------| -| user_id | string | | -| username | string | | +| user_id | string | User ID, for example UUID | +| username | string | User name | ## Configuration @@ -556,8 +581,6 @@ Service customization. | system_prompt | | | - - ## DatabaseConfiguration @@ -578,7 +601,7 @@ Model representing error response for query endpoint. | Field | Type | Description | |-------|------|-------------| -| detail | object | | +| detail | object | Error details | ## FeedbackCategory @@ -710,8 +733,8 @@ Example: | Field | Type | Description | |-------|------|-------------| -| name | string | | -| version | string | | +| name | string | Service name | +| version | string | Service version | ## JwkConfiguration @@ -792,7 +815,7 @@ Model representing a response to models request. | Field | Type | Description | |-------|------|-------------| -| models | array | | +| models | array | List of models available | ## PostgreSQLDatabaseConfiguration @@ -876,8 +899,8 @@ Attributes: | Field | Type | Description | |-------|------|-------------| -| conversation_id | | | -| response | string | | +| conversation_id | | The optional conversation ID (UUID) | +| response | string | Response from LLM | ## ReadinessResponse @@ -1012,4 +1035,3 @@ User data collection configuration. | loc | array | | | msg | string | | | type | string | | - diff --git a/docs/output.md b/docs/output.md index c21cbc90b..0757bbc82 100644 --- a/docs/output.md +++ b/docs/output.md @@ -56,6 +56,16 @@ Returns: Handle requests to the /models endpoint. +Process GET requests to the /models endpoint, returning a list of available +models from the Llama Stack service. + +Raises: + HTTPException: If unable to connect to the Llama Stack server or if + model retrieval fails for any reason. + +Returns: + ModelsResponse: An object containing the list of available models. + @@ -144,6 +154,9 @@ Returns: Handle feedback requests. +Processes a user feedback submission, storing the feedback and +returning a confirmation response. + Args: feedback_request: The request containing feedback information. ensure_feedback_enabled: The feedback handler (FastAPI Depends) that @@ -154,6 +167,9 @@ Args: Returns: Response indicating the status of the feedback storage request. +Raises: + HTTPException: Returns HTTP 500 if feedback storage fails. + @@ -166,24 +182,22 @@ Returns: | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | Feedback received and stored | [FeedbackResponse](#feedbackresponse) - | -| 401 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) - | -| 403 | Client does not have permission to access resource | [ForbiddenResponse](#forbiddenresponse) - | -| 500 | User feedback can not be stored | [ErrorResponse](#errorresponse) - | -| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) - | +| 200 | Feedback received and stored | [FeedbackResponse](#feedbackresponse) | +| 401 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | +| 403 | Client does not have permission to access resource | [ForbiddenResponse](#forbiddenresponse) | +| 500 | User feedback can not be stored | [ErrorResponse](#errorresponse) | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ## GET `/v1/feedback/status` > **Feedback Status** Handle feedback status requests. +Return the current enabled status of the feedback +functionality. + Returns: - Response indicating the status of the feedback. + StatusResponse: Indicates whether feedback collection is enabled. @@ -193,8 +207,7 @@ Returns: | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | Successful Response | [StatusResponse](#statusresponse) - | +| 200 | Successful Response | [StatusResponse](#statusresponse) | ## GET `/v1/conversations` > **Get Conversations List Endpoint Handler** @@ -209,8 +222,7 @@ Handle request to retrieve all conversations for the authenticated user. | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) - | +| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) | | 503 | Service Unavailable | | ## GET `/v1/conversations/{conversation_id}` @@ -218,6 +230,20 @@ Handle request to retrieve all conversations for the authenticated user. Handle request to retrieve a conversation by ID. +Retrieve a conversation's chat history by its ID. Then fetches +the conversation session from the Llama Stack backend, +simplifies the session data to essential chat history, and +returns it in a structured response. Raises HTTP 400 for +invalid IDs, 404 if not found, 503 if the backend is +unavailable, and 500 for unexpected errors. + +Parameters: + conversation_id (str): Unique identifier of the conversation to retrieve. + +Returns: + ConversationResponse: Structured response containing the conversation + ID and simplified chat history. + ### 🔗 Parameters @@ -231,18 +257,24 @@ Handle request to retrieve a conversation by ID. | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | Successful Response | [ConversationResponse](#conversationresponse) - | +| 200 | Successful Response | [ConversationResponse](#conversationresponse) | | 404 | Not Found | | | 503 | Service Unavailable | | -| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) - | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ## DELETE `/v1/conversations/{conversation_id}` > **Delete Conversation Endpoint Handler** Handle request to delete a conversation by ID. +Validates the conversation ID format and attempts to delete the +corresponding session from the Llama Stack backend. Raises HTTP +errors for invalid IDs, not found conversations, connection +issues, or unexpected failures. + +Returns: + ConversationDeleteResponse: Response indicating the result of the deletion operation. + ### 🔗 Parameters @@ -256,12 +288,10 @@ Handle request to delete a conversation by ID. | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) - | +| 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) | | 404 | Not Found | | | 503 | Service Unavailable | | -| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) - | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ## GET `/readiness` > **Readiness Probe Get Method** @@ -280,10 +310,8 @@ service is ready. | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | Service is ready | [ReadinessResponse](#readinessresponse) - | -| 503 | Service is not ready | [ReadinessResponse](#readinessresponse) - | +| 200 | Service is ready | [ReadinessResponse](#readinessresponse) | +| 503 | Service is not ready | [ReadinessResponse](#readinessresponse) | ## GET `/liveness` > **Liveness Probe Get Method** @@ -301,10 +329,8 @@ Returns: | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | Service is alive | [LivenessResponse](#livenessresponse) - | -| 503 | Service is not alive | [LivenessResponse](#livenessresponse) - | +| 200 | Service is alive | [LivenessResponse](#livenessresponse) | +| 503 | Service is not alive | [LivenessResponse](#livenessresponse) | ## POST `/authorized` > **Authorized Endpoint Handler** @@ -325,12 +351,9 @@ Returns: | Status Code | Description | Component | |-------------|-------------|-----------| -| 200 | The user is logged-in and authorized to access OLS | [AuthorizedResponse](#authorizedresponse) - | -| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) - | -| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) - | +| 200 | The user is logged-in and authorized to access OLS | [AuthorizedResponse](#authorizedresponse) | +| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | +| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) | ## GET `/metrics` > **Metrics Endpoint Handler** @@ -415,8 +438,8 @@ Attributes: | Field | Type | Description | |-------|------|-------------| -| user_id | string | | -| username | string | | +| user_id | string | User ID, for example UUID | +| username | string | User name | ## Configuration @@ -580,7 +603,6 @@ Service customization. | system_prompt | | | - ## DatabaseConfiguration @@ -601,7 +623,7 @@ Model representing error response for query endpoint. | Field | Type | Description | |-------|------|-------------| -| detail | object | | +| detail | object | Error details | ## FeedbackCategory @@ -723,8 +745,8 @@ Example: | Field | Type | Description | |-------|------|-------------| -| name | string | | -| version | string | | +| name | string | Service name | +| version | string | Service version | ## JwkConfiguration @@ -805,7 +827,7 @@ Model representing a response to models request. | Field | Type | Description | |-------|------|-------------| -| models | array | | +| models | array | List of models available | ## PostgreSQLDatabaseConfiguration @@ -889,8 +911,8 @@ Attributes: | Field | Type | Description | |-------|------|-------------| -| conversation_id | | | -| response | string | | +| conversation_id | | The optional conversation ID (UUID) | +| response | string | Response from LLM | ## ReadinessResponse diff --git a/src/models/responses.py b/src/models/responses.py index a1204dfbd..cb8ee09c0 100644 --- a/src/models/responses.py +++ b/src/models/responses.py @@ -527,16 +527,12 @@ class ErrorResponse(BaseModel): description="Error details", examples=[ { - "detail": { - "response": "Error while validation question", - "cause": "Failed to handle request to https://bam-api.res.ibm.com/v2/text", - }, + "response": "Error while validation question", + "cause": "Failed to handle request to https://bam-api.res.ibm.com/v2/text", }, { - "detail": { - "response": "Error retrieving conversation history", - "cause": "Invalid conversation ID 1237-e89b-12d3-a456-426614174000", - }, + "response": "Error retrieving conversation history", + "cause": "Invalid conversation ID 1237-e89b-12d3-a456-426614174000", }, ], )