Merge pull request #1885 from anik120/okp-in-container

tisnik · web-flow · commit 31b639911c65 · 2026-06-12T14:43:40.000+02:00
LCORE-2443: Simplify OKP RAG setup with git submodules and auto-enrichment
diff --git a/.github/workflows/build_and_push_dev.yaml b/.github/workflows/build_and_push_dev.yaml
@@ -26,6 +26,9 @@ jobs:
           sudo apt install -y buildah qemu-user-static
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: 'recursive'
       - name: Create dev image tag
         run: |
           echo "DEV_TAG=dev-$(date +%Y%m%d)-$(git rev-parse --short HEAD)" >> $GITHUB_ENV
diff --git a/.github/workflows/build_and_push_release.yaml b/.github/workflows/build_and_push_release.yaml
@@ -28,6 +28,9 @@ jobs:
           sudo apt install -y buildah qemu-user-static
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: 'recursive'
       - name: Build image with Buildah
         id: build_image
         uses: redhat-actions/buildah-build@v2
diff --git a/.github/workflows/build_pr.yaml b/.github/workflows/build_pr.yaml
@@ -24,6 +24,9 @@ jobs:
           sudo apt install -y buildah qemu-user-static
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: 'recursive'
       - name: Build image with Buildah
         id: build_image
         uses: redhat-actions/buildah-build@v2
diff --git a/.github/workflows/e2e_tests.yaml b/.github/workflows/e2e_tests.yaml
@@ -37,6 +37,9 @@ jobs:
           # Don’t keep credentials when running untrusted PR code under PR_TARGET.
           persist-credentials: ${{ github.event_name != 'pull_request_target' }}
 
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: ‘recursive’
+
       - name: Verify actual git checkout result
         run: |
           echo "=== Git Status After Checkout ==="
diff --git a/.github/workflows/e2e_tests_lightspeed_evaluation.yaml b/.github/workflows/e2e_tests_lightspeed_evaluation.yaml
@@ -30,6 +30,9 @@ jobs:
           # Don’t keep credentials when running untrusted PR code under PR_TARGET.
           persist-credentials: ${{ github.event_name != 'pull_request_target' }}
 
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: 'recursive'
+
       - name: Verify actual git checkout result
         run: |
           echo "=== Git Status After Checkout ==="
diff --git a/.github/workflows/e2e_tests_providers.yaml b/.github/workflows/e2e_tests_providers.yaml
@@ -62,6 +62,9 @@ jobs:
           # Don’t keep credentials when running untrusted PR code under PR_TARGET.
           persist-credentials: ${{ github.event_name != 'pull_request_target' }}
 
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: 'recursive'
+
       - name: Verify actual git checkout result
         run: |
           echo "=== Git Status After Checkout ==="
diff --git a/.github/workflows/e2e_tests_rhaiis.yaml b/.github/workflows/e2e_tests_rhaiis.yaml
@@ -51,6 +51,9 @@ jobs:
           # Don’t keep credentials when running untrusted PR code under PR_TARGET.
           persist-credentials: ${{ github.event_name != 'pull_request_target' }}
 
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: 'recursive'
+
       - name: Verify actual git checkout result
         run: |
           echo "=== Git Status After Checkout ==="
diff --git a/.github/workflows/e2e_tests_rhelai.yaml b/.github/workflows/e2e_tests_rhelai.yaml
@@ -45,6 +45,9 @@ jobs:
           # Don’t keep credentials when running untrusted PR code under PR_TARGET.
           persist-credentials: ${{ github.event_name != 'pull_request_target' }}
 
+          # Fetch submodules (required for lightspeed-providers)
+          submodules: 'recursive'
+
       - name: Verify actual git checkout result
         run: |
           echo "=== Git Status After Checkout ==="
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "providers"]
+	path = providers
+	url = https://github.com/lightspeed-core/lightspeed-providers.git
diff --git a/Makefile b/Makefile
@@ -72,7 +72,6 @@ start-llama-stack-container: build-llama-stack-image ## Start llama-stack contai
 		-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 \
 		-e OPENAI_API_KEY \
-		-e EXTERNAL_PROVIDERS_DIR=$${EXTERNAL_PROVIDERS_DIR:-/opt/app-root/external_providers} \
 		-e BRAVE_SEARCH_API_KEY \
 		-e TAVILY_SEARCH_API_KEY \
 		-e E2E_OPENAI_MODEL=$${E2E_OPENAI_MODEL:-gpt-4o-mini} \
diff --git a/README.md b/README.md
@@ -160,8 +160,23 @@ Lightspeed Core Stack is based on the FastAPI framework (Uvicorn). The service i
 
 # Installation
 
-Installation steps depends on operation system. Please look at instructions for your system:
+## Clone the Repository
+
+Lightspeed Stack uses a git submodule for external providers (required for features like OKP RAG). Clone with submodules:
+
+```bash
+git clone --recursive https://github.com/lightspeed-core/lightspeed-stack.git
+cd lightspeed-stack
+```
 
+**If you already cloned without `--recursive`:**
+```bash
+git submodule update --init
+```
+
+## System-Specific Installation
+
+Installation steps depends on operation system. Please look at instructions for your system:
 
 - [Linux installation](https://lightspeed-core.github.io/lightspeed-stack/installation_linux)
 - [macOS installation](https://lightspeed-core.github.io/lightspeed-stack/installation_macos)
diff --git a/deploy/llama-stack/test.containerfile b/deploy/llama-stack/test.containerfile
@@ -16,13 +16,15 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | sh
 WORKDIR /opt/app-root
 COPY pyproject.toml uv.lock LICENSE README.md ./
 COPY src ./src
+COPY providers ./providers
 
 # Install dependencies using uv sync
 RUN uv sync --locked --no-install-project --group llslibdev
 
 # Add virtual environment to PATH for llama command
+# Add providers to PYTHONPATH so lightspeed_stack_providers modules can be imported
 ENV PATH="/opt/app-root/.venv/bin:$PATH" \
-    PYTHONPATH="/opt/app-root/src"
+    PYTHONPATH="/opt/app-root/src:/opt/app-root/providers"
 
 # Set HOME directory so llama-stack uses /opt/app-root/src/.llama
 ENV HOME="/opt/app-root/src"
diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -24,7 +24,6 @@ services:
     environment:
       - BRAVE_SEARCH_API_KEY=${BRAVE_SEARCH_API_KEY:-}
       - TAVILY_SEARCH_API_KEY=${TAVILY_SEARCH_API_KEY:-}
-      - EXTERNAL_PROVIDERS_DIR=${EXTERNAL_PROVIDERS_DIR:-/opt/app-root/external_providers}
       # OpenAI
       - OPENAI_API_KEY=${OPENAI_API_KEY}
       - E2E_OPENAI_MODEL=${E2E_OPENAI_MODEL:-gpt-4o-mini}
diff --git a/docs/container_orchestration.md b/docs/container_orchestration.md
@@ -311,7 +311,6 @@ See [OKP Guide](okp_guide.md) for detailed setup instructions.
 
 #### Other Configuration
 
-- `EXTERNAL_PROVIDERS_DIR`: Path to external providers directory (default: `/opt/app-root/external_providers`)
 - `E2E_OPENAI_MODEL`: OpenAI model for E2E tests (default: `gpt-4o-mini`)
 - `LLAMA_STACK_LOGGING`: Enable debug logging in llama-stack
 - `FAISS_VECTOR_STORE_ID`: FAISS vector store identifier
diff --git a/docs/okp_guide.md b/docs/okp_guide.md
@@ -18,11 +18,10 @@ configuration, see the [RAG Configuration Guide](rag_guide.md).
 * [Introduction](#introduction)
 * [Prerequisites](#prerequisites)
 * [Step 1: Launch OKP](#step-1-launch-okp)
-* [Step 2: Setup llamastack config environment variables](`#step-2-setup-llamastack-config-environment-variables`)
-* [Step 3: Install Lightspeed Stack Dependencies](#step-3-install-lightspeed-stack-dependencies)
-* [Step 4: Configure Lightspeed Stack](#step-4-configure-lightspeed-stack)
-* [Step 5: Launch Lightspeed Stack](#step-5-launch-lightspeed-stack)
-* [Step 6: Verify the Stack](#step-6-verify-the-stack)
+* [Step 2: Install Dependencies and Set Environment Variables](#step-2-install-dependencies-and-set-environment-variables)
+* [Step 3: Configure Lightspeed Stack](#step-3-configure-lightspeed-stack)
+* [Step 4: Launch Lightspeed Stack](#step-4-launch-lightspeed-stack)
+* [Step 5: Verify the Stack](#step-5-verify-the-stack)
 
 ---
 
@@ -32,15 +31,18 @@ OKP (Offline Knowledge Portal) provides a Solr-backed RAG source that
 Lightspeed Stack can use for both **Inline RAG** (context injected before the
 LLM request) and **Tool RAG** (context retrieved on demand via the
 `file_search` tool). This guide walks through deploying the OKP container,
-enriching your Llama Stack config from Lightspeed Stack settings, and
+configuring Lightspeed Stack for OKP, and
 validating that queries return referenced chunks.
 
 ---
 
 ## Prerequisites
 
-* [lightspeed-stack repository](https://github.com/lightspeed-core/lightspeed-stack) cloned
-* [lightspeed-providers repository](https://github.com/lightspeed-core/lightspeed-providers) cloned
+* [lightspeed-stack repository](https://github.com/lightspeed-core/lightspeed-stack) cloned **with submodules**:
+  ```bash
+  git clone --recursive https://github.com/lightspeed-core/lightspeed-stack.git
+  ```
+  If you already cloned without `--recursive`, run: `git submodule update --init`
 * [Podman](https://podman.io/) (or Docker) to run the OKP image
 * [uv](https://docs.astral.sh/uv/) for Python dependency management
 * An OpenAI API key (for inference when using OpenAI in your run config)
@@ -69,51 +71,36 @@ podman run --rm -d -p 8081:8080 registry.redhat.io/offline-knowledge-portal/rhok
 
   Or visit: **http://localhost:8081**
 
-> **Note:** Lightspeed stack will automatically enrich the llamastack
-> configuration to add the necessary providers/resources for referencing OKP.
-> This assumes your OKP instance is running on localhost:8081.  If you need a
-> different OKP url, you can set the SOLR_URL environment variable with the
-> correct url prior to launching Lightspeed stack and that value will be used
-> instead.
+> **Note:** The default OKP URL is configured via the `RH_SERVER_OKP` environment variable
+> (see Step 2). You can override this by setting a different value for
+> `RH_SERVER_OKP`, or by changing the `okp.rhokp_url` field in 
+> `lightspeed-stack.yaml`.
 ---
 
-## Step 2: Setup llamastack config environment variables
+## Step 2: Install Dependencies and Set Environment Variables
 
-Set the required environment variables. The external providers path must point
-to the `external_providers` content inside the
-[lightspeed-providers](https://github.com/lightspeed-core/lightspeed-providers/tree/main/lightspeed_stack_providers/)
-repository:
+Install dependencies:
 
 ```bash
-export EXTERNAL_PROVIDERS_DIR=../lightspeed-providers/resources/external_providers
-export OPENAI_API_KEY=<your-openai-api-key>
-export RH_SERVER_OKP=http://localhost:8081
+uv sync --group dev --group llslibdev
 ```
 
-Adjust `EXTERNAL_PROVIDERS_DIR` if your lightspeed-providers repo is in a
-different location relative to your lightspeed-stack directory.
-
----
-
-## Step 3: Install Lightspeed Stack Dependencies
-
-Then install dependencies and custom providers:
+Set required environment variables:
 
 ```bash
-uv sync --group dev --group llslibdev
-uv pip install -e ../lightspeed-providers # Path to lightspeed-providers repo
-```
-
-* **`uv sync`**: Installs project and dev/llslibdev groups so that the app and tooling run correctly.
-* **`uv pip install -e ../lightspeed-providers`**: Installs the lightspeed stack providers from the local clone of the repository.  Adjust the directory path as needed.
+export OPENAI_API_KEY=<your-openai-api-key>
 
-> **Note:** Running `uv sync` will remove the lightspeed-providers dependency
-> installed by the `uv pip install` command, so you will need to rerun the `uv
-> pip install` command if you rerun `uv sync`.
+# Set OKP URL env var, using special hostname for container-to-host networking
+# when running locally
+# Podman:
+export RH_SERVER_OKP=http://host.containers.internal:8081
+# Docker:
+# export RH_SERVER_OKP=http://host.docker.internal:8081
+```
 
 ---
 
-## Step 4: Configure Lightspeed Stack
+## Step 3: Configure Lightspeed Stack
 
 ### Enable OKP in Lightspeed Stack
 
@@ -276,25 +263,9 @@ curl -sX POST http://localhost:8080/v1/query \
 - **String escaping:** Special Solr characters in filter values are automatically escaped
 - **Works with all search modes:** Filters apply to `semantic`, `hybrid`, and `lexical` search modes
 
-### Configure Lightspeed Stack for library mode
-
-For the simplest local development, configure `lightspeed-stack.yaml` to
-consume Llama Stack in library mode:
-
-```yaml
-llama_stack:
-  ...
-  use_as_library_client: true
-  library_client_config_path: run.yaml
-  # Comment these lines out if present
-  # url: http://lama-stack:87321
-  # api_key: xyzzy
-  ...
-```
-
 ---
 
-## Step 5: Launch Lightspeed Stack
+## Step 4: Launch Lightspeed Stack
 
 Then launch Lightspeed Stack using your Lightspeed Stack
 config(`lightspeed-stack.yaml`) which references the provided default
@@ -314,7 +285,7 @@ INFO     2026-03-17 11:20:31,349 uvicorn.error:224 uncategorized: Uvicorn runnin
 
 ---
 
-## Step 6: Verify the Stack
+## Step 5: Verify the Stack
 
 Confirm that the full stack (Lightspeed Stack + Llama Stack + OKP) is working
 by sending a query and checking that the response includes referenced chunks
diff --git a/providers b/providers
@@ -0,0 +1 @@
+Subproject commit 9ab872996b1b95448a9332bc3b468fe27b4ee2e6
diff --git a/run.yaml b/run.yaml
@@ -15,7 +15,7 @@ apis:
 benchmarks: []
 datasets: []
 image_name: starter
-external_providers_dir: ${env.EXTERNAL_PROVIDERS_DIR}
+external_providers_dir: /opt/app-root/providers/resources/external_providers
 
 providers:
   inference:
diff --git a/src/llama_stack_configuration.py b/src/llama_stack_configuration.py
@@ -496,9 +496,11 @@ def enrich_solr(  # pylint: disable=too-many-locals
     )
 
     rhokp_raw = okp_config.get("rhokp_url")
-    base_url = (
+    base_url_raw = (
         str(rhokp_raw) if rhokp_raw is not None else constants.RH_SERVER_OKP_DEFAULT_URL
     )
+    # Resolve environment variables in the URL (e.g., ${env.RH_SERVER_OKP})
+    base_url = replace_env_vars(base_url_raw)
     solr_url = urljoin(base_url, "/solr")
 
     logger.info("Enriching Llama Stack config with OKP")

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[submodule "providers"]`
	`2`	`+ path = providers`
	`3`	`+ url = https://github.com/lightspeed-core/lightspeed-providers.git`