From e5bdd4ee3c4064f2d814ded2947d8ecfbd3d42f6 Mon Sep 17 00:00:00 2001 From: Maxim Svistunov Date: Mon, 24 Aug 2026 16:52:03 +0200 Subject: [PATCH 1/2] LCORE-3694: move legacy two-file removal from 0.7 to 0.8 The startup deprecation WARN and the design doc both stated that the legacy two-file configuration (llama_stack.library_client_config_path plus an external run.yaml) is removed in release 0.7. That is no longer the plan: confirmed 2026-08-24, the legacy path is deprecated through 0.7 with warnings and a migration path, and removed in 0.8. Removing in 0.7 would have satisfied the Engineering Support Agreement's mandatory one-minor-release deprecation phase only formally. The unified replacement is itself only completed in 0.7, so operators would not have had a full release with a working migration path available to them. Left uncorrected, 0.7 GA would have shipped a startup warning promising a removal that does not happen. Changes the WARN string and its schedule comment in lightspeed_stack.py, the library_client_config_path field description in models/config.py (the source for the generated configuration documentation), and requirement R2, Decision S2 and the changelog in the design doc. Decision S2 now also carries the rationale for the revision and the real release dates in place of the tentative ones. --- .../llama-stack-config-merge.md | 16 ++++++++++++---- src/lightspeed_stack.py | 5 +++-- src/models/config.py | 2 +- 3 files changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/design/llama-stack-config-merge/llama-stack-config-merge.md b/docs/design/llama-stack-config-merge/llama-stack-config-merge.md index 30d0288d0..0d6d641d4 100644 --- a/docs/design/llama-stack-config-merge/llama-stack-config-merge.md +++ b/docs/design/llama-stack-config-merge/llama-stack-config-merge.md @@ -68,8 +68,9 @@ detail that LCORE owns, not an operator-facing artifact. server modes and serves `/v1/query` successfully. - **R2:** Legacy mode (`llama_stack.library_client_config_path` + external `run.yaml`) works unchanged through the deprecation window: - fully functional with a startup deprecation WARN in 0.6, removed in - 0.7 (Decision S2, confirmed 2026-05-20). + fully functional with a startup deprecation WARN in 0.6 and 0.7, + removed in 0.8 (Decision S2, confirmed 2026-05-20, schedule revised + 2026-08-24). - **R3:** Setting both `llama_stack.config` and `llama_stack.library_client_config_path` in the same file fails at configuration load time with a clear error message pointing to the @@ -427,8 +428,14 @@ Three operator-facing migration paths (choose per deployment): Deprecation schedule (Decision S2, confirmed by @sbunciak 2026-05-20): unified mode ships in 0.6 with legacy mode fully functional plus a startup deprecation WARN (no breaking change); the legacy two-file path -is removed in 0.7. Tentative releases: 0.6 end of June 2026, 0.7 end of -September 2026. +is removed in 0.8. + +Schedule revised 2026-08-24 (confirmed by @sbunciak): removal moves from +0.7 to 0.8. Removing in 0.7 would satisfy the Engineering Support +Agreement's one-minor-release deprecation phase only formally -- the +unified replacement is itself only completed in 0.7, so operators would +not have had a full release with a working migration path. Releases: +0.6 June 2026, 0.7 September 2026, 0.8 December 2026. ## Implementation Suggestions @@ -553,6 +560,7 @@ reference. |---|---|---| | 2026-04-23 | Initial version | Spike completion | | 2026-08-20 | Default baseline openai provider is conditional on `OPENAI_API_KEY` | LCORE-3607: `baseline: default` must load when the key is unset | +| 2026-08-24 | Legacy two-file removal moves from 0.7 to 0.8 | Unified replacement only completed in 0.7; operators need a full release with a working migration path (confirmed by @sbunciak) | ## Appendix A — Worked example: legacy → unified migration diff --git a/src/lightspeed_stack.py b/src/lightspeed_stack.py index 31ea4eb81..9742c50d6 100644 --- a/src/lightspeed_stack.py +++ b/src/lightspeed_stack.py @@ -190,12 +190,13 @@ def main() -> None: ) # Deprecation schedule (Decision S2): the legacy two-file path keeps - # working through 0.6 with this single startup WARN and is removed in 0.7. + # working through 0.6 and 0.7 with this single startup WARN and is removed + # in 0.8 (schedule revised 2026-08-24, confirmed by @sbunciak). if configuration.llama_stack_configuration.library_client_config_path is not None: logger.warning( "DEPRECATED: the two-file configuration " "(llama_stack.library_client_config_path + external run.yaml) is " - "deprecated and will be removed in release 0.7. Migrate to the " + "deprecated and will be removed in release 0.8. Migrate to the " "unified lightspeed-stack.yaml: https://lightspeed-core.github.io" "/lightspeed-stack/design/llama-stack-config-merge" "/llama-stack-config-merge.html#migration--backwards-compatibility" diff --git a/src/models/config.py b/src/models/config.py index a70f57e09..3ce430dd3 100644 --- a/src/models/config.py +++ b/src/models/config.py @@ -844,7 +844,7 @@ class LlamaStackConfiguration(ConfigurationBase): 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 " + "warning since 0.6 and is removed in 0.8 — use unified mode instead " "(the config block below, and/or the root-level inference.providers " "section); migrate with lightspeed-stack --migrate-config.", ) From 01a0f1cf6bc0ca5cf1eeaae36b0e6661273a365e Mon Sep 17 00:00:00 2001 From: Maxim Svistunov Date: Mon, 24 Aug 2026 16:52:19 +0200 Subject: [PATCH 2/2] LCORE-3694: regenerate configuration documentation for the 0.8 schedule Propagates the library_client_config_path description change to the generated documentation, so no document still tells operators the legacy two-file setup is removed in 0.7. Regenerated from source via the Makefile targets: docs/devel_doc/ openapi.json and docs/models/successful_responses.{json,md}. That regeneration also picks up two lines of unrelated drift already present on main, where a question-validity prompt default was edited without regenerating the documentation; those are included rather than hand-patching generated files back into a stale state. docs/user_doc/config.{json,md,html} are edited by hand because no Makefile target, script or workflow generates them. config.json is exactly the --dump-schema output, config.md is close to openapi-to-markdown piped through scripts/fix_openapi_doc.py but not identical, and config.html has no discoverable generator; the three were last regenerated manually under LCORE-3444. Editing the single affected line keeps them consistent with each other. The missing generation path is recorded on LCORE-3694 as a follow-up. docs/basic_info/getting_started.md carries the same correction in an example comment. --- docs/basic_info/getting_started.md | 2 +- docs/devel_doc/openapi.json | 2 +- docs/models/successful_responses.json | 4 ++-- docs/models/successful_responses.md | 2 +- docs/user_doc/config.html | 2 +- docs/user_doc/config.json | 2 +- docs/user_doc/config.md | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/basic_info/getting_started.md b/docs/basic_info/getting_started.md index 7bf966d5e..aa70f05cf 100644 --- a/docs/basic_info/getting_started.md +++ b/docs/basic_info/getting_started.md @@ -132,7 +132,7 @@ llama_stack: use_as_library_client: true # 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: + # deprecated and removed in 0.8 — see the migration guide: # ../user_doc/deployment_guide.md#migrating-from-the-legacy-two-file-configuration config: profile: run.yaml diff --git a/docs/devel_doc/openapi.json b/docs/devel_doc/openapi.json index 73dd0ba50..51812091c 100644 --- a/docs/devel_doc/openapi.json +++ b/docs/devel_doc/openapi.json @@ -15198,7 +15198,7 @@ } ], "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." + "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.8 \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/models/successful_responses.json b/docs/models/successful_responses.json index 0d164cb19..7605af4f8 100644 --- a/docs/models/successful_responses.json +++ b/docs/models/successful_responses.json @@ -2052,7 +2052,7 @@ "type": "string", "nullable": true, "default": null, - "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.", + "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.8 \u2014 use unified mode instead (the config block below, and/or the root-level inference.providers section); migrate with lightspeed-stack --migrate-config.", "title": "Llama Stack configuration path (legacy, deprecated)" }, "timeout": { @@ -4466,7 +4466,7 @@ "type": "string" }, "model_prompt": { - "default": "\nInstructions:\n- You are a question classifying tool\n- You are an expert in kubernetes and openshift\n- Your job is to determine where or a user's question is related to kubernetes and/or openshift technologies and to provide a one-word response.\n- If a question appears to be related to kubernetes or openshift technologies, answer with the word ${allowed}, otherwise answer with the word ${rejected}.\n- Do not explain your answer, just provide the one-word response. Do not give any other response.\n- If the given question is an empty string, answer with the word ${rejected}\n\n\nExample Question:\nWhy is the sky blue?\nExample Response:\n${rejected}\n\nExample Question:\nWhy is the grass green?\nExample Response:\n${rejected}\n\nExample Question:\nWhy is sand yellow?\nExample Response:\n${rejected}\n\nExample Question:\nCan you help configure my cluster to automatically scale?\nExample Response:\n${allowed}\n\nQuestion:\n${message}\nResponse:\n", + "default": "\nInstructions:\n- You are a question classifying tool\n- You are an expert in Kubernetes and OpenShift\n- Your job is to determine where or a user's question is related to Kubernetes and/or OpenShift technologies and to provide a one-word response.\n- If a question appears to be related to Kubernetes or OpenShift technologies, answer with the word ${allowed}, otherwise answer with the word ${rejected}.\n- Do not explain your answer, just provide the one-word response. Do not give any other response.\n- If the given question is an empty string, answer with the word ${rejected}\n\n\nExample Question:\nWhy is the sky blue?\nExample Response:\n${rejected}\n\nExample Question:\nWhy is the grass green?\nExample Response:\n${rejected}\n\nExample Question:\nWhy is sand yellow?\nExample Response:\n${rejected}\n\nExample Question:\nCan you help configure my cluster to automatically scale?\nExample Response:\n${allowed}\n\nQuestion:\n${message}\nResponse:\n", "description": "The default prompt sent to the LLM used to validate the Users' question.", "title": "Model prompt", "type": "string" diff --git a/docs/models/successful_responses.md b/docs/models/successful_responses.md index 1363bad97..a9e785d79 100644 --- a/docs/models/successful_responses.md +++ b/docs/models/successful_responses.md @@ -864,7 +864,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. 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. | +| library_client_config_path | string | 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.8 — use unified mode instead (the config block 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/config.html b/docs/user_doc/config.html index fdd3f64ac..750b0375c 100644 --- a/docs/user_doc/config.html +++ b/docs/user_doc/config.html @@ -1277,7 +1277,7 @@

LlamaStackConfiguration

string 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 +and is removed in 0.8 — use unified mode instead (the config block below, and/or the root-level inference.providers section); migrate with lightspeed-stack –migrate-config. diff --git a/docs/user_doc/config.json b/docs/user_doc/config.json index 3d681603b..457a4dc4d 100644 --- a/docs/user_doc/config.json +++ b/docs/user_doc/config.json @@ -1066,7 +1066,7 @@ "type": "string", "nullable": true, "default": null, - "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.", + "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.8 — use unified mode instead (the config block below, and/or the root-level inference.providers section); migrate with lightspeed-stack --migrate-config.", "title": "Llama Stack configuration path (legacy, deprecated)" }, "timeout": { diff --git a/docs/user_doc/config.md b/docs/user_doc/config.md index 15e1ccda1..60f987a70 100644 --- a/docs/user_doc/config.md +++ b/docs/user_doc/config.md @@ -454,7 +454,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. 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. | +| library_client_config_path | string | 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.8 — use unified mode instead (the config block 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). |