# QVAC (local AI)

The **QVAC** tab is an on-device assistant for the connected agent. Models run on your desktop; the agent only answers metrics tools over P2P.

## First-time setup

1. Open **QVAC** in the sidebar.
2. **Continue** through the welcome screen.
3. Review the system check (RAM, whether `@qvac/sdk` is installed).
4. Pick a **model profile**:
   - **Lite** — smallest download
   - **Recommended** — best default (tool calling)
   - **Strong** — larger model if you have RAM to spare
5. **Download & load** (or continue in tools-only mode if the SDK is not installed).

Re-run setup anytime with **Setup** in the QVAC header.

## Using chat

- Type a question or click a sample prompt.
- Answers use live tools (`host_snapshot`, charts, anomalies, processes).
- Tool chips under a reply show which RPCs ran.
- **Unload** frees model memory (weights stay on disk).
- **New chat** clears the conversation.

### Good questions

- “Summarize host health right now”
- “Any open alerts or anomalies?”
- “List charts related to disk”
- “Why might CPU be high?” (uses CPU summary + snapshot)

### Requires a connected agent

Connect from the **Connect** tab first. If offline, tools return a clear error instead of inventing numbers.

## Tools-only vs full QVAC

| Mode | When | Behavior |
|------|------|----------|
| Full QVAC | `@qvac/sdk` present + model loaded | Local Qwen (or other profile) + tools |
| Tools-only | SDK missing or load failed | Grounded formatting of RPC results, no LLM |

### From source / `pear run`

Install dependencies **in the PearData repo** (CI does this with `npm ci`):

```bash
npm ci
pear run -d .          # or: npm run start:client
```

Do not rely on a global or parent-folder `@qvac/sdk` install — release builds only include packages declared in this project.

### From CI / release zip

Rolling and tagged **desktop** builds package `@qvac/sdk` and a Bare worker when packaging succeeds. Open **QVAC → Setup** and choose a profile to download a model.

If a build was made with `PEARDATA_SKIP_QVAC=1`, the tab stays tools-only (metrics tools still work).

## Settings

**Settings → QVAC**:

- Default model profile
- Inject local knowledge (guide + chart catalog into prompts)
- Idle unload (minutes) — free RAM when idle; weights stay on disk

## Settings

**Settings → QVAC**:

| Preference | Effect |
|------------|--------|
| Default model profile | Lite / Recommended / Strong / Tool-tiny (used on next Setup) |
| Inject local knowledge | Keyword RAG over user-guide snippets + chart catalog |
| Idle unload (minutes) | Unload model from RAM after inactivity (`0` = never) |
| Open QVAC tab | Jump to the chat view |

## Tools available to chat

Tools are tiered (core always; deep on Recommended/Strong; write for operators).

| Tool | Purpose |
|------|---------|
| `investigate_host` | **Best first call** — findings, hot charts, top processes |
| `host_snapshot` | Lighter live health + KPIs |
| `hot_metrics` / `related_charts` / `compare_chart_windows` | Investigation drill-down |
| `search_charts` / `summarize_chart` / `summarize_charts` / `query_metric` | Catalog + time series |
| `get_weights` | Correlation / influence for a chart |
| `list_anomalies` / `list_alerts` / `get_alert` | Anomaly / alert state |
| `list_processes` | Top processes (when enabled on agent) |
| `query_logs` | Journal / anomaly / audit lines |
| `fleet_health` / `list_child_peers` / `storage_info` | Fleet + retention |
| `agent_health` / `node_info` / `db_info` / `list_contexts` / `get_chart` / `list_jobs` | Agent meta |
| `local_knowledge` | Offline product how-tos |
| `open_chart` / `open_view` | Navigate the desktop UI |
| `silence_alert` / `ack_alert` / `run_job` | Operator only, with confirmation |

## Privacy

- No cloud API keys for this feature.
- Inference stays on your machine.
- Agent never loads multi-GB models for the default design.

See also [docs/QVAC.md](../docs/QVAC.md).