lightspeed-stack 0.6.0rc2__tar.gz → 0.6.5__tar.gz

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: lightspeed-stack
-Version: 0.6.0rc2
+Version: 0.6.5
 Summary: LLM tooling stack
 Keywords: LLM,RAG
-Maintainer-Email: =?utf-8?b?UGF2ZWwgVGnFoW5vdnNrw70=?= <tisnik@centrum.cz>
+Maintainer-Email: Pavel Tišnovský <tisnik@centrum.cz>
 License:                                  Apache License
                                     Version 2.0, January 2004
                                  http://www.apache.org/licenses/
@@ -215,7 +215,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Project-URL: Homepage, https://github.com/lightspeed-core/lightspeed-stack
 Project-URL: Issues, https://github.com/lightspeed-core/lightspeed-stack/issues
 Requires-Python: <3.14,>=3.12
-Requires-Dist: fastapi>=0.115.12
+Requires-Dist: fastapi>=0.138.0
 Requires-Dist: uvicorn>=0.34.3
 Requires-Dist: kubernetes>=30.1.0
 Requires-Dist: llama-stack==0.6.0
@@ -249,6 +249,9 @@ Requires-Dist: datasets>=4.7.0
 Requires-Dist: sentry-sdk[fastapi]>=2.58.0
 Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: tiktoken>=0.8.0
+Requires-Dist: pydantic-ai>=1.99.0
+Requires-Dist: pydantic-ai-skills>=0.11.0
+Requires-Dist: setuptools-scm<10
 Description-Content-Type: text/markdown
 
 # Lightspeed Core Stack (LCS)
@@ -395,7 +398,7 @@ Lightspeed Core Stack is based on the FastAPI framework (Uvicorn). The service i
   | IBM WatsonX     | https://www.ibm.com/products/watsonx                                  |
   | AWS Bedrock     | https://aws.amazon.com/bedrock                                        |
   | RHOAI (vLLM)    | See tests/e2e-prow/rhoai/configs/run.yaml                             |
-  | RHEL AI (vLLM)  | See tests/e2e/configs/run-rhelai.yaml                                 |
+  | RHEL AI (RHAIIS/vLLM) | See tests/e2e/configs/run-rhelai.yaml                            |
 
   See `docs/providers.md` for configuration details.
 
@@ -413,8 +416,23 @@ Lightspeed Core Stack is based on the FastAPI framework (Uvicorn). The service i
 
 # Installation
 
-Installation steps depends on operation system. Please look at instructions for your system:
+## Clone the Repository
+
+Lightspeed Stack uses a git submodule for external providers (required for features like OKP RAG). Clone with submodules:
 
+```bash
+git clone --recursive https://github.com/lightspeed-core/lightspeed-stack.git
+cd lightspeed-stack
+```
+
+**If you already cloned without `--recursive`:**
+```bash
+git submodule update --init
+```
+
+## System-Specific Installation
+
+Installation steps depends on operation system. Please look at instructions for your system:
 
 - [Linux installation](https://lightspeed-core.github.io/lightspeed-stack/installation_linux)
 - [macOS installation](https://lightspeed-core.github.io/lightspeed-stack/installation_macos)
@@ -441,7 +459,7 @@ To quickly get hands on LCS, we can run it using the default configurations prov
    ```
 4. access LCS web UI at [http://localhost:8080/](http://localhost:8080/)
 
-**Note**: `make run` uses containerized llama-stack (service mode). To run llama-stack manually instead, see the [Llama Stack as separate server](#llama-stack-as-separate-server) section below.
+**Note**: `make run` uses containerized llama-stack (service mode). For details on container lifecycle management, customization, and troubleshooting, see the [Container Orchestration Guide](docs/container_orchestration.md). To run llama-stack manually instead, see the [Llama Stack as separate server](#llama-stack-as-separate-server) section below.
 
 ## Container Runtime Requirements
 
@@ -452,6 +470,8 @@ The Makefile requires either Podman or Docker to launch the Llama Stack containe
 
 The Makefile will auto-detect which runtime is available.
 
+**For advanced usage** including customization options, cleanup commands, and troubleshooting, see the [Container Orchestration Guide](docs/container_orchestration.md).
+
 
 # Configuration
 
@@ -478,8 +498,7 @@ __Note__: Support for individual models is dependent on the specific inference p
 | OpenAI         | gpt-5, gpt-4o, gpt-4-turbo, gpt-4.1, o1, o3, o4                               | Yes           | remote::openai   | [1](examples/openai-faiss-run.yaml) [2](examples/openai-pgvector-run.yaml) |
 | OpenAI         | gpt-3.5-turbo, gpt-4                                                         | No            | remote::openai   |                                                                            |
 | RHOAI (vLLM)   | meta-llama/Llama-3.2-1B-Instruct                                             | Yes           | remote::vllm     | [1](tests/e2e-prow/rhoai/configs/run.yaml)                                 |
-| RHAIIS (vLLM)  | meta-llama/Llama-3.1-8B-Instruct                                             | Yes           | remote::vllm     | [1](tests/e2e/configs/run-rhaiis.yaml)                                     |
-| RHEL AI (vLLM) | meta-llama/Llama-3.1-8B-Instruct                                             | Yes           | remote::vllm     | [1](tests/e2e/configs/run-rhelai.yaml)                                     |
+| RHEL AI (RHAIIS/vLLM) | meta-llama/Llama-3.1-8B-Instruct                                      | Yes           | remote::vllm     | [1](tests/e2e/configs/run-rhelai.yaml) [2](tests/e2e/configs/run-rhaiis.yaml) |
 | Azure          | gpt-5, gpt-5-mini, gpt-5-nano, gpt-4o-mini, o3-mini, o4-mini, o1             | Yes           | remote::azure    | [1](examples/azure-run.yaml)                                               |
 | Azure          | gpt-5-chat, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano,  o1-mini                    | No or limited | remote::azure    |                                                                            |
 | VertexAI       | google/gemini-2.0-flash, google/gemini-2.5-flash, google/gemini-2.5-pro [^1] | Yes           | remote::vertexai | [1](examples/vertexai-run.yaml)                                            |

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/README.md

@@ -142,7 +142,7 @@ Lightspeed Core Stack is based on the FastAPI framework (Uvicorn). The service i
   | IBM WatsonX     | https://www.ibm.com/products/watsonx                                  |
   | AWS Bedrock     | https://aws.amazon.com/bedrock                                        |
   | RHOAI (vLLM)    | See tests/e2e-prow/rhoai/configs/run.yaml                             |
-  | RHEL AI (vLLM)  | See tests/e2e/configs/run-rhelai.yaml                                 |
+  | RHEL AI (RHAIIS/vLLM) | See tests/e2e/configs/run-rhelai.yaml                            |
 
   See `docs/providers.md` for configuration details.
 
@@ -160,8 +160,23 @@ Lightspeed Core Stack is based on the FastAPI framework (Uvicorn). The service i
 
 # Installation
 
-Installation steps depends on operation system. Please look at instructions for your system:
+## Clone the Repository
+
+Lightspeed Stack uses a git submodule for external providers (required for features like OKP RAG). Clone with submodules:
 
+```bash
+git clone --recursive https://github.com/lightspeed-core/lightspeed-stack.git
+cd lightspeed-stack
+```
+
+**If you already cloned without `--recursive`:**
+```bash
+git submodule update --init
+```
+
+## System-Specific Installation
+
+Installation steps depends on operation system. Please look at instructions for your system:
 
 - [Linux installation](https://lightspeed-core.github.io/lightspeed-stack/installation_linux)
 - [macOS installation](https://lightspeed-core.github.io/lightspeed-stack/installation_macos)
@@ -188,7 +203,7 @@ To quickly get hands on LCS, we can run it using the default configurations prov
    ```
 4. access LCS web UI at [http://localhost:8080/](http://localhost:8080/)
 
-**Note**: `make run` uses containerized llama-stack (service mode). To run llama-stack manually instead, see the [Llama Stack as separate server](#llama-stack-as-separate-server) section below.
+**Note**: `make run` uses containerized llama-stack (service mode). For details on container lifecycle management, customization, and troubleshooting, see the [Container Orchestration Guide](docs/container_orchestration.md). To run llama-stack manually instead, see the [Llama Stack as separate server](#llama-stack-as-separate-server) section below.
 
 ## Container Runtime Requirements
 
@@ -199,6 +214,8 @@ The Makefile requires either Podman or Docker to launch the Llama Stack containe
 
 The Makefile will auto-detect which runtime is available.
 
+**For advanced usage** including customization options, cleanup commands, and troubleshooting, see the [Container Orchestration Guide](docs/container_orchestration.md).
+
 
 # Configuration
 
@@ -225,8 +242,7 @@ __Note__: Support for individual models is dependent on the specific inference p
 | OpenAI         | gpt-5, gpt-4o, gpt-4-turbo, gpt-4.1, o1, o3, o4                               | Yes           | remote::openai   | [1](examples/openai-faiss-run.yaml) [2](examples/openai-pgvector-run.yaml) |
 | OpenAI         | gpt-3.5-turbo, gpt-4                                                         | No            | remote::openai   |                                                                            |
 | RHOAI (vLLM)   | meta-llama/Llama-3.2-1B-Instruct                                             | Yes           | remote::vllm     | [1](tests/e2e-prow/rhoai/configs/run.yaml)                                 |
-| RHAIIS (vLLM)  | meta-llama/Llama-3.1-8B-Instruct                                             | Yes           | remote::vllm     | [1](tests/e2e/configs/run-rhaiis.yaml)                                     |
-| RHEL AI (vLLM) | meta-llama/Llama-3.1-8B-Instruct                                             | Yes           | remote::vllm     | [1](tests/e2e/configs/run-rhelai.yaml)                                     |
+| RHEL AI (RHAIIS/vLLM) | meta-llama/Llama-3.1-8B-Instruct                                      | Yes           | remote::vllm     | [1](tests/e2e/configs/run-rhelai.yaml) [2](tests/e2e/configs/run-rhaiis.yaml) |
 | Azure          | gpt-5, gpt-5-mini, gpt-5-nano, gpt-4o-mini, o3-mini, o4-mini, o1             | Yes           | remote::azure    | [1](examples/azure-run.yaml)                                               |
 | Azure          | gpt-5-chat, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano,  o1-mini                    | No or limited | remote::azure    |                                                                            |
 | VertexAI       | google/gemini-2.0-flash, google/gemini-2.5-flash, google/gemini-2.5-pro [^1] | Yes           | remote::vertexai | [1](examples/vertexai-run.yaml)                                            |

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/pyproject.toml

@@ -21,7 +21,7 @@ keywords = [
 requires-python = ">=3.12,<3.14"
 readme = "README.md"
 dependencies = [
-    "fastapi>=0.115.12",
+    "fastapi>=0.138.0",
     "uvicorn>=0.34.3",
     "kubernetes>=30.1.0",
     "llama-stack==0.6.0",
@@ -55,8 +55,11 @@ dependencies = [
     "sentry-sdk[fastapi]>=2.58.0",
     "python-dotenv>=1.2.2",
     "tiktoken>=0.8.0",
+    "pydantic-ai>=1.99.0",
+    "pydantic-ai-skills>=0.11.0",
+    "setuptools-scm<10",
 ]
-version = "0.6.0rc2"
+version = "0.6.5"
 
 [project.license]
 file = "LICENSE"
@@ -104,6 +107,10 @@ pythonpath = [
 addopts = [
     "--import-mode=importlib",
 ]
+markers = [
+    "destructive: marks tests as destructive (deselect with '-m \"not destructive\"')",
+    "order: controls test execution order (requires pytest-order plugin)",
+]
 
 [tool.pylint.main]
 source-roots = "src"
@@ -116,6 +123,11 @@ disable = [
     "R0801",
 ]
 
+[tool.black]
+target-version = [
+    "py312",
+]
+
 [tool.ruff]
 line-length = 88
 extend-exclude = [
@@ -157,6 +169,7 @@ dev = [
     "pytest-cov>=5.0.0",
     "pytest-mock>=3.14.0",
     "pytest-asyncio>=1.0.0",
+    "pytest-order>=1.2.0",
     "pyright>=1.1.401",
     "pylint>=3.3.7",
     "pydocstyle>=6.3.0",
@@ -196,7 +209,7 @@ llslibdev = [
     "transformers>=4.34.0",
     "numpy==2.3.5",
     "mcp>=1.23.0",
-    "torch==2.9.0",
+    "torch==2.10.0",
     "trl>=0.18.2",
     "peft>=0.15.2",
     "google-cloud-aiplatform>=1.130.0",
@@ -210,6 +223,7 @@ llslibdev = [
     "pydantic>=2.10.6",
     "protobuf>=6.33.5",
     "filelock>=3.20.3",
+    "uv-build==0.11.8",
 ]
 build = [
     "build>=1.2.2.post1",

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/src/app/endpoints/README.md

@@ -57,6 +57,9 @@ Handler for REST API calls to list and retrieve available RAGs.
 ## [responses.py](responses.py)
 Handler for REST API call to provide answer using Responses API (LCORE specification).
 
+## [responses_telemetry.py](responses_telemetry.py)
+Splunk telemetry helpers for the Responses API endpoint.
+
 ## [rlsapi_v1.py](rlsapi_v1.py)
 Handler for RHEL Lightspeed rlsapi v1 REST API endpoints.
 

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/src/app/endpoints/a2a.py

@@ -1,5 +1,7 @@
 """Handler for A2A (Agent-to-Agent) protocol endpoints using Responses API."""
 
+# pylint: disable=too-many-lines
+
 import asyncio
 import json
 import uuid
@@ -32,7 +34,7 @@ from fastapi import APIRouter, Depends, HTTPException, Request, status
 from llama_stack_api.openai_responses import (
     OpenAIResponseObjectStream,
 )
-from llama_stack_client import APIConnectionError
+from llama_stack_client import APIConnectionError, AsyncLlamaStackClient
 from starlette.responses import Response, StreamingResponse
 
 from a2a_storage import A2AContextStore, A2AStorageFactory
@@ -45,13 +47,18 @@ from configuration import configuration
 from constants import MEDIA_TYPE_EVENT_STREAM
 from log import get_logger
 from models.api.requests import QueryRequest
+from models.common.responses.types import ResponseInput
 from models.config import Action
+from utils.conversation_compaction import (
+    apply_compaction_blocking,
+    store_compacted_turn,
+)
 from utils.mcp_headers import McpHeaders, mcp_headers_dependency
 from utils.responses import (
     extract_text_from_response_item,
     prepare_responses_params,
 )
-from utils.suid import normalize_conversation_id
+from utils.suid import normalize_conversation_id, to_llama_stack_conversation_id
 from version import __version__
 
 logger = get_logger(__name__)
@@ -336,6 +343,19 @@ class A2AAgentExecutor(AgentExecutor):
                 store=True,
                 request_headers=self.request_headers,
             )
+            # Compact the conversation if it is approaching the context window
+            # limit. A2A is not a browser SSE stream, so no progress event is
+            # emitted; the blocking variant summarizes inline before the call.
+            # No conversation cache is passed: the A2A executor has no resolved
+            # user_id for the (user_id, conversation_id) cache key, so A2A runs
+            # in marker-only mode (additive summaries, no persisted fold).
+            compaction = await apply_compaction_blocking(
+                client,
+                responses_params,
+                configuration.inference,
+                configuration.compaction,
+            )
+            responses_params = compaction.params
             # Stream response from LLM using the Responses API
             stream = await client.responses.create(**responses_params.model_dump())
         except APIConnectionError as e:
@@ -392,9 +412,16 @@ class A2AAgentExecutor(AgentExecutor):
             )
         )
 
-        # Process stream using generator and aggregator pattern
+        # Process stream using generator and aggregator pattern. In compacted
+        # mode the conversation parameter is not sent, so the turn is stored
+        # explicitly once the response completes (see _convert_stream_to_events).
         async for a2a_event in self._convert_stream_to_events(
-            stream, task_id, context_id, conversation_id
+            stream,
+            task_id,
+            context_id,
+            conversation_id,
+            client,
+            compaction.original_input if compaction.compacted else None,
         ):
             aggregator.process_event(a2a_event)
             await event_queue.enqueue_event(a2a_event)
@@ -414,12 +441,14 @@ class A2AAgentExecutor(AgentExecutor):
                 final=True,
             )
 
-    async def _convert_stream_to_events(  # pylint: disable=too-many-branches,too-many-locals
+    async def _convert_stream_to_events(  # pylint: disable=too-many-branches,too-many-locals,too-many-arguments,too-many-positional-arguments
         self,
         stream: AsyncIterator[OpenAIResponseObjectStream],
         task_id: str,
         context_id: str,
         conversation_id: Optional[str],
+        client: Optional[AsyncLlamaStackClient] = None,
+        compacted_original_input: Optional[ResponseInput] = None,
     ) -> AsyncIterator[Any]:
         """Convert Responses API stream chunks to A2A events.
 
@@ -508,6 +537,20 @@ class A2AAgentExecutor(AgentExecutor):
 
                 if response_obj:
                     output = getattr(response_obj, "output", [])
+                    # In compacted mode the conversation parameter was not sent,
+                    # so persist this turn ourselves to keep the recent-turn
+                    # buffer and audit history intact for the next request.
+                    if (
+                        compacted_original_input is not None
+                        and client is not None
+                        and conversation_id
+                    ):
+                        await store_compacted_turn(
+                            client,
+                            to_llama_stack_conversation_id(conversation_id),
+                            compacted_original_input,
+                            output,
+                        )
                     a2a_parts = _convert_responses_content_to_a2a_parts(output)
                     if not a2a_parts and final_text:
                         a2a_parts = [Part(root=TextPart(text=final_text))]
@@ -642,8 +685,17 @@ async def get_agent_card(  # pylint: disable=unused-argument
     This endpoint provides the agent card that describes Lightspeed's
     capabilities according to the A2A protocol specification.
 
-    Returns:
-        AgentCard: The agent card describing this agent's capabilities.
+    ### Parameters:
+    - auth: Authentication tuple from the auth dependency (used by middleware).
+
+    ### Raises:
+    - 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:
+    - AgentCard: The agent card describing this agent's capabilities.
     """
     try:
         logger.info("Serving A2A Agent Card")
@@ -714,23 +766,29 @@ async def handle_a2a_jsonrpc_get(
     Thin wrapper that delegates to ``_handle_a2a_jsonrpc`` so GET and POST share
     the same processing path while keeping distinct OpenAPI operation metadata.
 
-    Args:
-        request: Incoming ASGI/FastAPI request (body, scope, headers).
-        auth: Resolved authentication tuple from ``auth_dependency`` (user
-            identity and bearer token used to build the per-request A2A app).
-        mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
-            into the A2A executor for downstream tool/context propagation.
+    ### Parameters:
+    - request: Incoming ASGI/FastAPI request (body, scope, headers).
+    - auth: Resolved authentication tuple from ``auth_dependency`` (user
+      identity and bearer token used to build the per-request A2A app).
+    - mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
+      into the A2A executor for downstream tool/context propagation.
+
+    ### 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:
+    - ``Response`` with the full buffered JSON-RPC (or HTTP)
+      payload when the request is non-streaming, or
+      ``StreamingResponse`` (SSE) when the JSON-RPC method is
+      ``message/stream`` and chunks are streamed to the client.
+      Error conditions are generally expressed as JSON-RPC or HTTP
+      responses rather than by raising from this wrapper.
 
-    Returns:
-        ``Response`` with the full buffered JSON-RPC (or HTTP) payload when the
-        request is non-streaming, or ``StreamingResponse`` (SSE) when the
-        JSON-RPC method is ``message/stream`` and chunks are streamed to the
-        client. Error conditions are generally expressed as JSON-RPC or HTTP
-        responses rather than by raising from this wrapper.
-
-    Raises:
-        HTTPException: If authentication or ``@authorize`` rejects the request
-            before or while entering the handler chain.
     """
     return await _handle_a2a_jsonrpc(request, auth, mcp_headers)
 
@@ -756,23 +814,27 @@ async def handle_a2a_jsonrpc_post(
     Thin wrapper that delegates to ``_handle_a2a_jsonrpc`` so GET and POST share
     the same processing path while keeping distinct OpenAPI operation metadata.
 
-    Args:
-        request: Incoming ASGI/FastAPI request (body, scope, headers).
-        auth: Resolved authentication tuple from ``auth_dependency`` (user
-            identity and bearer token used to build the per-request A2A app).
-        mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
-            into the A2A executor for downstream tool/context propagation.
+    ### Parameters:
+    - request: Incoming ASGI/FastAPI request (body, scope, headers).
+    - auth: Resolved authentication tuple from ``auth_dependency`` (user
+      identity and bearer token used to build the per-request A2A app).
+    - mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
+      into the A2A executor for downstream tool/context propagation.
+
+    ### Raises:
+    - 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:
+    - ``Response`` with the full buffered JSON-RPC (or HTTP)
+      payload when the request is non-streaming, or
+      ``StreamingResponse`` (SSE) when the JSON-RPC method is
+      ``message/stream`` and chunks are streamed to the client.
+      Error conditions are generally expressed as JSON-RPC or HTTP
+      responses rather than by raising from this wrapper.
 
-    Returns:
-        ``Response`` with the full buffered JSON-RPC (or HTTP) payload when the
-        request is non-streaming, or ``StreamingResponse`` (SSE) when the
-        JSON-RPC method is ``message/stream`` and chunks are streamed to the
-        client. Error conditions are generally expressed as JSON-RPC or HTTP
-        responses rather than by raising from this wrapper.
-
-    Raises:
-        HTTPException: If authentication or ``@authorize`` rejects the request
-            before or while entering the handler chain.
     """
     return await _handle_a2a_jsonrpc(request, auth, mcp_headers)
 
@@ -965,8 +1027,14 @@ async def a2a_health_check() -> dict[str, str]:
     """
     Health check endpoint for A2A service.
 
-    Returns:
-        Dict with health status information.
+    ### Parameters:
+    - None
+
+    ### Raises:
+    - None
+
+    ### Returns:
+    - Dict with health status information.
     """
     return {
         "status": "healthy",

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/src/app/endpoints/config.py

@@ -51,6 +51,14 @@ async def config_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:
     - ConfigurationResponse: The loaded service configuration response.
     """

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/src/app/endpoints/health.py

@@ -26,8 +26,12 @@ from models.api.responses.successful import (
     LivenessResponse,
     ReadinessResponse,
 )
-from models.common import HealthStatus, ProviderHealthStatus
+from models.common import (
+    HealthStatus,
+    ProviderHealthStatus,
+)
 from models.config import Action
+from utils.degraded_mode import DegradedModeTracker
 
 logger = get_logger(__name__)
 router = APIRouter(tags=["health"])
@@ -117,40 +121,86 @@ async def readiness_probe_get_method(
     response: Response,
 ) -> ReadinessResponse:
     """
-    Handle the readiness probe endpoint, returning service readiness.
+    Handle the readiness probe endpoint, returning service readiness and health status.
 
-    If any provider reports an error status, responds with HTTP 503
-    and details of unhealthy providers; otherwise, indicates the
-    service is ready.
+    Returns comprehensive health information including overall service status,
+    provider health, and functional impacts. The service is considered "ready" even
+    in degraded mode (returns 200), but reports reduced functionality.
 
     ### Parameters:
     - response: The outgoing HTTP response (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 503 when service is unhealthy (providers down,
+      models unavailable) and degraded mode is not enabled.
+
     ### Returns:
-    - ReadinessResponse: Object with `ready` indicating overall readiness,
-      `reason` explaining the outcome, and `providers` containing the list of
-      unhealthy ProviderHealthStatus entries (empty when ready).
+    - ReadinessResponse: Object with comprehensive health status including:
+      - ready: True if service can handle requests (even in degraded mode)
+      - reason: Description of service state
+      - overall_status: healthy, degraded, or unhealthy
+      - impacts: Functional limitations when degraded/unhealthy
+      - providers: List of unhealthy providers
     """
     # Used only for authorization
     _ = auth
 
-    logger.info("Response to /v1/readiness endpoint")
+    logger.info("Response to /readiness endpoint")
 
-    provider_statuses = await get_providers_health_statuses()
+    degraded_tracker = DegradedModeTracker()
+    is_degraded = degraded_tracker.is_degraded()
+
+    # Determine overall status
+    if is_degraded:
+        # Service is ready (can serve health checks, metrics, etc.) but degraded
+        impacts = [
+            "LLM inference unavailable",
+            "RAG functionality unavailable",
+            "Agent tools unavailable",
+        ]
+        return ReadinessResponse(
+            ready=True,
+            reason="Service running in degraded mode",
+            overall_status=HealthStatus.DEGRADED,
+            impacts=impacts,
+            providers=[],
+        )
 
-    # Check if any provider is unhealthy (not counting not_implemented as unhealthy)
+    # Not in degraded mode - check provider health
+    provider_statuses = await get_providers_health_statuses()
     unhealthy_providers = [
         p for p in provider_statuses if p.status == HealthStatus.ERROR.value
     ]
 
     if unhealthy_providers:
-        ready = False
-        unhealthy_provider_names = [p.provider_id for p in unhealthy_providers]
-        reason = f"Providers not healthy: {', '.join(unhealthy_provider_names)}"
+        # Check if this is a connection error (provider_id="unknown")
+        is_connection_error = any(
+            p.provider_id == "unknown" for p in unhealthy_providers
+        )
+
+        if is_connection_error:
+            reason = "Cannot connect to backend service"
+            impacts = [
+                "LLM inference unavailable",
+                "Provider health checks unavailable",
+            ]
+        else:
+            unhealthy_provider_names = [p.provider_id for p in unhealthy_providers]
+            reason = f"Providers not healthy: {', '.join(unhealthy_provider_names)}"
+            impacts = [
+                f"Provider {p.provider_id}: {p.message}" for p in unhealthy_providers
+            ]
+
         response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
         return ReadinessResponse(
-            ready=ready, reason=reason, providers=unhealthy_providers
+            ready=False,
+            reason=reason,
+            overall_status=HealthStatus.UNHEALTHY,
+            impacts=impacts,
+            providers=unhealthy_providers if not is_connection_error else [],
         )
 
     # Check that the default model is registered in the model registry
@@ -158,11 +208,20 @@ async def readiness_probe_get_method(
     if not model_available:
         response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
         return ReadinessResponse(
-            ready=False, reason=model_reason, providers=unhealthy_providers
+            ready=False,
+            reason=model_reason,
+            overall_status=HealthStatus.UNHEALTHY,
+            impacts=["Default model not available in registry"],
+            providers=[],
         )
 
+    # All healthy
     return ReadinessResponse(
-        ready=True, reason="All providers are healthy", providers=unhealthy_providers
+        ready=True,
+        reason="All providers are healthy",
+        overall_status=HealthStatus.HEALTHY,
+        impacts=None,
+        providers=[],
     )
 
 
@@ -177,6 +236,14 @@ async def liveness_probe_get_method(
     ### Parameters:
     - 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:
     - LivenessResponse: Indicates that the service is alive.
     """

{lightspeed_stack-0.6.0rc2 → lightspeed_stack-0.6.5}/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.