feat(ai): AI gateway integration with custom provider support

web/CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+All commands use **Yarn** (not npm).
+
+```bash
+yarn dev              # Start dev server (processes env YAML first via scripts/unyamlify-env-local.ts)
+yarn build            # Type-check (tsc) then build for production
+yarn test             # Run all tests once (Vitest, non-watch)
+yarn format           # Format all .ts/.tsx/.json/.md files with Prettier
+yarn format:check     # Check formatting without writing
+yarn storybook        # Launch Storybook on port 6006
+```
+
+**Run a single test file:**
+
+```bash
+yarn vitest run src/core/usecases/launcher/decoupledLogic/computeHelmValues.test.ts
+```
+
+**Run tests matching a name pattern:**
+
+```bash
+yarn vitest run --reporter=verbose -t "pattern"
+```
+
+Pre-commit hooks run `eslint --fix` and `prettier --write` via lint-staged.
+
+## Architecture
+
+Onyxia Web is a React SPA — a data science platform portal for launching Kubernetes services (Helm charts), browsing catalogs, managing S3 files, managing Vault secrets, and querying data via DuckDB. It is deployed as static files served by nginx.
+
+### Core principles
+
+- **React is only for rendering.** Business logic is React-agnostic and lives in `src/core/`. The `src/ui/` layer is strictly for React components and hooks.
+- **Unidirectional dependencies.** `src/core/` never imports from `src/ui/`, not even for types.
+- **Reactive over promise-based.** Thunks update observable state; the UI reacts to state changes. Prefer dispatching actions and reading state over returning values from thunks.
+- **Constants outside Redux state.** Values that don't change are not stored in state — they are retrieved from thunks when needed, to avoid unnecessary re-renders.
+
+### `src/core/` — Business logic
+
+Follows a clean-architecture / ports-and-adapters pattern using the `clean-architecture` npm package (a Redux-like store without Redux).
+
+- **`ports/`** — TypeScript interfaces defining contracts for external dependencies (`OnyxiaApi`, `Oidc`, `S3Client`, `SecretsManager`, `SqlOlap`).
+- **`adapters/`** — Concrete implementations: `onyxiaApi/` (axios-based HTTP), `oidc/` (oidc-spa), `s3Client/` (AWS SDK v3), `secretManager/` (Vault), `sqlOlap/` (DuckDB WASM). Each adapter has a mock counterpart for dev/testing.
+- **`usecases/`** — One folder per feature (20+ total: `catalog`, `launcher`, `serviceManagement`, `fileExplorer`, `secretExplorer`, `dataExplorer`, etc.). Each usecase follows the pattern:
+    - `state.ts` — state shape + `createUsecaseActions` (slice-like)
+    - `thunks.ts` — async side effects, accesses adapters via `createUsecaseContextApi`
+    - `selectors.ts` — memoized state derivations
+    - `index.ts` — re-exports all three
+- **`bootstrap.ts`** — Wires adapters together and creates the core store.
+- **`index.ts`** — Exports `useCoreState`, `getCore`, `createReactApi` bindings consumed by `src/ui/`.
+
+**Complex use-cases** (especially `launcher/`) have a `decoupledLogic/` subfolder with pure functions and no framework dependencies — this is where most unit tests live.
+
+### `src/ui/` — React layer
+
+- **`App/`** — Root layout: Header, LeftBar, Main, Footer. `App.tsx` triggers core bootstrap; `Main.tsx` is the route-based page switcher.
+- **`pages/`** — One folder per route/page. Each page exports `routeDefs` (via `type-route`'s `defineRoute`) and `routeGroup`. All are merged in `pages/index.ts`.
+- **`routes.tsx`** — Router instantiation. Navigation uses `routes.catalog(...).push()` or `session.push()`.
+- **`i18n/`** — i18nifty setup. Translation keys are declared at the component level via `declareComponentKeys`, collected into a `ComponentKey` union in `i18n/types.ts`. Nine languages: en, fr, zh-CN, no, fi, nl, it, es, de.
+- **`theme/`** — onyxia-ui theme setup (palette, fonts, favicon).
+- **`shared/`** — Reusable components (CommandBar, CodeBlock, SettingField, etc.).
+
+### Key patterns
+
+**Consuming core state in React:**
+
+```ts
+import { useCoreState, getCore } from "core";
+const helmReleases = useCoreState(state => state.serviceManagement.helmReleases);
+await getCore().dispatch(usecases.serviceManagement.thunks.initialize());
+```
+
+**Styling — tss-react** (not plain CSS modules):
+
+```ts
+import { tss } from "tss";
+const useStyles = tss.withName({ MyComponent }).create(({ theme }) => ({ ... }));
+const { classes, cx } = useStyles();
+```
+
+**Absolute imports** — `tsconfig.json` sets `baseUrl: "src"`, so use `import { foo } from "core/usecases/catalog"` (not relative paths).
+
+**Environment variables** — All env vars are centrally parsed and validated in `src/env.ts`. The `index.html` is an EJS template processed by `vite-envs` at build time.
+
+**Authentication** — OIDC init (`oidc-spa`) happens before React renders, in `main.tsx`. Use the `Oidc` port interface, not the adapter directly.
+
+**Plugin system** — `src/pluginSystem.ts` exposes `window.onyxia` after boot and fires an `"onyxiaready"` `CustomEvent`, allowing external JS to interact with core state, routes, theme, and i18n.
+
+**Keycloak theme** — `src/keycloak-theme/` is a Keycloakify login theme that shares env and i18n infrastructure with the main app. Build with `yarn build-keycloak-theme`.
+
+## Key libraries
+
+| Library              | Role                                                         |
+| -------------------- | ------------------------------------------------------------ |
+| `onyxia-ui`          | In-house design system on top of MUI v6                      |
+| `type-route`         | Strongly-typed client-side router                            |
+| `i18nifty`           | Component-level i18n                                         |
+| `clean-architecture` | Redux-like store (ports/usecases pattern)                    |
+| `oidc-spa`           | OIDC/OAuth2 authentication                                   |
+| `keycloakify`        | Keycloak login theme from React components                   |
+| `tss-react`          | CSS-in-JS bound to onyxia-ui theme                           |
+| `vite-envs`          | Env var injection into EJS `index.html` at build time        |
+| DuckDB WASM          | In-browser SQL OLAP queries (`dataExplorer`, `sqlOlapShell`) |

web/src/core/adapters/ai/index.ts

@@ -0,0 +1 @@
+export * from "./openWebUi";

web/src/core/adapters/ai/mock.ts

@@ -0,0 +1,18 @@
+import type { Ai } from "core/ports/Ai";
+
+export function createAi(params: { id: string; name: string; webUiUrl: string }): Ai {
+    const { id, name, webUiUrl } = params;
+
+    return {
+        id,
+        name,
+        webUiUrl,
+        apiBase: `${webUiUrl}/api`,
+        getToken: async () => ({ status: "success" as const, token: "mock-ai-token" }),
+        listModels: async () => [
+            { id: "llama3.2", name: "Llama 3.2" },
+            { id: "mistral-7b", name: "Mistral 7B" },
+            { id: "codestral", name: "Codestral" }
+        ]
+    };
+}

web/src/core/adapters/ai/openWebUi.ts

@@ -0,0 +1,52 @@
+import type { Ai, GetTokenResult } from "core/ports/Ai";
+import { oidcTokenExchange, OidcTokenExchangeError } from "core/tools/oidcTokenExchange";
+import { z } from "zod";
+
+export function createAi(params: {
+    id: string;
+    name: string;
+    webUiUrl: string;
+    oauthProvider: string;
+    getOidcAccessToken: () => Promise<string>;
+}): Ai {
+    const { id, name, webUiUrl, oauthProvider, getOidcAccessToken } = params;
+
+    const apiBase = `${webUiUrl}/api`;
+
+    return {
+        id,
+        name,
+        webUiUrl,
+        apiBase,
+        getToken: async (): Promise<GetTokenResult> => {
+            const oidcAccessToken = await getOidcAccessToken();
+
+            return oidcTokenExchange({
+                tokenExchangeEndpoint: `${webUiUrl}/api/v1/auths/oauth/${oauthProvider}/token/exchange`,
+                oidcAccessToken
+            })
+                .then(token => ({ status: "success" as const, token }))
+                .catch((error: unknown) => {
+                    if (error instanceof OidcTokenExchangeError && error.status === 403) {
+                        return { status: "no-account" as const };
+                    }
+                    return { status: "error" as const };
+                });
+        },
+        listModels: async (token: string) => {
+            const response = await fetch(`${apiBase}/models`, {
+                headers: { Authorization: `Bearer ${token}` }
+            });
+
+            if (!response.ok) {
+                throw new Error(`Failed to list models (${response.status})`);
+            }
+
+            const { data } = z
+                .object({ data: z.array(z.object({ id: z.string(), name: z.string() })) })
+                .parse(await response.json());
+
+            return data.map(({ id, name }) => ({ id, name }));
+        }
+    };
+}

web/src/core/adapters/onyxiaApi/ApiTypes.ts

@@ -82,6 +82,13 @@ export type ApiTypes = {
                 };
             };
             data?: {
+                ai?: ArrayOrNot<{
+                    id?: string;
+                    URL: string;
+                    name?: string;
+                    oauthProvider: string;
+                    oidcConfiguration?: Partial<ApiTypes.OidcConfiguration>;
+                }>;
                 S3?: ArrayOrNot<{
                     URL: string;
                     pathStyleAccess?: true;

web/src/core/adapters/onyxiaApi/onyxiaApi.ts

@@ -435,6 +435,27 @@
                                                   apiRegion.vault.oidcConfiguration
                                               )
                                       },
+                            ai: (() => {
+                                const value = apiRegion.data?.ai;
+
+                                const aiConfigs_api =
+                                    value === undefined
+                                        ? []
+                                        : value instanceof Array
+                                          ? value
+                                          : [value];
+
+                                return aiConfigs_api.map(aiConfig_api => ({
+                                    id: aiConfig_api.id ?? aiConfig_api.URL,
+                                    url: aiConfig_api.URL,
+                                    name: aiConfig_api.name,
+                                    oauthProvider: aiConfig_api.oauthProvider,
+                                    oidcParams:
+                                        apiTypesOidcConfigurationToOidcParams_Partial(
+                                            aiConfig_api.oidcConfiguration
+                                        )
+                                }));
+                            })(),
                             proxyInjection:
                                 apiRegion.proxyInjection === undefined
                                     ? undefined

web/src/core/bootstrap.ts

@@ -8,6 +8,7 @@
 import type { SqlOlap } from "core/ports/SqlOlap";
 import { usecases } from "./usecases";
 import type { SecretsManager } from "core/ports/SecretsManager";
+import type { Ai } from "core/ports/Ai";
 import type { Oidc } from "core/ports/Oidc";
 import type { Language } from "core/ports/OnyxiaApi/Language";
 import { createDuckDbSqlOlap } from "core/adapters/sqlOlap";
@@ -38,11 +39,12 @@
     onyxiaApi: OnyxiaApi;
     secretsManager: SecretsManager;
     sqlOlap: SqlOlap;
+    ai: Ai[];
 };
 
 export type Core = GenericCore<typeof usecases, Context>;
 
 export async function bootstrapCore(
     params: ParamsOfBootstrapCore
 ): Promise<{ core: Core }> {
     const {
@@ -83,7 +85,6 @@
                     );
             } catch (error) {
                 if (error instanceof AccessError) {
-                    // NOTE: Not initialized yet, it's not a bug.
                     return undefined;
                 }
                 throw error;
@@ -105,7 +106,6 @@
                     );
             } catch (error) {
                 if (error instanceof AccessError) {
-                    // NOTE: Not initialized yet, it's not a bug.
                     return undefined;
                 }
                 throw error;
@@ -137,7 +137,6 @@
 
     if (isAuthGloballyRequired && !oidc.isUserLoggedIn) {
         await oidc.login({ doesCurrentHrefRequiresAuth: true });
-        // NOTE: Never reached
     }
 
     const context: Context = {
@@ -177,7 +176,8 @@
                     s3_region: s3Profile.paramsOfCreateS3Client.region
                 };
             }
-        })
+        }),
+        ai: []
     };
 
     const { core, dispatch, getState } = createCore({
@@ -275,6 +275,72 @@
         await dispatch(usecases.s3ProfilesManagement.protectedThunks.initialize());
     }
 
+    init_ai: {
+        if (!oidc.isUserLoggedIn) {
+            break init_ai;
+        }
+
+        const deploymentRegion =
+            usecases.deploymentRegionManagement.selectors.currentDeploymentRegion(
+                getState()
+            );
+
+        if (deploymentRegion.ai.length === 0) {
+            break init_ai;
+        }
+
+        const [{ createAi }, { createOidc, mergeOidcParams }, { oidcParams }] =
+            await Promise.all([
+                import("core/adapters/ai"),
+                import("core/adapters/oidc"),
+                onyxiaApi.getAvailableRegionsAndOidcParams()
+            ]);
+
+        assert(oidcParams !== undefined);
+
+        // One Ai adapter per region-provided provider, but providers may share the
+        // same OIDC client: oidc-spa identifies a client by issuerUri + clientId, so
+        // creating it twice would collide. Create each distinct client only once.
+        const getOidcAccessTokenByOidcKey = new Map<string, () => Promise<string>>();
+
+        for (const aiConfig of deploymentRegion.ai) {
+            const oidcParams_ai = mergeOidcParams({
+                oidcParams,
+                oidcParams_partial: aiConfig.oidcParams
+            });
+
+            const oidcKey = `${oidcParams_ai.issuerUri}${oidcParams_ai.clientId}`;
+
+            let getOidcAccessToken = getOidcAccessTokenByOidcKey.get(oidcKey);
+
+            if (getOidcAccessToken === undefined) {
+                const oidc_ai = await createOidc({
+                    ...oidcParams_ai,
+                    transformBeforeRedirectForKeycloakTheme,
+                    getCurrentLang,
+                    autoLogin: true,
+                    enableDebugLogs: enableOidcDebugLogs
+                });
+
+                getOidcAccessToken = async () => (await oidc_ai.getTokens()).accessToken;
+
+                getOidcAccessTokenByOidcKey.set(oidcKey, getOidcAccessToken);
+            }
+
+            context.ai.push(
+                createAi({
+                    id: aiConfig.id,
+                    name: aiConfig.name ?? new URL(aiConfig.url).hostname,
+                    webUiUrl: aiConfig.url,
+                    oauthProvider: aiConfig.oauthProvider,
+                    getOidcAccessToken
+                })
+            );
+        }
+
+        await dispatch(usecases.ai.protectedThunks.initialize());
+    }
+
     pluginSystemInitCore({ core, context });
 
     return { core };

web/src/core/ports/Ai.ts

@@ -0,0 +1,13 @@
+export type Ai = {
+    id: string;
+    name: string;
+    webUiUrl: string;
+    apiBase: string;
+    getToken: () => Promise<GetTokenResult>;
+    listModels: (token: string) => Promise<{ id: string; name: string }[]>;
+};
+
+export type GetTokenResult =
+    | { status: "success"; token: string }
+    | { status: "no-account" }
+    | { status: "error" };

web/src/core/ports/OnyxiaApi/DeploymentRegion.ts

@@ -44,6 +44,13 @@ export type DeploymentRegion = {
               oidcParams: OidcParams_Partial;
           }
         | undefined;
+    ai: {
+        id: string;
+        url: string;
+        name: string | undefined;
+        oauthProvider: string;
+        oidcParams: OidcParams_Partial;
+    }[];
     proxyInjection:
         | {
               enabled: boolean | undefined;

web/src/core/ports/OnyxiaApi/XOnyxia.ts

@@ -182,6 +182,16 @@ export type XOnyxiaContext = {
         useCertManager: boolean;
         certManagerClusterIssuer: string | undefined;
     };
+    ai:
+        | {
+              enabled: boolean;
+              apiKey: string;
+              apiBase: string;
+              model: string;
+              provider: string;
+              embeddingsModel: string;
+          }
+        | undefined;
     proxyInjection:
         | {
               enabled: boolean | undefined;