priyeshkaratha commented on code in PR #469: URL: https://github.com/apache/ozone-site/pull/469#discussion_r3546032213
########## docs/05-administrator-guide/03-operations/09-observability/02-recon/03-recon-ai-assistant.mdx: ########## @@ -0,0 +1,484 @@ +--- +sidebar_label: Recon AI Assistant +--- + +# Recon AI Assistant + +The **Recon AI Assistant** lets you ask questions about your Apache Ozone cluster in plain English +and get answers assembled from the data Recon already collects. It is an optional, **disabled by +default**, experimental feature of the Recon service. + +> **Note:** This page is for operators (who enable, secure, configure and run the assistant) and end +> users (who ask it questions). It is not a code walkthrough; contributors can find the internal flow +> in `CODE_FLOW.md` next to the chatbot source. + +## 1. Overview + +Recon continuously derives a large amount of cluster metadata - container health and replica state, +namespace and usage rollups, open and pending-delete keys, datanode and pipeline status, background +task and sync state - and exposes it across many REST endpoints and UI screens. In practice most of +that information is never seen or correlated, because you have to know which endpoint or screen holds +the answer. + Review Comment: Just an improvement idea that came to mind: it would be useful to ask the Recon Assistant for metrics related to one or more services. Since there are so many metrics, instead of returning raw JMX query results, the AI could summarize the most relevant metrics and present them in a concise, easy-to-understand format. ########## docs/05-administrator-guide/03-operations/09-observability/02-recon/03-recon-ai-assistant.mdx: ########## @@ -0,0 +1,484 @@ +--- +sidebar_label: Recon AI Assistant +--- + +# Recon AI Assistant + +The **Recon AI Assistant** lets you ask questions about your Apache Ozone cluster in plain English +and get answers assembled from the data Recon already collects. It is an optional, **disabled by +default**, experimental feature of the Recon service. + +> **Note:** This page is for operators (who enable, secure, configure and run the assistant) and end +> users (who ask it questions). It is not a code walkthrough; contributors can find the internal flow +> in `CODE_FLOW.md` next to the chatbot source. + +## 1. Overview + +Recon continuously derives a large amount of cluster metadata - container health and replica state, +namespace and usage rollups, open and pending-delete keys, datanode and pipeline status, background +task and sync state - and exposes it across many REST endpoints and UI screens. In practice most of +that information is never seen or correlated, because you have to know which endpoint or screen holds +the answer. + +The assistant closes that gap: you ask a question, and it decides which Recon view(s) answer it, runs +those reads, and writes back a readable summary. + +**What it is not:** + +- It is **not** a computing or analytics engine - it reports what Recon's endpoints return and does + not perform ad-hoc aggregations, joins, or math across the cluster. +- It is **read-only** - it never mutates the cluster. +- Its results are **bounded** (at most 1000 records per read - see [Limits](#11-limits--boundary-conditions)). +- Its answers reflect Recon's **last metadata sync**, not the live cluster state. + +> **Important:** The assistant calls an **external `LLM` provider**, so cluster metadata leaves your +> network when it is used. Read [Data sent to third-party providers](#5-data-sent-to-third-party-llm-providers) +> before enabling it. The feature is marked unstable and may change between releases. + +## 2. Architecture at a glance Review Comment: I would prefer to explain the architecture using a simple diagram that illustrates how a user query is transformed into an API call, how the LLM processes the request, and how it generates a plain English response. ########## docs/05-administrator-guide/03-operations/09-observability/02-recon/03-recon-ai-assistant.mdx: ########## @@ -0,0 +1,484 @@ +--- +sidebar_label: Recon AI Assistant +--- + +# Recon AI Assistant + +The **Recon AI Assistant** lets you ask questions about your Apache Ozone cluster in plain English +and get answers assembled from the data Recon already collects. It is an optional, **disabled by +default**, experimental feature of the Recon service. + +> **Note:** This page is for operators (who enable, secure, configure and run the assistant) and end +> users (who ask it questions). It is not a code walkthrough; contributors can find the internal flow +> in `CODE_FLOW.md` next to the chatbot source. + +## 1. Overview + +Recon continuously derives a large amount of cluster metadata - container health and replica state, +namespace and usage rollups, open and pending-delete keys, datanode and pipeline status, background +task and sync state - and exposes it across many REST endpoints and UI screens. In practice most of +that information is never seen or correlated, because you have to know which endpoint or screen holds +the answer. + +The assistant closes that gap: you ask a question, and it decides which Recon view(s) answer it, runs +those reads, and writes back a readable summary. + +**What it is not:** + +- It is **not** a computing or analytics engine - it reports what Recon's endpoints return and does + not perform ad-hoc aggregations, joins, or math across the cluster. +- It is **read-only** - it never mutates the cluster. +- Its results are **bounded** (at most 1000 records per read - see [Limits](#11-limits--boundary-conditions)). +- Its answers reflect Recon's **last metadata sync**, not the live cluster state. + +> **Important:** The assistant calls an **external `LLM` provider**, so cluster metadata leaves your +> network when it is used. Read [Data sent to third-party providers](#5-data-sent-to-third-party-llm-providers) +> before enabling it. The feature is marked unstable and may change between releases. + +## 2. Architecture at a glance + +At a high level a question flows through three steps: + +1. **Tool selection** - the assistant asks the `LLM` which Recon view(s) can answer the question. +2. **In-process execution** - Recon runs those reads inside the Recon JVM (no HTTP loopback), with + hard safety limits applied. +3. **Summarization** - the raw results are sent back to the `LLM`, which writes the final answer. + +The assistant is **provider-agnostic**: OpenAI, Google Gemini, and Anthropic are all reachable behind +one interface (see [Supported providers & models](#3-supported-providers--models)). + +## 3. Supported providers & models + +The assistant supports **three** `LLM` providers. You configure one (or more) by supplying an API key; +a provider with no key is simply unavailable. + +| Provider | Reached via | Notes | +|---|---|---| +| **OpenAI** | Native OpenAI API (`https://api.openai.com`) | Standard chat-completions API. | +| **Google Gemini** | Google's **OpenAI-compatible** endpoint (`https://generativelanguage.googleapis.com/v1beta/openai/`) | Used instead of the native Gemini client for reliable timeout handling. | +| **Anthropic (Claude)** | Native Anthropic API | Sends a beta header for the 1M-token context window (`anthropic.beta.header`). | + +**Default model lists** (configurable without a code change; surfaced by `GET /chatbot/models`): + +| Provider | Config key | Default models | +|---|---|---| +| OpenAI | `ozone.recon.chatbot.openai.models` | `gpt-4.1, gpt-4.1-mini, gpt-4.1-nano` | +| Gemini | `ozone.recon.chatbot.gemini.models` | `gemini-2.5-pro, gemini-2.5-flash, gemini-3-flash-preview, gemini-3.1-pro-preview` | +| Anthropic | `ozone.recon.chatbot.anthropic.models` | `claude-opus-4-6, claude-sonnet-4-6` | + +The **default selection** is provider `gemini`, model `gemini-2.5-flash`. + +> **Tip - reasoning vs. fast models:** "Reasoning" models (for example `gemini-2.5-pro`) spend output +> tokens on internal thinking and are slower and more token-hungry; "fast" models (for example +> `gemini-2.5-flash`) return snappier answers. For an interactive assistant, prefer a fast model as +> the default and reserve reasoning models for harder questions. + +### Provider & model routing (fallback behavior) + +A request may name a `provider` and/or `model`, but the assistant resolves them against what is +actually configured. This explains why an answer can come from a different model than requested: + +- A requested **provider** is honored only if it is **configured** (has an API key). Otherwise the + provider is inferred from the requested model; if that fails, the **default provider** is used. +- A requested **model** is used only if it appears in a configured model list. Otherwise the + **default model** is used. +- If the resolved model is not valid for the resolved provider, **both reset to the defaults**. + +## 4. Prerequisites & network egress + +Before enabling the assistant: + +- Recon is deployed and running. +- You have an account and API key for at least one supported provider. +- The **Recon server** can make **outbound HTTPS** calls to the provider endpoint(s) listed in + [Supported providers](#3-supported-providers--models). Only the Recon server needs egress - end + users' browsers do not. + +> **Note:** In firewalled or proxied environments, allowlist the provider hostnames on HTTPS (443), +> or route through your outbound proxy. In air-gapped environments, either leave the feature disabled +> or point the relevant `*.base.url` at an in-VPC, OpenAI-compatible gateway (see +> [Configuration](#8-configuration-reference)). + +Each concurrent query holds one Recon worker thread for its full duration (up to two `LLM` calls plus +up to five Recon reads), so size the thread pool to your expected concurrency (see +[Configuration](#8-configuration-reference)). + +## 5. Data sent to third-party `LLM` providers + +Because the assistant calls an external provider, you should understand exactly what leaves your +cluster before enabling it. + +**Transmitted to the provider:** + +- The user's **question text**. +- The **system prompts** (the catalog of Recon tools and the semantic guide describing them). +- The **raw JSON results** of the Recon reads used to answer - this is cluster **metadata** such as + volume / bucket / key names, paths, container and pipeline IDs, sizes, counts, and health states. +- A second round-trip containing those results for **summarization**. + +**Not transmitted:** + +- Ozone object **data** (file contents) - only metadata is ever read. +- Any credential beyond the provider's own API authentication. + +> **Warning:** Object **names and paths are themselves potentially sensitive** - real volume, bucket, +> and key names can reveal business or data structure. The 1000-record cap bounds the *volume* of +> data sent, not its sensitivity. + +**Controls and mitigations:** + +- Keep the feature **disabled** where data-egress policy forbids sending metadata off-cluster. +- Encourage **scoped** queries (a specific volume/bucket/path) so less data is read and sent. +- Point `*.base.url` at a **self-hosted or in-VPC** OpenAI-compatible endpoint to avoid public egress. +- Review each provider's **data-retention and training** policy. +- **Restrict access** to the Recon chat endpoint, since all users share the server-configured key. + +## 6. Managing API keys (secure vs. insecure storage) + +API keys are resolved **server-side only** - they are never accepted per request, and every chat user +shares the single admin-configured key. (This is why you should gate who can reach the endpoint.) + +**Resolution order** (handled by Recon's `CredentialHelper`): + +1. The Hadoop Credential Provider (`JCEKS`), if `hadoop.security.credential.provider.path` is set. +2. A plaintext value in `ozone-site.xml` (backward-compatible fallback). + +### Insecure: plaintext in `ozone-site.xml` (dev/test only) + +```xml +<property> + <name>ozone.recon.chatbot.gemini.api.key</name> + <value>YOUR_API_KEY</value> +</property> +``` + +> **Warning:** Plaintext keys are readable by anyone who can read `ozone-site.xml`. Use this only for +> local development or testing, never in production. + +### Secure: Hadoop Credential Provider (`JCEKS`) - recommended + +The credential **alias must equal the config key name** (for example +`ozone.recon.chatbot.gemini.api.key`). + +1. Create the keystore and add each secret: + + ```bash + hadoop credential create ozone.recon.chatbot.gemini.api.key \ + -provider localjceks://file/etc/security/recon-keys.jceks + ``` + + Repeat for `ozone.recon.chatbot.openai.api.key` and + `ozone.recon.chatbot.anthropic.api.key` as needed. The command prompts for the secret value. + +2. Point Recon at the keystore in `ozone-site.xml`: + + ```xml + <property> + <name>hadoop.security.credential.provider.path</name> + <value>localjceks://file/etc/security/recon-keys.jceks</value> + </property> + ``` + +3. Protect the keystore. Restrict file permissions (for example `chmod 600`, owned by the Recon + service user) and supply the keystore password out-of-band - for example via + `HADOOP_CREDSTORE_PASSWORD` or a password file - rather than relying on the default. + +4. Restart Recon and verify with `GET /api/v1/chatbot/health` (`llmClientAvailable` should be `true`). + +**Rotation / removal:** update or delete the alias with `hadoop credential create` / `hadoop +credential delete`, then restart Recon. If a key is missing, that provider is simply unavailable; the +feature still works through any other configured provider. + +| Environment | Recommended storage | +|---|---| +| Local dev / testing | `ozone-site.xml` (plaintext) | +| Production | Hadoop Credential Provider (`JCEKS`) | + +## 7. Getting started + +1. Enable the feature: + + ```xml + <property> + <name>ozone.recon.chatbot.enabled</name> + <value>true</value> + </property> + ``` + +2. Choose a provider and model (defaults are `gemini` / `gemini-2.5-flash`). +3. Supply an API key - see [Managing API keys](#6-managing-api-keys-secure-vs-insecure-storage). +4. Restart Recon and verify: + - `GET /api/v1/chatbot/health` + - `GET /api/v1/chatbot/models` + - open the assistant panel in the Recon UI. + +When the feature is disabled, none of its components are wired in and it cannot affect Recon. + +## 8. Configuration reference + +All keys are under the prefix `ozone.recon.chatbot.`. + +### Feature toggle + +| Key | Default | Description | +|---|---|---| +| `enabled` | `false` | Master switch for the assistant. Off by default. | + +### Provider & model + +| Key | Default | Description | +|---|---|---| +| `provider` | `gemini` | Default provider: `openai`, `gemini`, or `anthropic`. | +| `default.model` | `gemini-2.5-flash` | Default model when none is requested or the requested one is unavailable. | + +### API keys (see Section 6) + +| Key | Default | Description | +|---|---|---| +| `openai.api.key` | _(none)_ | OpenAI API key. Prefer `JCEKS` storage. | +| `gemini.api.key` | _(none)_ | Gemini API key. Prefer `JCEKS` storage. | +| `anthropic.api.key` | _(none)_ | Anthropic API key. Prefer `JCEKS` storage. | + +### Base URL overrides + +| Key | Default | Description | +|---|---|---| +| `openai.base.url` | `https://api.openai.com` | Override to target an OpenAI-compatible gateway. | +| `gemini.base.url` | `https://generativelanguage.googleapis.com/v1beta/openai/` | Gemini's OpenAI-compatible endpoint. | + +### Execution policy + +| Key | Default | Description | +|---|---|---| +| `exec.require.safe.scope` | `true` | Require a bucket-scoped prefix for key listings. Keep enabled in production (see [Limits](#11-limits--boundary-conditions)). | +| `max.tool.calls` | `5` | Maximum number of Recon reads a single question may trigger. | + +### Concurrency & timeouts + +| Key | Default | Description | +|---|---|---| +| `thread.pool.size` | `5` | Worker threads for chatbot requests. Size to expected concurrent users. | +| `max.queue.size` | `10` | Requests that may wait when all threads are busy; beyond this, clients get HTTP 503. | +| `timeout.ms` | `120000` | Timeout for a single provider call (ms). | +| `request.timeout.ms` | `180000` | Overall per-request wall-clock timeout (ms); exceeding it returns HTTP 504. Default is 3 minutes. | + +### Model lists (UI dropdown) + +| Key | Default | +|---|---| +| `openai.models` | `gpt-4.1, gpt-4.1-mini, gpt-4.1-nano` | +| `gemini.models` | `gemini-2.5-pro, gemini-2.5-flash, gemini-3-flash-preview, gemini-3.1-pro-preview` | +| `anthropic.models` | `claude-opus-4-6, claude-sonnet-4-6` | + +### Anthropic header + +| Key | Default | Description | +|---|---|---| +| `anthropic.beta.header` | `context-1m-2025-08-07` | Anthropic beta header (enables the 1M-token context window). Set empty to disable. | + +## 9. Using the assistant - what you can ask Review Comment: Do you think it would be helpful to add a short sample video of the UI in this section? It could explain the workflow more effectively than plain text. ########## docs/05-administrator-guide/03-operations/09-observability/02-recon/03-recon-ai-assistant.mdx: ########## @@ -0,0 +1,484 @@ +--- +sidebar_label: Recon AI Assistant +--- + +# Recon AI Assistant + +The **Recon AI Assistant** lets you ask questions about your Apache Ozone cluster in plain English +and get answers assembled from the data Recon already collects. It is an optional, **disabled by +default**, experimental feature of the Recon service. + +> **Note:** This page is for operators (who enable, secure, configure and run the assistant) and end +> users (who ask it questions). It is not a code walkthrough; contributors can find the internal flow +> in `CODE_FLOW.md` next to the chatbot source. + +## 1. Overview + +Recon continuously derives a large amount of cluster metadata - container health and replica state, +namespace and usage rollups, open and pending-delete keys, datanode and pipeline status, background +task and sync state - and exposes it across many REST endpoints and UI screens. In practice most of +that information is never seen or correlated, because you have to know which endpoint or screen holds +the answer. + +The assistant closes that gap: you ask a question, and it decides which Recon view(s) answer it, runs +those reads, and writes back a readable summary. + +**What it is not:** + +- It is **not** a computing or analytics engine - it reports what Recon's endpoints return and does + not perform ad-hoc aggregations, joins, or math across the cluster. +- It is **read-only** - it never mutates the cluster. +- Its results are **bounded** (at most 1000 records per read - see [Limits](#11-limits--boundary-conditions)). +- Its answers reflect Recon's **last metadata sync**, not the live cluster state. + +> **Important:** The assistant calls an **external `LLM` provider**, so cluster metadata leaves your +> network when it is used. Read [Data sent to third-party providers](#5-data-sent-to-third-party-llm-providers) +> before enabling it. The feature is marked unstable and may change between releases. + +## 2. Architecture at a glance + +At a high level a question flows through three steps: + +1. **Tool selection** - the assistant asks the `LLM` which Recon view(s) can answer the question. +2. **In-process execution** - Recon runs those reads inside the Recon JVM (no HTTP loopback), with + hard safety limits applied. +3. **Summarization** - the raw results are sent back to the `LLM`, which writes the final answer. + +The assistant is **provider-agnostic**: OpenAI, Google Gemini, and Anthropic are all reachable behind +one interface (see [Supported providers & models](#3-supported-providers--models)). + +## 3. Supported providers & models + +The assistant supports **three** `LLM` providers. You configure one (or more) by supplying an API key; +a provider with no key is simply unavailable. + +| Provider | Reached via | Notes | +|---|---|---| +| **OpenAI** | Native OpenAI API (`https://api.openai.com`) | Standard chat-completions API. | +| **Google Gemini** | Google's **OpenAI-compatible** endpoint (`https://generativelanguage.googleapis.com/v1beta/openai/`) | Used instead of the native Gemini client for reliable timeout handling. | +| **Anthropic (Claude)** | Native Anthropic API | Sends a beta header for the 1M-token context window (`anthropic.beta.header`). | + +**Default model lists** (configurable without a code change; surfaced by `GET /chatbot/models`): + +| Provider | Config key | Default models | +|---|---|---| +| OpenAI | `ozone.recon.chatbot.openai.models` | `gpt-4.1, gpt-4.1-mini, gpt-4.1-nano` | +| Gemini | `ozone.recon.chatbot.gemini.models` | `gemini-2.5-pro, gemini-2.5-flash, gemini-3-flash-preview, gemini-3.1-pro-preview` | +| Anthropic | `ozone.recon.chatbot.anthropic.models` | `claude-opus-4-6, claude-sonnet-4-6` | + +The **default selection** is provider `gemini`, model `gemini-2.5-flash`. + +> **Tip - reasoning vs. fast models:** "Reasoning" models (for example `gemini-2.5-pro`) spend output +> tokens on internal thinking and are slower and more token-hungry; "fast" models (for example +> `gemini-2.5-flash`) return snappier answers. For an interactive assistant, prefer a fast model as +> the default and reserve reasoning models for harder questions. + +### Provider & model routing (fallback behavior) + +A request may name a `provider` and/or `model`, but the assistant resolves them against what is +actually configured. This explains why an answer can come from a different model than requested: + +- A requested **provider** is honored only if it is **configured** (has an API key). Otherwise the + provider is inferred from the requested model; if that fails, the **default provider** is used. +- A requested **model** is used only if it appears in a configured model list. Otherwise the + **default model** is used. +- If the resolved model is not valid for the resolved provider, **both reset to the defaults**. + +## 4. Prerequisites & network egress + +Before enabling the assistant: + +- Recon is deployed and running. +- You have an account and API key for at least one supported provider. +- The **Recon server** can make **outbound HTTPS** calls to the provider endpoint(s) listed in + [Supported providers](#3-supported-providers--models). Only the Recon server needs egress - end + users' browsers do not. + +> **Note:** In firewalled or proxied environments, allowlist the provider hostnames on HTTPS (443), +> or route through your outbound proxy. In air-gapped environments, either leave the feature disabled +> or point the relevant `*.base.url` at an in-VPC, OpenAI-compatible gateway (see +> [Configuration](#8-configuration-reference)). + +Each concurrent query holds one Recon worker thread for its full duration (up to two `LLM` calls plus +up to five Recon reads), so size the thread pool to your expected concurrency (see +[Configuration](#8-configuration-reference)). + +## 5. Data sent to third-party `LLM` providers + +Because the assistant calls an external provider, you should understand exactly what leaves your +cluster before enabling it. + +**Transmitted to the provider:** + +- The user's **question text**. +- The **system prompts** (the catalog of Recon tools and the semantic guide describing them). +- The **raw JSON results** of the Recon reads used to answer - this is cluster **metadata** such as + volume / bucket / key names, paths, container and pipeline IDs, sizes, counts, and health states. +- A second round-trip containing those results for **summarization**. + +**Not transmitted:** + +- Ozone object **data** (file contents) - only metadata is ever read. +- Any credential beyond the provider's own API authentication. + +> **Warning:** Object **names and paths are themselves potentially sensitive** - real volume, bucket, +> and key names can reveal business or data structure. The 1000-record cap bounds the *volume* of +> data sent, not its sensitivity. + +**Controls and mitigations:** + +- Keep the feature **disabled** where data-egress policy forbids sending metadata off-cluster. +- Encourage **scoped** queries (a specific volume/bucket/path) so less data is read and sent. +- Point `*.base.url` at a **self-hosted or in-VPC** OpenAI-compatible endpoint to avoid public egress. +- Review each provider's **data-retention and training** policy. +- **Restrict access** to the Recon chat endpoint, since all users share the server-configured key. + +## 6. Managing API keys (secure vs. insecure storage) + +API keys are resolved **server-side only** - they are never accepted per request, and every chat user +shares the single admin-configured key. (This is why you should gate who can reach the endpoint.) + +**Resolution order** (handled by Recon's `CredentialHelper`): + +1. The Hadoop Credential Provider (`JCEKS`), if `hadoop.security.credential.provider.path` is set. +2. A plaintext value in `ozone-site.xml` (backward-compatible fallback). + +### Insecure: plaintext in `ozone-site.xml` (dev/test only) + +```xml +<property> + <name>ozone.recon.chatbot.gemini.api.key</name> + <value>YOUR_API_KEY</value> +</property> +``` + +> **Warning:** Plaintext keys are readable by anyone who can read `ozone-site.xml`. Use this only for +> local development or testing, never in production. + +### Secure: Hadoop Credential Provider (`JCEKS`) - recommended + +The credential **alias must equal the config key name** (for example +`ozone.recon.chatbot.gemini.api.key`). + +1. Create the keystore and add each secret: + + ```bash + hadoop credential create ozone.recon.chatbot.gemini.api.key \ + -provider localjceks://file/etc/security/recon-keys.jceks + ``` + + Repeat for `ozone.recon.chatbot.openai.api.key` and + `ozone.recon.chatbot.anthropic.api.key` as needed. The command prompts for the secret value. + +2. Point Recon at the keystore in `ozone-site.xml`: + + ```xml + <property> + <name>hadoop.security.credential.provider.path</name> + <value>localjceks://file/etc/security/recon-keys.jceks</value> + </property> + ``` + +3. Protect the keystore. Restrict file permissions (for example `chmod 600`, owned by the Recon + service user) and supply the keystore password out-of-band - for example via + `HADOOP_CREDSTORE_PASSWORD` or a password file - rather than relying on the default. + +4. Restart Recon and verify with `GET /api/v1/chatbot/health` (`llmClientAvailable` should be `true`). + +**Rotation / removal:** update or delete the alias with `hadoop credential create` / `hadoop +credential delete`, then restart Recon. If a key is missing, that provider is simply unavailable; the +feature still works through any other configured provider. + +| Environment | Recommended storage | +|---|---| +| Local dev / testing | `ozone-site.xml` (plaintext) | +| Production | Hadoop Credential Provider (`JCEKS`) | + +## 7. Getting started + +1. Enable the feature: + + ```xml + <property> + <name>ozone.recon.chatbot.enabled</name> + <value>true</value> + </property> + ``` + +2. Choose a provider and model (defaults are `gemini` / `gemini-2.5-flash`). +3. Supply an API key - see [Managing API keys](#6-managing-api-keys-secure-vs-insecure-storage). +4. Restart Recon and verify: + - `GET /api/v1/chatbot/health` + - `GET /api/v1/chatbot/models` + - open the assistant panel in the Recon UI. + +When the feature is disabled, none of its components are wired in and it cannot affect Recon. + +## 8. Configuration reference + +All keys are under the prefix `ozone.recon.chatbot.`. + +### Feature toggle + +| Key | Default | Description | +|---|---|---| +| `enabled` | `false` | Master switch for the assistant. Off by default. | + +### Provider & model + +| Key | Default | Description | +|---|---|---| +| `provider` | `gemini` | Default provider: `openai`, `gemini`, or `anthropic`. | +| `default.model` | `gemini-2.5-flash` | Default model when none is requested or the requested one is unavailable. | + +### API keys (see Section 6) + +| Key | Default | Description | +|---|---|---| +| `openai.api.key` | _(none)_ | OpenAI API key. Prefer `JCEKS` storage. | +| `gemini.api.key` | _(none)_ | Gemini API key. Prefer `JCEKS` storage. | +| `anthropic.api.key` | _(none)_ | Anthropic API key. Prefer `JCEKS` storage. | + +### Base URL overrides + +| Key | Default | Description | +|---|---|---| +| `openai.base.url` | `https://api.openai.com` | Override to target an OpenAI-compatible gateway. | +| `gemini.base.url` | `https://generativelanguage.googleapis.com/v1beta/openai/` | Gemini's OpenAI-compatible endpoint. | + +### Execution policy + +| Key | Default | Description | +|---|---|---| +| `exec.require.safe.scope` | `true` | Require a bucket-scoped prefix for key listings. Keep enabled in production (see [Limits](#11-limits--boundary-conditions)). | +| `max.tool.calls` | `5` | Maximum number of Recon reads a single question may trigger. | + +### Concurrency & timeouts + +| Key | Default | Description | +|---|---|---| +| `thread.pool.size` | `5` | Worker threads for chatbot requests. Size to expected concurrent users. | +| `max.queue.size` | `10` | Requests that may wait when all threads are busy; beyond this, clients get HTTP 503. | +| `timeout.ms` | `120000` | Timeout for a single provider call (ms). | +| `request.timeout.ms` | `180000` | Overall per-request wall-clock timeout (ms); exceeding it returns HTTP 504. Default is 3 minutes. | + +### Model lists (UI dropdown) + +| Key | Default | +|---|---| +| `openai.models` | `gpt-4.1, gpt-4.1-mini, gpt-4.1-nano` | +| `gemini.models` | `gemini-2.5-pro, gemini-2.5-flash, gemini-3-flash-preview, gemini-3.1-pro-preview` | +| `anthropic.models` | `claude-opus-4-6, claude-sonnet-4-6` | + +### Anthropic header + +| Key | Default | Description | +|---|---|---| +| `anthropic.beta.header` | `context-1m-2025-08-07` | Anthropic beta header (enables the 1M-token context window). Set empty to disable. | + +## 9. Using the assistant - what you can ask + +Ask by **intent**; the assistant maps your question to the right Recon view. It can answer questions +about: + +- **Cluster & capacity** - overall health, storage used/available. +- **Datanodes** - inventory, health, dead/stale nodes. +- **Pipelines** - inventory, leaders, members, state. +- **Containers** - inventory and health: unhealthy, missing, deleted, OM/SCM mismatch, quasi-closed. +- **Keys** - committed key listings, open/uncommitted keys, pending-delete keys, multipart uploads. +- **Volumes & buckets** - inventory, ownership, layout, quotas. +- **Namespace** - disk usage, object counts, quota usage, file-size distribution for a path. +- **Tasks** - Recon background task and sync status. + +**Example questions:** "How much storage is used?", "Are any containers under-replicated?", "Show +open keys in `/vol1/bucket1`", "List buckets in volume `sales`", "What is the disk usage of +`/vol1/bucket1`?", "Did any Recon task fail?". + +**Conceptual questions** (for example "What is an FSO bucket?") are answered directly, without reading +cluster data. + +**What it cannot do** (it will decline and suggest the nearest supported view rather than guess): +per-container replica timelines, raw block-to-key mapping, any mutation, and arbitrary computation. + +> **Tip:** Name the volume and bucket, and say "open" when you mean uncommitted keys. FSO/OBS is a +> bucket *layout*, not a key *state* - "FSO keys" means committed keys in an FSO bucket, while "open +> FSO keys" means uncommitted keys. + +## 10. Tool (endpoint) reference + +These are the Recon views the assistant can call. This list mirrors the in-code catalog (see +[Extending](#14-extending-the-assistant-for-new-recon-features)). + +| Group | Tool | Answers | +|---|---|---| +| Cluster | `api_v1_clusterState` | Overall cluster snapshot (capacity, counts, health). | +| Cluster | `api_v1_datanodes` | Datanode inventory and health. | +| Cluster | `api_v1_pipelines` | Pipeline inventory, leaders, members, state. | +| Containers | `api_v1_containers` | General container inventory. | +| Containers | `api_v1_containers_missing` | Missing / lost containers. | +| Containers | `api_v1_containers_unhealthy` | All unhealthy containers (aggregate). | +| Containers | `api_v1_containers_unhealthy_state` | Unhealthy containers filtered to one state. | +| Containers | `api_v1_containers_deleted` | Containers deleted in SCM. | +| Containers | `api_v1_containers_mismatch` | OM/SCM existence mismatches. | +| Containers | `api_v1_containers_mismatch_deleted` | Deleted in SCM but still present in OM. | +| Containers | `api_v1_containers_quasiClosed` | Quasi-closed containers. | +| Containers | `api_v1_containers_unhealthy_export` | Export jobs for unhealthy-container data. | +| Keys | `api_v1_keys_open` | Open / uncommitted keys (detailed). | +| Keys | `api_v1_keys_open_summary` | Open-key totals. | +| Keys | `api_v1_keys_open_mpu_summary` | Open multipart-upload totals. | +| Keys | `api_v1_keys_deletePending` | Keys pending deletion (detailed). | +| Keys | `api_v1_keys_deletePending_summary` | Pending-delete key totals. | +| Keys | `api_v1_keys_deletePending_dirs` | Directories pending deletion. | +| Keys | `api_v1_keys_deletePending_dirs_summary` | Pending-delete directory totals. | +| Keys | `api_v1_keys_listKeys` | Committed key/file listing and filtering. | +| Namespace | `api_v1_volumes` | Volume inventory. | +| Namespace | `api_v1_buckets` | Bucket inventory (optionally by volume). | +| Namespace | `api_v1_namespace_summary` | Object counts under a path. | +| Namespace | `api_v1_namespace_usage` | Disk usage for a path. | +| Namespace | `api_v1_namespace_quota` | Quota limit vs. usage for a path. | +| Namespace | `api_v1_namespace_dist` | File-size distribution under a path. | +| Utilization | `api_v1_utilization_fileCount` | File-count distribution by size tier. | +| Utilization | `api_v1_utilization_containerCount` | Container-count distribution by size tier. | +| Tasks | `api_v1_task_status` | Recon background task and sync status. | + +## 11. Limits & boundary conditions Review Comment: Should we mention the current limitations, such as the chatbot not retaining conversation context? Each user query is processed independently, so previous interactions are not remembered. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
