Metadata-Version: 2.4
Name: measure-monitor
Version: 0.1.0
Summary: Unattended cross-platform anomaly monitoring for the Measure ecosystem: fetch metric observations, detect irregular drops/spikes, deliver alerts.
Project-URL: Homepage, https://github.com/measure-mcp/measure-monitor
Project-URL: Repository, https://github.com/measure-mcp/measure-monitor
Author: Measure MCP contributors
License: Apache-2.0
License-File: LICENSE
Keywords: alerts,anomaly-detection,mcp,measureops,monitoring,paid-media
Requires-Python: >=3.12
Requires-Dist: measure-paid-media-mcp<0.5,>=0.4
Requires-Dist: measure-sdk<0.3,>=0.2
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Measure Monitor

Unattended cross-platform anomaly monitoring for the **Measure** ecosystem.

`measure-monitor` is the ecosystem's **orchestrator**, not an MCP product. It sits
*one level above* the products — which never import one another — and wires them
together: it fetches metric `Observation`s from a source product (paid media
today), runs the SDK's shared anomaly detector, and delivers alerts to your
channels. Run it on a schedule for hands-off monitoring of irregular drops and
spikes.

```
  ┌── cron / /schedule ──────────────────────────────────────────────┐
  │  measure-monitor run --config monitors.toml                       │
  │                                                                   │
  │   paid-media.get_metric_observations(metric)   ← fetch + history  │
  │            │                                                      │
  │            ▼  detect_anomaly (SDK)              ← shared brain     │
  │       irregular drop/spike?                                       │
  │            │                                                      │
  │            ▼                                                      │
  │     Slack / Teams / email                       ← centralized     │
  └───────────────────────────────────────────────────────────────────┘
```

## Install

```bash
pip install measure-monitor          # pulls in measure-paid-media-mcp + measure-sdk
measure login                        # one-time Google sign-in (from the SDK)
```

## Configure

Describe what to watch in a JSON or TOML file — see [`examples/monitors.toml`](examples/monitors.toml):

```toml
[[monitors]]
name = "spend-anomaly"
metric = "spend"        # spend | revenue | conversions | clicks | impressions | roas | cpa | ctr
days = 7                # each period is a 7-day window
periods = 4             # 4 prior windows form the baseline
method = "z_score"      # z_score | mad | pct_change
sensitivity = 3.0       # stdevs (z_score/mad) or fraction (pct_change)

  [[monitors.channels]]
  type = "console"      # console | slack | teams | discord | email
```

## Run

```bash
measure-monitor run --config monitors.toml            # detect + deliver
measure-monitor run --config monitors.toml --dry-run  # detect only, no delivery
```

Output is a JSON report. **Exit code is `1` when any anomaly was found** (0 = clean,
2 = error), so a cron wrapper can react to it.

Email delivery reads SMTP from the environment: `MEASURE_SMTP_HOST`,
`MEASURE_SMTP_PORT`, `MEASURE_SMTP_USER`, `MEASURE_SMTP_PASSWORD`, `MEASURE_SMTP_FROM`.

## Schedule it

**System cron** — every hour:

```cron
0 * * * * cd /path/to/work && measure-monitor run --config monitors.toml >> monitor.log 2>&1
```

**Claude Code `/schedule`** — a cloud routine that runs the check and reacts to the
result in natural language (no config file needed; the agent has both MCPs
connected). Example prompt to schedule:

> *Every hour: use paid-media `get_metric_observations` for spend and roas across
> all platforms; for any anomaly, deliver a summary with the alerts engine.*

Both modes respect the ecosystem rule: products never import each other — only
this orchestrator depends on more than one.

## How it fits the ecosystem

- **Source of truth for detection:** `measure_sdk.detect_anomaly` — the same brain
  every product uses, so results are comparable across platforms.
- **Extensible:** as GA4 / SEO products expose `get_metric_observations`, point a
  monitor at them; the runner is source-agnostic (it depends only on the
  `Observation` contract).
