From 316eeefa40f9c02710b83456aaa057a14870b236 Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Wed, 13 Aug 2025 08:25:44 +0200 Subject: [PATCH 1/3] Better docstrings for conversation endpoints --- src/app/endpoints/conversations.py | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/src/app/endpoints/conversations.py b/src/app/endpoints/conversations.py index 87a0ce71..5be41228 100644 --- a/src/app/endpoints/conversations.py +++ b/src/app/endpoints/conversations.py @@ -204,7 +204,22 @@ async def get_conversation_endpoint_handler( conversation_id: str, auth: Any = Depends(auth_dependency), ) -> ConversationResponse: - """Handle request to retrieve a conversation by ID.""" + """ + 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. + """ check_configuration_loaded(configuration) # Validate conversation ID format @@ -286,7 +301,17 @@ async def delete_conversation_endpoint_handler( conversation_id: str, auth: Any = Depends(auth_dependency), ) -> ConversationDeleteResponse: - """Handle request to delete 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. + """ check_configuration_loaded(configuration) # Validate conversation ID format From d0e96d7282b312f65f450b0f66d928b90f1f52bf Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Wed, 13 Aug 2025 08:25:52 +0200 Subject: [PATCH 2/3] Better docstrings for feedback endpoints --- src/app/endpoints/feedback.py | 44 ++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/src/app/endpoints/feedback.py b/src/app/endpoints/feedback.py index c91b6857..c19640f9 100644 --- a/src/app/endpoints/feedback.py +++ b/src/app/endpoints/feedback.py @@ -24,6 +24,7 @@ router = APIRouter(prefix="/feedback", tags=["feedback"]) auth_dependency = get_auth_dependency() +# Response for the feedback endpoint feedback_response: dict[int | str, dict[str, Any]] = { 200: { "description": "Feedback received and stored", @@ -45,22 +46,29 @@ def is_feedback_enabled() -> bool: - """Check if feedback is enabled. + """ + Check if feedback is enabled. + + Return whether user feedback collection is currently enabled + based on configuration. Returns: - bool: True if feedback is enabled, False otherwise. + bool: True if feedback collection is enabled; otherwise, False. """ return configuration.user_data_collection_configuration.feedback_enabled async def assert_feedback_enabled(_request: Request) -> None: - """Check if feedback is enabled. + """ + Ensures that feedback collection is enabled. + + Raises an HTTP 403 error if it is not. Args: request (Request): The FastAPI request object. Raises: - HTTPException: If feedback is disabled. + HTTPException: If feedback collection is disabled. """ feedback_enabled = is_feedback_enabled() if not feedback_enabled: @@ -78,6 +86,9 @@ def feedback_endpoint_handler( ) -> FeedbackResponse: """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 @@ -87,6 +98,9 @@ def feedback_endpoint_handler( Returns: Response indicating the status of the feedback storage request. + + Raises: + HTTPException: Returns HTTP 500 if feedback storage fails. """ logger.debug("Feedback received %s", str(feedback_request)) @@ -107,11 +121,15 @@ def feedback_endpoint_handler( def store_feedback(user_id: str, feedback: dict) -> None: - """Store feedback in the local filesystem. - - Args: - user_id: The user ID (UUID). - feedback: The feedback to store. + """ + Store feedback in the local filesystem. + + Persist user feedback to a uniquely named JSON file in the + configured local storage directory. + + Parameters: + user_id (str): Unique identifier of the user submitting feedback. + feedback (dict): Feedback data to be stored, merged with user ID and timestamp. """ logger.debug("Storing feedback for user %s", user_id) # Creates storage path only if it doesn't exist. The `exist_ok=True` prevents @@ -135,10 +153,14 @@ def store_feedback(user_id: str, feedback: dict) -> None: @router.get("/status") def feedback_status() -> StatusResponse: - """Handle feedback status requests. + """ + 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. """ logger.debug("Feedback status requested") feedback_status_enabled = is_feedback_enabled() From 14b0c1620802666a9a244807143c02a92d968b0c Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Wed, 13 Aug 2025 08:26:00 +0200 Subject: [PATCH 3/3] Better docstrings for model list endpoint --- src/app/endpoints/conversations.py | 3 ++- src/app/endpoints/feedback.py | 4 ++-- src/app/endpoints/models.py | 16 ++++++++++++++-- 3 files changed, 18 insertions(+), 5 deletions(-) diff --git a/src/app/endpoints/conversations.py b/src/app/endpoints/conversations.py index 5be41228..38d25b1b 100644 --- a/src/app/endpoints/conversations.py +++ b/src/app/endpoints/conversations.py @@ -218,7 +218,8 @@ async def get_conversation_endpoint_handler( conversation_id (str): Unique identifier of the conversation to retrieve. Returns: - ConversationResponse: Structured response containing the conversation ID and simplified chat history. + ConversationResponse: Structured response containing the conversation + ID and simplified chat history. """ check_configuration_loaded(configuration) diff --git a/src/app/endpoints/feedback.py b/src/app/endpoints/feedback.py index c19640f9..17fa1c00 100644 --- a/src/app/endpoints/feedback.py +++ b/src/app/endpoints/feedback.py @@ -60,7 +60,7 @@ def is_feedback_enabled() -> bool: async def assert_feedback_enabled(_request: Request) -> None: """ - Ensures that feedback collection is enabled. + Ensure that feedback collection is enabled. Raises an HTTP 403 error if it is not. @@ -126,7 +126,7 @@ def store_feedback(user_id: str, feedback: dict) -> None: Persist user feedback to a uniquely named JSON file in the configured local storage directory. - + Parameters: user_id (str): Unique identifier of the user submitting feedback. feedback (dict): Feedback data to be stored, merged with user ID and timestamp. diff --git a/src/app/endpoints/models.py b/src/app/endpoints/models.py index d583f390..feac9e4c 100644 --- a/src/app/endpoints/models.py +++ b/src/app/endpoints/models.py @@ -1,4 +1,4 @@ -"""Handler for REST API call to provide info.""" +"""Handler for REST API call to list available models.""" import logging from typing import Any @@ -44,7 +44,19 @@ @router.get("/models", responses=models_responses) async def models_endpoint_handler(_request: Request) -> ModelsResponse: - """Handle requests to the /models endpoint.""" + """ + 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. + """ check_configuration_loaded(configuration) llama_stack_configuration = configuration.llama_stack_configuration