diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f760ff5b..ae4a1788 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ * [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 diff --git a/README.md b/README.md index 1a81d1e8..60b98824 100644 --- a/README.md +++ b/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: diff --git a/docs/README.md b/docs/README.md index eaece51d..65534f45 100644 --- a/docs/README.md +++ b/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/`. diff --git a/docs/testing.md b/docs/testing.md index 512c4835..2b78ce42 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,5 +1,23 @@ # Testing + + +* [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) + + + 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,15 +28,19 @@ 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 @@ -26,6 +48,19 @@ 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)