lightspeed-stack 0.1.2__tar.gz → 0.2.0__tar.gz

{lightspeed_stack-0.1.2 → lightspeed_stack-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lightspeed-stack
-Version: 0.1.2
+Version: 0.2.0
 Summary: LLM tooling stack
 Keywords: LLM,RAG
 Maintainer-Email: =?utf-8?b?UGF2ZWwgVGnFoW5vdnNrw70=?= <tisnik@centrum.cz>
@@ -215,17 +215,21 @@ 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.6
+Requires-Dist: fastapi>=0.115.12
 Requires-Dist: uvicorn>=0.34.3
 Requires-Dist: kubernetes>=30.1.0
-Requires-Dist: llama-stack==0.2.16
-Requires-Dist: llama-stack-client==0.2.16
+Requires-Dist: llama-stack==0.2.17
+Requires-Dist: llama-stack-client==0.2.17
 Requires-Dist: rich>=14.0.0
 Requires-Dist: cachetools>=6.1.0
 Requires-Dist: prometheus-client>=0.22.1
 Requires-Dist: starlette>=0.47.1
 Requires-Dist: aiohttp>=3.12.14
 Requires-Dist: authlib>=1.6.0
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: openai==1.99.9
+Requires-Dist: sqlalchemy>=2.0.42
+Requires-Dist: semver<4.0.0
 Description-Content-Type: text/markdown
 
 # lightspeed-stack
@@ -236,9 +240,11 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/badge/license-Apache-blue)](https://github.com/lightspeed-core/lightspeed-stack/blob/main/LICENSE)
 [![made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)](https://www.python.org/)
 [![Required Python version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Flightspeed-core%2Flightspeed-stack%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://www.python.org/)
-[![Tag](https://img.shields.io/github/v/tag/lightspeed-core/lightspeed-stack)](https://github.com/lightspeed-core/lightspeed-stack/releases/tag/0.1.2)
+[![Tag](https://img.shields.io/github/v/tag/lightspeed-core/lightspeed-stack)](https://github.com/lightspeed-core/lightspeed-stack/releases/tag/0.2.0)
 
 Lightspeed Core Stack (LCS) is an AI-powered assistant that provides answers to product questions using backend LLM services, agents, and RAG databases.
+ 
+The service includes comprehensive user data collection capabilities for various types of user interaction data, which can be exported to Red Hat's Dataverse for analysis using the companion [lightspeed-to-dataverse-exporter](https://github.com/lightspeed-core/lightspeed-to-dataverse-exporter) service.
 
 
 <!-- vim-markdown-toc GFM -->
@@ -249,11 +255,21 @@ Lightspeed Core Stack (LCS) is an AI-powered assistant that provides answers to
 * [Configuration](#configuration)
     * [Integration with Llama Stack](#integration-with-llama-stack)
     * [Llama Stack as separate server](#llama-stack-as-separate-server)
+        * [MCP Server and Tool Configuration](#mcp-server-and-tool-configuration)
+            * [Configuring MCP Servers](#configuring-mcp-servers)
+            * [Configuring MCP Headers](#configuring-mcp-headers)
         * [Llama Stack project and configuration](#llama-stack-project-and-configuration)
         * [Check connection to Llama Stack](#check-connection-to-llama-stack)
     * [Llama Stack as client library](#llama-stack-as-client-library)
+    * [Llama Stack version check](#llama-stack-version-check)
+    * [User data collection](#user-data-collection)
     * [System prompt](#system-prompt)
     * [Safety Shields](#safety-shields)
+    * [Authentication](#authentication)
+        * [K8s based authentication](#k8s-based-authentication)
+        * [JSON Web Keyset based authentication](#json-web-keyset-based-authentication)
+        * [No-op authentication](#no-op-authentication)
+* [RAG Configuration](#rag-configuration)
 * [Usage](#usage)
     * [Make targets](#make-targets)
     * [Running Linux container image](#running-linux-container-image)
@@ -272,10 +288,12 @@ Lightspeed Core Stack (LCS) is an AI-powered assistant that provides answers to
     * [Utility to generate OpenAPI schema](#utility-to-generate-openapi-schema)
         * [Path](#path)
         * [Usage](#usage-1)
-    * [Data Collector Service](#data-collector-service)
-        * [Features](#features)
-        * [Configuration](#configuration-1)
-        * [Running the Service](#running-the-service)
+* [Data Export Integration](#data-export-integration)
+    * [Quick Integration](#quick-integration)
+    * [Documentation](#documentation)
+* [Project structure](#project-structure)
+    * [Configuration classes](#configuration-classes)
+    * [REST API](#rest-api)
 
 <!-- vim-markdown-toc -->
 
@@ -317,13 +335,14 @@ Llama Stack Client. It is a library available for Python, Swift, Node.js or
 Kotlin, which "wraps" the REST API stack in a suitable way, which is easier for
 many applications.
 
+
 ![Integration with Llama Stack](docs/core2llama-stack_interface.png)
 
 
 
 ## Llama Stack as separate server
 
-If Llama Stack runs as a separate server, the Lightspeed service needs to be configured to be able to access it. For example, if server runs on localhost:8321, the service configuration stored in file `llama-stack.yaml` should look like:
+If Llama Stack runs as a separate server, the Lightspeed service needs to be configured to be able to access it. For example, if server runs on localhost:8321, the service configuration stored in file `lightspeed-stack.yaml` should look like:
 
 ```yaml
 name: foo bar baz
@@ -344,8 +363,45 @@ user_data_collection:
   transcripts_storage: "/tmp/data/transcripts"
 ```
 
+### MCP Server and Tool Configuration
+
+**Note**: The `run.yaml` configuration is currently an implementation detail. In the future, all configuration will be available directly from the lightspeed-core config.
+
+#### Configuring MCP Servers
+
+MCP (Model Context Protocol) servers provide tools and capabilities to the AI agents. These are configured in the `mcp_servers` section of your `lightspeed-stack.yaml`:
+
+```yaml
+mcp_servers:
+  - name: "filesystem-tools"
+    provider_id: "model-context-protocol"
+    url: "http://localhost:3000"
+  - name: "git-tools"
+    provider_id: "model-context-protocol"
+    url: "http://localhost:3001"
+  - name: "database-tools"
+    provider_id: "model-context-protocol"
+    url: "http://localhost:3002"
+```
+
+**Important**: Only MCP servers defined in the `lightspeed-stack.yaml` configuration are available to the agents. Tools configured in the llama-stack `run.yaml` are not accessible to lightspeed-core agents.
+
+#### Configuring MCP Headers
+
+MCP headers allow you to pass authentication tokens, API keys, or other metadata to MCP servers. These are configured **per request** via the `MCP-HEADERS` HTTP header:
+
+```bash
+curl -X POST "http://localhost:8080/v1/query" \
+  -H "Content-Type: application/json" \
+  -H "MCP-HEADERS: {\"filesystem-tools\": {\"Authorization\": \"Bearer token123\"}}" \
+  -d '{"query": "List files in /tmp"}'
+```
+
+
 ### Llama Stack project and configuration
 
+**Note**: The `run.yaml` configuration is currently an implementation detail. In the future, all configuration will be available directly from the lightspeed-core config.
+
 To run Llama Stack in separate process, you need to have all dependencies installed. The easiest way how to do it is to create a separate repository with Llama Stack project file `pyproject.toml` and Llama Stack configuration file `run.yaml`. The project file might look like:
 
 ```toml
@@ -423,6 +479,37 @@ user_data_collection:
   transcripts_storage: "/tmp/data/transcripts"
 ```
 
+## Llama Stack version check
+
+During Lightspeed Core Stack service startup, the Llama Stack version is retrieved. The version is tested against two constants `MINIMAL_SUPPORTED_LLAMA_STACK_VERSION` and `MAXIMAL_SUPPORTED_LLAMA_STACK_VERSION` which are defined in `src/constants.py`. If the actual Llama Stack version is outside the range defined by these two constants, the service won't start and administrator will be informed about this problem.
+
+
+
+## User data collection
+
+The Lightspeed Core Stack includes comprehensive user data collection capabilities to gather various types of user interaction data for analysis and improvement. This includes feedback, conversation transcripts, and other user interaction data.
+
+User data collection is configured in the `user_data_collection` section of the configuration file:
+
+```yaml
+user_data_collection:
+  feedback_enabled: true
+  feedback_storage: "/tmp/data/feedback"
+  transcripts_enabled: true
+  transcripts_storage: "/tmp/data/transcripts"
+```
+
+**Configuration options:**
+
+- `feedback_enabled`: Enable/disable collection of user feedback data
+- `feedback_storage`: Directory path where feedback JSON files are stored
+- `transcripts_enabled`: Enable/disable collection of conversation transcripts
+- `transcripts_storage`: Directory path where transcript JSON files are stored
+
+> **Note**: The data collection system is designed to be extensible. Additional data types can be configured and collected as needed for your specific use case.
+
+For data export integration with Red Hat's Dataverse, see the [Data Export Integration](#data-export-integration) section.
+
 ## System prompt
 
    The service uses the, so called, system prompt to put the question into context before the question is sent to the selected LLM. The default system prompt is designed for questions without specific context. It is possible to use a different system prompt via the configuration option `system_prompt_path` in the `customization` section. That option must contain the path to the text file with the actual system prompt (can contain multiple lines). An example of such configuration:
@@ -460,6 +547,161 @@ utilized:
 1. If the `shield_id` starts with `inout_`, it will be used both for input and output.
 1. Otherwise, it will be used for input only.
 
+## Authentication
+
+Currently supported authentication modules are:
+*  `k8s` Kubernetes based authentication
+*  `jwk-token` JSON Web Keyset based authentication
+*  `noop` No operation authentication (default)
+*  `noop-with-token` No operation authentication with token
+
+### K8s based authentication
+
+K8s based authentication is suitable for running the Lightspeed Stack in Kubernetes environments.
+The user accessing the service must have a valid Kubernetes token and the appropriate RBAC permissions to access the service.
+The user must have `get` permission on the Kubernetes RBAC non-resource URL `/ls-access`. 
+Here is an example of granting `get` on `/ls-access` via a ClusterRole’s nonResourceURLs rule. 
+Example:
+```yaml
+# Allow GET on non-resource URL /ls-access
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: lightspeed-access
+rules:
+  - nonResourceURLs: ["/ls-access"]
+    verbs: ["get"]
+---
+# Bind to a user, group, or service account
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: lightspeed-access-binding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: lightspeed-access
+subjects:
+  - kind: User            # or ServiceAccount, Group
+    name: SOME_USER_OR_SA
+    apiGroup: rbac.authorization.k8s.io
+```
+
+Configuring K8s based authentication requires the following steps:
+1. Enable K8s authentication module
+```yaml
+authentication:
+  module: "k8s"
+```
+2. Configure the Kubernetes authentication settings. 
+   When deploying Lightspeed Stack in a Kubernetes cluster, it is not required to specify cluster connection details.
+   It automatically picks up the in-cluster configuration or through a kubeconfig file.
+   This step is not neccessary.
+   When running outside a kubernetes cluster or connecting to external Kubernetes clusters, Lightspeed Stack requires the cluster connection details in the configuration file: 
+   - `k8s_cluster_api` Kubernetes Cluster API URL. The URL of the K8S/OCP API server where tokens are validated.
+   - `k8s_ca_cert_path` Path to the CA certificate file for clusters with self-signed certificates.
+   - `skip_tls_verification` Whether to skip TLS verification.
+```yaml
+authentication:
+  module: "k8s"
+  skip_tls_verification: false
+  k8s_cluster_api: "https://your-k8s-api-server:6443"
+  k8s_ca_cert_path: "/path/to/ca.crt"
+```
+
+### JSON Web Keyset based authentication
+
+JWK (JSON Web Keyset) based authentication is suitable for scenarios where you need to authenticate users based on tokens. This method is commonly used in web applications and APIs.
+
+To configure JWK based authentication, you need to specify the following settings in the configuration file:
+- `module` must be set to `jwk-token`
+- `jwk_config` JWK configuration settings must set at least `url` field:
+  - `url`: The URL of the JWK endpoint.
+  - `jwt_configuration`: JWT configuration settings.
+    - `user_id_claim`: The key of the user ID in JWT claim.
+    - `username_claim`: The key of the username in JWT claim.
+
+```yaml
+authentication:
+  module: "jwk-token"
+  jwk_config:
+    url: "https://your-jwk-url"
+    jwt_configuration:
+      user_id_claim: user_id
+      username_claim: username
+```
+
+### No-op authentication
+
+Lightspeed Stack provides 2 authentication module to bypass the authentication and authorization checks:
+- `noop` No operation authentication (default)
+- `noop-with-token` No operation authentication accepting a bearer token
+
+If authentication module is not specified, Lightspeed Stack will use `noop` by default.
+To activate `noop-with-token`, you need to specify it in the configuration file:
+
+```yaml
+authentication:
+  module: "noop-with-token"
+```
+
+## CORS
+
+It is possible to configure CORS handling. This configuration is part of service configuration:
+
+```yaml
+service:
+  host: localhost
+  port: 8080
+  auth_enabled: false
+  workers: 1
+  color_log: true
+  access_log: true
+  cors:
+    allow_origins:
+      - http://foo.bar.baz
+      - http://test.com
+    allow_credentials: true
+    allow_methods:
+      - *
+    allow_headers:
+      - *
+```
+
+### Default values
+
+```yaml
+  cors:
+    allow_origins:
+      - *
+    allow_credentials: false
+    allow_methods:
+      - *
+    allow_headers:
+      - *
+```
+
+## Allow credentials
+
+Credentials are not allowed with wildcard origins per CORS/Fetch spec.
+See https://fastapi.tiangolo.com/tutorial/cors/
+
+# RAG Configuration
+
+The [guide to RAG setup](docs/rag_guide.md) provides guidance on setting up RAG and includes tested examples for both inference and vector store integration.
+
+## Example configurations for inference
+
+The following configurations are llama-stack config examples from production deployments:
+
+- [Granite on vLLM example](examples/vllm-granite-run.yaml)
+- [Qwen3 on vLLM example](examples/vllm-qwen3-run.yaml)
+- [Gemini example](examples/gemini-run.yaml)
+- [VertexAI example](examples/vertexai-run.yaml)
+
+> [!NOTE]
+> RAG functionality is **not tested** for these configurations.
+
 # Usage
 
 ```
@@ -483,7 +725,6 @@ Usage: make <OPTIONS> ... <TARGETS>
 Available targets are:
 
 run                               Run the service locally
-run-data-collector                Run the data collector service
 test-unit                         Run the unit tests
 test-integration                  Run integration tests tests
 test-e2e                          Run BDD tests for the service
@@ -491,6 +732,7 @@ check-types                       Checks type hints in sources
 security-check                    Check the project for security issues
 format                            Format the code into unified format
 schema                            Generate OpenAPI schema file
+openapi-doc                       Generate OpenAPI documentation
 requirements.txt                  Generate requirements.txt file containing hashes for all non-devel packages
 shellcheck                        Run shellcheck
 verify                            Run all linters
@@ -520,6 +762,80 @@ Container images are built for the following platforms:
 1. `linux/amd64` - main platform for deployment
 1. `linux/arm64`- Mac users with M1/M2/M3 CPUs
 
+## Building Container Images
+
+The repository includes production-ready container configurations that support two deployment modes:
+
+1. **Server Mode**: lightspeed-core connects to llama-stack as a separate service
+2. **Library Mode**: llama-stack runs as a library within lightspeed-core
+
+### Llama-Stack as Separate Service (Server Mode)
+
+When using llama-stack as a separate service, the existing `docker-compose.yaml` provides the complete setup. This builds two containers for lightspeed core and llama stack.
+
+**Configuration** (`lightspeed-stack.yaml`):
+```yaml
+llama_stack:
+  use_as_library_client: false
+  url: http://llama-stack:8321  # container name from docker-compose.yaml
+  api_key: xyzzy
+```
+
+In the root of this project simply run:
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY="your-api-key-here"
+
+# Start both services
+podman compose up --build
+
+# Access lightspeed-core at http://localhost:8080
+# Access llama-stack at http://localhost:8321
+```
+
+### Llama-Stack as Library (Library Mode)
+
+When embedding llama-stack directly in the container, use the existing `Containerfile` directly (this will not build the llama stack service in a separate container). First modify the `lightspeed-stack.yaml` config to use llama stack in library mode.
+
+**Configuration** (`lightspeed-stack.yaml`):
+```yaml
+llama_stack:
+  use_as_library_client: true
+  library_client_config_path: /app-root/run.yaml
+```
+
+**Build and run**:
+```bash
+# Build lightspeed-core with embedded llama-stack
+podman build -f Containerfile -t my-lightspeed-core:latest .
+
+# Run with embedded llama-stack
+podman run \
+  -p 8080:8080 \
+  -v ./lightspeed-stack.yaml:/app-root/lightspeed-stack.yaml:Z \
+  -v ./run.yaml:/app-root/run.yaml:Z \
+  -e OPENAI_API_KEY=your-api-key \
+  my-lightspeed-core:latest
+```
+
+For macosx users:
+```bash
+podman run \
+  -p 8080:8080 \
+  -v ./lightspeed-stack.yaml:/app-root/lightspeed-stack.yaml:ro \
+  -v ./run.yaml:/app-root/run.yaml:ro \
+  -e OPENAI_API_KEY=your-api-key \
+  my-lightspeed-core:latest
+```
+
+### Verify it's running properly
+
+A simple sanity check:
+
+```bash
+curl -H "Accept: application/json" http://localhost:8080/v1/models
+```
 
 
 # Endpoints
@@ -651,51 +967,27 @@ This script re-generated OpenAPI schema for the Lightspeed Service REST API.
 make schema
 ```
 
-## Data Collector Service
-
-The data collector service is a standalone service that runs separately from the main web service. It is responsible for collecting and sending user data including feedback and transcripts to an ingress server for analysis and archival.
-
-### Features
+# Data Export Integration
 
-- **Periodic Collection**: Runs at configurable intervals
-- **Data Packaging**: Packages feedback and transcript files into compressed tar.gz archives
-- **Secure Transmission**: Sends data to a configured ingress server with optional authentication
-- **File Cleanup**: Optionally removes local files after successful transmission
-- **Error Handling**: Includes retry logic and comprehensive error handling
-
-### Configuration
-
-The data collector service is configured through the `user_data_collection.data_collector` section in your configuration file:
-
-```yaml
-user_data_collection:
-  feedback_enabled: true
-  feedback_storage: "/tmp/data/feedback"
-  transcripts_enabled: true
-  transcripts_storage: "/tmp/data/transcripts"
-  data_collector:
-    enabled: true
-    ingress_server_url: "https://your-ingress-server.com"
-    ingress_server_auth_token: "your-auth-token"
-    ingress_content_service_name: "lightspeed-team"
-    collection_interval: 7200  # 2 hours in seconds
-    cleanup_after_send: true
-    connection_timeout: 30
-```
+The Lightspeed Core Stack integrates with the [lightspeed-to-dataverse-exporter](https://github.com/lightspeed-core/lightspeed-to-dataverse-exporter) service to automatically export various types of user interaction data to Red Hat's Dataverse for analysis.
 
-### Running the Service
+## Quick Integration
 
-To run the data collector service:
+1. **Enable data collection** in your `lightspeed-stack.yaml`:
+   ```yaml
+   user_data_collection:
+     feedback_enabled: true
+     feedback_storage: "/shared/data/feedback"
+     transcripts_enabled: true
+     transcripts_storage: "/shared/data/transcripts"
+   ```
 
-```bash
-# Using Python directly
-uv run src/lightspeed_stack.py --data-collector
+2. **Deploy the exporter service** pointing to the same data directories
 
-# Using Make target
-make run-data-collector
-```
 
+## Documentation
 
+For complete integration setup, deployment options, and configuration details, see [exporter repository](https://github.com/lightspeed-core/lightspeed-to-dataverse-exporter).
 
 # Project structure