diff --git a/README.md b/README.md index e46c8f36c..3285ab416 100644 --- a/README.md +++ b/README.md @@ -685,7 +685,12 @@ service: access_log: true llama_stack: use_as_library_client: true - library_client_config_path: + # Unified mode (recommended): LCORE synthesizes the Llama Stack run.yaml. + # Point profile at a run.yaml-shaped file you author, or omit the config + # block and drive everything from the top-level inference.providers + # section over the built-in default baseline. + config: + profile: user_data_collection: feedback_enabled: true feedback_storage: "/tmp/data/feedback" @@ -693,6 +698,12 @@ user_data_collection: transcripts_storage: "/tmp/data/transcripts" ``` +> [!WARNING] +> The legacy two-file setup (`library_client_config_path:` pointing at an +> externally maintained `run.yaml`) is deprecated — it logs a startup +> warning since 0.6 and is removed in 0.7. See the +> [migration guide](docs/user_doc/deployment_guide.md#migrating-from-the-legacy-two-file-configuration). + ## 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. @@ -1048,7 +1059,11 @@ When embedding llama-stack directly in the container, use the existing `deploy/l ```yaml llama_stack: use_as_library_client: true - library_client_config_path: /app-root/run.yaml + # Unified mode: the mounted run.yaml is the synthesis profile. (The + # legacy library_client_config_path equivalent is deprecated, removed + # in 0.7.) + config: + profile: /app-root/run.yaml ``` **Build and run**: diff --git a/docs/basic_info/getting_started.md b/docs/basic_info/getting_started.md index ea21c3923..7bf966d5e 100644 --- a/docs/basic_info/getting_started.md +++ b/docs/basic_info/getting_started.md @@ -130,7 +130,12 @@ service: access_log: true llama_stack: use_as_library_client: true - library_client_config_path: run.yaml + # Unified mode (recommended): the run.yaml created above is consumed as + # the synthesis profile. The legacy library_client_config_path setup is + # deprecated and removed in 0.7 — see the migration guide: + # ../user_doc/deployment_guide.md#migrating-from-the-legacy-two-file-configuration + config: + profile: run.yaml user_data_collection: feedback_enabled: true feedback_storage: "/tmp/data/feedback" diff --git a/docs/devel_doc/openapi.json b/docs/devel_doc/openapi.json index e57645739..66ad7ccda 100644 --- a/docs/devel_doc/openapi.json +++ b/docs/devel_doc/openapi.json @@ -15275,8 +15275,8 @@ "type": "null" } ], - "title": "Llama Stack configuration path", - "description": "Path to configuration file used when Llama Stack is run in library mode" + "title": "Llama Stack configuration path (legacy, deprecated)", + "description": "Path to configuration file used when Llama Stack is run in library mode. DEPRECATED legacy two-file setup: logs a startup warning since 0.6 and is removed in 0.7 \u2014 use unified mode instead (the config block below, and/or the root-level inference.providers section); migrate with lightspeed-stack --migrate-config." }, "timeout": { "type": "integer", diff --git a/docs/devel_doc/providers.md b/docs/devel_doc/providers.md index d133731ab..e6dec28c8 100644 --- a/docs/devel_doc/providers.md +++ b/docs/devel_doc/providers.md @@ -1,7 +1,7 @@ # Lightspeed Core Providers Lightspeed Core Stack (LCS) builds on top of llama-stack and its provider system. -Any llama-stack provider can be enabled in LCS with minimal effort by installing the required dependencies and updating llama-stack configuration in `run.yaml` file. +Any llama-stack provider can be enabled in LCS with minimal effort by installing the required dependencies and updating the Llama Stack configuration — in unified mode that is your synthesis profile (or `native_override`) inside `lightspeed-stack.yaml`; in the deprecated legacy mode, the external `run.yaml` file. This document catalogs all available llama-stack providers and indicates which ones are officially supported in the current LCS version. It also provides a step-by-step guide on how to enable any llama-stack provider in LCS. diff --git a/docs/user_doc/config.md b/docs/user_doc/config.md index bf8d52d2b..2339f562a 100644 --- a/docs/user_doc/config.md +++ b/docs/user_doc/config.md @@ -464,7 +464,7 @@ Useful resources: | url | string | URL to Llama Stack service; used when library mode is disabled. Must be a valid HTTP or HTTPS URL. | | api_key | string | API key to access Llama Stack service | | use_as_library_client | boolean | When set to true Llama Stack will be used in library mode, not in server mode (default) | -| library_client_config_path | string | Path to configuration file used when Llama Stack is run in library mode | +| library_client_config_path | string | DEPRECATED legacy two-file setup: path to an external run.yaml used in library mode. Logs a startup warning since 0.6; removed in 0.7 — use unified mode instead (the config field below and/or the root-level inference.providers section); migrate with `lightspeed-stack --migrate-config` | | timeout | integer | Timeout in seconds for requests to Llama Stack service. Default is 180 seconds (3 minutes) to accommodate long-running RAG queries. | | max_retries | integer | Maximum number of connection attempts before giving up. Used on startup to connect to Llama Stack and retrieve its version. Connection attempts are retried with a fixed delay to handle the case where Llama Stack is still starting up (e.g., when running as a sidecar in the same pod). | | retry_delay | integer | Delay in seconds between retry attempts. Used on startup to connect to Llama Stack and retrieve its version. Connection attempts are retried with a fixed delay to handle the case where Llama Stack is still starting up (e.g., when running as a sidecar in the same pod). | diff --git a/docs/user_doc/deployment_guide.md b/docs/user_doc/deployment_guide.md index dc2a9a3d8..76a26377b 100644 --- a/docs/user_doc/deployment_guide.md +++ b/docs/user_doc/deployment_guide.md @@ -79,6 +79,29 @@ All those deployments methods will be covered later. +## Configuration modes + +*LCS* reads one operator-facing file: `lightspeed-stack.yaml`. There are two +ways it can drive the underlying Llama Stack: + +1. **Unified mode (recommended).** The single `lightspeed-stack.yaml` is the + only configuration file you maintain. LCORE *synthesizes* the Llama Stack + `run.yaml` from it at startup — from a built-in default baseline, an + optional [profile](#profiles) you author, the high-level + `inference.providers` section, and a raw `native_override` escape hatch. + All examples in this guide show unified mode first. +2. **Legacy two-file mode (deprecated).** `llama_stack.library_client_config_path` + points at an external, hand-maintained `run.yaml`. This path is deprecated: + since release 0.6 it logs a startup warning, and it is **removed in + release 0.7**. See + [Migrating from the legacy two-file configuration](#migrating-from-the-legacy-two-file-configuration). + +The two modes are mutually exclusive in one file — configuration loading +fails if a unified synthesis input and `library_client_config_path` are both +present. + + + ## Integration with Llama Stack framework The Llama Stack framework can be run as a standalone server and accessed via its the REST API. However, instead of direct communication via the REST API (and JSON format), there is an even better alternative. It is based on the so-called 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. @@ -92,7 +115,11 @@ When this mode is selected, Llama Stack is used as a regular Python library. Thi ![Llama Stack as library](./llama_stack_as_library.svg) > [!NOTE] -> Even when Llama Stack is used as a library, it still requires the configuration file `run.yaml` to be presented. This configuration file is loaded during initialization phase. +> Even when Llama Stack is used as a library, it still requires a `run.yaml` +> configuration during the initialization phase. In unified mode (the +> recommended default) LCORE synthesizes that file for you from +> `lightspeed-stack.yaml`; only the deprecated legacy mode requires you to +> maintain `run.yaml` by hand. @@ -160,6 +187,78 @@ When this mode is selected, Llama Stack is started as a separate REST API servic +## Migrating from the legacy two-file configuration + +Three migration paths, per deployment: + +| Path | Effort | Result | +|---|---|---| +| Do nothing | none | Legacy keeps working until removal in 0.7 (with a startup deprecation warning) | +| Lift-and-shift | seconds — `--migrate-config` | Single file, byte-equivalent Llama Stack behavior | +| Re-express | hours+ | Single file; high-level sections and/or a profile replace the lifted `run.yaml` | + +### Step-by-step: lift-and-shift with `--migrate-config` + +Given a legacy pair — a hand-maintained `run.yaml` plus a +`lightspeed-stack.yaml` that points at it: + +```yaml +# lightspeed-stack.yaml (legacy, deprecated) +name: LCS +llama_stack: + use_as_library_client: true + library_client_config_path: ./run.yaml +# ... rest ... +``` + +1. Run the migration tool: + + ```bash + lightspeed-stack --migrate-config \ + --run-yaml run.yaml \ + -c lightspeed-stack.yaml \ + --migrate-output lightspeed-stack-unified.yaml + ``` + +2. Inspect the output. Everything from your `lightspeed-stack.yaml` is + preserved; only the `llama_stack` section changes — + `library_client_config_path` is removed and your entire `run.yaml` is + lifted into the unified config block: + + ```yaml + # lightspeed-stack-unified.yaml + name: LCS + llama_stack: + use_as_library_client: true + config: + baseline: empty + native_override: + # ... your run.yaml content, verbatim ... + ``` + +3. Replace literal secrets. If your `run.yaml` contained secret values + directly, replace them with `${env.MY_VAR}` environment references — + the migrated file otherwise carries them onto disk verbatim (the + synthesized output is written owner-only, mode 0600, as a safety net). + +4. Swap the file in (`mv lightspeed-stack-unified.yaml + lightspeed-stack.yaml`), delete the now-unused external `run.yaml` + mount/copy, and restart. Llama Stack behavior is identical: synthesis + starts from an empty baseline and deep-merges only your lifted + `run.yaml`. + +Later, at your own pace, you can slim the `native_override` down by moving +providers into the high-level `inference.providers` section or into a +[profile](#profiles) — that is the "re-express" path. + +### Deprecation schedule + +Unified mode shipped in release 0.6 with legacy mode fully functional plus +a startup deprecation warning; the legacy two-file path is removed in +release 0.7. + + + ## Local deployment In this chapter it will be shown how to run LCS locally. This mode is especially useful for developers, as it is possible to work with the latest versions of source codes, including locally made changes and improvements. And last but not least, it is possible to trace, monitor and debug the entire system from within integrated development environment etc. @@ -542,12 +641,17 @@ cp examples/run.yaml . #### LCS configuration to use Llama Stack in library mode -Copy the example LCS config file from examples/lightspeed-stack-library.yaml to the project directory: +Copy the example LCS config file from examples/lightspeed-stack-lls-library.yaml to the project directory: ```bash cp examples/lightspeed-stack-lls-library.yaml lightspeed-stack.yaml ``` +The example is a unified-mode configuration: the `run.yaml` you created above +is consumed as the synthesis [profile](#profiles) via +`llama_stack.config.profile` — there is no deprecated +`library_client_config_path` in it. + #### Start LCS @@ -1074,7 +1178,9 @@ Create a file named `run.yaml`. Use the example configuration from [examples/run ### LCS configuration -Create file `lightspeed-stack.yaml` with the following content: +Create file `lightspeed-stack.yaml` with the following content (unified +mode — the `run.yaml` created above is consumed as the synthesis +[profile](#profiles)): ```yaml name: Lightspeed Core Service (LCS) @@ -1087,7 +1193,8 @@ service: access_log: true llama_stack: use_as_library_client: true - library_client_config_path: ./run.yaml + config: + profile: ./run.yaml api_key: xyzzy user_data_collection: feedback_enabled: true @@ -1099,6 +1206,12 @@ authentication: module: "noop" ``` +> [!WARNING] +> The legacy equivalent — `library_client_config_path: ./run.yaml` instead +> of the `config:` block — is deprecated and will be removed in release +> 0.7. See +> [Migrating from the legacy two-file configuration](#migrating-from-the-legacy-two-file-configuration). + ### Start *Lightspeed Core Service* from a container diff --git a/docs/user_doc/okp_guide.md b/docs/user_doc/okp_guide.md index 52f72bd87..8b7567633 100644 --- a/docs/user_doc/okp_guide.md +++ b/docs/user_doc/okp_guide.md @@ -140,7 +140,7 @@ okp: chunk_filter_query: "product:*openshift* AND product_version:4.21" ``` -When you launch Lightspeed stack it will augment the Llamastack run.yaml with +When you launch Lightspeed stack it will augment the Llama Stack configuration (the synthesized run.yaml in unified mode, or your external run.yaml in the deprecated legacy mode) with configuration for OKP. ### Dynamic Metadata Filtering @@ -266,7 +266,7 @@ curl -sX POST http://localhost:8080/v1/query \ Then launch Lightspeed Stack using your Lightspeed Stack config(`lightspeed-stack.yaml`) which references the provided default -Llamastack config file (`run.yaml`): +Effective Llama Stack config (the synthesized `run.yaml` — in legacy mode, your external `run.yaml`): ```bash make run diff --git a/docs/user_doc/rag_guide.md b/docs/user_doc/rag_guide.md index e888f1265..36e7180de 100644 --- a/docs/user_doc/rag_guide.md +++ b/docs/user_doc/rag_guide.md @@ -227,7 +227,7 @@ podman run \ > For other supported models and configuration options, see the vLLM documentation: > [vLLM: Tool Calling](https://docs.vllm.ai/en/stable/features/tool_calling.html) -After starting the container, configure the vLLM provider in your `run.yaml`, matching `model_id` with the model provided in the `podman run` command. +After starting the container, configure the vLLM provider in your synthesis profile / baseline `run.yaml` (unified mode) or external `run.yaml` (deprecated legacy mode), matching `model_id` with the model provided in the `podman run` command. ```yaml [...] @@ -250,7 +250,7 @@ providers: ### OpenAI example -Add a provider for your language model in your `run.yaml` (e.g., OpenAI): +Add a provider for your language model in your synthesis profile / baseline `run.yaml` (e.g., OpenAI): ```yaml models: diff --git a/examples/lightspeed-stack-lls-library.yaml b/examples/lightspeed-stack-lls-library.yaml index 386a97ea3..331d23183 100644 --- a/examples/lightspeed-stack-lls-library.yaml +++ b/examples/lightspeed-stack-lls-library.yaml @@ -8,7 +8,11 @@ service: access_log: true llama_stack: use_as_library_client: true - library_client_config_path: run.yaml + # Unified mode: the run.yaml next to this file is consumed as the + # synthesis profile (legacy library_client_config_path is deprecated, + # removed in 0.7). + config: + profile: run.yaml user_data_collection: feedback_enabled: true feedback_storage: "/tmp/data/feedback" diff --git a/src/models/config.py b/src/models/config.py index 757eeaa13..192de9b1b 100644 --- a/src/models/config.py +++ b/src/models/config.py @@ -841,8 +841,12 @@ class LlamaStackConfiguration(ConfigurationBase): library_client_config_path: Optional[str] = Field( None, - title="Llama Stack configuration path", - description="Path to configuration file used when Llama Stack is run in library mode", + title="Llama Stack configuration path (legacy, deprecated)", + description="Path to configuration file used when Llama Stack is run " + "in library mode. DEPRECATED legacy two-file setup: logs a startup " + "warning since 0.6 and is removed in 0.7 — use unified mode instead " + "(the config block below, and/or the root-level inference.providers " + "section); migrate with lightspeed-stack --migrate-config.", ) timeout: PositiveInt = Field(