From 9f3bb2db45d4c4c4e8d06aabd3c75b00bc786bc0 Mon Sep 17 00:00:00 2001 From: Jakub Walaszczyk Date: Fri, 30 Oct 2026 16:36:13 +0100 Subject: [PATCH] Release v0.25.4 Signed-off-by: Jakub Walaszczyk Assisted-by: OpenAI Codex --- README.md | 5 ++ ai4rag/__init__.py | 2 +- .../agentic_rag/README.md | 22 +++++- docs/about/changelog.md | 16 +++- .../assets-generator/starter-kit.md | 73 ++++++++++++++++--- docs/architecture/rag-components.md | 8 ++ docs/getting-started/installation.md | 11 +++ docs/user-guide/pipeline-components.md | 19 +++-- 8 files changed, 130 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index b794ffe0..12f30aeb 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/ai4rag/__init__.py b/ai4rag/__init__.py index 3fe44985..b223b308 100644 --- a/ai4rag/__init__.py +++ b/ai4rag/__init__.py @@ -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")) diff --git a/ai4rag/assets_generator/starter_kit_templates/agentic_rag/README.md b/ai4rag/assets_generator/starter_kit_templates/agentic_rag/README.md index d3516846..fcae5354 100644 --- a/ai4rag/assets_generator/starter_kit_templates/agentic_rag/README.md +++ b/ai4rag/assets_generator/starter_kit_templates/agentic_rag/README.md @@ -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=` or `OPENSHELL_CLI_STATE=` 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 diff --git a/docs/about/changelog.md b/docs/about/changelog.md index 67abfbce..b20d79ec 100644 --- a/docs/about/changelog.md +++ b/docs/about/changelog.md @@ -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) diff --git a/docs/api-reference/assets-generator/starter-kit.md b/docs/api-reference/assets-generator/starter-kit.md index d0ba65f2..0a4b5713 100644 --- a/docs/api-reference/assets-generator/starter-kit.md +++ b/docs/api-reference/assets-generator/starter-kit.md @@ -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. diff --git a/docs/architecture/rag-components.md b/docs/architecture/rag-components.md index adf3a153..a40211b2 100644 --- a/docs/architecture/rag-components.md +++ b/docs/architecture/rag-components.md @@ -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`) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 6c486f83..6608c7e2 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -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_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`. diff --git a/docs/user-guide/pipeline-components.md b/docs/user-guide/pipeline-components.md index 8d3bb18f..275d97da 100644 --- a/docs/user-guide/pipeline-components.md +++ b/docs/user-guide/pipeline-components.md @@ -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