# Setup guide — Metric Anomaly Investigation Agent

## 1. Install and connect read-only

Install the agent and connect it to your warehouse/metrics with a read-only role and to your events/deploy log.

```
pipx install anomaly-agent
anomaly-agent connect --warehouse bigquery --events launchdarkly,github
anomaly-agent doctor   # verifies read-only access
```

## 2. Configure guardrails

Cost and safety limits are enforced by the gate, not the model.

```
cp .env.example .env
ANTHROPIC_API_KEY=sk-ant-...
READ_ONLY=true
MAX_SCAN_ROWS=20000000
QUERY_TIMEOUT_S=30
MAX_TOOL_CALLS=10
```

## 3. Define metrics, dimensions, seasonality

Tell it how each KPI is defined, which dimensions to decompose by, and known seasonality.

```
# metrics/checkout_conversion.yml
definition: "paid_orders / checkout_sessions"
dimensions: [region, platform, payment_method, plan]
seasonality: "weekly (weekend dip), monthly billing spike"
expected_range: "0.28–0.34"
```

## 4. Investigate from the CLI

Point it at a metric and window and review the localized, ranked findings.

```
anomaly-agent investigate --metric checkout_conversion --window 2026-06-18:2026-06-20 --explain
# prints anomaly_confirmed, localization, ranked hypotheses + confidence, next checks
```

## 5. Wire to alerts

Trigger an investigation when a metric alert fires; the report posts to the channel for a human.

```
# metric alert -> POST https://your-host/anomaly/investigate (HMAC)
# posts ranked hypotheses + recommended checks to #analytics
```
