RHIDP-16107: Switch Lightspeed RAG Container to OKP

modules/shared/con-retrieval-augmented-generation-rag-embeddings-for-grounded-ai-responses.adoc

@@ -1,15 +1,29 @@
 :_mod-docs-content-type: CONCEPT
 
 [id="retrieval-augmented-generation-rag-embeddings-for-grounded-ai-responses_{context}"]
-= Retrieval augmented generation (RAG) embeddings for grounded AI responses
+= Retrieval-augmented generation for grounded AI responses
 
 [role="_abstract"]
-Use retrieval-augmented generation (RAG) embeddings to ground artificial intelligence (AI) responses in your internal documentation and provide verified citations during user interactions.
+Use retrieval-augmented generation (RAG) to ground artificial intelligence (AI) responses in {product-very-short} product documentation and provide verified citations during user interactions.
 
-The {product-very-short} documentation serves as the primary data source for RAG operations. To provide accurate citations to production documentation during inference, the system uses RAG embeddings stored within a vector database.
+{product-very-short} {ia-name} uses the Offline Knowledge Portal (OKP) as the RAG backend for product documentation. OKP is a knowledge base curated by Red Hat that contains {product-very-short} product documentation optimized for RAG operations. OKP runs as a standalone service alongside the {ia-brand-name} installation.
 
-The system processes RAG data through the following sequence:
+The {lcs-name} ({lcs-short}) uses OKP as a RAG tool during inference to retrieve relevant {product-very-short} documentation and attaches documentation references to chat responses.
 
-* An initialization container copies the RAG data to a shared volume.
-* The {lcs-name} ({lcs-short}) sidecar container mounts the shared volume to access the data.
-* The sidecar layer uses the embeddings to attach precise documentation references to the chat responses.
+OKP supports the following search modes:
+
+`hybrid`:: The default mode, which combines semantic and keyword search. This mode requires an embedding model.
+`semantic`:: Uses vector-based semantic search. This mode requires an embedding model.
+`keyword`:: Uses BM25 text search. This mode does not require downloading an embedding model, which makes it suitable for disconnected deployments.
+
+OKP is optional and disabled by default on all platforms. The OKP image is large, so enabling it can significantly increase the time of the first installation while the image is downloaded. How you enable OKP depends on your deployment method:
+
+* With the {product} Operator, enable the `intelligent-assistant-okp` add-on flavor alongside the base `intelligent-assistant` flavor. On {ocp-short}, the Operator automatically creates the OKP `Deployment`, `Service`, and `Route`, and sets the OKP service URL for the {lcs-short} sidecar. On other Kubernetes platforms, the Operator deploys OKP, but you must provide the registry credentials, Ingress, TLS, and OKP service URL yourself, because the Operator does not manage Ingress.
+* With the Helm chart, set `intelligentAssistant.okp.enabled` to `true`. On {ocp-short}, the chart creates the OKP `Route` automatically. On other Kubernetes platforms, you must also enable and configure `intelligentAssistant.okp.ingress`.
+
+When OKP is not enabled, the assistant runs without a knowledge base: general chat still works, but product-specific responses might be less accurate.
+
+[NOTE]
+====
+The Notebooks feature, which enables you to upload and query your own documents, uses a separate RAG mechanism and is not affected by the OKP integration.
+====

modules/shared/proc-configure-agent-skills-for-the-intelligent-assistant.adoc

@@ -33,10 +33,10 @@ Otherwise, configure the volume, init container, and mount before you deploy or
 
 .. For an Operator installation, add a strategic merge patch to the {backstage} custom resource (CR):
 +
-[source,yaml,subs="+quotes"]
+[source,yaml,subs="+quotes,+attributes"]
 ----
 apiVersion: rhdh.redhat.com/v1alpha5
-kind: Backstage
+kind: {product-custom-resource-type}
 metadata:
   name: _<rhdh_instance_name>_
 spec:

modules/shared/proc-configure-by-using-the-helm-chart.adoc

@@ -40,7 +40,7 @@ intelligentAssistant:
 +
 [IMPORTANT]
 ====
-Provide only the `name` and `key` of your existing ConfigMap. The chart manages the mount path and file configuration.
+Reference the config map by its `name` and set `key` to `lightspeed-stack.yaml`. Keep the file configuration unchanged so that the Helm deployment mounts it correctly.
 ====
 +
 [source,yaml]
@@ -49,7 +49,7 @@ intelligentAssistant:
   config:
     stack:
       existingConfigMap:
-        name: my-custom-stack
+        name: "my-custom-stack"
         key: lightspeed-stack.yaml
 ----
 

modules/shared/proc-configure-rate-limits-for-intelligent-assistant.adoc

@@ -40,7 +40,7 @@ The following example shows a tightened configuration for a small deployment wit
 +
 [source,yaml]
 ----
-lightspeed:
+intelligent-assistant:
   rateLimit:
     expensive:
       max: 10

modules/shared/proc-configure-safety-guards-in-rhdh.adoc

@@ -6,7 +6,7 @@
 [role="_abstract"]
 Enable the question-validity shield to classify each prompt before {ia-name} answers it, so that off-topic or harmful prompts never reach your answering model.
 
-In {product-very-short} 2.1, {ia-name} validates prompts through a single question-validity shield that {lcs-name} ({lcs-short}) defines in the `lightspeed-stack.yaml` configuration file. This shield replaces the Llama Guard safety provider, registered shield resources, and `run.yaml` overrides used in earlier releases. Do not edit {ogx-name} ({ogx-short}) files or the generated `run.yaml` file to change validation behavior.
+In {product-very-short} {product-version}, {ia-name} validates prompts through a single question-validity shield that {lcs-name} ({lcs-short}) defines in the `lightspeed-stack.yaml` configuration file. This shield replaces the Llama Guard safety provider, registered shield resources, and `run.yaml` overrides used in earlier releases. Do not edit {ogx-name} ({ogx-short}) files or the generated `run.yaml` file to change validation behavior.
 
 The shipped `lightspeed-stack.yaml` file includes the shield in a disabled state. You enable or disable the shield through environment variables in the Kubernetes Secret that {lcs-short} reads. When you enable the shield, {lcs-short} sends each prompt to the validation model, which classifies the prompt as allowed or rejected.
 
@@ -29,7 +29,7 @@ stringData:
 +
 where:
 +
-`ENABLE_VALIDATION`:: Specifies whether the shield is enabled. You must set the value to `question_validity`. A nonempty value such as `true` does not enable the shield in {product-very-short} 2.1.
+`ENABLE_VALIDATION`:: Specifies whether the shield is enabled. You must set the value to `question_validity`. A nonempty value such as `true` does not enable the shield in {product-very-short} {product-version}.
 `VALIDATION_PROVIDER`:: Specifies the type of the inference provider that runs the classification, for example, `openai` or `vllm`. A provider of this type must be enabled in `inference.providers`.
 `VALIDATION_MODEL_NAME`:: Specifies the model that classifies each prompt. If the provider defines `allowed_models`, include this model in that list.
 +
@@ -59,5 +59,5 @@ Running without query validation increases the risk of off-topic or harmful mode
 . Apply the updated Secret, and then restart the {lcs-short} service so that the container reads the new environment variables.
 
 .Verification
-. Open the *Intelligent Assistant* and submit a development question, for example, `How do I create a software template in {product-very-short}?`. Confirm that the assistant answers the question.
+. Open the *{ia-short}* and submit a development question, for example, `How do I create a software template in {product-very-short}?`. Confirm that the assistant answers the question.
 . Submit a clearly unrelated question, for example, `What is a good recipe for pizza?`. Confirm that the assistant rejects the question when validation is enabled.

modules/shared/proc-create-isolated-research-workspaces.adoc

@@ -5,7 +5,7 @@
 [role="_abstract"]
 Organize your work into individual notebook sessions to keep research topics separate and private.
 
-image::integrate_shared/intelligent-assistant-notebook-fullscreen-page.png["Notebook upload option"]
+image::integrate_interacting-with-the-developer-hub-intelligent-assistant/intelligent-assistant-notebook-fullscreen-page.png["Notebook upload option"]
 
 .Procedure
 . In the {product-very-short} interface, click the *Open intelligent assistant* floating action button (FAB) at the lower right of the screen to open the chat overlay.

modules/shared/proc-mirror-images-for-helm-deployments-on-kubernetes.adoc

@@ -18,42 +18,58 @@ Isolate image references, copy them manually to your internal registry, and upda
 ----
 $ helm show values redhat-developer-hub --repo https://charts.openshift.io/ --version {product-chart-version} > values.default.yaml
 
-LS_RAG_IMAGE=$(yq '.global.lightspeed.initContainer.image | .registry + "/" + .repository' values.default.yaml)
-LS_RAG_DIGEST=$(yq '.global.lightspeed.initContainer.image.tag' values.default.yaml)
-LS_CORE_IMAGE=$(yq '.global.lightspeed.sidecar.image | .registry + "/" + .repository' values.default.yaml)
-LS_CORE_DIGEST=$(yq '.global.lightspeed.sidecar.image.tag' values.default.yaml)
+LS_OKP_REGISTRY=$(yq -r '.intelligentAssistant.okp.image.registry' values.default.yaml)
+LS_OKP_REPOSITORY=$(yq -r '.intelligentAssistant.okp.image.repository' values.default.yaml)
+LS_OKP_DIGEST=$(yq -r '.intelligentAssistant.okp.image.digest' values.default.yaml)
+LS_OKP_IMAGE="${LS_OKP_REGISTRY}/${LS_OKP_REPOSITORY}"
+
+LS_CORE_REGISTRY=$(yq -r '.intelligentAssistant.core.image.registry' values.default.yaml)
+LS_CORE_REPOSITORY=$(yq -r '.intelligentAssistant.core.image.repository' values.default.yaml)
+LS_CORE_DIGEST=$(yq -r '.intelligentAssistant.core.image.digest' values.default.yaml)
+LS_CORE_IMAGE="${LS_CORE_REGISTRY}/${LS_CORE_REPOSITORY}"
 ----
 
 . Mirror the images to your internal mirror registry:
 +
 [source,terminal]
 ----
-skopeo copy --all docker://${LS_RAG_IMAGE}:${LS_RAG_DIGEST} docker://<mirror_registry_name>/<ls_rag_repo_name>:${LS_RAG_DIGEST}
-skopeo copy --all docker://${LS_CORE_IMAGE}:${LS_CORE_DIGEST} docker://<mirror_registry_name>/<ls_core_repo_name>:${LS_CORE_DIGEST}
+skopeo copy --all docker://${LS_OKP_IMAGE}@${LS_OKP_DIGEST} docker://<mirror_registry_name>/<ls_okp_repo_name>@${LS_OKP_DIGEST}
+skopeo copy --all docker://${LS_CORE_IMAGE}@${LS_CORE_DIGEST} docker://<mirror_registry_name>/<ls_core_repo_name>@${LS_CORE_DIGEST}
 ----
 
 . Update your custom Helm values file with the mirrored registry locations and plugin references. Mirror the dynamic plugins to the local registry before you add their package paths to the file. For mirroring instructions, see {installing-and-viewing-plugins-book-link}#mirror-rhdh-dynamic-plugins-in-disconnected-environments_install-dynamic-plugins-in-rhdh[Mirroring {product} dynamic plugins in disconnected environments]:
 +
 [source,yaml]
 ----
-global:
-  lightspeed:
-    initContainer:
-      image:
-        registry: "<mirror_registry_name>"
-        repository: <ls_rag_repo_name>
-        tag: "${LS_RAG_DIGEST}"
-    sidecar:
-      image:
-        registry: "<mirror_registry_name>"
-        repository: <ls_core_repo_name>
-        tag: "${LS_CORE_DIGEST}"
-    plugins:
-      - package: "oci://<mirror_registry_name>/rhdh/red-hat-developer-hub-backstage-plugin-lightspeed@<ls_frontend_digest>"
-        disabled: false
-      - package: "oci://<mirror_registry_name>/rhdh/red-hat-developer-hub-backstage-plugin-lightspeed-backend@<ls_backend_digest>"
-        disabled: false
+intelligentAssistant:
+  enabled: true
+  core:
+    image:
+      registry: <mirror_registry_name>
+      repository: <ls_core_repo_name>
+      tag: ""
+      digest: <ls_core_digest>
+  okp:
+    enabled: true
+    image:
+      registry: <mirror_registry_name>
+      repository: <ls_okp_repo_name>
+      tag: ""
+      digest: <ls_okp_digest>
+    ingress:
+      enabled: true
+      host: <okp_ingress_host>
+  plugins:
+    - package: "oci://<mirror_registry_name>/rhdh/red-hat-developer-hub-backstage-plugin-intelligent-assistant@<ls_frontend_digest>"
+      enabled: true
+    - package: "oci://<mirror_registry_name>/rhdh/red-hat-developer-hub-backstage-plugin-intelligent-assistant-backend@<ls_backend_digest>"
+      enabled: true
 ----
++
+[NOTE]
+====
+OKP is disabled by default. On non-{platform-generic} platforms, enable it by setting `intelligentAssistant.okp.enabled` to `true` and configuring `intelligentAssistant.okp.ingress` with an Ingress host.
+====
 
 .Additional resources
 * {installing-and-viewing-plugins-book-link}#mirror-rhdh-dynamic-plugins-in-disconnected-environments_install-dynamic-plugins-in-rhdh[Mirror {product} dynamic plugins in disconnected environments]

modules/shared/proc-mirror-images-for-helm-deployments-on-ocp.adoc

@@ -12,16 +12,21 @@ Mirror the required {ia-name} container images to your local registry by using t
 
 .Procedure
 
-. Identify the initialization and sidecar container images from the default values file of the chart:
+. Identify the OKP and {lcs-short} container images from the default values file of the chart:
 +
 [source,terminal,subs=attributes]
 ----
 helm show values redhat-developer-hub --repo https://charts.openshift.io/ --version {product-chart-version} > values.default.yaml
 
-LS_RAG_IMAGE=$(yq '.global.lightspeed.initContainer.image | .registry + "/" + .repository' values.default.yaml)
-LS_RAG_DIGEST=$(yq '.global.lightspeed.initContainer.image.tag' values.default.yaml)
-LS_CORE_IMAGE=$(yq '.global.lightspeed.sidecar.image | .registry + "/" + .repository' values.default.yaml)
-LS_CORE_DIGEST=$(yq '.global.lightspeed.sidecar.image.tag' values.default.yaml)
+LS_OKP_REGISTRY=$(yq -r '.intelligentAssistant.okp.image.registry' values.default.yaml)
+LS_OKP_REPOSITORY=$(yq -r '.intelligentAssistant.okp.image.repository' values.default.yaml)
+LS_OKP_DIGEST=$(yq -r '.intelligentAssistant.okp.image.digest' values.default.yaml)
+LS_OKP_IMAGE="${LS_OKP_REGISTRY}/${LS_OKP_REPOSITORY}"
+
+LS_CORE_REGISTRY=$(yq -r '.intelligentAssistant.core.image.registry' values.default.yaml)
+LS_CORE_REPOSITORY=$(yq -r '.intelligentAssistant.core.image.repository' values.default.yaml)
+LS_CORE_DIGEST=$(yq -r '.intelligentAssistant.core.image.digest' values.default.yaml)
+LS_CORE_IMAGE="${LS_CORE_REGISTRY}/${LS_CORE_REPOSITORY}"
 ----
 
 . Add these images to the `additionalImages` section of your `ImageSetConfiguration` file:
@@ -32,8 +37,8 @@ apiVersion: mirror.openshift.io/v2alpha1
 kind: ImageSetConfiguration
 mirror:
   additionalImages:
-    - name: ${LS_RAG_IMAGE}:${LS_RAG_DIGEST}
-    - name: ${LS_CORE_IMAGE}:${LS_CORE_DIGEST}
+    - name: ${LS_OKP_IMAGE}@${LS_OKP_DIGEST}
+    - name: ${LS_CORE_IMAGE}@${LS_CORE_DIGEST}
   helm:
     repositories:
       - name: openshift-charts

modules/shared/proc-mirror-images-for-operator-deployments.adoc

@@ -1,43 +1,49 @@
 :_mod-docs-content-type: PROCEDURE
 [id="mirror-images-for-operator-deployments_{context}"]
-= Mirror {ia-name} images for air-gapped environments
+= Mirror {ia-name} images for disconnected environments
 
 [role="_abstract"]
-Mirror the required {ia-name} container images and plugins to your local registry to provide chat assistance in an air-gapped environment. 
+Mirror the required {ia-name} container images and plugins to your local registry to provide chat assistance in an disconnected environment. 
 
-The {installing-in-air-gap-book-link}#install-rhdh-in-a-fully-disconnected-environment-with-the-operator_install-rhdh-in-an-air-gapped-environment-with-the-operator[`prepare-restricted-environment.sh`] script does not automatically parse `{ia-name}` images from the bundle manifest, so mirror these images manually before running the script.
+The {lcs-short} and OKP images are embedded in the {ia-name} flavour and plugin-dependency `ConfigMap` resources rather than listed in the Operator cluster service version (CSV) `relatedImages` field. As a result, the {installing-in-air-gap-book-link}#install-rhdh-in-a-fully-disconnected-environment-with-the-operator_install-rhdh-in-an-disconnected-environment-with-the-operator[`prepare-restricted-environment.sh`] script does not automatically parse `{ia-name}` images from the bundle manifest. You must explicitly mirror these images and configure the cluster to redirect the original image references to your mirror registry before running the script.
 
 .Prerequisites
 * You have a target mirror registry accessible to your disconnected cluster.
 * You authenticated to the {rhcr} and your target mirror registry.
-* You have configured image pull authentication for your mirror registry as described in {installing-in-air-gap-book-link}#install-rhdh-in-an-air-gapped-environment-with-the-operator[Install {product} in an air-gapped environment with the Operator]. The `kubelet` requires these credentials to pull all {product} container images, including the {ia-name} sidecar images.
+* You have configured image pull authentication for your mirror registry as described in {installing-in-air-gap-book-link}#install-rhdh-in-an-disconnected-environment-with-the-operator[Install {product} in an disconnected environment with the Operator]. The `kubelet` requires these credentials to pull all {product} container images, including the {ia-name} sidecar images.
 
 .Procedure
 
-. Extract the deployment configurations from the official Operator bundle:
+. Extract the deployment configurations from the official Operator bundle. The {lcs-short} sidecar image is defined in the `intelligent-assistant` flavour config map, and the OKP image is defined in the plugin dependencies config map:
 +
 [source,terminal,subs=+attributes]
 ----
 BUNDLE_IMAGE="registry.redhat.io/rhdh/rhdh-operator-bundle:{product-version}"
 CONTAINER_ID=$(podman create "${BUNDLE_IMAGE}")
-podman cp $CONTAINER_ID:/manifests/rhdh-flavour-lightspeed-config_v1_configmap.yaml ./lightspeed-config.yaml
+podman cp $CONTAINER_ID:/manifests/rhdh-flavour-intelligent-assistant-config_v1_configmap.yaml ./lightspeed-config.yaml
+podman cp $CONTAINER_ID:/manifests/rhdh-plugin-deps_v1_configmap.yaml ./plugin-deps-config.yaml
 podman rm $CONTAINER_ID
 ----
 
-. Identify the initialization and sidecar container image tags from the extracted configuration file:
+. Identify the {lcs-short} and OKP container image tags from the extracted configuration files:
 +
 [source,terminal]
 ----
-LS_RAG_IMAGE=$(yq '.data["deployment.yaml"]' lightspeed-config.yaml | yq '.spec.template.spec.initContainers[] | select(.name == "init-rag-data") | .image')
 LS_CORE_IMAGE=$(yq '.data["deployment.yaml"]' lightspeed-config.yaml | yq '.spec.template.spec.containers[] | select(.name == "lightspeed-core") | .image')
+LS_OKP_IMAGE=$(yq '.data["okp.yaml"]' plugin-deps-config.yaml | yq 'select(.kind == "Deployment") | .spec.template.spec.containers[] | select(.name == "okp") | .image' | head -1)
 ----
++
+[NOTE]
+====
+OKP is an optional add-on that is disabled by default. Mirror the OKP image only if you intend to enable the `intelligent-assistant-okp` flavour.
+====
 
 . Mirror the images to your internal registry by running the `skopeo copy` command:
 +
 [source,terminal]
 ----
-skopeo copy docker://${LS_RAG_IMAGE} docker://<mirror_registry>/<ls_rag_repo>@<digest>
 skopeo copy docker://${LS_CORE_IMAGE} docker://<mirror_registry>/<ls_core_repo>@<digest>
+skopeo copy docker://${LS_OKP_IMAGE} docker://<mirror_registry>/<ls_okp_repo>@<digest>
 ----
 
 .Additional resources

modules/shared/proc-mount-agent-skills-by-using-a-configmap.adoc

@@ -30,10 +30,10 @@ Specify each file individually. When you pass a directory to `--from-file`, `oc`
 
 .. For an Operator installation, use the same `configMap` volume definition in a strategic merge patch to the {backstage} custom resource (CR):
 +
-[source,yaml,subs="+quotes"]
+[source,yaml,subs="+quotes,+attributes"]
 ----
 apiVersion: rhdh.redhat.com/v1alpha5
-kind: Backstage
+kind: {product-custom-resource-type}
 metadata:
   name: _<rhdh_instance_name>_
 spec: