LCORE-1347 - Restructure source code

Makefile

@@ -31,9 +31,9 @@ CONTAINER_RUNTIME ?= $(shell command -v podman 2>/dev/null || command -v docker
 
 run-stack: ## Run lightspeed-stack directly, without building dependent service/s
 	@if [ "$${OTEL_SDK_DISABLED:-true}" = "false" ]; then \
-		uv run opentelemetry-instrument python3.12 src/lightspeed_stack.py -c $(CONFIG); \
+		uv run opentelemetry-instrument lightspeed_stack -c $(CONFIG); \
 	else \
-		uv run python3.12 src/lightspeed_stack.py -c $(CONFIG); \
+		uv run lightspeed-stack -c $(CONFIG); \
 	fi
 
 run: start-llama-stack-container ## Run the service locally with dependent services
@@ -84,7 +84,7 @@ start-llama-stack-container: build-llama-stack-image ## Start llama-stack contai
 		-v $(PWD)/$(LLAMA_STACK_CONFIG):/opt/app-root/run.yaml:z \
 		-v $(PWD)/$(CONFIG):/opt/app-root/lightspeed-stack.yaml:ro,z \
 		-v $(PWD)/scripts/llama-stack-entrypoint.sh:/opt/app-root/enrich-entrypoint.sh:ro,z \
-		-v $(PWD)/src/llama_stack_configuration.py:/opt/app-root/llama_stack_configuration.py:ro,z \
+		-v $(PWD)/src/lightspeed_stack/llama_stack_configuration.py:/opt/app-root/llama_stack_configuration.py:ro,z \
 		-e OPENAI_API_KEY \
 		-e BRAVE_SEARCH_API_KEY \
 		-e TAVILY_SEARCH_API_KEY \
@@ -143,7 +143,7 @@ clean-llama-stack: remove-llama-stack-container ## Remove container and image
 	fi
 
 run-llama-stack: ## Start Llama Stack with enriched config (for local service mode)
-	uv run src/llama_stack_configuration.py -c $(CONFIG) -i $(LLAMA_STACK_CONFIG) -o $(LLAMA_STACK_CONFIG) && \
+	uv run src/lightspeed_stack/llama_stack_configuration.py -c $(CONFIG) -i $(LLAMA_STACK_CONFIG) -o $(LLAMA_STACK_CONFIG) && \
 	uv run ogx stack run $(LLAMA_STACK_CONFIG)
 
 test-unit: ## Run the unit tests
@@ -228,31 +228,31 @@ docs/models/agents.md:	docs/models/agents.json
 	openapi-to-markdown --input_file $< --output_file $@
 
 docs/models/requests.json:	$(wildcard src/models/api/requests/*)	## Generate OpenAPI specification with requests models
-	uv run src/lightspeed_stack.py --dump-models-group requests
+	uv run lightspeed-stack --dump-models-group requests
 	mv requests.json $@
 
 docs/models/conversation_summary.json:	src/models/compaction.py	## Generate OpenAPI specification with conversation_summary models
-	uv run src/lightspeed_stack.py --dump-models-group conversation_summary
+	uv run lightspeed-stack --dump-models-group conversation_summary
 	mv conversation_summary.json $@
 
 docs/models/successful_responses.json:	$(wildcard src/models/api/responses/successful/*)	## Generate OpenAPI specification with successful_responses models
-	uv run src/lightspeed_stack.py --dump-models-group successful_responses
+	uv run lightspeed-stack --dump-models-group successful_responses
 	mv successful_responses.json $@
 
 docs/models/error_responses.json:	$(wildcard src/models/api/responses/error/*)	## Generate OpenAPI specification with error_responses models
-	uv run src/lightspeed_stack.py --dump-models-group error_responses
+	uv run lightspeed-stack --dump-models-group error_responses
 	mv error_responses.json $@
 
 docs/models/common.json:	$(wildcard src/models/common/*)	## Generate OpenAPI specification with common models
-	uv run src/lightspeed_stack.py --dump-models-group common
+	uv run lightspeed-stack --dump-models-group common
 	mv common.json $@
 
 docs/models/agents.json:	$(wildcard src/models/common/agents/*)	## Generate OpenAPI specification with agents models
-	uv run src/lightspeed_stack.py --dump-models-group agents
+	uv run lightspeed-stack --dump-models-group agents
 	mv agents.json $@
 
 docs/models/common_responses.json:	$(wildcard src/models/common/responses/*)	## Generate OpenAPI specification with common_responses models
-	uv run src/lightspeed_stack.py --dump-models-group common_responses
+	uv run lightspeed-stack --dump-models-group common_responses
 	mv common_responses.json $@
 
 docs/models/requests.puml:	$(wildcard src/models/api/requests/*)	## Generate PlantUML class diagram for requests data models

README.md

@@ -1147,7 +1147,7 @@ ENV PATH="/app-root/.venv/bin:$PATH"
 
 # Run the application
 EXPOSE 8080
-ENTRYPOINT ["opentelemetry-instrument", "python3.12", "src/lightspeed_stack.py"]
+ENTRYPOINT ["opentelemetry-instrument", "lightspeed-stack"]
 USER 1001
 ```
 

deploy/llama-stack/test.containerfile

@@ -40,7 +40,7 @@ RUN mkdir -p /opt/app-root/src/.llama/storage \
     chmod -R 775 /opt/app-root
 
 # Copy enrichment scripts for runtime config enrichment
-COPY src/llama_stack_configuration.py /opt/app-root/llama_stack_configuration.py
+COPY src/lightspeed_stack/llama_stack_configuration.py /opt/app-root/llama_stack_configuration.py
 COPY scripts/llama-stack-entrypoint.sh /opt/app-root/enrich-entrypoint.sh
 RUN chmod +x /opt/app-root/enrich-entrypoint.sh && \
     chown 1001:0 /opt/app-root/enrich-entrypoint.sh /opt/app-root/llama_stack_configuration.py

docker-compose.yaml

@@ -15,7 +15,7 @@ services:
       - ./run.yaml:/opt/app-root/run.yaml:z
       # Host copies so `docker compose up` picks up script changes without rebuilding llama-stack
       - ./scripts/llama-stack-entrypoint.sh:/opt/app-root/enrich-entrypoint.sh:ro,z
-      - ./src/llama_stack_configuration.py:/opt/app-root/llama_stack_configuration.py:ro,z
+      - ./src/lightspeed_stack/llama_stack_configuration.py:/opt/app-root/llama_stack_configuration.py:ro,z
       - ${GCP_KEYS_PATH:-./tmp/.gcp-keys-dummy}:/opt/app-root/.gcp-keys:ro
       - ./lightspeed-stack.yaml:/opt/app-root/lightspeed-stack.yaml:ro,z
       - llama-storage:/opt/app-root/src/.llama/storage

docs/basic_info/getting_started.md

@@ -153,7 +153,7 @@ authentication:
     ```
 1. Check the output
     ```text
-    uv run src/lightspeed_stack.py
+    uv run lightspeed-stack
     Using config run.yaml:
     apis:
     - agents

docs/design/llama-stack-config-merge/llama-stack-config-merge-spike.md

@@ -442,7 +442,7 @@ configuration model. (Full design: the spec doc.)
   - Add the unified-vs-legacy `@model_validator` to the **root**
     `Configuration` model (it spans top-level `inference.providers` and
     `llama_stack.*`).
-- New functions in `src/llama_stack_configuration.py`:
+- New functions in `src/lightspeed_stack/llama_stack_configuration.py`:
   `synthesize_configuration`, `deep_merge_list_replace`,
   `apply_high_level_inference`, `load_default_baseline`, `synthesize_to_file`.
 - A shipped default baseline at `src/data/default_run.yaml`.
@@ -468,7 +468,7 @@ Read the "Architecture" and "Implementation Suggestions" sections of
 docs/design/llama-stack-config-merge/llama-stack-config-merge.md.
 Key files to create or modify:
   src/models/config.py  (new classes; modify LlamaStackConfiguration)
-  src/llama_stack_configuration.py  (synthesize_configuration + helpers)
+  src/lightspeed_stack/llama_stack_configuration.py  (synthesize_configuration + helpers)
   src/data/default_run.yaml  (new)
   src/client.py  (library-mode wiring)
 To verify: run a unified-mode config end-to-end via `uv run lightspeed-stack -c <config>` and confirm /v1/query succeeds.
@@ -486,7 +486,7 @@ that produces a unified single-file config from an existing
 
 **Scope**:
 
-- `migrate_config_dumb()` function in `src/llama_stack_configuration.py`.
+- `migrate_config_dumb()` function in `src/lightspeed_stack/llama_stack_configuration.py`.
 - `--migrate-config`, `--run-yaml`, `--migrate-output` flags in
   `src/lightspeed_stack.py`.
 - Round-trip test: migrate → synthesize → byte-identical to original
@@ -504,7 +504,7 @@ that produces a unified single-file config from an existing
 
 ```text
 Read "Migration / backwards compatibility" and "Appendix A — Worked example: legacy → unified migration" in docs/design/llama-stack-config-merge/llama-stack-config-merge.md.
-Key files: src/lightspeed_stack.py, src/llama_stack_configuration.py,
+Key files: src/lightspeed_stack.py, src/lightspeed_stack/llama_stack_configuration.py,
 tests/unit/test_llama_stack_synthesize.py.
 To verify: migrate the repo's root run.yaml + lightspeed-stack.yaml, then
 start LCORE with the output; confirm /v1/query works.
@@ -946,7 +946,7 @@ Two files:
   (inference, safety, tool_runtime, vector_io, agents, ...), `storage`,
   `registered_resources`, `vector_stores`, `safety`.
 
-**Existing enrichment** (`src/llama_stack_configuration.py`):
+**Existing enrichment** (`src/lightspeed_stack/llama_stack_configuration.py`):
 
 - LCORE already enriches an input `run.yaml` with dynamic values from
   `lightspeed-stack.yaml`: Azure Entra ID tokens (side-effect to `.env`),
@@ -1136,7 +1136,7 @@ Relative to `upstream/main`:
 | File | Purpose |
 |---|---|
 | `src/models/config.py` | New classes: `UnifiedInferenceProvider`, `UnifiedInferenceSection`, `UnifiedLlamaStackConfig`; modified `LlamaStackConfiguration` (adds `config` field + mutual-exclusion validator). _PoC layout; the implementation follows Decision S5 — `inference.providers` on the top-level `InferenceConfiguration`, validator on the root `Configuration` model, no `UnifiedInferenceSection` (see the schema JIRA)._ |
-| `src/llama_stack_configuration.py` | New: `synthesize_configuration`, `deep_merge_list_replace`, `apply_high_level_inference`, `load_default_baseline`, `synthesize_to_file`, `migrate_config_dumb`. CLI `main()` auto-detects unified vs legacy. |
+| `src/lightspeed_stack/llama_stack_configuration.py` | New: `synthesize_configuration`, `deep_merge_list_replace`, `apply_high_level_inference`, `load_default_baseline`, `synthesize_to_file`, `migrate_config_dumb`. CLI `main()` auto-detects unified vs legacy. |
 | `src/data/default_run.yaml` | Built-in default baseline (copied from repo root `run.yaml` for the PoC — implementation JIRA should slim it down; see PoC surprise about `EXTERNAL_PROVIDERS_DIR`) |
 | `src/client.py` | Library-mode path picks synthesis for unified configs, enrichment for legacy |
 | `src/lightspeed_stack.py` | `--migrate-config`, `--run-yaml`, `--migrate-output` flags |

docs/design/llama-stack-config-merge/llama-stack-config-merge.md

@@ -3,7 +3,7 @@
 |                    |                                                                                  |
 |--------------------|----------------------------------------------------------------------------------|
 | **Date**           | 2026-04-23                                                                       |
-| **Component**      | Lightspeed Core Stack (src/models/config.py, src/llama_stack_configuration.py, src/client.py, src/lightspeed_stack.py, scripts/llama-stack-entrypoint.sh) |
+| **Component**      | Lightspeed Core Stack (src/models/config.py, src/lightspeed_stack/llama_stack_configuration.py, src/client.py, src/lightspeed_stack.py, scripts/llama-stack-entrypoint.sh) |
 | **Authors**        | Maxim Svistunov                                                                   |
 | **Feature**        | [LCORE-836](https://redhat.atlassian.net/browse/LCORE-836)                       |
 | **Spike**          | [llama-stack-config-merge-spike.md](llama-stack-config-merge-spike.md)           |
@@ -328,7 +328,7 @@ class Configuration(ConfigurationBase):
 ### API changes
 
 None at the REST API surface. Internal API additions in
-`src/llama_stack_configuration.py`:
+`src/lightspeed_stack/llama_stack_configuration.py`:
 
 - `synthesize_configuration(lcs_config, config_file_dir, default_baseline)
   -> dict` — the synthesis pipeline.
@@ -430,7 +430,7 @@ September 2026.
 | File | What to do |
 |---|---|
 | `src/models/config.py` | Add `UnifiedInferenceProvider`. Extend the existing `InferenceConfiguration` with `providers: list[UnifiedInferenceProvider]`. Add `UnifiedLlamaStackConfig` (`baseline`/`profile`/`native_override`) and a `config` field on `LlamaStackConfiguration`. Put the unified-vs-legacy `model_validator` on the **root** `Configuration` model (spans `inference.providers` + `llama_stack.*`). |
-| `src/llama_stack_configuration.py` | Add `synthesize_configuration`, `deep_merge_list_replace`, `apply_high_level_inference`, `load_default_baseline`, `synthesize_to_file`, `migrate_config_dumb`, `PROVIDER_TYPE_MAP`, `DEFAULT_BASELINE_RESOURCE`. Update `main()` to auto-detect unified vs legacy. |
+| `src/lightspeed_stack/llama_stack_configuration.py` | Add `synthesize_configuration`, `deep_merge_list_replace`, `apply_high_level_inference`, `load_default_baseline`, `synthesize_to_file`, `migrate_config_dumb`, `PROVIDER_TYPE_MAP`, `DEFAULT_BASELINE_RESOURCE`. Update `main()` to auto-detect unified vs legacy. |
 | `src/data/default_run.yaml` | New file — a thinner baseline than today's repo-root `run.yaml`. Notably do **not** reference `${env.EXTERNAL_PROVIDERS_DIR}` without a default (see "Findings discovered during PoC" in the spike doc). |
 | `src/client.py` | In `_load_library_client`: branch on `config.config` presence. Add `_synthesize_library_config()` that calls the synthesizer and writes to the deterministic path (R10). Keep `_enrich_library_config` for legacy. |
 | `src/lightspeed_stack.py` | Add `--migrate-config`, `--run-yaml`, `--migrate-output`, `--synthesized-config-output` flags. Add an early-exit branch in `main()` that dispatches to `migrate_config_dumb` when `--migrate-config` is set. Clean up stale docstring. |

docs/design/observability-opentelemetry/observability-opentelemetry-design.md

@@ -297,7 +297,7 @@ See the [OpenTelemetry SDK environment variables reference](https://opentelemetr
 **`docker-compose.yaml` (LCORE service)** — set `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`; add headers, sampler, `OTEL_SDK_DISABLED`, etc. as needed via `environment` / `env_file`.
 
 **`Containerfile` (LCORE image)** —  
-`ENTRYPOINT ["opentelemetry-instrument", "python3.12", "src/lightspeed_stack.py"]`
+`ENTRYPOINT ["opentelemetry-instrument", "lightspeed-stack"]`
 
 ### Trigger mechanism
 
@@ -366,7 +366,7 @@ No **required** change to JSON requests/responses. The `/config` response gains
 | `pyproject.toml` | Add OTel API, SDK, OTLP exporter, FastAPI instrumentor, propagators; pin versions per project policy. |
 | `src/app/endpoints/config.py` | Scrape `OTEL_*` env vars into `observability.otel` on `/config` response; redact secrets. |
 | `app/endpoints/*.py`, `utils/*.py` | Add manual spans around logical sections of request handlers. |
-| `Containerfile` | Add OTel packages; set **`ENTRYPOINT`** to **`["opentelemetry-instrument", "python3.12", "src/lightspeed_stack.py"]`**. |
+| `Containerfile` | Add OTel packages; set **`ENTRYPOINT`** to **`["opentelemetry-instrument", "lightspeed-stack"]`**. |
 | `docker-compose.yaml` | **`environment`** / **`env_file`**: required **`OTEL_*`** exporter fields. |
 
 ## Open Questions

docs/design/prompt-guardrails/poc-results/README.md

@@ -81,7 +81,7 @@ LCS_GUARDRAILS_POC_CONFIG=docs/design/prompt-guardrails/poc-results/guardrails-p
 # 3. Full stack (see meta/docs/local-stack-testing.md for service startup)
 #    Start Llama Stack (run-ci.yaml) then:
 LCS_GUARDRAILS_POC_CONFIG=docs/design/prompt-guardrails/poc-results/guardrails-poc.yaml \
-  uv run src/lightspeed_stack.py -c docs/design/prompt-guardrails/poc-results/lcs-poc-config.yaml
+  uv run lightspeed-stack -c docs/design/prompt-guardrails/poc-results/lcs-poc-config.yaml
 #    Then POST /v1/query with {"query":"...","shield_ids":[]} to isolate the
 #    guardrails layer from the run-ci.yaml llama-guard shield.
 ```

docs/devel_doc/container_orchestration.md

@@ -146,7 +146,7 @@ make wait-for-llama-stack-health
 make run-stack
 ```
 
-- Starts the FastAPI service with `uv run src/lightspeed_stack.py`
+- Starts the FastAPI service with `uv run lightspeed-stack`
 - Connects to llama-stack at `http://localhost:8321` (or configured URL)
 - Sets up trap handler to stop container on exit
 
@@ -459,7 +459,7 @@ Container logs:
 3. **Test config enrichment:**
    ```bash
    # Run enrichment script manually to check for errors
-   uv run src/llama_stack_configuration.py \
+   uv run src/lightspeed_stack/llama_stack_configuration.py \
      -c lightspeed-stack.yaml \
      -i run.yaml \
      -o /tmp/enriched-run.yaml
@@ -685,7 +685,7 @@ When the llama-stack container starts, it automatically enriches the `run.yaml`
 
 1. **Entrypoint script** (`scripts/llama-stack-entrypoint.sh`) is mounted at `/opt/app-root/enrich-entrypoint.sh`
 2. **Script runs** `/opt/app-root/.venv/bin/python3 /opt/app-root/llama_stack_configuration.py`
-3. **Enrichment logic** (`src/llama_stack_configuration.py`) reads both configs and merges them
+3. **Enrichment logic** (`src/lightspeed_stack/llama_stack_configuration.py`) reads both configs and merges them
 4. **Output** is written to `/tmp/enriched-run.yaml` inside the container
 5. **Llama Stack starts** with the enriched config
 
@@ -699,7 +699,7 @@ When the llama-stack container starts, it automatically enriches the `run.yaml`
 
 ```bash
 # Run enrichment locally to see output
-uv run src/llama_stack_configuration.py \
+uv run src/lightspeed_stack/llama_stack_configuration.py \
   -c lightspeed-stack.yaml \
   -i run.yaml \
   -o enriched-run.yaml
@@ -717,7 +717,7 @@ The container uses these volume mounts:
 | `$(PWD)/run.yaml` | `/opt/app-root/run.yaml` | rw | Llama Stack config (enriched version written here) |
 | `$(PWD)/lightspeed-stack.yaml` | `/opt/app-root/lightspeed-stack.yaml` | ro | LCORE config (read for enrichment) |
 | `$(PWD)/scripts/llama-stack-entrypoint.sh` | `/opt/app-root/enrich-entrypoint.sh` | ro | Entrypoint script with enrichment logic |
-| `$(PWD)/src/llama_stack_configuration.py` | `/opt/app-root/llama_stack_configuration.py` | ro | Python enrichment script |
+| `$(PWD)/src/lightspeed_stack/llama_stack_configuration.py` | `/opt/app-root/llama_stack_configuration.py` | ro | Python enrichment script |
 
 **SELinux labels:**
 - `:z`: Relabels for sharing between host and container (read-write)

docs/user_doc/deployment_guide.md

@@ -468,7 +468,7 @@ make run
 ```
 
 ```
-uv run opentelemetry-instrument python3.12 src/lightspeed_stack.py
+uv run opentelemetry-instrument lightspeed_stack
 [07/29/25 15:43:35] INFO     Initializing app                                                                                 main.py:19
                     INFO     Including routers                                                                                main.py:68
 INFO:     Started server process [1922983]
@@ -561,7 +561,7 @@ cp examples/lightspeed-stack-lls-library.yaml lightspeed-stack.yaml
     ```
 1. Check the output
     ```text
-    uv run opentelemetry-instrument python3.12 src/lightspeed_stack.py
+    uv run opentelemetry-instrument lightspeed_stack
     Using config run.yaml:
     apis:
     - agents
@@ -663,10 +663,10 @@ It should get the image, copy all layers, and write manifest:
 ```text
 Trying to pull quay.io/lightspeed-core/lightspeed-stack:dev-latest...
 Getting image source signatures
-Copying blob 455d71b0a12b done   | 
-Copying blob d8e516fe2a03 done   | 
-Copying blob a299c213c55c done   | 
-Copying config 4468f47593 done   | 
+Copying blob 455d71b0a12b done   |
+Copying blob d8e516fe2a03 done   |
+Copying blob a299c213c55c done   |
+Copying config 4468f47593 done   |
 Writing manifest to image destination
 4468f475931a54ad1e5c26270ff4c3e55ec31444c1b0bf8fb77a576db7ab33f1
 ```
@@ -680,10 +680,10 @@ podman pull quay.io/lightspeed-core/lightspeed-stack:0.2.0
 ```text
 Trying to pull quay.io/lightspeed-core/lightspeed-stack:0.2.0...
 Getting image source signatures
-Copying blob 7c9e86f872c9 done   | 
-Copying blob 455d71b0a12b skipped: already exists  
-Copying blob a299c213c55c skipped: already exists  
-Copying config a4982f4319 done   | 
+Copying blob 7c9e86f872c9 done   |
+Copying blob 455d71b0a12b skipped: already exists
+Copying blob a299c213c55c skipped: already exists
+Copying config a4982f4319 done   |
 Writing manifest to image destination
 a4982f43195537b9eb1cec510fe6655f245d6d4b7236a4759808115d5d719972
 ```

pyproject.toml

@@ -90,22 +90,20 @@ dependencies = [
 
 
 [tool.pyright]
-exclude = [
-]
-extraPaths = ["./src"]
+include = ["src", "tests"]
 
 [tool.pdm]
 distribution = true
 
 [tool.pdm.version]
 source = "file"
-path = "src/version.py"
+path = "src/lightspeed_stack/version.py"
 
 [tool.behave]
 paths = ["tests/e2e/features"]
 
 [project.scripts]
-lightspeed-stack = "lightspeed_stack:main"
+lightspeed-stack = "lightspeed_stack.cli:main"
 
 [project.urls]
 Homepage = "https://github.com/lightspeed-core/lightspeed-stack"
@@ -240,7 +238,7 @@ requires = ["pdm-backend"]
 build-backend = "pdm.backend"
 
 [tool.pylint."MESSAGES CONTROL"]
-disable = ["R0801"]
+disable = ["R0801", "C0301"]
 
 [tool.ruff]
 line-length = 88