Merge pull request #1927 from tisnik/lcore-2572-2

LCORE-2572: Updated description for /providers, /shields and /rags endpoints.

Author: tisnik

docs/openapi.json

@@ -1500,7 +1500,7 @@
                     "shields"
                 ],
                 "summary": "Shields Endpoint Handler",
-                "description": "Handle requests to the /shields endpoint.\n\nProcess GET requests to the /shields endpoint, returning a list of available\nshields from the Llama Stack service.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- ShieldsResponse: An object containing the list of available shields.\n\n### Raises:\n- HTTPException: If unable to connect to the Llama Stack server or if\n  shield retrieval fails for any reason.",
+                "description": "Handle requests to the /shields endpoint.\n\nProcess GET requests to the /shields endpoint, returning a list of available\nshields from the Llama Stack service.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 500 and a detail object containing `response`\n  and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n  and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- ShieldsResponse: An object containing the list of available shields.",
                 "operationId": "shields_endpoint_handler_v1_shields_get",
                 "responses": {
                     "200": {
@@ -1677,7 +1677,7 @@
                     "providers"
                 ],
                 "summary": "Providers Endpoint Handler",
-                "description": "List all available providers grouped by API type.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\n\n### Returns:\n- ProvidersListResponse: Mapping from API type to list of providers.\n\n### Raises:\n- HTTPException:\n- 401: Authentication failed\n- 403: Authorization failed\n- 500: Lightspeed Stack configuration not loaded\n- 503: Unable to connect to Llama Stack",
+                "description": "List all available providers grouped by API type.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 500 and a detail object containing `response`\n  and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n  and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- ProvidersListResponse: Mapping from API type to list of providers.",
                 "operationId": "providers_endpoint_handler_v1_providers_get",
                 "responses": {
                     "200": {
@@ -3211,7 +3211,7 @@
                     "rags"
                 ],
                 "summary": "Rags Endpoint Handler",
-                "description": "List all available RAGs.\n\nReturns:\n    RAGListResponse: List of RAG identifiers.\n\nRaises:\n    HTTPException:\n        - 401: Authentication failed\n        - 403: Authorization failed\n        - 500: Lightspeed Stack configuration not loaded\n        - 503: Unable to connect to Llama Stack",
+                "description": "List all available RAGs.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 500 and a detail object containing `response`\n  and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n  and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n    - RAGListResponse: List of RAG identifiers.",
                 "operationId": "rags_endpoint_handler_v1_rags_get",
                 "responses": {
                     "200": {

docs/openapi.md

@@ -1,11 +1,11 @@
-# Lightspeed Core Service (LCS) service - OpenAPI
+# Lightspeed Core Stack (LCS) service - OpenAPI
 
-Lightspeed Core Service (LCS) service API specification.
+Lightspeed Core Stack (LCS) service API specification.
 
 
 <!-- vim-markdown-toc GFM -->
 
-* [🛠️ APIs](#-apis)
+* [🛠️ APIs](#apis)
     * [List of REST API endpoints](#list-of-rest-api-endpoints)
     * [GET `/`](#get-)
         * [Parameters:](#parameters)
@@ -192,7 +192,6 @@ Lightspeed Core Service (LCS) service API specification.
         * [✅ Responses](#-responses-42)
     * [GET `/a2a/health`](#get-a2ahealth)
         * [✅ Responses](#-responses-43)
-    * [| 200 | Successful Response | object |](#-200--successful-response--object-)
 * [📋 Components](#-components)
     * [A2AStateConfiguration](#a2astateconfiguration)
     * [APIKeySecurityScheme](#apikeysecurityscheme)
@@ -398,7 +397,7 @@ Lightspeed Core Service (LCS) service API specification.
 
 | URL | Description |
 |-----|-------------|
-| http://localhost:8080/ | Locally running service |
+| http://localhost:8080 | Locally running service |
 
 
 # 🛠️ APIs
@@ -1248,13 +1247,17 @@ shields from the Llama Stack service.
 - request: The incoming HTTP request (used by middleware).
 - auth: Authentication tuple from the auth dependency (used by middleware).
 
+### Raises:
+- HTTPException: with status 401 for unauthorized access.
+- HTTPException: with status 403 if permission is denied.
+- HTTPException: with status 500 and a detail object containing `response`
+  and `cause` when service configuration is wrong or incomplete.
+- HTTPException: with status 503 and a detail object containing `response`
+  and `cause` when unable to connect to Llama Stack.
+
 ### Returns:
 - ShieldsResponse: An object containing the list of available shields.
 
-### Raises:
-- HTTPException: If unable to connect to the Llama Stack server or if
-  shield retrieval fails for any reason.
-
 
 
 
@@ -1343,15 +1346,17 @@ List all available providers grouped by API type.
 - request: The incoming HTTP request.
 - auth: Authentication tuple from the auth dependency.
 
+### Raises:
+- HTTPException: with status 401 for unauthorized access.
+- HTTPException: with status 403 if permission is denied.
+- HTTPException: with status 500 and a detail object containing `response`
+  and `cause` when service configuration is wrong or incomplete.
+- HTTPException: with status 503 and a detail object containing `response`
+  and `cause` when unable to connect to Llama Stack.
+
 ### Returns:
 - ProvidersListResponse: Mapping from API type to list of providers.
 
-### Raises:
-- HTTPException:
-- 401: Authentication failed
-- 403: Authorization failed
-- 500: Lightspeed Stack configuration not loaded
-- 503: Unable to connect to Llama Stack
 
 
 
@@ -2174,15 +2179,20 @@ Examples
 
 List all available RAGs.
 
-Returns:
-    RAGListResponse: List of RAG identifiers.
+### Parameters:
+- request: The incoming HTTP request (used by middleware).
+- auth: Authentication tuple from the auth dependency (used by middleware).
 
-Raises:
-    HTTPException:
-        - 401: Authentication failed
-        - 403: Authorization failed
-        - 500: Lightspeed Stack configuration not loaded
-        - 503: Unable to connect to Llama Stack
+### Raises:
+- HTTPException: with status 401 for unauthorized access.
+- HTTPException: with status 403 if permission is denied.
+- HTTPException: with status 500 and a detail object containing `response`
+  and `cause` when service configuration is wrong or incomplete.
+- HTTPException: with status 503 and a detail object containing `response`
+  and `cause` when unable to connect to Llama Stack.
+
+### Returns:
+    - RAGListResponse: List of RAG identifiers.
 
 
 

src/app/endpoints/providers.py

@@ -67,15 +67,16 @@ async def providers_endpoint_handler(
     - request: The incoming HTTP request.
     - auth: Authentication tuple from the auth dependency.
 
+    ### Raises:
+    - HTTPException: with status 401 for unauthorized access.
+    - HTTPException: with status 403 if permission is denied.
+    - HTTPException: with status 500 and a detail object containing `response`
+      and `cause` when service configuration is wrong or incomplete.
+    - HTTPException: with status 503 and a detail object containing `response`
+      and `cause` when unable to connect to Llama Stack.
+
     ### Returns:
     - ProvidersListResponse: Mapping from API type to list of providers.
-
-    ### Raises:
-    - HTTPException:
-    - 401: Authentication failed
-    - 403: Authorization failed
-    - 500: Lightspeed Stack configuration not loaded
-    - 503: Unable to connect to Llama Stack
     """
     # Used only by the middleware
     _ = auth

src/app/endpoints/rags.py

@@ -62,15 +62,20 @@ async def rags_endpoint_handler(
     """
     List all available RAGs.
 
-    Returns:
-        RAGListResponse: List of RAG identifiers.
-
-    Raises:
-        HTTPException:
-            - 401: Authentication failed
-            - 403: Authorization failed
-            - 500: Lightspeed Stack configuration not loaded
-            - 503: Unable to connect to Llama Stack
+    ### Parameters:
+    - request: The incoming HTTP request (used by middleware).
+    - auth: Authentication tuple from the auth dependency (used by middleware).
+
+    ### Raises:
+    - HTTPException: with status 401 for unauthorized access.
+    - HTTPException: with status 403 if permission is denied.
+    - HTTPException: with status 500 and a detail object containing `response`
+      and `cause` when service configuration is wrong or incomplete.
+    - HTTPException: with status 503 and a detail object containing `response`
+      and `cause` when unable to connect to Llama Stack.
+
+    ### Returns:
+        - RAGListResponse: List of RAG identifiers.
     """
     # Used only by the middleware
     _ = auth

src/app/endpoints/shields.py

@@ -54,12 +54,16 @@ async def shields_endpoint_handler(
     - request: The incoming HTTP request (used by middleware).
     - auth: Authentication tuple from the auth dependency (used by middleware).
 
+    ### Raises:
+    - HTTPException: with status 401 for unauthorized access.
+    - HTTPException: with status 403 if permission is denied.
+    - HTTPException: with status 500 and a detail object containing `response`
+      and `cause` when service configuration is wrong or incomplete.
+    - HTTPException: with status 503 and a detail object containing `response`
+      and `cause` when unable to connect to Llama Stack.
+
     ### Returns:
     - ShieldsResponse: An object containing the list of available shields.
-
-    ### Raises:
-    - HTTPException: If unable to connect to the Llama Stack server or if
-      shield retrieval fails for any reason.
     """
     # Used only by the middleware
     _ = auth