diff --git a/docs/openapi.json b/docs/openapi.json index 17a77b73b..aec8c65f1 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -28,7 +28,7 @@ "root" ], "summary": "Root Endpoint Handler", - "description": "Handle GET requests to the root (\"/\") endpoint and returns the static HTML index page.\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- HTMLResponse: The HTML content of the index page, including a heading,\n embedded image with the service icon, and links to the API documentation\n via Swagger UI and ReDoc.", + "description": "Handle GET requests to the root (\"/\") endpoint and returns the static HTML index page.\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\n### Returns:\n- HTMLResponse: The HTML content of the index page, including a heading,\n embedded image with the service icon, and links to the API documentation\n via Swagger UI and ReDoc.", "operationId": "root_endpoint_handler__get", "responses": { "200": { @@ -172,7 +172,7 @@ "info" ], "summary": "Info Endpoint Handler", - "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\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 500 and a detail object\n containing `response` and `cause` when unable to connect to\n Llama Stack. It can also return status 401 or 403 for\n unauthorized access.\n\n### Returns:\n- InfoResponse: An object containing the service's name and version.", + "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\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 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- InfoResponse: An object containing the service's name and version.", "operationId": "info_endpoint_handler_v1_info_get", "responses": { "200": { @@ -323,7 +323,7 @@ "models" ], "summary": "Models Endpoint Handler", - "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. It is possible to specify \"model_type\"\nquery parameter that is used as a filter. For example, if model type is set\nto \"llm\", only LLM models will be returned:\n\n curl http://localhost:8080/v1/models?model_type=llm\n\nThe \"model_type\" query parameter is optional. When not specified, all models\nwill be returned.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- model_type: Optional filter to return only models matching this type.\n\n### Raises:\n- HTTPException: If unable to connect to the Llama Stack server or if\n model retrieval fails for any reason.\n\n### Returns:\n- ModelsResponse: An object containing the list of available models.", + "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. It is possible to specify \"model_type\"\nquery parameter that is used as a filter. For example, if model type is set\nto \"llm\", only LLM models will be returned:\n\n curl http://localhost:8080/v1/models?model_type=llm\n\nThe \"model_type\" query parameter is optional. When not specified, all models\nwill be returned.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- model_type: Optional filter to return only models matching this type.\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 422 if model_type parameter is\n improper.\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- ModelsResponse: An object containing the list of available models.", "operationId": "models_endpoint_handler_v1_models_get", "parameters": [ { @@ -536,7 +536,7 @@ "tools" ], "summary": "Tools Endpoint Handler", - "description": "Handle requests to the /tools endpoint.\n\nProcess GET requests to the /tools endpoint, returning a consolidated list of\navailable tools from all configured MCP servers.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- mcp_headers: Headers that should be passed to MCP servers.\n### Raises:\n- HTTPException: If unable to connect to the Llama Stack server or if tool\n retrieval fails for any reason.\n\n### Returns:\n- ToolsResponse: An object containing the consolidated list of available\n tools with metadata including tool name, description, parameters, and\n server source.", + "description": "Handle requests to the /tools endpoint.\n\nProcess GET requests to the /tools endpoint, returning a consolidated list of\navailable tools from all configured MCP servers.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- mcp_headers: Headers that should be passed to MCP servers.\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 422 if mcp_headers parameter is\n improper.\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- ToolsResponse: An object containing the consolidated list of available\n tools with metadata including tool name, description, parameters, and\n server source.", "operationId": "tools_endpoint_handler_v1_tools_get", "responses": { "200": { diff --git a/docs/openapi.md b/docs/openapi.md index b2f1b512d..6a32d05d7 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -5,7 +5,6 @@ Lightspeed Core Service (LCS) service API specification. - * [🌍 Base URL](#-base-url) * [🛠️ APIs](#-apis) * [List of REST API endpoints](#list-of-rest-api-endpoints) * [GET `/`](#get-) @@ -474,6 +473,10 @@ Handle GET requests to the root ("/") endpoint and returns the static HTML index - 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. + ### Returns: - HTMLResponse: The HTML content of the index page, including a heading, embedded image with the service icon, and links to the API documentation @@ -533,10 +536,10 @@ service name, version and Llama-stack version. - auth: Authentication tuple from the auth dependency (used by middleware). ### Raises: -- HTTPException: with status 500 and a detail object - containing `response` and `cause` when unable to connect to - Llama Stack. It can also return status 401 or 403 for - unauthorized access. +- HTTPException: with status 401 for unauthorized access. +- HTTPException: with status 403 if permission is denied. +- HTTPException: with status 503 and a detail object containing `response` + and `cause` when unable to connect to Llama Stack. ### Returns: - InfoResponse: An object containing the service's name and version. @@ -668,8 +671,14 @@ will be returned. - model_type: Optional filter to return only models matching this type. ### Raises: -- HTTPException: If unable to connect to the Llama Stack server or if - model retrieval fails for any reason. +- HTTPException: with status 401 for unauthorized access. +- HTTPException: with status 403 if permission is denied. +- HTTPException: with status 422 if model_type parameter is + improper. +- 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: - ModelsResponse: An object containing the list of available models. @@ -754,9 +763,16 @@ available tools from all configured MCP servers. - request: The incoming HTTP request (used by middleware). - auth: Authentication tuple from the auth dependency (used by middleware). - mcp_headers: Headers that should be passed to MCP servers. + ### Raises: -- HTTPException: If unable to connect to the Llama Stack server or if tool - retrieval fails for any reason. +- HTTPException: with status 401 for unauthorized access. +- HTTPException: with status 403 if permission is denied. +- HTTPException: with status 422 if mcp_headers parameter is + improper. +- 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: - ToolsResponse: An object containing the consolidated list of available diff --git a/src/app/endpoints/info.py b/src/app/endpoints/info.py index 2acd89b03..52490e611 100644 --- a/src/app/endpoints/info.py +++ b/src/app/endpoints/info.py @@ -52,10 +52,10 @@ async def info_endpoint_handler( - auth: Authentication tuple from the auth dependency (used by middleware). ### Raises: - - HTTPException: with status 500 and a detail object - containing `response` and `cause` when unable to connect to - Llama Stack. It can also return status 401 or 403 for - unauthorized access. + - HTTPException: with status 401 for unauthorized access. + - HTTPException: with status 403 if permission is denied. + - HTTPException: with status 503 and a detail object containing `response` + and `cause` when unable to connect to Llama Stack. ### Returns: - InfoResponse: An object containing the service's name and version. diff --git a/src/app/endpoints/models.py b/src/app/endpoints/models.py index e094992ef..fa435a6f9 100644 --- a/src/app/endpoints/models.py +++ b/src/app/endpoints/models.py @@ -98,8 +98,14 @@ async def models_endpoint_handler( - model_type: Optional filter to return only models matching this type. ### Raises: - - HTTPException: If unable to connect to the Llama Stack server or if - model retrieval fails for any reason. + - HTTPException: with status 401 for unauthorized access. + - HTTPException: with status 403 if permission is denied. + - HTTPException: with status 422 if model_type parameter is + improper. + - 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: - ModelsResponse: An object containing the list of available models. diff --git a/src/app/endpoints/root.py b/src/app/endpoints/root.py index 45d7d4bb6..956a6805b 100644 --- a/src/app/endpoints/root.py +++ b/src/app/endpoints/root.py @@ -801,6 +801,10 @@ async def root_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. + ### Returns: - HTMLResponse: The HTML content of the index page, including a heading, embedded image with the service icon, and links to the API documentation diff --git a/src/app/endpoints/tools.py b/src/app/endpoints/tools.py index 222e1fc7a..f0941a6a6 100644 --- a/src/app/endpoints/tools.py +++ b/src/app/endpoints/tools.py @@ -119,9 +119,16 @@ async def tools_endpoint_handler( # pylint: disable=too-many-locals,too-many-st - request: The incoming HTTP request (used by middleware). - auth: Authentication tuple from the auth dependency (used by middleware). - mcp_headers: Headers that should be passed to MCP servers. + ### Raises: - - HTTPException: If unable to connect to the Llama Stack server or if tool - retrieval fails for any reason. + - HTTPException: with status 401 for unauthorized access. + - HTTPException: with status 403 if permission is denied. + - HTTPException: with status 422 if mcp_headers parameter is + improper. + - 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: - ToolsResponse: An object containing the consolidated list of available