lightspeed-stack 0.1.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1 @@
+"""REST API service based on FastAPI."""

app/endpoints/.ruff_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by ruff.
+*

app/endpoints/.ruff_cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

app/endpoints/__init__.py

@@ -0,0 +1 @@
+"""Implementation of all endpoints."""

app/endpoints/config.py

@@ -0,0 +1,64 @@
+"""Handler for REST API call to retrieve service configuration."""
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Request
+
+from models.config import Configuration
+from configuration import configuration
+from utils.endpoints import check_configuration_loaded
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["config"])
+
+
+get_config_responses: dict[int | str, dict[str, Any]] = {
+    200: {
+        "name": "foo bar baz",
+        "service": {
+            "host": "localhost",
+            "port": 8080,
+            "auth_enabled": False,
+            "workers": 1,
+            "color_log": True,
+            "access_log": True,
+            "tls_config": {
+                "tls_certificate_path": "config/certificate.crt",
+                "tls_key_path": "config/private.key",
+                "tls_key_password": None,
+            },
+        },
+        "llama_stack": {
+            "url": "http://localhost:8321",
+            "api_key": "xyzzy",
+            "use_as_library_client": False,
+            "library_client_config_path": None,
+        },
+        "user_data_collection": {
+            "feedback_disabled": False,
+            "feedback_storage": "/tmp/data/feedback",
+            "transcripts_disabled": True,
+            "transcripts_storage": None,
+        },
+        "mcp_servers": [
+            {"name": "server1", "provider_id": "provider1", "url": "http://url.com:1"},
+            {"name": "server2", "provider_id": "provider2", "url": "http://url.com:2"},
+            {"name": "server3", "provider_id": "provider3", "url": "http://url.com:3"},
+        ],
+    },
+    503: {
+        "detail": {
+            "response": "Configuration is no loaded",
+        }
+    },
+}
+
+
+@router.get("/config", responses=get_config_responses)
+def config_endpoint_handler(_request: Request) -> Configuration:
+    """Handle requests to the /config endpoint."""
+    # ensure that configuration is loaded
+    check_configuration_loaded(configuration)
+
+    return configuration.configuration

app/endpoints/feedback.py

@@ -0,0 +1,129 @@
+"""Handler for REST API call to provide info."""
+
+import logging
+from typing import Any
+from pathlib import Path
+import json
+from datetime import datetime, UTC
+
+from fastapi import APIRouter, Request, HTTPException, Depends, status
+
+from auth import get_auth_dependency
+from configuration import configuration
+from models.responses import FeedbackResponse, StatusResponse
+from models.requests import FeedbackRequest
+from utils.suid import get_suid
+from utils.common import retrieve_user_id
+
+logger = logging.getLogger(__name__)
+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: {"response": "Feedback received and stored"},
+}
+
+
+def is_feedback_enabled() -> bool:
+    """Check if feedback is enabled.
+
+    Returns:
+        bool: True if feedback is enabled, False otherwise.
+    """
+    return not configuration.user_data_collection_configuration.feedback_disabled
+
+
+async def assert_feedback_enabled(_request: Request) -> None:
+    """Check if feedback is enabled.
+
+    Args:
+        request (Request): The FastAPI request object.
+
+    Raises:
+        HTTPException: If feedback is disabled.
+    """
+    feedback_enabled = is_feedback_enabled()
+    if not feedback_enabled:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Forbidden: Feedback is disabled",
+        )
+
+
+@router.post("", responses=feedback_response)
+def feedback_endpoint_handler(
+    _request: Request,
+    feedback_request: FeedbackRequest,
+    _ensure_feedback_enabled: Any = Depends(assert_feedback_enabled),
+    auth: Any = Depends(auth_dependency),
+) -> FeedbackResponse:
+    """Handle feedback requests.
+
+    Args:
+        feedback_request: The request containing feedback information.
+        ensure_feedback_enabled: The feedback handler (FastAPI Depends) that
+            will handle feedback status checks.
+        auth: The Authentication handler (FastAPI Depends) that will
+            handle authentication Logic.
+
+    Returns:
+        Response indicating the status of the feedback storage request.
+    """
+    logger.debug("Feedback received %s", str(feedback_request))
+
+    user_id = retrieve_user_id(auth)
+    try:
+        store_feedback(user_id, feedback_request.model_dump(exclude={"model_config"}))
+    except Exception as e:
+        logger.error("Error storing user feedback: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "response": "Error storing user feedback",
+                "cause": str(e),
+            },
+        ) from e
+
+    return FeedbackResponse(response="feedback received")
+
+
+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.
+    """
+    logger.debug("Storing feedback for user %s", user_id)
+    # Creates storage path only if it doesn't exist. The `exist_ok=True` prevents
+    # race conditions in case of multiple server instances trying to set up storage
+    # at the same location.
+    storage_path = Path(
+        configuration.user_data_collection_configuration.feedback_storage or ""
+    )
+    storage_path.mkdir(parents=True, exist_ok=True)
+
+    current_time = str(datetime.now(UTC))
+    data_to_store = {"user_id": user_id, "timestamp": current_time, **feedback}
+
+    # stores feedback in a file under unique uuid
+    feedback_file_path = storage_path / f"{get_suid()}.json"
+    with open(feedback_file_path, "w", encoding="utf-8") as feedback_file:
+        json.dump(data_to_store, feedback_file)
+
+    logger.info("Feedback stored sucessfully at %s", feedback_file_path)
+
+
+@router.get("/status")
+def feedback_status() -> StatusResponse:
+    """Handle feedback status requests.
+
+    Returns:
+        Response indicating the status of the feedback.
+    """
+    logger.debug("Feedback status requested")
+    feedback_status_enabled = is_feedback_enabled()
+    return StatusResponse(
+        functionality="feedback", status={"enabled": feedback_status_enabled}
+    )

app/endpoints/health.py

@@ -0,0 +1,111 @@
+"""Handlers for health REST API endpoints.
+
+These endpoints are used to check if service is live and prepared to accept
+requests. Note that these endpoints can be accessed using GET or HEAD HTTP
+methods. For HEAD HTTP method, just the HTTP response code is used.
+"""
+
+import logging
+from typing import Any
+
+from llama_stack.providers.datatypes import HealthStatus
+
+from fastapi import APIRouter, status, Response
+from client import get_llama_stack_client
+from configuration import configuration
+from models.responses import (
+    LivenessResponse,
+    ReadinessResponse,
+    ProviderHealthStatus,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["health"])
+
+
+def get_providers_health_statuses() -> list[ProviderHealthStatus]:
+    """Check health of all providers.
+
+    Returns:
+        List of provider health statuses.
+    """
+    try:
+        llama_stack_config = configuration.llama_stack_configuration
+
+        client = get_llama_stack_client(llama_stack_config)
+
+        providers = client.providers.list()
+        logger.debug("Found %d providers", len(providers))
+
+        health_results = [
+            ProviderHealthStatus(
+                provider_id=provider.provider_id,
+                status=str(provider.health.get("status", "unknown")),
+                message=str(provider.health.get("message", "")),
+            )
+            for provider in providers
+        ]
+        return health_results
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        # eg. no providers defined
+        logger.error("Failed to check providers health: %s", e)
+        return [
+            ProviderHealthStatus(
+                provider_id="unknown",
+                status=HealthStatus.ERROR.value,
+                message=f"Failed to initialize health check: {str(e)}",
+            )
+        ]
+
+
+get_readiness_responses: dict[int | str, dict[str, Any]] = {
+    200: {
+        "description": "Service is ready",
+        "model": ReadinessResponse,
+    },
+    503: {
+        "description": "Service is not ready",
+        "model": ReadinessResponse,
+    },
+}
+
+
+@router.get("/readiness", responses=get_readiness_responses)
+def readiness_probe_get_method(response: Response) -> ReadinessResponse:
+    """Ready status of service with provider health details."""
+    provider_statuses = get_providers_health_statuses()
+
+    # Check if any provider is unhealthy (not counting not_implemented as unhealthy)
+    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)}"
+        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+    else:
+        ready = True
+        reason = "All providers are healthy"
+
+    return ReadinessResponse(ready=ready, reason=reason, providers=unhealthy_providers)
+
+
+get_liveness_responses: dict[int | str, dict[str, Any]] = {
+    200: {
+        "description": "Service is alive",
+        "model": LivenessResponse,
+    },
+    503: {
+        "description": "Service is not alive",
+        "model": LivenessResponse,
+    },
+}
+
+
+@router.get("/liveness", responses=get_liveness_responses)
+def liveness_probe_get_method() -> LivenessResponse:
+    """Live status of service."""
+    return LivenessResponse(alive=True)

app/endpoints/info.py

@@ -0,0 +1,26 @@
+"""Handler for REST API call to provide info."""
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Request
+
+from version import __version__
+from models.responses import InfoResponse
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["info"])
+
+
+get_into_responses: dict[int | str, dict[str, Any]] = {
+    200: {
+        "name": "Service name",
+        "version": "Service version",
+    },
+}
+
+
+@router.get("/info", responses=get_into_responses)
+def info_endpoint_handler(_request: Request) -> InfoResponse:
+    """Handle request to the /info endpoint."""
+    return InfoResponse(name="foo", version=__version__)

app/endpoints/models.py

@@ -0,0 +1,79 @@
+"""Handler for REST API call to provide info."""
+
+import logging
+from typing import Any
+
+from llama_stack_client import APIConnectionError
+from fastapi import APIRouter, HTTPException, Request, status
+
+from client import get_llama_stack_client
+from configuration import configuration
+from models.responses import ModelsResponse
+from utils.endpoints import check_configuration_loaded
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["models"])
+
+
+models_responses: dict[int | str, dict[str, Any]] = {
+    200: {
+        "models": [
+            {
+                "identifier": "all-MiniLM-L6-v2",
+                "metadata": {"embedding_dimension": 384},
+                "api_model_type": "embedding",
+                "provider_id": "ollama",
+                "provider_resource_id": "all-minilm:latest",
+                "type": "model",
+                "model_type": "embedding",
+            },
+            {
+                "identifier": "llama3.2:3b-instruct-fp16",
+                "metadata": {},
+                "api_model_type": "llm",
+                "provider_id": "ollama",
+                "provider_resource_id": "llama3.2:3b-instruct-fp16",
+                "type": "model",
+                "model_type": "llm",
+            },
+        ]
+    },
+    503: {"description": "Connection to Llama Stack is broken"},
+}
+
+
+@router.get("/models", responses=models_responses)
+def models_endpoint_handler(_request: Request) -> ModelsResponse:
+    """Handle requests to the /models endpoint."""
+    check_configuration_loaded(configuration)
+
+    llama_stack_configuration = configuration.llama_stack_configuration
+    logger.info("LLama stack config: %s", llama_stack_configuration)
+
+    try:
+        # try to get Llama Stack client
+        client = get_llama_stack_client(llama_stack_configuration)
+        # retrieve models
+        models = client.models.list()
+        m = [dict(m) for m in models]
+        return ModelsResponse(models=m)
+    # connection to Llama Stack server
+    except APIConnectionError as e:
+        logger.error("Unable to connect to Llama Stack: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "response": "Unable to connect to Llama Stack",
+                "cause": str(e),
+            },
+        ) from e
+    # any other exception that can occur during model listing
+    except Exception as e:
+        logger.error("Unable to retrieve list of models: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "response": "Unable to retrieve list of models",
+                "cause": str(e),
+            },
+        ) from e