Hardstop is a deterministic supply-chain risk engine. It monitors public alert sources (NWS, FDA, USCG, RSS feeds), links events to your operational network, and generates actionable risk briefs — all local, all auditable.
Supply chain teams drown in alerts from dozens of sources. Hardstop filters the noise, scores impact against your actual facilities, lanes, and shipments, and produces daily briefs with clear classification: Interesting, Relevant, or Impactful. Same input always produces the same output.
python -m venv .venv && source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
pip install --require-hashes -r requirements.lock.txt
pip install --no-deps -e .
hardstop init # copy example configs
hardstop doctor # verify environment
hardstop ingest # load network data (facilities, lanes, shipments)
hardstop run --since 24h # fetch + process events
hardstop brief --today --since 24h- Fetch — adapters pull from RSS/Atom, NWS Alerts API, FDA, USCG
- Filter — configurable suppression rules drop noise (keyword, regex, exact match)
- Link — events matched to your facilities, lanes, and shipments
- Score — deterministic impact scoring with trust-tier weighting and quality validation
- Brief — tier-aware daily summaries in markdown or JSON
| Command | What it does |
|---|---|
hardstop run --since 24h |
Fetch + ingest pipeline |
hardstop brief --today |
Generate daily brief |
hardstop doctor |
Health check (PATH, DB, configs, sources) |
hardstop sources health |
Source status table with failure budgets |
hardstop sources test <id> |
Test a single source |
hardstop export alerts --format csv |
Export alert data |
hardstop demo --mode pinned |
Deterministic demo run for verification |
Exit codes: 0 = healthy, 1 = warning, 2 = broken. Use --strict to fail on warnings.
config/sources.yaml— external alert sources and tier settingsconfig/suppression.yaml— noise filtering ruleshardstop.config.yaml— quality thresholds and runtime settings
See docs/CONFIGURATION.md for the full reference.
- Local-first: SQLite storage, no cloud dependencies
- Deterministic: strict mode guarantees identical inputs produce identical outputs
- Self-evaluating: exit codes and health checks surface problems, no silent failures
- Auditable: run records, config fingerprints, and artifact hashes for every execution
See docs/ARCHITECTURE.md for the runtime specification.
src/hardstop/
├── retrieval/ # Source adapters and fetching
├── suppression/ # Noise filtering engine
├── parsing/ # Event normalization and entity extraction
├── alerts/ # Alert generation, correlation, and impact scoring
├── database/ # SQLite storage, schema, and migrations
├── output/ # Brief generation and incident evidence
├── api/ # Query surface for alerts, briefs, and sources
├── ops/ # Run records, status evaluation, artifacts
├── runners/ # Executable workflows (demo, ingest, network load)
├── config/ # Configuration loading and defaults
└── cli.py # CLI entrypoint
- Python 3.10+
- SQLite (bundled with Python)
pytest30 test files covering determinism regression, adapter parsing, alert quality validation, source health, suppression, and end-to-end pipeline verification.
- Architecture — runtime spec, operator taxonomy, determinism contract
- Configuration — sources, suppression, quality thresholds
- CSV Contract — network data format for facilities, lanes, shipments
- Integrations — Slack, CI/CD, and agent integration patterns
- Specs — run-record schema, canonicalization, export format
Hardstop Business License (SBL-1.0) — free for evaluation and personal use. Production use requires a commercial agreement with WhatsYourWhy, Inc. Dual-licenses to Apache 2.0 on January 1, 2029. See docs/LICENSING.md for details.
See CHANGELOG.md for version history.
