# Radar Brief

> It does the analysis before your daily or weekly review, so the few things that
> need a decision are ready when you are. A **rule, not the AI**, decides what makes
> the brief.

Radar Brief runs on a schedule, checks the things you care about (business metrics,
service health, an inbox) against rules you set, and hands you a short brief:
**"all clear,"** or **"2 of 6 things crossed a line, here's what and why."** It's
management-by-exception, automated. The noise stays quiet, and the decisions come to you.
You point each watcher at your own data with one config file (a CSV or an HTTP endpoint);
there are no integrations to wire up (first-class connectors are on the roadmap).

The catch with always-on AI is trust. Will it cry wolf, or miss the fire? Radar Brief
answers that by design: **a deterministic rule decides what surfaces; the AI only
proposes what to do; you approve; the log learns.** Same inputs, same brief, every
time, and every finding shows the number that tripped it.

## Who it's for

Built for **early-stage B2B SaaS founders and operators without a dedicated data or
ops team** — the people who tend to learn about the problems that matter (creeping
churn, failed-payment bleed, a degraded service, an enterprise deal going cold) about
a week too late. Radar Brief gives you a daily or weekly brief of **only the few
things that need a decision**, each with the number that tripped it and a suggested
next step. Unlike a dashboard you have to remember to open, or alerting tools that cry
wolf, **a rule (not the AI) decides what surfaces, you approve each suggestion, and it
learns your playbook.**

## See it first (no install)

Live demo, nothing to set up: **https://vnieto.com/skills/radar-brief** — run the
check, switch between a SaaS startup and a coffee-shop chain, edit a rule and watch
the verdict recompute.

## Get started (4 steps)

**Prerequisites:** Python 3.10+ . That's it — the engine needs no API keys and no
other services.

**1. Clone and install** (only `pyyaml` + `pytest`):

```bash
git clone https://github.com/viviana-nieto/radar-brief.git
cd radar-brief
python3 -m pip install -r requirements.txt
```

**2. Run it** — prints today's brief from bundled sample data, with zero keys:

```bash
python3 -m core.brief
```

```
ATTENTION: 9 of 21 signals need your attention.
 !! #1 [Reliability] auth-api is degraded (expected ok)
 !! #2 [Retention] Churn rate crossed its 5.0% ceiling
 !     [Payments]   Failed-payment recovery fell below 40.0%
 !     [Revenue]    Net revenue retention fell below 100.0%
 ...
engine flagged 9 of 21 signals; the AI only wrote the narration.
```

**3. Point it at your own data** — copy the example config and edit it (no code):

```bash
cp config.example.yaml config.yaml
```

Set any watcher's `source` to your data and write your rules:

```yaml
radar:
  watchers:
    - name: metrics
      type: metrics
      source: { kind: csv, path: metrics.csv }   # columns: name,value,history,label,unit
      rules:
        - { name: Churn ceiling, entity: churn, signal: value, op: above, threshold: 0.05, severity: critical, area: Retention }
```

Sources: `sample`, `csv` (a local file), or `http` (a JSON array of rows). Operators:
`above`, `below`, `pct_change_above/below`, `breaches_floor/ceiling`, `equals`,
`not_equals`, `latency_above`, `count_above`. Run `python3 -m core.brief` again — it
now reads `config.yaml`.

**4. Make it a teammate** — get suggested next steps, then put it on a schedule:

```bash
python3 -m orchestration.advise            # the brief + 2-3 next steps per flag
```

Then copy a runner from [`adapters/schedulers/`](adapters/schedulers/) — `launchd`
(macOS), `cron` (Linux), GitHub Actions, or Cloudflare Cron — and read
[`reliability.md`](adapters/schedulers/reliability.md) first.

> **How it runs:** scheduled checks, not a live stream. Each run pulls the current
> values, applies your rules, and delivers the brief, so it catches things within one
> cadence. Running `python3 -m core.brief` once is a single check — the scheduler is
> what makes it recurring and unattended (and you have to install it; nothing is
> registered for you). Pick your cadence: daily/weekly for a review, or an interval
> (e.g. `*/15 * * * *`) for something closer to continuous.

## Install (pick how you'll use it)

**As a Claude Code skill** — copy the adapter into your commands and call it:

```bash
cp adapters/claude-code/skill.md ~/.claude/commands/radar-brief.md
# then, in Claude Code:  /radar-brief
```

**As a CLI on any LLM (or none):**

```bash
python3 -m core.brief                         # no LLM at all
export LLM_PROVIDER=ollama                     # free + local; or anthropic / openai (your key)
python3 -m orchestration.ask "what needs me today?"
```

**As an MCP server** (drops into Claude Desktop / Cursor):

```bash
python3 -m pip install mcp
python3 adapters/mcp/server.py
```

Then add it to your client (see [`adapters/mcp/README.md`](adapters/mcp/README.md)):

```json
{
  "mcpServers": {
    "radar-brief": {
      "command": "python3",
      "args": ["/absolute/path/to/radar-brief/adapters/mcp/server.py"]
    }
  }
}
```

## The 4 pillars

- **Trust** — every finding shows its evidence (the value, the rule, the threshold).
  No black-box alerts.
- **Governance** — a deterministic engine decides what crosses a line; the LLM only
  narrates, routes, or drafts suggestions. It runs with **no LLM at all**.
- **Access** — ask in plain language (`python3 -m orchestration.ask "…"`) **and** an
  MCP server for the tools you already use.
- **Adaptability** — point it at *your* data and rules via `config.yaml` — no code.

## It brings the fix, not just the problem (human-in-the-loop)

Every flag comes with 2-3 **suggested next steps**, each labelled by where it came from:

- **learned** — what you did last time this flag tripped (from your `decisions.json`)
- **draft, review** — an AI-drafted or playbook suggestion to check before you rely on it
- an honest **"not enough information to advise"** note when there's nothing solid to say

You accept, reject, or edit each one, and that feedback folds back into the log so the
next brief reflects *your* playbook:

```bash
python3 -m orchestration.advise feedback "Churn ceiling" accepted "Call the top churned accounts"
```

**The engine decides what's flagged, the AI only proposes, you approve, the log learns.**
AI drafting uses your own `LLM_PROVIDER`; with none set, it falls back to your learned
actions plus the config playbook.

## Bring your own credentials

This skill ships with **zero credentials.** The engine and the brief need no keys.
Optional AI uses *your* provider (`LLM_PROVIDER` = `ollama` free-local / `anthropic` /
`openai`); Slack delivery reads your own `SLACK_WEBHOOK_URL`. Nothing is bundled.

## How it works (three layers)

- `core/` — pure Python, **zero LLM**: watchers (Watch), the rules engine (Decide),
  the brief assembler, and the decision log. Deterministic and fully tested.
- `orchestration/` — a portable, any-LLM runner (`LLM_PROVIDER` = anthropic / openai /
  ollama / mock); the AI *narrates, routes, and drafts* — it never decides.
- `adapters/` — the Claude Code skill, an MCP server, delivery channels, and scheduler
  configs.

## Develop

```bash
python3 -m pip install -r requirements.txt
python3 -m pytest          # offline, no keys (uses the mock provider)
```

MIT License. Copyright (c) 2026 Viviana Nieto. Sample data is illustrative, not real.