diff --git a/docs/en/build-custom-kb.mdx b/docs/en/build-custom-kb.mdx new file mode 100644 index 0000000..dd0b595 --- /dev/null +++ b/docs/en/build-custom-kb.mdx @@ -0,0 +1,305 @@ +--- +weight: 18 +--- + +# Build a Custom Knowledge Base + +The Alauda Hyperflux plugin ships with a built-in **system knowledge base** covering Alauda Container Platform +(ACP) and Alauda product documentation. Alongside it, Hyperflux maintains a separate **user knowledge base** +that you can fill with your own content — internal runbooks, SRE playbooks, design documents, versions of +Alauda product docs that don't ship in the bundled corpus, or any other private Git repositories. Hyperflux +retrieves from **both** knowledge bases on every question and merges the results, so adding a custom corpus +**augments** the bundled product knowledge rather than replacing it. + +This guide covers the admin-driven path: bulk-ingest a list of Git repositories into the user knowledge base +using the in-pod builder. (For end-user file uploads through the chat UI, use the BYO Knowledge tool added +in v1.3.1 — same destination, different entry point.) + +The workflow runs **inside the deployed `smart-doc` pod**. The image already contains the builder source, +the embedding model, and the right Python environment, and the pod already has connectivity to the user +knowledge-base PostgreSQL. You only need a manifest of repositories to ingest and `kubectl exec` access to +the global cluster. + +## How the embedding pipeline works + +The smart-doc builder turns a list of Git repositories into a vectorised knowledge base in two stages: + +1. **Prepare** — clone the repos, split each `.md` / `.mdx` document by heading and chunk size, then call an LLM + (the same one already configured for the running Hyperflux plugin) to generate a one-paragraph summary and + a few representative questions per document. Output: `documents.json`. +2. **Embed** — load the `gte-multilingual-base` embedding model, embed both the chunks and the per-document + summaries, and write them to the user-knowledge-base PostgreSQL (`docvec_user_kb`) under the collection + name the running server reads (`user_defined_kb` by default). + +Once embedded, the running server picks up the new content **on the next query** — no chart edit, no pod +restart. The system knowledge base is untouched. + +> **NOTE:** The BM25 index used by hybrid retrieval is **not** built by the embed step. The bundled system-KB +> dumps include a pre-built BM25 index, but the user-KB database is created empty during install. If your +> deployment has hybrid retrieval enabled (the default), you must create the BM25 index on the user-KB +> collection once — see Step 5. + +## Prerequisites + +- `kubectl` access to the cluster running Hyperflux (the global cluster) with `exec` permission on the + `smart-doc` pod in the `cpaas-system` namespace. +- **Read access** to every Git repository you want to ingest. If they are private, have an HTTPS user/token + pair ready. +- **An LLM endpoint with sufficient quota.** The prepare phase calls the LLM once per source document + (roughly 1,000–3,000 calls per ACP-sized knowledge base). By default the in-pod commands reuse the LLM + endpoint already configured for Hyperflux (the one set during install via **LLM Base URL** / **LLM API Key** + / **LLM Model Name**). If your account is rate-limited, prepare a separate higher-quota endpoint and + override the env vars in the exec session (Step 3). + +You do **not** need a separate workstation Python environment, a downloaded copy of `gte-multilingual-base`, +a separate PostgreSQL instance, or a clone of the smart-doc repository — the smart-doc container has all of +this baked in. + +## Step 1 — Describe your corpus + +Create a JSON manifest listing every Git repository you want to ingest. Save it on your local machine as +`my-kb.json` (any name works — you'll copy it into the pod in Step 2). + +```json +{ + "kb_version": "1.0", + "repos": [ + { + "git_repo": "https://github.com/myorg/internal-docs", + "branch": "main", + "doc_version": "1.0", + "title": "Internal Docs", + "doc_url_template": "/internal-docs/{{ABSOLUTE_URL.split('/docs/en/')[-1].replace('.mdx','.html').replace('.md','.html')}}", + "origin": "internal", + "sub_dirs": ["docs/en"], + "doc_type": "md,mdx" + } + ] +} +``` + +Add more `repos` entries to ingest multiple repositories in a single run. + +Field reference: + +| Field | Description | +|---|---| +| `git_repo` | Git URL. HTTPS auth uses `GIT_USER` / `GIT_TOKEN` (or `GITHUB_USER` / `GITHUB_TOKEN` for github.com). | +| `branch` / `tag` | Branch (default `main`) or tag (tag wins if both set). | +| `doc_version` | Version label stored on each chunk; surfaced in retrieval filters. | +| `title` | Human-readable corpus name; appears in answer citations. | +| `doc_url_template` | Jinja template producing the relative URL for each doc; concatenated with `ONLINE_DOC_BASE_URL` at retrieval time. The `ABSOLUTE_URL` variable is the doc's local absolute path. | +| `origin` | Free-form bucket label (e.g., `internal`, `ACP`). | +| `sub_dirs` | Optional — only ingest these subdirectories of the repo. | +| `doc_type` | `md`, `mdx`, or `md,mdx`. | +| `kb_version` | Stamped on every chunk under `metadata.version`; used to sanity-check that all chunks in a dump came from the same prepare run. | + +## Step 2 — Copy the manifest into the smart-doc pod + +```bash +# Find the smart-doc pod (single-replica by default). +POD=$(kubectl -n cpaas-system get pod -l app=smart-doc \ + -o jsonpath='{.items[0].metadata.name}') + +# Copy your manifest into the pod's /tmp (the only reliably writable path +# under runAsUser=697; /workspace-smart-doc is read-only). +kubectl -n cpaas-system cp my-kb.json "${POD}:/tmp/my-kb.json" -c serve +``` + +## Step 3 — Run `prepare` inside the pod + +Open an interactive shell in the `serve` container and run the prepare phase: + +```bash +kubectl -n cpaas-system exec -it "${POD}" -c serve -- bash + +# --- inside the pod --- +cd /tmp # writable; outputs land here + +# Required for doc_summary vectors. Read by split_doc.py at PREPARE time — +# setting it later (at embed time) has no effect. +export ENABLE_GEN_QUESTIONS=true + +# Only if your repos are private: +export GIT_USER= +export GIT_TOKEN= +# For github.com use these instead: +# export GITHUB_USER= +# export GITHUB_TOKEN= + +# Optionally override the LLM endpoint for this session if the chart-default +# one is rate-limited. The builder uses langchain's AzureChatOpenAI, so the +# Azure-style env vars below are honoured; AZURE_OPENAI_API_VERSION defaults +# to "2024-12-01-preview" if you omit it. +# export LLM_BASE_URL=... +# export LLM_API_KEY=... +# export LLM_MODEL_NAME=... +# export AZURE_OPENAI_DEPLOYMENT_NAME=... +# export AZURE_OPENAI_API_VERSION=... # optional + +python /opt/packages/emb_builder/smart_doc_builder.py prepare \ + --config /tmp/my-kb.json +# → writes /tmp/documents.json +``` + +Useful flags: + +- `--dryrun` — clone the repos and print the document list, but don't call the LLM. Use this first to confirm + your `sub_dirs` and `doc_type` filters match what you expect. + +> **NOTE:** `prepare` does **not** cache LLM responses across runs — every invocation re-issues one LLM call +> per source document. Plan for the full per-document cost on each re-roll, and only re-run prepare when the +> source corpus actually changed (otherwise re-run only `embed` against the existing `documents.json`). + +## Step 4 — Run `embed` inside the pod + +Stay in the same shell (so the env vars from Step 3 are still in effect): + +```bash +python /opt/packages/emb_builder/smart_doc_builder.py embed \ + --from-json /tmp/documents.json \ + --pg-conn-str "${PG_USER_KB_CONN_STR}" \ + --collection-name user_defined_kb \ + --vector-types chunk,doc_summary \ + --min-chunk-size 600 --max-chunk-size 2000 --chunk-overlap 200 +``` + +The chart already exports `EMB_MODEL_NAME=/opt/gte-multilingual-base`, `DEVICE=cpu`, and +`PG_USER_KB_CONN_STR` (pointing at the user-KB database `docvec_user_kb`), so you don't need to pass +`--emb-model` or `--device`. Pass `--pg-conn-str "${PG_USER_KB_CONN_STR}"` explicitly because the script's +default is the system-KB connection string (`PG_SYS_KB_CONN_STR`). + +What the flags do: + +| Flag | Recommendation | +|---|---| +| `--pg-conn-str "${PG_USER_KB_CONN_STR}"` | Targets the user knowledge-base database. **Do not** point at `PG_SYS_KB_CONN_STR` unless you are deliberately trying to replace the bundled product knowledge base (see "Replacing the system knowledge base" below). | +| `--collection-name user_defined_kb` | The collection name the running server reads from `docvec_user_kb`. Use this exact value — the chart does not currently expose a way to change the user-KB collection name the server reads. | +| `--vector-types chunk,doc_summary` | Multi-vector: each doc contributes both chunk vectors and a doc-level summary vector. Matches the production retrieval shape — leave it on. | +| `--min-chunk-size` / `--max-chunk-size` / `--chunk-overlap` | Defaults are `600 / 0 / 200` (the embed `--help` output); `--max-chunk-size 0` means header-only split with no upper bound. Set an upper bound like `2000`–`3000` if you want every long-form document re-split into smaller chunks. Larger chunks slightly help recall on long-form docs but use more tokens per answer. | + +> **WARNING:** When `--vector-types` includes `doc_summary` but `documents.json` was produced by a `prepare` +> run that didn't have `ENABLE_GEN_QUESTIONS=true` set, embed silently emits **zero** summary vectors and +> only logs `no_summary=N` at the end. If you see a high `no_summary` count, re-run `prepare` with +> `ENABLE_GEN_QUESTIONS=true` before re-running embed. + +> **NOTE:** The serve container runs on CPU by default (`DEVICE=cpu`). Embedding 5,000 chunks on CPU takes +> roughly an hour; for a small internal corpus (a few hundred docs) it's a few minutes. If you need GPU +> throughput, run the build on a GPU-scheduled pod (out of scope for this guide) and use the multi-cluster +> dump-and-restore path described later. + +The embed step does not call the LLM; it can be re-run cheaply against the same `documents.json` to try a +different chunk size or to extend an existing collection with new documents. + +## Step 5 — Create the BM25 index on the user knowledge base (one-time) + +The user-KB database is created empty during install — unlike the bundled system-KB dumps, it does not ship +with a BM25 index pre-built. If hybrid retrieval is enabled (the default), create the index once after your +first embed run: + +```bash +psql "${PG_USER_KB_CONN_STR}" -c " + CREATE INDEX IF NOT EXISTS langchain_pg_embedding_bm25_idx + ON langchain_pg_embedding + USING bm25 (id, document) + WITH (key_field='id'); +" +``` + +Without this index, the hybrid-retrieval path silently falls back to dense-only on the user KB (which still +returns results, just without exact-keyword recall). + +That's it — there is **no chart edit and no pod restart** required. The running server already reads from +`docvec_user_kb` / `user_defined_kb` on every query, so your custom corpus starts contributing to answers +immediately. Run a representative question through the chat UI to confirm. + +## (Optional) Multi-cluster: dump and restore + +If you want to build the corpus once and push it to several clusters, take a `pg_dump` of the user KB after +Step 4 and restore it on each target cluster: + +```bash +# --- on the source cluster, inside the smart-doc pod --- +pg_dump "${PG_USER_KB_CONN_STR}" -Fc -f /tmp/user_kb.dump + +# --- on the workstation --- +kubectl -n cpaas-system cp \ + "${POD}:/tmp/user_kb.dump" \ + ./user_kb.dump + +# --- for each target cluster --- +TARGET_POD=$(kubectl -n cpaas-system get pod -l app=smart-doc \ + -o jsonpath='{.items[0].metadata.name}' --context ) + +kubectl -n cpaas-system --context cp \ + ./user_kb.dump \ + "${TARGET_POD}:/tmp/user_kb.dump" -c serve + +kubectl -n cpaas-system --context exec -it \ + "${TARGET_POD}" -c serve -- bash -c \ + "pg_restore -d \"\${PG_USER_KB_CONN_STR}\" /tmp/user_kb.dump" +``` + +Then perform Step 5 (BM25 index) on each target cluster — the index is per-database and doesn't survive a +restore-into-empty-DB on its own (a restore into a populated DB merges BM25 if present in the dump; for a +fresh user KB, run the `CREATE INDEX` after the restore). + +> **NOTE:** `pg_restore` of the user-KB dump into a target cluster that already has user-KB content (e.g., +> previous BYO uploads) will conflict on the langchain table CREATEs. For a clean overlay, use the chart's +> swap mechanism instead, or first drop and recreate `docvec_user_kb` on the target. Plain `pg_restore` is +> safest only when the target user KB is empty. + +## Replacing the bundled system knowledge base (advanced) + +The workflow above adds to the user KB and leaves the bundled product knowledge intact. If you have a +different requirement — for example, the bundled Alauda product docs are wrong for your environment and you +want to **replace** them with an in-house variant — repeat the same in-pod workflow but target the system KB: + +- `--pg-conn-str "${PG_SYS_KB_CONN_STR}"` +- `--collection-name ` +- Update `pgconnect.pgCollectionName` in the chart to point at your collection name and re-roll. + +This path requires a chart edit and disables automatic system-KB upgrades on future Hyperflux releases (the +auto-swap rule scan won't match your custom collection name). Use it only if user-KB augmentation isn't +enough. + +## Re-roll cadence + +Custom knowledge bases drift faster than product documentation. Plan to re-run **prepare → embed** on a +schedule that matches your source repos: + +- Daily-changing runbooks → nightly cron (a Kubernetes `CronJob` that runs the same in-pod commands as a + one-shot job) re-embedding into the same `user_defined_kb` collection. +- Quarterly architecture docs → manual re-roll on each release boundary. + +Re-running embed against the **same** collection name uses deterministic row IDs (`make_row_id` at +`smart_doc_builder.py:38-48`), so unchanged chunks upsert idempotently and changed chunks overwrite — but +rows for documents that were *removed* from the manifest become orphans. For a clean replacement, drop and +recreate the collection before re-embedding: + +```bash +psql "${PG_USER_KB_CONN_STR}" -c " + DELETE FROM langchain_pg_embedding + WHERE collection_id = (SELECT uuid FROM langchain_pg_collection WHERE name='user_defined_kb'); + DELETE FROM langchain_pg_collection WHERE name='user_defined_kb'; +" +``` + +Then re-run Step 4 to repopulate. The BM25 index on `langchain_pg_embedding` continues to apply to the new +rows automatically, so you do **not** need to re-run Step 5 — unless you also dropped the database itself +(e.g., for the multi-cluster `pg_restore` overlay above). + +## Caveats + +- **The custom corpus shares the user KB with BYO Knowledge tool uploads.** Files end users upload through + the chat UI (introduced in v1.3.1) land in the same `user_defined_kb` collection as your admin-curated + corpus. They coexist as long as URLs don't collide; in practice this is fine because BYO uploads use a + distinct URL scheme. If you ever drop and recreate the collection (Re-roll cadence section), BYO uploads + in that collection are wiped along with your corpus — back them up first if you care about them. +- **System KB version filters do not apply to the user KB.** When a user asks a version-specific question + (e.g., about ACP 4.3), the system KB is filtered to that version but the user KB returns matches across + all versions. If your custom corpus is multi-version, expect cross-version chunks to surface in answers. +- **Embedding-model mismatch** is the most common silent failure: vectors built with anything other than the + in-pod `/opt/gte-multilingual-base` will be retrievable but always score near zero, so answers collapse to + "I don't have enough information" without an obvious error. The in-pod workflow described here uses the + baked-in model by default — only override `EMB_MODEL_NAME` if you know what you're doing. diff --git a/docs/en/how-to/configure-external-mcp.mdx b/docs/en/how-to/configure-external-mcp.mdx new file mode 100644 index 0000000..8738cd4 --- /dev/null +++ b/docs/en/how-to/configure-external-mcp.mdx @@ -0,0 +1,114 @@ +--- +weight: 10 +--- + +# Configure External MCP Servers + +Alauda Hyperflux ships with a built-in MCP server that provides cluster-aware tools. +You can extend the agent's tool set with your own (external) MCP servers — for example an +internal wiki search, a CMDB query service, or any other MCP-compatible endpoint. + +External MCP servers are declared in ConfigMaps and registered through the installation form. +At startup, Alauda Hyperflux connects to each server, lists its tools, and makes them available +to the agent alongside the built-in tools. + +## Declare the MCP servers in a ConfigMap + +Create a ConfigMap **in the namespace where Alauda Hyperflux is installed** (`cpaas-system`). +Every data key with a `.yaml`, `.yml` or `.json` extension is parsed; the content of each file +must be a **list** of server entries: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-org-mcp-servers + namespace: cpaas-system +data: + servers.yaml: | + - name: corp-wiki + url: https://wiki-mcp.example.com/mcp + transport: streamable_http + headers: + Authorization: "Bearer " + - name: cmdb + url: https://cmdb-mcp.example.com/sse + transport: sse + tls_verify: false +``` + +Fields per server entry: + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | Unique server name matching `^[a-z][a-z0-9_-]*$`. The name `acp_mcp_server` is reserved. | +| `url` | Yes | The MCP endpoint URL. | +| `transport` | No | `streamable_http` (default) or `sse`. | +| `headers` | No | Static HTTP headers sent on every request, e.g. for token auth. `${VAR}` placeholders are substituted from the container environment if the variable exists. | +| `tls_verify` | No | Whether to verify the server's TLS certificate. Default `true`. For endpoints using an internal CA, prefer keeping this `true` and adding the CA via **Extra CA ConfigMaps** (see [Configure TLS](./configure-tls.mdx)). | + +Invalid entries (bad name, missing url, unknown transport, duplicate name) are skipped with an +ERROR log; they never prevent the other servers or the service itself from starting. + +> **NOTE:** ConfigMap values are stored in plain text. Avoid putting long-lived secrets directly +> in `headers`; rotate any token you place there as you would any shared credential. + +## Register the ConfigMap + +In **Administrator / Marketplace / Cluster Plugins**, install or update the `Alauda Hyperflux` +plugin and add the ConfigMap name under **Extra MCP Servers ConfigMaps**. + +Each listed ConfigMap is mounted read-only at `/opt/extra-mcp//` and scanned +**once at startup**: + +- Adding or removing a ConfigMap name in the form triggers a rolling restart automatically. +- Editing the *content* of an already-registered ConfigMap does **not** — restart manually: + + ```bash + kubectl -n cpaas-system rollout restart deploy/smart-doc + ``` + +## Tool naming and approval + +Tools from an external server are exposed to the agent with the server name as a prefix, +e.g. `corp-wiki__search_pages`, so they can never collide with built-in tool names. + +External tools are subject to the same **Tool Approval Strategy** as built-in tools: + +- With the default strategy `disabled`, any tool **not** annotated `readOnlyHint: true` by its + MCP server is filtered out of the agent's tool set entirely. Many MCP servers do not annotate + their tools — in that case none of their tools will be visible until you either switch the + strategy to `tool_annotations` (write tools then require interactive approval) or have the + MCP server annotate its read-only tools. +- With `tool_annotations`, read-only tools run freely and all other tools prompt the user for + approval before each call. + +## Verify + +Check the startup logs: + +```bash +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep -i "extra mcp\|MCP tools" +``` + +Expected lines: + +``` +Loading extra MCP servers from file /opt/extra-mcp/my-org-mcp-servers/servers.yaml +Loading extra MCP server name=corp-wiki url=https://wiki-mcp.example.com/mcp transport=streamable_http headers={'Authorization': ''} +Extra MCP corp-wiki loaded 3 tools: ['corp-wiki__search_pages', ...] +Loaded 15 MCP tools (acp=12, extra=3) +``` + +Common failure modes: + +| Log message | Cause | +|---|---| +| `Extra MCP timed out after 10.0s; skipped` | The endpoint is unreachable or slow; each server has a 10-second connection budget and is skipped without affecting the others. | +| `Extra MCP failed to load: ...; skipped` | Connection or protocol error — check the URL, transport and TLS trust. | +| ` is not valid YAML` / `must be a list` | The ConfigMap file content is malformed. | +| `extra MCP header placeholder ${VAR} not in environment; leaving as-is` | A `${VAR}` header referenced an environment variable that does not exist in the container. | +| `AGENT_APPROVAL_STRATEGY=disabled — filtered out N write/unannotated tools` | Tools without `readOnlyHint: true` were removed under the default approval strategy (see above). | + +Sensitive header values (`Authorization`, `X-API-Key`, cookies, and any value longer than +16 characters) are always redacted in logs. diff --git a/docs/en/how-to/configure-redaction.mdx b/docs/en/how-to/configure-redaction.mdx new file mode 100644 index 0000000..40c24bd --- /dev/null +++ b/docs/en/how-to/configure-redaction.mdx @@ -0,0 +1,144 @@ +--- +weight: 50 +--- + +# Configure Data Redaction + +Alauda Hyperflux can redact sensitive values — internal IPs, tokens, passwords — before they +leave the service or get persisted. Redaction is opt-in and has three parts: + +- **Value rules** (`queryRedactionFilters`): regex rules applied to the user's question and + attachments, and to agent tool results, *before* the text is sent to the LLM and *before* it + is written to the conversation history. +- **Key-name redaction** (`toolArgRedactKeys`): tool-call arguments whose key name looks like a + credential (`password`, `token`, `api_key`, ...) are masked on approval cards and in the + approval audit records. +- **Redaction audit**: every rule hit is recorded (rule name and hit count — never the value + itself) and is queryable by platform administrators. + +> **NOTE:** Redaction is an input-side filter with the precision of your regex rules. A value +> that no rule matches still flows to the LLM and may appear in answers. Do not treat it as a +> guaranteed output filter. + +Both settings are **not** in the installation form. They are applied by patching the plugin +configuration (`ModuleInfo`), and take effect after the pods restart (the platform rolls them +automatically after a patch). + +## Value rules (`queryRedactionFilters`) + +Each rule is an object: + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | Rule label; shows up in logs and the audit records. | +| `pattern` | Yes | Regular expression (Python `re` syntax). | +| `mode` | No | `redact` (default) — replace the match with `replace_with`; or `tokenize` — replace the match with an opaque per-request token that is substituted back only when the value is passed to an actual tool execution, so the LLM never sees it but tools still receive the real value. | +| `replace_with` | For `redact` | Literal replacement text, e.g. `[REDACTED_IP]`. | +| `applies_to` | No | Surfaces the rule runs on: `query` (the user's question and attachments — the default) and/or `tool_result` (agent tool outputs before they are fed back to the LLM). | + +Example rule set: + +```json +[ + { + "name": "internal_ip", + "pattern": "\\b(?:10|127)\\.(?:\\d{1,3}\\.){2}\\d{1,3}\\b", + "replace_with": "[REDACTED_IP]", + "applies_to": ["query"] + }, + { + "name": "jwt", + "pattern": "eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+", + "replace_with": "[REDACTED_JWT]", + "applies_to": ["query", "tool_result"] + } +] +``` + +Apply it (the value is the JSON array as a **string**): + +```bash +MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}') +kubectl patch moduleinfo "$MI" --type=merge -p '{ + "spec": {"config": {"smartdoc": { + "queryRedactionFilters": "[{\"name\":\"internal_ip\",\"pattern\":\"\\\\b(?:10|127)\\\\.(?:\\\\d{1,3}\\\\.){2}\\\\d{1,3}\\\\b\",\"replace_with\":\"[REDACTED_IP]\",\"applies_to\":[\"query\"]}]" + }}} +}' +``` + +Validation is strict: a malformed JSON string fails the deployment render, and an invalid +individual rule (missing `name`/`pattern`, unknown `mode` or `applies_to`, uncompilable regex) +prevents the service from starting. Redaction itself is fail-closed — if applying the rules to +a request errors out, the turn is aborted rather than letting the raw text through. + +Writing rules well: + +- Rules run **sequentially in list order** on every request; an earlier rule's replacement text + is visible to later rules. Put broad rules last. +- Keep patterns narrow and anchored. Regex syntax is validated at startup, but catastrophic + backtracking is not — avoid nested quantifiers. +- Over-broad rules silently degrade answer quality (the LLM sees `[REDACTED_...]` instead of + the real value), which is why the feature ships empty by default. + +## Key-name redaction (`toolArgRedactKeys`) + +Independent of the value rules, tool-call arguments shown on approval cards and stored in the +approval audit are masked when the argument's key name contains one of the configured +substrings (case-insensitive). The tool itself still receives the real value. + +When unset, a built-in safe set applies: + +``` +password, passwd, secret, token, api_key, apikey, api-key, +authorization, credential, private_key, access_key, secret_key +``` + +Setting `toolArgRedactKeys` (comma-separated substrings) **replaces** this set — include the +defaults you want to keep. Setting it to an empty string does not disable the feature; the +default set applies again. + +## Redaction audit + +As soon as either setting above is configured, every rule hit is recorded in the +`redaction_audit` table of the conversation-history database: request id, session, username, +surface (`query` / `attachment` / `tool_result` / `tool_args`), rule name, mode, and hit count. +**The matched value is never stored.** + +Platform administrators (see **Admin Users** in the installation form) can query the records: + +``` +GET https:///smart-doc/api/admin/redaction_audit +``` + +Supported query parameters (all optional, ANDed): `username`, `session_id`, `request_id`, +`surface`, `rule_name`, `from`, `to`, plus `limit` (default 100, max 1000) and `offset`. +Non-admin callers receive 403. + +Two operational notes: + +- Audit writes are best-effort: a failed write is logged and dropped, never failing the user's + request. Do not treat the table as a guaranteed-complete compliance ledger. +- There is no automatic retention/cleanup for `redaction_audit` — prune it externally if your + deployment handles large volumes. + +## Verify + +Send a question containing a value your rule matches, then check the logs: + +```bash +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep 'redaction hits' +``` + +Expected (rule names and counts only, never values): + +``` +query redaction hits: {'internal_ip': 2} +tool-result redaction hits: {'jwt': 1} +``` + +And query the audit as an admin: + +```bash +curl -sk "https:///smart-doc/api/admin/redaction_audit?rule_name=internal_ip" \ + -H "Authorization: Bearer " +``` diff --git a/docs/en/how-to/configure-tls.mdx b/docs/en/how-to/configure-tls.mdx new file mode 100644 index 0000000..1d6d5b2 --- /dev/null +++ b/docs/en/how-to/configure-tls.mdx @@ -0,0 +1,99 @@ +--- +weight: 30 +--- + +# Configure TLS + +This guide covers the TLS-related configuration of Alauda Hyperflux for its outbound +connections: the LLM service, the reranker, MCP servers and PostgreSQL. + +The most common need — trusting an LLM or MCP endpoint that uses an internal or self-signed +certificate — is solved with **Extra CA ConfigMaps**, available directly in the installation +form. For test environments, certificate verification for LLM calls can also be skipped +entirely (see the last section). + +## Trust an internal / self-signed CA (Extra CA ConfigMaps) + +If your LLM, reranker or MCP endpoint presents a certificate signed by an internal CA, requests +fail with `CERTIFICATE_VERIFY_FAILED`. Add the CA certificate to the trust bundle: + +1. Create a ConfigMap holding the CA certificate (PEM) **in the namespace where Alauda + Hyperflux is installed** (`cpaas-system`). CA certificates are public, so a ConfigMap — not + a Secret — is appropriate. One ConfigMap can hold multiple `*.pem` keys: + + ```bash + kubectl create configmap my-org-internal-ca -n cpaas-system \ + --from-file=ca.pem=/path/to/internal-ca.pem + ``` + +2. In **Administrator / Marketplace / Cluster Plugins**, install or update the + `Alauda Hyperflux` plugin and add the ConfigMap name under **Extra CA ConfigMaps**. + The service restarts automatically. + +Each listed ConfigMap is mounted read-only at `/opt/extra-ca//`. At startup the +certificates are merged with the default CA bundle and the merged bundle is applied +process-wide, so it covers **LLM, reranker and MCP** connections. + +> **NOTE:** PostgreSQL is the exception — it does not use this bundle. TLS to an external +> PostgreSQL is configured separately via the `pgSSLMode` / `pgSSLRootCert` values of the +> plugin configuration. + +Updating the *content* of an already-registered ConfigMap (e.g. rotating the CA) requires a +manual restart: + +```bash +kubectl -n cpaas-system rollout restart deploy/smart-doc +``` + +### Verify + +```bash +# The mounted CA and the merged bundle +kubectl -n cpaas-system exec deploy/smart-doc -c serve -- ls /opt/extra-ca/my-org-internal-ca/ +kubectl -n cpaas-system exec deploy/smart-doc -c serve -- grep -c 'BEGIN CERTIFICATE' /tmp/smart-doc-ca.pem + +# The startup log line +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep extra_ca +``` + +Expected log line: + +``` +extra_ca: merged 1/1 CA file(s) into /tmp/smart-doc-ca.pem +``` + +Then ask a question in the chat panel — requests to the endpoint that previously failed with +`CERTIFICATE_VERIFY_FAILED` should now succeed. + +## Skip TLS certificate verification (not recommended) + +For test or development environments where importing the CA is not practical, TLS certificate +verification for **LLM calls** can be switched off entirely with `llmSkipSslVerify`. + +> **WARNING:** This exposes the LLM connection to man-in-the-middle attacks, and it overrides +> both the TLS profile and any extra CA trust — which is why it is deliberately not offered in +> the installation form. The production-safe path for internal certificates is +> **Extra CA ConfigMaps** above. The setting affects LLM calls only; reranker, MCP and +> PostgreSQL connections are not touched. + +Apply it by patching the plugin configuration (`ModuleInfo`) directly: + +```bash +# Find the ModuleInfo of the Hyperflux plugin (cluster-scoped, name like global-) +MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}') + +kubectl patch moduleinfo "$MI" --type=merge -p \ + '{"spec":{"config":{"smartdoc":{"llmSkipSslVerify":true}}}}' +``` + +The platform reconciles the change and rolls the pods automatically. When enabled, every +startup logs a warning: + +``` +LLM_SKIP_SSL_VERIFY=true — LLM TLS certificate verification is DISABLED (verify=False) +``` + +To revert, patch the value back to `false`. + +For external MCP servers there is an equivalent per-server `tls_verify: false` field — see +[Configure External MCP Servers](./configure-external-mcp.mdx), with the same caveat. diff --git a/docs/en/how-to/custom-skills.mdx b/docs/en/how-to/custom-skills.mdx new file mode 100644 index 0000000..a4ebc79 --- /dev/null +++ b/docs/en/how-to/custom-skills.mdx @@ -0,0 +1,126 @@ +--- +weight: 20 +--- + +# Create Custom Skills + +Skills are procedural prompts — step-by-step expert playbooks — that Alauda Hyperflux +automatically loads when a user's question matches. When a query hits a skill, the skill body is +injected into the agent's context so the answer follows your organization's procedure instead of +a generic one. + +Alauda Hyperflux ships with built-in troubleshooting skills (pod failure diagnosis, node +NotReady, ingress 5xx triage, PVC binding failure, routine inspection), active out of the box. +You can add your own skills via ConfigMaps; a custom skill with the same `name` as a built-in +one overrides it. + +## How matching works + +Each skill declares a `name` and a `description`. At startup they are embedded with the same +embedding model used by the knowledge base; at query time the user's question is compared +against them by cosine similarity. The single best match at or above the **Skills Match +Threshold** (default `0.35`) is injected; below the threshold nothing happens. + +Write the `description` accordingly: it is the matching surface. State what the skill diagnoses +and mention the phrases users are likely to use. + +## Write a skill file + +A skill is a Markdown file with YAML frontmatter: + +```markdown +--- +name: etcd-degraded +description: Diagnose an etcd cluster reporting degraded or unhealthy members. Use when the user reports etcd alerts, slow API server, or a control-plane node showing etcd errors. +--- + +# etcd Degraded Diagnosis + +1. List the etcd pods in `kube-system` and check their status and recent events. +2. Check member health: report which member is unhealthy and the specific error. +3. Correlate with node disk pressure or clock skew; cite the exact log line. +4. Recommend the remediation matching the identified cause; do not guess. +``` + +Rules: + +- `name` (required): must match `^[a-z][a-z0-9_-]*$`. Duplicate names within one scan: the first + file wins; a custom skill overrides a built-in skill of the same name. +- `description` (required): non-empty; drives matching. +- Body (required): everything after the frontmatter. Keep it under 4 KB — larger bodies still + load but log a warning and consume context on every match. +- Files that fail these rules are skipped with a WARN log; they never break the service. + +## Deploy skills via a ConfigMap + +Create a ConfigMap **in the namespace where Alauda Hyperflux is installed** (`cpaas-system`). +Every `*.md` data key is loaded as one skill: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-org-skills-sre + namespace: cpaas-system +data: + etcd-degraded.md: | + --- + name: etcd-degraded + description: Diagnose an etcd cluster reporting degraded or unhealthy members. Use when the user reports etcd alerts, slow API server, or a control-plane node showing etcd errors. + --- + + # etcd Degraded Diagnosis + + 1. List the etcd pods in `kube-system` and check their status and recent events. + 2. Check member health: report which member is unhealthy and the specific error. + 3. Correlate with node disk pressure or clock skew; cite the exact log line. + 4. Recommend the remediation matching the identified cause; do not guess. +``` + +Then in **Administrator / Marketplace / Cluster Plugins**, install or update the +`Alauda Hyperflux` plugin: + +- **Enable Skills**: on (default). +- **Skills Match Threshold**: keep `0.35` unless skills fire too eagerly (raise it) or never + match (lower it). +- **Skills ConfigMaps**: add the ConfigMap name, e.g. `my-org-skills-sre`. + +Each listed ConfigMap is mounted read-only at `/opt/skills//` and scanned +**once at startup**. Adding or removing a ConfigMap name in the form restarts the service +automatically; editing the content of an already-registered ConfigMap requires a manual restart: + +```bash +kubectl -n cpaas-system rollout restart deploy/smart-doc +``` + +## Verify + +Check the startup logs: + +```bash +kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep '\[skills\]' +``` + +Expected on load: + +``` +[skills] loaded 6 skill(s) (built-in=5, admin=1 from /opt/skills), threshold=0.35, vec_dim=768 +``` + +Then ask a question in the chat panel that is semantically close to your skill's description. +On a hit the log shows the selected skill and its score: + +``` +[skills] selected name=etcd-degraded team=my-org-skills-sre score=0.62 query='...' +``` + +If a skill never matches, compare the logged scores against the threshold and rewrite the +`description` to be closer to how users actually phrase the question. + +Other notable log lines: + +| Log message | Meaning | +|---|---| +| `[skills] feature disabled (ENABLE_SKILLS=false)` | The Enable Skills toggle is off. | +| `[skills] enabled but no skills loaded` | No valid skill files were found — check WARN lines above it for per-file reasons. | +| `[skills] admin skill(s) override built-in: [...]` | Your custom skills replaced built-in skills of the same name. | diff --git a/docs/en/how-to/index.mdx b/docs/en/how-to/index.mdx new file mode 100644 index 0000000..58368ab --- /dev/null +++ b/docs/en/how-to/index.mdx @@ -0,0 +1,7 @@ +--- +weight: 17 +--- + +# How To + + diff --git a/docs/en/how-to/use-mcp-in-ide.mdx b/docs/en/how-to/use-mcp-in-ide.mdx new file mode 100644 index 0000000..47bad5c --- /dev/null +++ b/docs/en/how-to/use-mcp-in-ide.mdx @@ -0,0 +1,120 @@ +--- +weight: 40 +--- + +# Use Hyperflux as an MCP Server in Your IDE + +Alauda Hyperflux can expose itself as an MCP (Model Context Protocol) server, so AI coding +assistants — Claude Code, Cursor, VS Code Copilot, or any MCP-compatible agent — can ask it +Alauda product questions and inspect (or, with approval, operate) ACP clusters, directly from +the IDE. + +The MCP server exposes a single tool, `hyperflux_agent`, which delegates to the full Hyperflux +agent: knowledge-base retrieval plus cluster tools (clusters, projects, namespaces, nodes, pods, +resources, events, pod logs, metrics, alerts). It returns a grounded answer with citations. + +## Enable the MCP server + +In **Administrator / Marketplace / Cluster Plugins**, install or update the `Alauda Hyperflux` +plugin: + +- **Expose as MCP Server**: on (default off). +- **MCP Write-Approval Timeout (s)**: how long a mutating action waits for your approval in the + IDE before being treated as declined. Default `300`. Keep it below your ingress idle timeout, + otherwise the connection may be severed while waiting for approval. + +## The endpoint + +The MCP endpoint uses the streamable HTTP transport, at: + +``` +https:///smart-doc/mcp/ +``` + +> **NOTE:** The trailing slash matters. Requests to `/smart-doc/mcp` (without the slash) are +> answered with an HTTP 307 redirect that some MCP clients do not follow. + +## Authentication + +Unauthenticated requests are rejected with HTTP 403. + +Send your ACP identity token as a bearer header: `Authorization: Bearer `. +You can obtain the token from a logged-in ACP Web Console session: open the browser developer +tools and copy the value of the `cpaas_id_token` cookie (strip the surrounding quotes and the +leading `Bearer ` prefix). + +This identifies you as a real user: with an MCP client that supports elicitation, mutating +actions become available behind interactive approval (see below). The token expires with your +ACP session, so refresh it when you start getting 403 responses. + +## Configure your IDE + +Claude Code: + +```bash +claude mcp add --transport http hyperflux \ + "https:///smart-doc/mcp/" \ + --header "Authorization: Bearer " +``` + +Generic `mcp.json` (Cursor, VS Code, and most other MCP clients): + +```json +{ + "mcpServers": { + "hyperflux": { + "type": "http", + "url": "https:///smart-doc/mcp/", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +Then ask your assistant something like *"Using the hyperflux tool, check why pods in namespace +foo are not ready"*. The tool accepts a `question` plus optional `session_id` (to continue a +previous conversation), `cluster`, `namespace` and `project` hints. + +## Read-only vs. write actions + +What the agent may do through the IDE depends on the plugin's **Tool Approval Strategy** and +your MCP client: + +- With the default strategy `disabled`, the MCP tool is read-only for everyone — write tools + are removed from the agent entirely. +- With other strategies, mutating actions (create / update / delete / scale resources) are + available **only** when your MCP client supports *elicitation*. Before executing a write, + Hyperflux sends an approval request that your IDE shows as a confirmation prompt; no answer + within the configured timeout counts as a decline, and a declined action is not re-asked + within the same session. +- Clients without elicitation support get read-only behavior: write attempts are declined with + a "read-only MCP session" message, while reads keep working. + +## Troubleshooting + +Verify the endpoint end-to-end with curl: + +```bash +curl -sk -X POST "https:///smart-doc/mcp/" \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -H "Authorization: Bearer " \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' +``` + +A healthy server answers with `"serverInfo":{"name":"hyperflux",...}`. + +| Symptom | Cause | +|---|---| +| HTTP 403 | Authentication failed: missing or expired ACP token. | +| HTTP 404 | **Expose as MCP Server** is off, or the setting was changed without the pods restarting. | +| HTTP 307 | Missing trailing slash — use `/smart-doc/mcp/`. | +| Writes always declined | Your client does not support elicitation, or the approval strategy is `disabled`. | +| Approval prompt disappears / connection drops during approval | The ingress idle timeout is shorter than the **MCP Write-Approval Timeout** — lower the timeout or raise the ingress limit. | + +Server-side logs (`kubectl -n cpaas-system logs -l app=smart-doc -c serve`) show +`Outbound MCP server mounted at /mcp` at startup when the feature is enabled, and +`MCP read-only session — blocked write tool ` when a write was declined due to a +read-only session. diff --git a/docs/en/install.mdx b/docs/en/install.mdx index 8411c80..7f57f1b 100644 --- a/docs/en/install.mdx +++ b/docs/en/install.mdx @@ -12,12 +12,12 @@ The downloaded package is a tarball file named `alauda-hyperflux-.tar.g Download the `violet` command line tool if it is not present on the machine: 1. Log into the ACP Web Console and switch to the **Administrator** view. -1. In **Marketplace / Upload Packages**, click **Download Packaging and Listing Tool**. -2. Select the right OS/CPU arch, and click **Download**. -3. Run `chmod +x ${PATH_TO_THE_VIOLET_TOOL}` to make the tool executable. +2. In **Marketplace / Upload Packages**, click **Download Packaging and Listing Tool**. +3. Select the right OS/CPU arch, and click **Download**. +4. Run `chmod +x ${PATH_TO_THE_VIOLET_TOOL}` to make the tool executable. Save the following script in `upload.sh`, -then edit the file to fill in the correct configuration values acording to the comments. +then edit the file to fill in the correct configuration values according to the comments. ```bash #!/usr/bin/env bash @@ -46,13 +46,14 @@ if [[ "${IS_EXTERNAL_REGISTRY}" == "true" ]]; then ) fi -# Push **Alauda AI Cluster** operator package to destination cluster +# Push the Alauda Hyperflux plugin package to the `global` cluster +# (Alauda Hyperflux MUST be installed in the `global` cluster) violet push \ - ${AI_CLUSTER_OPERATOR_NAME} \ + ${PACKAGE_FILE} \ --platform-address=${PLATFORM_ADDRESS} \ --platform-username=${PLATFORM_ADMIN_USER} \ --platform-password=${PLATFORM_ADMIN_PASSWORD} \ - --clusters=${CLUSTER} \ + --clusters=global \ ${VIOLET_EXTRA_ARGS[@]} ``` @@ -66,11 +67,9 @@ You will use the LLM service endpoint, model name and API key in the Alauda Hype Optionally, if you want to enable the rerank feature in Alauda Hyperflux, you also need to prepare a rerank service that supports Cohere Reranker API v2. -## Prepare the database dump file (ONLY needed for v1.2.0) - -Download the database dump file like `docvec_acp_4_1.dump` for your current ACP version. -You **MUST** use the file name like `docvec_acp_4_1` as the database name during installation. - +> **NOTE:** The knowledge base is initialized automatically from a built-in database dump file +> selected during installation. Manually preparing and importing a database dump file is no longer +> needed (it was only required for v1.2.0). ## Install Alauda Hyperflux cluster plugin @@ -78,15 +77,20 @@ Go to **Administrator / Marketplace / Cluster Plugins** page, select "global" cluster from the cluster dropdown list, then find the `Alauda Hyperflux` plugin and click **Install**. -> **NOTE:** Alauda Hyperflux **MUST** be installed in the `Global` cluster. +> **NOTE:** Alauda Hyperflux **MUST** be installed in the `global` cluster. Fill in the configurations below: -- Built-in PG database: - - Enabled: will install a single PostgreSQL instance in the cluster for Alauda Hyperflux to use. You need to set: - - storage size: the storage size for PostgreSQL data. - - storage class name: Kubernetes storage class name, e.g. `sc-topolvm` - - Disabled: create a secret below to provide external PostgreSQL connection info. +### Knowledge base and databases + +- **Built-in KnowledgeBase File**: the built-in database dump file used to initialize the knowledge base + on first startup. Select the file matching your ACP version, e.g. `docvec_gte_acp_4_3_.dump` for ACP 4.3. +- **Enable builtin PGVector**: + - Enabled: a single PostgreSQL (with pgvector) instance will be installed in the cluster for Alauda Hyperflux to use. You need to set: + - **PGVector Storage Size**: the storage size for PostgreSQL data, e.g. `10Gi`. + - **PGVector StorageClass name**: Kubernetes storage class name, e.g. `sc-topolvm`. + - Disabled: provide the connection info of an external PostgreSQL (pgvector extension required) via a secret, + and fill the secret name in **pg database secret name**: ```yaml apiVersion: v1 kind: Secret @@ -99,62 +103,124 @@ Fill in the configurations below: port: username: password: - uri: "postgresql+pg8000://:@:" + uri: "postgresql+psycopg://:@:" + ``` +- **PG database name**: the PostgreSQL database name for storing conversation history. +- **PG collection name**: the collection name for storing document vectors. + **MUST** be the same as the selected built-in knowledge base file name without the `.dump` suffix. +- **Enable builtin Redis**: Redis is used by the rate limiter and caching. + - Enabled: a single Redis instance will be installed in the cluster. + - Disabled: provide the connection info of an external Redis via a secret, + and fill the secret name in **redis database secret name**: + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: redis-secret + namespace: cpaas-system + type: Opaque + stringData: + REDIS_HOST: + REDIS_PORT: + REDIS_PASSWORD: + REDIS_DB: "0" ``` -- PG database name: the database name for Alauda Hyperflux to use. **MUST** be the same as the database dump file name without the `.dump` suffix. -- Node Selector(Optional): set the node selector for Alauda Hyperflux pods if needed. -- LLM Model Type: Azure or OpenAI. -- LLM Base URL: the base URL for LLM API calls. When using On-Premise deployment of LLM service like vllm, the url should like `http://:/v1`. -- Model Name: the model name for LLM API calls. -- API Key: the API key for LLM API calls. -- Azure API Version(Optional): when using Azure OpenAI service, set the API version here. -- Azure Deployment Name(Optional): when using Azure OpenAI service, set the deployment name here. -- Enable Rerank: whether to enable the rerank feature in Alauda Hyperflux using **Cohere API**. Set below values if enabled: - - Cohere Reranker BaseURL: the base URL for Cohere Reranker API calls. - - Cohere Reranker Model: the model name for Cohere Reranker API calls. - - Cohere API Key: the API key for Cohere Reranker API calls. -- Enable Agent Mode: whether to enable Agent mode to leverage MCP tools to retrieve real-time cluster information. - - **NOTE**: Agent mode is an experimental feature, please use with caution. -- MCP K8s API Server Address: the K8s API server address of the MCP cluster. - - **IMPORTANT:** You should set this url to erebus address like `https://erebus.cpaas-system:443/kubernetes/`. - - **IMPORTANT:** the `cluster-name` should be set to the cluster name you want MCP tools to access. -- Admin User Names: the comma-separated admin user list. Admin users can manage Audit logs in Alauda Hyperflux. - +### LLM service + +- **LLM Model type**: `azure` (Azure OpenAI) or `openai` (OpenAI-compatible API, e.g. vllm). +- **LLM Base URL**: the base URL for LLM API calls. When using an On-Premise deployment of LLM service + like vllm, the URL should look like `http://:/v1`. +- **LLM Model Name**: the model name for LLM API calls. +- **Use an existing credentials Secret**: + - Disabled (default): enter the API keys directly in the form below; a secret is created automatically. + - **LLM API Key**: the API key for LLM API calls. + - **Cohere Reranker API key**: shown when the reranker is enabled. + - Enabled: reference a pre-existing secret in **Existing credentials Secret**. + The secret must contain the keys `llm-api-key`, `cohere-api-key` and `api-key`. +- **Azure API Version** (Azure only): the Azure OpenAI API version, e.g. `2024-12-01-preview`. +- **Azure Deployment Name** (Azure only): the Azure OpenAI deployment name. +- **Model Context Window** (Optional): context window size of the LLM model (e.g. `128000`). + Leave empty to auto-detect by model name. + +### Reranker (Optional) + +- **Enable Reranker**: whether to enable the reranking feature, which improves the relevance of + retrieved documents. Only Cohere Reranker API is supported currently. Set below values if enabled: + - **Cohere Reranker BaseUrl**: the base URL for Cohere Reranker API calls. + - **Cohere Reranker Model**: the model name for Cohere Reranker API calls, e.g. `rerank-v3.5`. + - **Cohere Reranker API key**: the API key for Cohere Reranker API calls + (hidden when using an existing credentials secret). + +### Agent tools (MCP) + +- **Expose MCP**: whether to access the built-in MCP server via Ingress. +- **Tool Approval Strategy**: decide which agent tool calls require human approval: + - `disabled` (default): write tools are filtered out of the LLM tool set, so the LLM cannot call them at all. + - `tool_annotations`: write tools (MCP `readOnlyHint=false`) require interactive approval. + - `always`: every tool call requires interactive approval. + - `never`: no approval, the LLM can call any tool unattended. **Use with caution in production.** +- **Expose as MCP Server**: expose Alauda Hyperflux itself as an MCP server at `/mcp`, so IDEs and + agents can call it as a tool. Read operations are always allowed; write actions require + interactive approval. Default off. See + [Use Hyperflux as an MCP Server in Your IDE](./how-to/use-mcp-in-ide.mdx). + - **MCP Write-Approval Timeout (s)**: max seconds to wait for a write-approval response before + treating it as a decline. Default `300`. +- **Extra MCP Servers ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) holding + extra MCP server definitions; each ConfigMap's `*.yaml`/`*.yml`/`*.json` entries are scanned at startup. + See [Configure External MCP Servers](./how-to/configure-external-mcp.mdx). + +### Skills + +- **Enable Skills**: auto-load admin-configured procedural skills (mounted from ConfigMaps) when a query matches. + - **Skills Match Threshold**: cosine threshold (0-1) for matching a query to a skill. + Higher is stricter. Default `0.35`. + - **Skills ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) whose `*.md` + entries are loaded as skills. See [Create Custom Skills](./how-to/custom-skills.mdx). + +### Rate and quota limits + +- **Enable Rate Limiter**: whether to enable per-user rate limiting and daily token quotas. + Set below values if enabled: + - **Max Requests Per Minute (RPM)**: default `5`. + - **RPM Window Time (Minute)**: default `5`. + - **Max Total Tokens Per Day**: default `1000000`. + - **Max Input Tokens Per Day**: default `200000`. + - **Max Output Tokens Per Day**: default `1000000`. + +### RAG tuning + +The defaults work for most cases; adjust only if needed. + +- **Total Search K**: total number of search results to retrieve from the knowledge base. Default `20`. +- **RAG Similarity Threshold**: similarity threshold for retrieving relevant documents. Default `0.8`. +- **Cohere Reranker Top N**: number of top documents to keep after reranking. Default `6`. +- **Max History Number**: number of previous interactions to retain in chat history. Default `1`. + +### Other settings + +- **Node Selector** (Optional): set the node label key/value terms for Alauda Hyperflux pods if needed. +- **Admin Users**: comma-separated admin user names, e.g. `admin@cpaas.io,user1`. + Admin users can manage audit logs in Alauda Hyperflux. +- **Extra CA ConfigMaps** (Optional): names of ConfigMaps (in the plugin namespace) holding + internal / self-signed CA certificates (PEM). The certificates are appended to the outbound TLS + trust bundle, so LLM / MCP / reranker endpoints using such certificates can be accessed. + See [Configure TLS](./how-to/configure-tls.mdx). Click **Install** to start installation. -## Import database dump to initialize knowledge base (ONLY needed for v1.2.0) +## Verify the installation + +The knowledge base is initialized automatically on the first startup: an init container creates the +databases and restores the selected built-in dump file. This may take a few minutes. -After the Alauda Hyperflux installation is complete, you need to import the database dump file to initialize the knowledge base. -Use the following command to import the database dump file: +Check that the pods are running: ```bash -# Get the PostgreSQL pod name -kubectl -n cpaas-system get pod | grep postgre-vec -# Copy the dump file to the PostgreSQL pod -kubectl -n cpaas-system cp docvec_acp_4_1.dump :/tmp/docvec_acp_4_1.dump -# Temporarily stop the Alauda Hyperflux deployment to avoid connection issues during database import -kubectl -n cpaas-system scale deployment smart-doc --replicas=0 -# Exec into the PostgreSQL pod -kubectl -n cpaas-system exec -it -- /bin/bash -# Import the database dump file -# NOTE: change the database name docvec_acp_4_1 to the actual database name -psql -U postgres -W -c "DROP DATABASE docvec_acp_4_1;" -psql -U postgres -W -c "CREATE DATABASE docvec_acp_4_1;" -pg_restore -U postgres -W -d docvec_acp_4_1 /tmp/docvec_acp_4_1.dump -# Enter the password when prompted -# Exit the pod -exit - -# Restart the Alauda Hyperflux deployment -kubectl -n cpaas-system scale deployment smart-doc --replicas=1 -# execute db_orm.py to re-init database schema -kubectl -n cpaas-system exec -it -- python /workspace/db_orm.py +kubectl -n cpaas-system get pod | grep smart-doc ``` -> **NOTE:** when using built-in PostgreSQL database, the default password is `alauda-test`. - +Once the `smart-doc` pod is ready, open the ACP Web Console and the Alauda Hyperflux chat panel is available. ## Troubleshooting diff --git a/docs/en/overview/release_notes.mdx b/docs/en/overview/release_notes.mdx index 063152a..1a80240 100644 --- a/docs/en/overview/release_notes.mdx +++ b/docs/en/overview/release_notes.mdx @@ -4,6 +4,108 @@ weight: 40 # Release Notes +## v1.5.0 + +### Features and Enhancements + +#### **Agent Mode by Default** + +Agent mode is now enabled by default and no longer requires a deploy-time toggle. Smart Doc answers with an explicit reasoning loop that can call MCP tools to retrieve real-time cluster information, and routes each request to the right behavior (question answering, troubleshooting, or operations) for more reliable multi-step tasks. + +#### **Tool-Call Approval** + +Any agent action that creates, modifies, or deletes cluster resources now requires explicit user confirmation before it runs. Read-only tools continue to execute without interruption, giving you real-time insight while keeping write operations under human control. + +#### **External MCP Servers** + +Administrators can register additional MCP servers through a ConfigMap so that custom tools become available to the agent. Tool names are prefixed per server to avoid collisions, and an approval strategy governs which tools are exposed. + +#### **Custom Skills** + +Skills let you shape the agent's behavior for specific tasks using a simple frontmatter format, matched to each request by name and description. A set of built-in skills ships and loads by default, and custom skills can override them. + +#### **Hyperflux as an MCP Server** + +Hyperflux can now be consumed as an MCP server from your IDE or other agents. It exposes read access with ACP bearer-token authentication, and write operations are gated by an elicitation-based approval flow. + +#### **Data Redaction** + +A configurable redaction subsystem masks sensitive data across user queries, tool arguments, and tool results, with support for both redact and tokenize modes. An admin-only audit API records redaction hits as metadata only, so the original values are never stored. + +#### **Transport Security** + +Smart Doc now supports custom CA certificates for outbound connections to the LLM, MCP, and reranker services, along with configurable TLS profiles and security headers. Air-gapped and data-residency deployments are supported, including a fail-safe reranker path. + +### Improvements + +- Enabled BM25 hybrid search by default to improve retrieval quality. +- Reused MCP sessions across reasoning rounds to remove per-round re-handshakes and reduce latency in agent mode. +- Ran mode classification and glossary lookup in parallel and shared a cached base prompt across modes to reduce response latency. +- Added a stop-generation control that truly cancels the in-progress request on the backend and records the interrupted answer in history. +- Added SSE heartbeats so long-running tool calls no longer cause the frontend to disconnect. +- Reduced the container image size by shipping a CPU-only build. +- Hardened authentication and secret handling, including JWT expiry verification and redaction of secrets in logs. +- Improved production diagnosability with per-request trace IDs and reduced log noise. + +### Bug Fixes + +- Fixed an access-control issue where a user could reach another user's sessions. +- Fixed session and history API error paths so failures return the correct status codes. +- Fixed agent conversation history being lost when a request was cancelled mid-stream. +- Fixed leftover UI markup being replayed into the model when resuming a conversation from history. +- Fixed knowledge base initialization on fresh installs and on Kunpeng 920 (ARM) hardware. +- Resolved all outstanding high and critical dependency and image security vulnerabilities. + + +## v1.4.0 + +### Features and Enhancements + +#### **Improved retrieval quality** + +The bundled knowledge base has been re-embedded with a stronger model, substantially improving answer relevance — including cross-language retrieval (for example, asking a question in Chinese against English documentation). Existing v1.3.x deployments are migrated automatically during the upgrade — see the [Upgrade guide](../upgrade/index.mdx). + +#### **Hybrid keyword and semantic retrieval** + +Answers are now retrieved using a combination of semantic similarity and keyword matching, then fused into a single ranking. This recovers exact-keyword matches that pure semantic search misses — such as CRD names, command flags, and error strings — without giving up the ability to answer natural-language questions. + +#### **Document-level retrieval** + +Each document is now indexed at the document level in addition to its individual sections. Questions about a document's overall topic now find the right document even when the user's wording doesn't overlap with any specific paragraph. + +#### **Built-in knowledge base preset selection** + +The installation page now offers a choice between two presets for the bundled knowledge base. The default works well for most queries; the larger preset can give slightly better recall on questions that span long-form documents. + +#### **Bundled knowledge base refresh during upgrade** + +Upgrading from v1.3.x to v1.4.x replaces the bundled product knowledge base with the new GTE-embedded dump and migrates per-document metadata automatically. No manual database export, import, or restart step is required — see the [Upgrade guide](../upgrade/index.mdx). Custom and BYO knowledge bases are not touched by this step (see Breaking Changes and Known Limitations below). + +#### **Conversation history compression** + +Long conversations are automatically summarised so they fit within the LLM's context window without losing earlier turns. This reduces token cost on extended agent-mode sessions and lets users continue an investigation across many messages without quality degradation. + +#### **Agent Mode and MCP tool loading can now be configured independently** + +Agent Mode (multi-step reasoning) and ACP MCP tool loading are now controlled by separate install switches. You can turn on Agent Mode without loading the ACP MCP tools — for example, when the LLM should plan over the bundled knowledge base alone — and turn the tools back on when live cluster operations are required. + +#### **Build a Custom Knowledge Base** + +A new guide walks administrators through ingesting internal Git repositories into the Hyperflux knowledge base, so Hyperflux can answer questions grounded in private runbooks, design documents, or other internal references. See [Build a Custom Knowledge Base](../build-custom-kb.mdx). + +### Improvements + +- Reduced token cost on agent-mode answers when tools return long output (such as logs or large resource definitions). +- Improved storage performance on the bundled knowledge-base database. + +### Breaking Changes + +- **Custom knowledge bases built under v1.3.x must be rebuilt before upgrading.** The new embedding model is incompatible with the previous one, so existing custom corpus data will not be usable until rebuilt. See the [Build a Custom Knowledge Base](../build-custom-kb.mdx) guide for the new procedure. + +### Known Limitations + +- Documents you uploaded via the BYO Knowledge tool are preserved unchanged across the v1.4.0 upgrade — only the bundled product knowledge base is refreshed. + ## v1.3.1 ### Features and Enhancements