LCORE-304: devel documentation

CONTRIBUTING.md

@@ -4,7 +4,7 @@
 <!-- vim-markdown-toc GFM -->
 
 * [TLDR;](#tldr)
-* [Prerequisities](#prerequisities)
+* [Prerequisites](#prerequisites)
     * [Tooling installation](#tooling-installation)
 * [Setting up your development environment](#setting-up-your-development-environment)
 * [Definition of Done](#definition-of-done)
@@ -15,11 +15,6 @@
     * [Type hints checks](#type-hints-checks)
     * [Linters](#linters)
     * [Security checks](#security-checks)
-* [Testing](#testing)
-    * [Tips and hints for developing unit tests](#tips-and-hints-for-developing-unit-tests)
-        * [Patching](#patching)
-        * [Verifying that some exception is thrown](#verifying-that-some-exception-is-thrown)
-        * [Checking what was printed and logged to stdout or stderr by the tested code](#checking-what-was-printed-and-logged-to-stdout-or-stderr-by-the-tested-code)
 * [Code style](#code-style)
     * [Docstrings style](#docstrings-style)
 
@@ -34,7 +29,7 @@
 5. Submit PR from your fork to main branch of the project repo
 
 
-## Prerequisities
+## Prerequisites
 
 - git
 - Python 3.12 or 3.13

README.md

@@ -71,6 +71,8 @@ Installation steps depends on operation system. Please look at instructions for
 
 # Configuration
 
+
+
 ## Integration with Llama Stack
 
 The Llama Stack can be run as a standalone server and accessed via its the REST
@@ -82,9 +84,11 @@ 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 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 `llama-stack.yaml` should look like:
 
 ```yaml
 name: foo bar baz
@@ -105,6 +109,60 @@ user_data_collection:
   transcripts_storage: "/tmp/data/transcripts"
 ```
 
+### Llama Stack project and configuration
+
+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
+[project]
+name = "llama-stack-runner"
+version = "0.1.0"
+description = "Llama Stack runner"
+authors = []
+dependencies = [
+    "llama-stack==0.2.14",
+    "fastapi>=0.115.12",
+    "opentelemetry-sdk>=1.34.0",
+    "opentelemetry-exporter-otlp>=1.34.0",
+    "opentelemetry-instrumentation>=0.55b0",
+    "aiosqlite>=0.21.0",
+    "litellm>=1.72.1",
+    "uvicorn>=0.34.3",
+    "blobfile>=3.0.0",
+    "datasets>=3.6.0",
+    "sqlalchemy>=2.0.41",
+    "faiss-cpu>=1.11.0",
+    "mcp>=1.9.4",
+    "autoevals>=0.0.129",
+    "psutil>=7.0.0",
+    "torch>=2.7.1",
+    "peft>=0.15.2",
+    "trl>=0.18.2"]
+requires-python = "==3.12.*"
+readme = "README.md"
+license = {text = "MIT"}
+
+
+[tool.pdm]
+distribution = false
+```
+
+To run Llama Stack perform these two commands:
+
+```
+export OPENAI_API_KEY="sk-{YOUR-KEY}"
+
+uv run llama stack run run.yaml
+```
+
+### Check connection to Llama Stack
+
+```
+curl -X 'GET' localhost:8321/openapi.json | jq .
+```
+
+
+
 ## Llama Stack as client library
 
 There are situations in which it is not advisable to run two processors (one with Llama Stack, the other with a service). In these cases, the stack can be run directly within the client application. For such situations, the configuration file could look like:

docs/README.md

@@ -1 +1,4 @@
-# GitHub pages
+# Lightspeed-Stack Documentation
+
+Welcome. This directory is published via GitHub Pages.
+See the full documentation at [`../README.md`](../README.md) or browse sub-pages in `docs/`.

docs/testing.md

@@ -1,5 +1,23 @@
 # Testing
 
+<!-- vim-markdown-toc GFM -->
+
+* [Running tests](#running-tests)
+    * [Run all tests](#run-all-tests)
+    * [Select one group of tests](#select-one-group-of-tests)
+    * [Select individual test or group of tests to be run](#select-individual-test-or-group-of-tests-to-be-run)
+* [Unit tests](#unit-tests)
+    * [Unit tests structure](#unit-tests-structure)
+* [Integration tests](#integration-tests)
+* [End to end tests](#end-to-end-tests)
+* [Tips and hints](#tips-and-hints)
+    * [Developing unit tests](#developing-unit-tests)
+        * [Patching](#patching)
+        * [Verifying that some exception is thrown](#verifying-that-some-exception-is-thrown)
+        * [Checking what was printed and logged to stdout or stderr by the tested code](#checking-what-was-printed-and-logged-to-stdout-or-stderr-by-the-tested-code)
+
+<!-- vim-markdown-toc -->
+
 Three groups of software tests are used in this repository, each group from the test suite having different granularity. These groups are designed to represent three layers:
 
 1. Unit Tests
@@ -10,22 +28,39 @@ Three groups of software tests are used in this repository, each group from the
 
 ## Running tests
 
+### Run all tests
+
 Unit tests followed by integration and end to end tests can be started by using the following command:
 
-```
+```bash
 make test
 ```
 
+### Select one group of tests
+
 It is also possible to run just one selected group of tests:
 
-```
+```bash
 make test-unit                 Run the unit tests
 make test-integration          Run integration tests tests
 make test-e2e                  Run end to end tests
 ```
 
 
 
+### Select individual test or group of tests to be run
+
+```bash
+uv run python -m pytest -vv tests/unit/utils/
+```
+
+Or, if you prefer to see coverage information, use following command:
+
+```bash
+uv run python -m pytest -vv tests/unit/utils/ --cov=src/utils/ --cov-report term-missing
+```
+
+
 ## Unit tests
 
 Unit tests are based on the [Pytest framework](https://docs.pytest.org/en/) and code coverage is measured by the plugin [pytest-cov](https://github.com/pytest-dev/pytest-cov). For mocking and patching, the [unittest framework](https://docs.python.org/3/library/unittest.html) is used.
@@ -34,6 +69,8 @@ Currently code coverage threshold for integration tests is set to 60%. This valu
 
 As specified in Definition of Done, new changes need to be covered by tests.
 
+
+
 ### Unit tests structure
 
 * Defined in [tests/unit](https://github.com/lightspeed-core/lightspeed-stack/tree/main/tests/unit)