Metadata-Version: 2.4
Name: alertsift
Version: 0.1.0
Summary: Turn an alert storm into the few incidents that actually matter — dedupe, correlate, rank, and (optionally) AI-explain alerts from any source, with Slack digests.
Author-email: Jay Tank <tankjai24@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jay-tank/alertsift
Project-URL: Repository, https://github.com/jay-tank/alertsift
Project-URL: Issues, https://github.com/jay-tank/alertsift/issues
Keywords: alerts,alertmanager,prometheus,sre,devops,on-call,incident,observability,ai,slack
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Provides-Extra: claude
Requires-Dist: anthropic>=0.40; extra == "claude"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# alertsift

> Turn an alert storm into the few incidents that actually matter — dedupe, correlate, rank, and (optionally) AI-explain alerts from **any** source, then push a clean digest to Slack.

[![CI](https://github.com/jay-tank/alertsift/actions/workflows/ci.yml/badge.svg)](https://github.com/jay-tank/alertsift/actions/workflows/ci.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

It's 2 a.m., you're on-call, and 214 alerts are firing. Your real question isn't
"what fired?" — it's **"what's actually broken, and where do I start?"** Studies show
40–60% of alerts never even get investigated because the signal drowns in noise.

`alertsift` does that triage for you, in one command:

```text
🔔 214 alert(s) → 3 incident(s)  (deduped to 60, suppressed 22)

  ● checkout-svc (critical, 47 alerts) ← start here
     types: HighLatency, High5xxRate, PodRestart
     checkout-svc is crash-looping and timing out payment calls.
     likely cause: a bad deploy or failing dependency in checkout-svc.

  ● node-7 (medium, 1 alerts)
     types: DiskUsage
```

**Source-agnostic by design.** It normalizes alerts from Prometheus/Alertmanager,
generic JSON, or plain logs into one shape, then dedupes, groups related alerts into
incidents, ranks them, and (optionally) has an LLM explain the likely root cause.
Adding a new platform (Datadog, CloudWatch, PagerDuty…) is just one new parser.

## Why alertsift

| | Raw alert channel | **alertsift** |
| :--- | :--- | :--- |
| Collapses duplicate alerts | ❌ | ✅ |
| Groups related alerts into incidents | ❌ | ✅ |
| Ranks "what to look at first" | ❌ | ✅ |
| Suppresses known noise | ❌ | ✅ `.alertsiftignore` |
| Plain-English likely cause | ❌ | ✅ (optional LLM) |
| Works with no API key | — | ✅ `--no-ai` / `mock` / local Ollama |
| Posts a clean digest to Slack | ❌ | ✅ |

## Install

```bash
git clone https://github.com/jay-tank/alertsift.git
cd alertsift
pip install .
# optional LLM providers:
pip install '.[claude]'   # or '.[openai]'
```

## Usage

```bash
# Triage a file (auto-detects Alertmanager / JSON / logs)
alertsift alerts.json

# From a pipe — e.g. Alertmanager, kubectl, a log tail
amtool alert -o json | alertsift --stdin

# Pure/offline — no LLM, no key (dedupe + correlate + rank only)
alertsift alerts.json --no-ai

# Post a digest to Slack (webhook from env; preview first with --dry-run)
export ALERTSIFT_SLACK_WEBHOOK="https://hooks.slack.com/services/..."
alertsift alerts.json --slack --dry-run     # preview the payload
alertsift alerts.json --slack               # actually post

# Machine-readable
alertsift alerts.json --json
```

**Exit codes:** `0` = nothing actionable, `1` = actionable incident(s) found, `2` =
usage/parse error — so it slots into cron or CI (only pages you when it matters).

## How it works

```
INPUT ──► parse (pluggable) ──► normalize ──► dedupe ──► suppress ──►
correlate ──► rank ──► [AI enrich] ──► render / --json / Slack
```

Steps up to `rank` are **pure and fully offline**; the LLM only writes the
plain-English explanation (and is skippable with `--no-ai`). See
[docs/USAGE.md](docs/USAGE.md) and [docs/PROVIDERS.md](docs/PROVIDERS.md).

## Safety

- **Secrets never leave your machine.** Alert summaries are run through best-effort
  redaction before being sent to an LLM **or** posted to Slack.
- **Read-only.** alertsift never mutates your systems; it reads alerts and reports.
- **Slack webhook comes from the environment** (`$ALERTSIFT_SLACK_WEBHOOK`), never a
  flag literal, never logged.

## Supported sources

Prometheus/Alertmanager, generic JSON, and plain logs today. The core is
source-agnostic — Datadog, CloudWatch, and PagerDuty are drop-in parsers on the
roadmap.

## Limitations

- Correlation in v1 is heuristic (groups by service/namespace) — solid and
  explainable, but not a full dependency-graph. Treat "likely cause" as an assist to
  your judgment, not gospel.
- Log parsing is best-effort.

## License

MIT — see [LICENSE](LICENSE).
