LukaszCmielowski · Oct 30, 2026 · Oct 30, 2026
@@ -68,6 +68,11 @@ Each config is a frozen dataclass with a `.from_env()` constructor and an `env_v
 
 ai4RAG uses [`docling-core`](https://github.com/docling-project/docling-core) for document representation and chunking. Documents are represented as `DoclingDocument` instances, and the `DoclingChunker` leverages docling's `HybridChunker` for structure-aware, token-aware chunking. `docling-core`, `openai`, `langchain`/`langchain-openai`, and the vector store clients (`pymilvus` with Milvus Lite, `pgvector`, `asyncpg`) are all installed automatically with `ai4rag`.
 
+The core dependency `certifi>=2026.7.22,<2027` supplies public CA roots when MaaS
+clients add deployment-mounted CA bundles. See
+[private CA configuration](https://ibm.github.io/ai4rag/latest/user-guide/pipeline-components/#private-ca-certificates-on-openshift-ai)
+for explicit bundle settings and automatic mounted-bundle discovery.
+
 For OCR and audio ingestion, install `ai4rag[text-extraction]`. This extra includes
 `rapidocr~=3.9.2`, `onnxruntime~=1.25.0`, and `huggingface-hub>=0.30,<2` along with
 Docling's conversion and audio dependencies. Both the core package and this extra

@@ -5,7 +5,7 @@
 import logging
 import os
 
-__version__ = "0.25.3"
+__version__ = "0.25.4"
 
 logger = logging.getLogger("ai4rag")
 logger.setLevel(os.getenv("LOG_LEVEL", "INFO"))

@@ -24,6 +24,7 @@ and answer using the evidence found.
   certificates in `~/.config/openshell` (`OPENSHELL_CLI_STATE`), so no local
   OpenShell CLI installation is required.
 - `uv` installed locally to update the dependency lockfile.
+- `python3` and `curl` installed locally for image discovery and API CA checks.
 - An OpenShift AI MaaS deployment exposing chat and embedding models, together
   with credentials. The chat model must support tool calling so the agent can
   invoke the retriever.
@@ -43,10 +44,14 @@ and answer using the evidence found.
   index documents.
 - The Red Hat build of the Agent Sandbox operator installed in the cluster.
 
-> **Hint:** For production deployments, we recommend using the Red Hat OpenShell
-> sandbox image `registry.redhat.io/rhoai/odh-openshell-sandbox-rhel9` as the
-> `BASE_IMAGE` in `Containerfile.openshell`, with a tag or digest appropriate for
-> your environment.
+`make build-openshell` selects the Red Hat OpenShell sandbox base from the latest
+succeeded RHOAI ClusterServiceVersion (CSV), and builds its Python 3.12 runtime
+using UBI. The containerized CLI also uses the RHOAI CSV image, with a matching
+`quay.io/rhoai` fallback when needed. The CSV namespace defaults to
+`redhat-ods-operator`; export `RHOAI_CSV_NAMESPACE` to select another namespace.
+Export `OPENSHELL_BASE_IMAGE` or `OPENSHELL_CLI_IMAGE` to override image selection.
+Editing only the Containerfile's `BASE_IMAGE` default does not override the
+Makefile's build selection.
 
 ### Commands
 
@@ -57,6 +62,7 @@ Run the following commands from the starter-kit root directory:
 uv lock --upgrade-package ai4rag
 
 make build-openshell
+make refresh-certs
 make deploy-openshell
 ```
 
@@ -73,9 +79,17 @@ make refresh-certs
 This target pulls the client certificates from the `openshell-client-tls` secret
 and registers the `openshell-gateway` route as gateway `openshift`. Re-run it
 after the cluster gateway is recreated or the certificates are rotated.
+For another gateway namespace, export `OPENSHELL_NAMESPACE` (default `openshell`).
+Pass `OPENSHELL_GATEWAY_NAME=<name>` or `OPENSHELL_CLI_STATE=<directory>` to `make`
+when using another registration name or host state directory. Use the same settings
+as the administrator's gateway setup. The gateway must be compatible with the
+downstream RHOAI CLI; an upstream 0.0.99 gateway needs migration by its administrator.
 
 `make deploy-openshell` creates and configures the sandbox, starts the agent,
 and exposes it through an OpenShift route.
+It checks gateway connectivity before replacing an existing sandbox. The generated
+agent startup enables a local CONNECT proxy for Milvus gRPC and native database
+connections under OpenShell's egress policies.
 
 To remove the sandbox and the agent route, run `make undeploy-openshell`. The
 cluster gateway, the images, and the other cluster prerequisites are left

@@ -7,12 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## Unreleased
+## [0.25.4](https://github.com/IBM/ai4rag/releases/tag/v0.25.4)
+
+### Changed
+
+- **Assets generator** — generated starter kits run the RHOAI OpenShell CLI through Podman and build a Python 3.12 runtime on the Red Hat sandbox base; CLI and sandbox image selection follows the installed RHOAI CSV, with registry fallbacks
+- **OpenShell gateway** — setup provisions the downstream Red Hat OpenShell 3.6 gateway with mTLS authentication and RHOAI image references; an explicit `--reset` option supports migration from the incompatible upstream 0.0.99 gateway database
+- **Dependencies** — added an explicit `certifi>=2026.7.22,<2027` dependency for public CA roots used alongside mounted MaaS certificates
 
 ### Fixed
 
-- **MaaS TLS** — fall back to a mounted `SSL_CERT_DIR`/`ca.crt` when no explicit CA is configured; defaults unchanged if the mount is absent
+- **Text extraction** — local Whisper ASR uses native timestamp-aware long-form generation instead of fixed 30-second pipeline windows; multilingual models explicitly transcribe the source language while retaining automatic detection unless the model config specifies a language
+- **MaaS TLS** — add mounted `SSL_CERT_DIR`/`ca.crt` bundles to public trust when `ca_bundle`, `MAAS_CA_BUNDLE`, and `SSL_CERT_FILE` are unset; defaults remain unchanged when the mount is absent
 - **MaaS TLS** — preserve hashed certificate-directory trust when adding plain bundles and retain configured CA trust in synchronous and asynchronous agent chat clients
+- **Assets generator** — OpenShell starter kits route Milvus gRPC through a local CONNECT proxy, retain native database tunneling, and use the cluster API endpoint with a CA bundle checked against that endpoint for service-account authentication
+- **Assets generator** — OpenShell deployment respects the gateway namespace, handles Kyverno pull-secret conflicts with runtime-image mirroring and sandbox retries, and improves build completion checks and agent startup recovery
+- **Assets generator** — `make refresh-certs` registers the cluster gateway and refreshes mTLS credentials; sandbox creation checks gateway connectivity before replacing an existing sandbox and reports recovery instructions when unavailable
+
+---
 
 ## [0.25.3](https://github.com/IBM/ai4rag/releases/tag/v0.25.3)
 

@@ -36,7 +36,7 @@ require a collection that has already been indexed; document indexing is a separ
 pipeline step.
 
 Deployment requires an OpenShift cluster with the Agent Sandbox operator, a logged-in
-`oc` client, `podman`, and `uv`. The generated Makefile runs the OpenShell CLI from the
+`oc` client, `podman`, `uv`, `python3`, and `curl`. The generated Makefile runs the OpenShell CLI from the
 RHOAI image in a container and keeps the gateway registration and the mTLS client
 certificates in `~/.config/openshell`, so no local OpenShell CLI installation is needed.
 It also requires an OpenShell gateway that is already installed on the cluster.
@@ -59,6 +59,26 @@ Helm, `curl`, `jq`, and `podman` installed and the required cluster permissions:
 bash scripts/setup-openshell-gateway.sh
 ```
 
+The script installs the downstream Red Hat OpenShell 3.6 gateway with mTLS
+authentication. It reads gateway, sandbox runtime, supervisor, and CLI image
+references from the installed RHOAI ClusterServiceVersion (CSV), preserving image
+digests. The Helm chart is pinned by `OPENSHELL_CHART_REPO` and
+`OPENSHELL_CHART_REF`; these replace the former `OPENSHELL_VERSION` setting.
+Run `bash scripts/setup-openshell-gateway.sh --help` for all setup overrides.
+
+!!! warning "Migrating an upstream 0.0.99 gateway"
+    The downstream 3.6 gateway cannot read the upstream 0.0.99 gateway database.
+    A cluster administrator must reset that database during migration with
+    `bash scripts/setup-openshell-gateway.sh --reset` (or `OPENSHELL_RESET=true`).
+    This deletes gateway records for sandboxes, policies, and stored credentials;
+    workspace PVCs are preserved. Recreate the required sandbox deployments afterward.
+
+Gateway setup automatically mirrors sandbox runtime and supervisor images into the
+cluster registry when the `add-imagepullsecrets` Kyverno policy is installed.
+`OPENSHELL_MIRROR_RUNTIME_IMAGES=true` or `false` overrides this detection. Sandbox
+creation also retries the specific Pod-update failure caused by duplicated pull
+secrets, with `SANDBOX_CREATE_ATTEMPTS=3` by default.
+
 The generated Makefile has no `setup-gateway` or `teardown-gateway` targets.
 Manage the shared cluster gateway separately from starter-kit deployment.
 
@@ -80,27 +100,56 @@ text for the agent. Use `MILVUS_CA_CERT` in place of the obsolete `MILVUS_SERVER
 For Neo4j, use a verified TLS URI such as `neo4j+s://host:7687`; egress setup reads
 the host and port from that URI, defaulting to port `7687` when it is omitted.
 
-For pgvector and Neo4j, the generated OpenShell image includes `proxychains4` and an
-entrypoint that tunnels native TCP connections through OpenShell's HTTP CONNECT proxy.
-When either `PGVECTOR_HOST` or `NEO4J_URI` is set, startup requires a proxy supplied through `grpc_proxy`,
-`GRPC_PROXY`, `https_proxy`, `HTTPS_PROXY`, `http_proxy`, or `HTTP_PROXY` (first
-non-empty value wins). The proxy must use HTTP, have no authentication, and resolve
-to an IPv4 address. If both database variables are unset, the entrypoint launches
-the agent directly.
-
-For production deployments, the generated README recommends
-`registry.redhat.io/rhoai/odh-openshell-sandbox-rhel9` as the `BASE_IMAGE` in
-`Containerfile.openshell`, with a tag or digest appropriate for your environment.
+The generated OpenShell image includes Python 3.12 and `proxychains4`. The Makefile
+sets `OPENSHELL_GRPC_PROXY_PORT=18080` when starting the agent, enabling a local
+IPv4 HTTP CONNECT proxy for Milvus gRPC and native pgvector/Neo4j TCP traffic
+under OpenShell's egress policies. For Kubernetes service-account authentication,
+deployment uses the API endpoint reported by `oc whoami --show-server` and selects
+CA material from the cluster trust bundles.
+
+If the entrypoint is used without `OPENSHELL_GRPC_PROXY_PORT`, setting
+`PGVECTOR_HOST` or `NEO4J_URI` selects the direct OpenShell proxy mode. That mode
+reads `grpc_proxy`, `GRPC_PROXY`, `https_proxy`, `HTTPS_PROXY`, `http_proxy`, or
+`HTTP_PROXY` (first non-empty value wins); the proxy must use HTTP, have no
+authentication, and resolve to IPv4. With neither a local-proxy setting nor a
+native database host, the entrypoint launches the agent directly.
+
+`make build-openshell` selects the Red Hat sandbox base image from the latest
+succeeded RHOAI CSV and assembles its Python runtime using UBI Python 3.12.
+Set `OPENSHELL_BASE_IMAGE` to override the build's base image; editing the
+Containerfile's default `BASE_IMAGE` alone does not override the Makefile.
+The CLI can fall back to a matching image under `quay.io/rhoai`, and failed
+`registry.redhat.io` sandbox-image pulls are retried through `quay.io`.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `RHOAI_CSV_NAMESPACE` | `redhat-ods-operator` | Namespace queried for the installed RHOAI CSV |
+| `OPENSHELL_CLI_IMAGE` | RHOAI CSV CLI image | Override the containerized CLI image |
+| `OPENSHELL_BASE_IMAGE` | RHOAI CSV sandbox image | Override the sandbox build's base image |
+| `OPENSHELL_FALLBACK_REGISTRY` | `quay.io/rhoai` | Registry prefix used for CLI image fallback |
+| `OPENSHELL_NAMESPACE` | `openshell` | Namespace of the gateway, certificates, and agent route |
+| `OPENSHELL_GATEWAY_NAME` | `openshift` | Gateway registration selected by the CLI |
+| `OPENSHELL_CLI_STATE` | `~/.config/openshell` | Host directory holding gateway registration and mTLS credentials |
+| `OPENSHELL_PODMAN_USERNS` | `--userns=keep-id` | User-namespace flags for the CLI container |
+
+Export environment settings before running `make`. Make variables such as
+`OPENSHELL_GATEWAY_NAME` and `OPENSHELL_CLI_STATE` can also be passed on its command
+line. To use a compatible locally installed CLI, pass `OPENSHELL_CLI=openshell`.
 
 Run these commands from the extracted starter-kit directory:
 
 ```bash
 uv lock --upgrade-package ai4rag
 make build-openshell
+make refresh-certs
 make deploy-openshell
 ```
 
 Run `make refresh-certs` if the gateway registration or the mTLS client certificates
 are missing or stale.
 
+Sandbox creation checks gateway connectivity before replacing an existing sandbox.
+Run `make undeploy-openshell` to remove the sandbox and agent route; shared gateway
+resources and built images remain available.
+
 Regenerate older starter kits to obtain the updated Makefile and deployment guidance.
@@ -1365,6 +1365,14 @@ class AgenticRAG(BaseRAGTemplate):
 - `enable_context_compression` enables one retry after a recognized context
   overflow. It must be a boolean and defaults to `True`.
 
+When `create_maas_client()` configures per-client CA trust through `ca_bundle`,
+`MAAS_CA_BUNDLE`, or the mounted `SSL_CERT_DIR`/`ca.crt` fallback, the automatically
+constructed chat model reuses that client's synchronous completions interface and
+applies the same trust to its asynchronous HTTP client. Both retain the OpenAI
+SDK's HTTP client defaults. A supplied `chat_model` is used as configured. See
+[Private CA certificates on OpenShift AI](../user-guide/pipeline-components.md#private-ca-certificates-on-openshift-ai)
+for CA selection and precedence.
+
 **How it works:**
 
 1. An initial retrieval (via the inherited `_build_enriched_user_message`)

@@ -43,6 +43,10 @@ No extra step is needed to use a remote Milvus server, embedded Milvus Lite, Pos
 compatibility. Generated knowledge-graph indexing notebooks call `nest_asyncio.apply()`
 before graph extraction.
 
+`certifi>=2026.7.22,<2027` is installed as a core dependency to supply public CA
+roots alongside deployment-mounted MaaS certificates. Include it in offline package
+mirrors when upgrading.
+
 !!! note "OCR and audio ingestion"
     Text extraction from born-digital documents (PDF, DOCX, Markdown, HTML, …) works out of the box.
     Scanned PDFs/images (via RapidOCR) and audio transcription (via a local Hugging Face Whisper model)
@@ -223,6 +227,13 @@ MAAS_BASE_URL="<maas_endpoint_url>"
 MAAS_API_KEY="<maas_api_key>"
 ```
 
+!!! note "Private CA certificates for MaaS"
+    Pass a PEM bundle path as `ca_bundle=` to `create_maas_client()`, or set
+    `MAAS_CA_BUNDLE`. When both are unset and `SSL_CERT_FILE` is also unset, the
+    factory adds a mounted `ca.crt` under `SSL_CERT_DIR` to certifi's public trust.
+    See [Private CA certificates on OpenShift AI](../user-guide/pipeline-components.md#private-ca-certificates-on-openshift-ai)
+    for precedence and platform configuration.
+
 !!! warning "Security"
     **Never commit your `.env` file to version control.** Add it to `.gitignore`.
 

@@ -87,13 +87,18 @@ The MaaS client (`create_maas_client()`) honors the same pattern via `MAAS_CA_BU
 os.environ.setdefault("MAAS_CA_BUNDLE", "/etc/pki/tls/custom-certs/ca-bundle.crt")
 ```
 
-When no explicit CA is set, `create_maas_client()` also accepts a plain
-`ca.crt` under `SSL_CERT_DIR` (DSP task pods) and adds it to public trust.
-Missing mounts leave defaults unchanged; invalid bundles raise.
-Existing hashed certificate directories remain trusted alongside the plain bundle.
-When per-client CA trust is configured, agent chat requests reuse the MaaS client
-for synchronous calls and retain the same CA configuration for asynchronous calls.
-Without per-client CA settings, agent client construction remains unchanged.
+`create_maas_client()` uses a non-empty `ca_bundle=` argument first, then
+`MAAS_CA_BUNDLE`. If neither is set, a non-empty `SSL_CERT_FILE` leaves trust
+configuration to the SDK/HTTPX defaults and disables the mounted-bundle fallback.
+Otherwise, the factory looks for a plain `ca.crt` in each directory listed in
+`SSL_CERT_DIR` (separated by `os.pathsep`, `:` on Linux and macOS). When found,
+these PEM bundles are added to certifi's public CA roots; existing hashed
+certificate-directory trust is preserved. Missing mounts leave defaults unchanged;
+invalid mounted bundles raise rather than disabling verification.
+
+For clients created by this factory with per-client CA trust, `AgenticRAG` reuses
+the MaaS client for synchronous chat calls and applies the same CA configuration
+to asynchronous calls, retaining the OpenAI SDK's HTTP client defaults.
 
 ## Data Components