From 8d0ca1612498bb1fdc1948f068ecefff9541e146 Mon Sep 17 00:00:00 2001 From: rcourtman Date: Mon, 22 Dec 2025 14:43:56 +0000 Subject: [PATCH] docs: update AI.md with v5 patrol and finding management features - Added finding management section (resolve, dismiss, suppress) - Documented patrol service and severity levels - Added AI-assisted remediation capabilities - Added Ollama tool/function calling support note - Added new troubleshooting tips for findings persistence --- docs/AI.md | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/AI.md b/docs/AI.md index 56bb2562d..920938276 100644 --- a/docs/AI.md +++ b/docs/AI.md @@ -8,6 +8,7 @@ Pulse AI adds an optional assistant for troubleshooting, summarization, and proa - **Patrol**: Background checks that generate findings on a schedule. - **Alert analysis**: Optional analysis when alerts fire (token-efficient). - **Command proposals and execution**: When enabled, Pulse can propose commands and (optionally) execute them via connected agents. +- **Finding management**: Dismiss findings as expected behavior, resolve after fixing, with suppression rules to prevent recurrence. - **Cost tracking**: Tracks usage and supports a monthly budget target. ## Configuration @@ -26,7 +27,7 @@ Pulse supports multiple providers configured independently: - **OpenAI** - **DeepSeek** - **Google Gemini** -- **Ollama** (self-hosted) +- **Ollama** (self-hosted, with tool/function calling support) - **OpenAI-compatible base URL** (for providers that implement the OpenAI API shape) ### Models @@ -46,9 +47,45 @@ You can set separate models for: - Test provider connectivity: `POST /api/ai/test` and `POST /api/ai/test/{provider}` - List available models (queried live from the provider): `GET /api/ai/models` +## Patrol Service + +Patrol runs automated health checks on a configurable schedule (default: 15 minutes). It analyzes: + +- Proxmox nodes, VMs, and containers +- PBS backup status +- Host agent metrics +- Resource utilization trends + +### Finding Severity + +Patrol generates findings with severity levels: + +- **Critical**: Immediate attention required +- **Warning**: Should be addressed soon + +Note: `info` and `watch` level findings are filtered out by default to reduce noise. + +### Managing Findings + +Findings can be managed via the UI or API: + +- **Resolve**: Mark as fixed (finding will reappear if the issue resurfaces) +- **Dismiss**: Mark as expected behavior with a reason (`not_an_issue`, `expected_behavior`, `will_fix_later`) +- **Suppress**: Create a rule to prevent similar findings from recurring + +Dismissed and resolved findings are persisted across Pulse restarts. + +### AI-Assisted Remediation + +When chatting with AI about a patrol finding, the AI can: +- Run diagnostic commands on connected agents +- Propose fixes with explanations +- Automatically resolve findings after successful remediation +- Dismiss findings it determines are expected behavior + ## Safety Controls -Pulse includes settings that control how “active” AI features are: +Pulse includes settings that control how "active" AI features are: - **Autonomous mode** (`autonomous_mode`): when enabled, AI may execute actions without a separate approval step in the UI. - **Patrol auto-fix** (`patrol_auto_fix`): allows patrol findings to trigger remediation attempts. @@ -61,4 +98,5 @@ If you enable execution features, ensure agent tokens and scopes are appropriate - **AI not responding**: verify provider credentials in **Settings → AI** and confirm `GET /api/ai/models` works. - **OAuth issues (Anthropic)**: verify the OAuth flow is completing and that Pulse can reach the callback endpoint. - **No execution capability**: confirm at least one compatible agent is connected and that the instance has execution enabled. - +- **Findings not persisting**: check that Pulse has write access to its config directory. +- **Too many findings**: Adjust patrol thresholds in Settings, which derive from your alert thresholds.