Metadata-Version: 2.4
Name: pyblastradius
Version: 0.2.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Dist: click>=8.0
Requires-Dist: click>=8.0 ; extra == 'all'
Requires-Dist: rich>=12.0 ; extra == 'all'
Requires-Dist: fastapi>=0.100.0 ; extra == 'all'
Requires-Dist: uvicorn>=0.23.0 ; extra == 'all'
Requires-Dist: pyyaml>=6.0 ; extra == 'all'
Requires-Dist: click>=8.0 ; extra == 'cli'
Requires-Dist: rich>=12.0 ; extra == 'cli'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: black>=23.0 ; extra == 'dev'
Requires-Dist: isort>=5.0 ; extra == 'dev'
Requires-Dist: flake8>=6.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: sphinx>=6.0 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.0 ; extra == 'docs'
Requires-Dist: fastapi>=0.100.0 ; extra == 'server'
Requires-Dist: uvicorn>=0.23.0 ; extra == 'server'
Provides-Extra: all
Provides-Extra: cli
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: server
License-File: LICENSE
Summary: Operational Blast Radius Intelligence Platform - Predict cascading failures and quantify business impact
Keywords: observability,incident-response,dependency-graph,blast-radius,sre,reliability,cascade-prediction,data-quality
Home-Page: https://github.com/Mullassery/PyBlastRadius
Author-email: Georgi Mammen Mullassery <mullassery@gmail.com>
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/Mullassery/PyBlastRadius/blob/main/docs/QUICK_START.md
Project-URL: Homepage, https://github.com/Mullassery/PyBlastRadius
Project-URL: Issues, https://github.com/Mullassery/PyBlastRadius/issues
Project-URL: Repository, https://github.com/Mullassery/PyBlastRadius

# PyBlastRadius

![PyPI](https://img.shields.io/pypi/v/pyblastradius)
[![CI](https://github.com/Mullassery/PyBlastRadius/actions/workflows/ci.yml/badge.svg)](https://github.com/Mullassery/PyBlastRadius/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/license-Proprietary-blue)
![Python](https://img.shields.io/badge/python-3.10+-blue)
![Rust](https://img.shields.io/badge/rust-1.70+-orange)

**Operational Blast Radius Intelligence Platform** — Predict cascading failures and quantify business impact across infrastructure, data pipelines, and AI systems.

## Features

Working today, backed by the real Rust engine (`pyblastradius._core`):

- **Blast Radius Analysis** — BFS-based impact categorization (direct, indirect, tertiary), via `BlastRadiusAnalyzer`
- **Criticality Scoring** — Risk-weighted ranking using downstream dependencies, recovery time, business exposure, via `CriticalityScorer`
- **Cascade Simulation** — Simulate outage/degradation/high-latency/high-error-rate/data-quality failures and estimate recovery time and business impact, via `Simulator`
- **Graph import/export** — JSON round-trip and Graphviz DOT export
- **REST API server** — FastAPI server with real bearer-token auth and an explicit CORS allowlist (`pyblastradius server`)
- **CLI** — `analyze`, `criticality`, `simulate`, `visualize` commands operate on a graph you build or load from JSON

Not yet implemented (present as scaffolding/placeholders, listed here so you don't spend time debugging them):

- **Dependency discovery** — `KubernetesDiscoverer`, `TerraformDiscoverer`, `AirflowDiscoverer`, `OtelDiscoverer` (used by `pyblastradius scan`) currently always return an empty graph. There is no YAML/HCL parsing or live cluster/API connection behind them yet.
- **Hidden Dependency Detection / Anomaly Detection** — `HiddenDependencyDetector` and `AnomalyDetector` always return empty results; they are not wired to any metrics/trace source.
- **`pyblastradius.integrations`** — `OtelCollectorClient` and `StatGuardianClient` are placeholders that return empty/fake data; `DbtManifestParser` genuinely parses a dbt `manifest.json` you already have on disk and is real.
- **GraphQL API** — not exposed anywhere; the Rust crate has a query-string builder (`src/api/graphql.rs`) that nothing serves or executes.
- **Slack/PagerDuty integrations** — the Rust structs (`src/api/integrations.rs`) build correct payloads but never send them (the HTTP calls are commented out), and are not exposed to Python at all yet.

## Quick Start

### Installation

```bash
# Basic installation
pip install pyblastradius

# With all dependencies
pip install pyblastradius[all]

# For CLI features only
pip install pyblastradius[cli]

# For REST API server
pip install pyblastradius[server]
```

### CLI Usage

`scan` is wired up end-to-end but its discoverers are not implemented yet
(see Features above) — it will run without error and produce an empty
graph. To analyze something real today, build a graph via the Python API
below (or hand-write one and export it with `graph.to_json()`) and feed
that JSON file into `analyze`/`criticality`/`simulate`.

```bash
# Not yet functional - always produces an empty graph (see Features)
pyblastradius scan \
  kubernetes://kubeconfig=~/.kube/config \
  terraform://path=./infrastructure

# Analyze blast radius for a service (graph.json from Graph.to_json())
pyblastradius analyze graph.json --service payment-service

# Rank systems by criticality
pyblastradius criticality graph.json --limit 10

# Simulate failure cascade
pyblastradius simulate graph.json --target postgres

# Generate visualization
pyblastradius visualize graph.json --output blast-radius.html

# Start REST API server
pyblastradius server --host 0.0.0.0 --port 8080
```

### Configuration File

Create `blastradius.yml` in your project:

```yaml
version: 1

discovery:
  sources:
    - type: kubernetes
      kubeconfig: ~/.kube/config
    - type: terraform
      path: ./infrastructure

analysis:
  max-depth: 5

outputs:
  - type: json
    path: blast-radius.json
  - type: html
    path: blast-radius.html
```

Then run:
```bash
pyblastradius analyze
```

### Python API

This example is real and runnable end-to-end against the Rust engine —
build a small graph by hand, then run blast-radius, criticality, and
cascade-simulation analysis on it:

```python
from pyblastradius import (
    Graph, Node, Edge, NodeType, EdgeType, FailureType,
    BlastRadiusAnalyzer, CriticalityScorer, Simulator,
)

graph = Graph()
api = graph.add_node(Node("api-server", NodeType.Service))
auth = graph.add_node(Node("auth-service", NodeType.Service))
db = graph.add_node(Node("postgresql", NodeType.Database))

graph.add_edge(Edge(EdgeType.Calls, api, auth))
graph.add_edge(Edge(EdgeType.Calls, auth, db))

# Blast radius: what does api-server's own call graph reach?
result = BlastRadiusAnalyzer.analyze(graph, api)
print(f"Blast radius score: {result.blast_radius_score:.2f}")
print(f"Directly impacted: {len(result.directly_impacted)} services")
print(f"Indirectly impacted: {len(result.indirectly_impacted)} services")

# Criticality ranking across the whole graph
for score in CriticalityScorer.score_all(graph):
    print(score.node_name, score.criticality_score, score.is_single_point_of_failure)

# Simulate a database outage
sim = Simulator.simulate(graph, db, FailureType.Outage)
print(f"Estimated recovery: {sim.estimated_recovery_time_minutes} min, "
      f"business impact: {sim.business_impact_score:.1f}")

# Persist/reload as JSON (this is what the CLI's `analyze`/`criticality`/
# `simulate` commands read via `Graph.from_json(...)`)
with open("graph.json", "w") as f:
    f.write(graph.to_json())
```

## Architecture

PyBlastRadius orchestrates an open-source observability ecosystem:

```
┌─────────────────────────────────────────────────┐
│         PyBlastRadius Orchestration Layer        │
├─────────────────────────────────────────────────┤
│                                                   │
│  OpenTelemetry (Traces)  → Runtime Dependencies  │
│  dbt (Manifest)         → Column Lineage         │
│  StatGuardian (Quality) → Data Quality Cascade   │
│                                                   │
│  Discovery Engines:                              │
│  • Kubernetes manifests  • Terraform HCL         │
│  • Airflow DAGs         • OTLP traces            │
│                                                   │
│  Analysis Engines:                               │
│  • Blast radius (BFS)   • Criticality scoring    │
│  • Anomaly detection    • Hidden dependencies    │
│  • Cascade prediction   • Time-to-failure        │
│                                                   │
└─────────────────────────────────────────────────┘
```

This is the intended end-state architecture. As of this release, the
**Analysis Engines** box (blast radius, criticality, cascade simulation)
is real and Rust-backed; the **Discovery Engines** and OpenTelemetry/dbt/
StatGuardian integration boxes are scaffolding that returns empty/fake
data today (see Features above for the exact status of each piece).

## Documentation

- **[Quick Start](docs/QUICK_START.md)** — 5-minute tutorial with examples
- **[Architecture](docs/ARCHITECTURE.md)** — System design, algorithms, performance
- **[Contributing](CONTRIBUTING.md)** — Development setup and guidelines

## Why PyBlastRadius?

### Problem
- SRE teams spend **4-24 hours** on MTTR manually tracing dependencies
- Existing tools answer "What broke?" but not "What will break next?"
- Business impact is guesswork, not data-driven
- Data quality issues cascade invisibly through pipelines

### Solution
PyBlastRadius provides:
- **Unified graph** across infrastructure, data, and applications
- **Column-level lineage** (raw data → dashboards → business metrics)
- **Cascade prediction** with quantified business impact
- **Anomaly detection** with time-to-failure estimates
- **Open-source first** — works with any observability backend

### Value (aspirational — not yet measured on real deployments)
- **50%+ MTTR reduction** through automated dependency discovery, once discovery is implemented
- **$705K+ per prevented incident** (illustrative, based on $15K/min downtime)
- **99% cost savings** vs proprietary tools (OTel vs Datadog)
- **Zero vendor lock-in** with open-source stack

These are the goals the project is designed around, not measured results —
there are no discovery engines wired up yet to generate the "automated
dependency discovery" this depends on. Treat this section as intent, not a
claim about the current release.

## Platform Support

Discovery source integration status (i.e. what `pyblastradius scan` /
`KubernetesDiscoverer` etc. actually do today):

| Discovery Source | Status | Notes |
|-----------------|--------|----------|
| Kubernetes | 🚧 Not implemented | `discover()` always returns an empty graph; no manifest parsing or API calls |
| Terraform | 🚧 Not implemented | `discover()` always returns an empty graph; no HCL parsing |
| Airflow | 🚧 Not implemented | `discover()` always returns an empty graph |
| OpenTelemetry | 🚧 Not implemented | `discover()` always returns an empty graph (there is a separate, real Rust OTLP client used by `examples/cli.rs`, but it is not exposed to the Python package) |
| dbt | ✅ Partial | `DbtManifestParser` genuinely parses a local `manifest.json` for column lineage |
| StatGuardian | 🚧 Not implemented | `StatGuardianClient` returns empty/hardcoded fake data |

What **is** real and working: build a `Graph` directly via the Python API
(`Graph`, `Node`, `Edge`) or load one from JSON, then run
`BlastRadiusAnalyzer`, `CriticalityScorer`, and `Simulator` on it — that
whole path is backed by real, tested Rust code. See the Python API example
above.

## API Examples

### GraphQL

Not implemented. The Rust crate contains a query-string builder
(`src/api/graphql.rs`) for the intended future schema, but nothing serves
or executes GraphQL queries today — there is no GraphQL endpoint to call.

### Python SDK

```python
from pyblastradius.integrations import DbtManifestParser

# Parse dbt lineage (the one integration in this module that's real)
dbt = DbtManifestParser("./dbt/manifest.json")
lineage = dbt.extract_column_lineage()
```

`OtelCollectorClient` and `StatGuardianClient` also live in
`pyblastradius.integrations` but are placeholders — `discover_dependencies()`
always returns an empty graph and `get_quality_rules()`/
`track_quality_incident()` return empty/hardcoded data, not real results
from a live collector or StatGuardian instance.

## Integrations

**Not usable from Python today.** The Rust crate has `SlackIntegration` and
`PagerDutyIntegration` structs (`src/api/integrations.rs`) that build
correct Slack/PagerDuty payloads, but:

- neither is exposed to the Python package — `from pyblastradius.api import
  SlackIntegration` raises `ModuleNotFoundError`, there is no
  `pyblastradius.api` module
- even on the Rust side, the actual HTTP calls are commented out; every
  method returns `Ok(())` (or a hardcoded fake incident id) without sending
  anything

This is tracked as a known gap, not a working feature. If you need
Slack/PagerDuty alerting today, call their APIs directly with the analysis
results from `BlastRadiusAnalyzer`/`Simulator`.

## Performance

No benchmarks have been run against this release. Numbers below are
targets, not measurements — treat them as design goals, not verified
performance. `cargo bench` benchmark scaffolding exists in the crate but
results aren't published here yet.

| Operation | Target |
|-----------|--------|
| Dependency discovery (1000 nodes) | <2 min |
| Blast radius analysis | <100ms |
| Criticality scoring (all nodes) | <500ms |
| Graph visualization export | <1s |
| End-to-end scan → analyze → alert | <5 min |

## Project Status

| Phase | Release | Status | Delivered |
|-------|---------|--------|-----------|
| Phase 0 | Research & Planning | ✅ Complete | Architecture, personas, roadmap |
| Phase 1 | Foundation (Graph + Analysis) | ✅ Complete | Core graph engine, algorithms |
| Phase 2 | CLI Implementation | ✅ Complete | Full CLI with all commands |
| Phase 3 | Config & YAML | ✅ Complete | blastradius.yml support |
| Phase 4 | CI/CD Integration | ✅ Complete | GitHub Actions workflow |
| Phase 5 | Examples & Documentation | ✅ Complete | Working examples, configs |
| Phase 6 | REST API Server | ✅ Complete | FastAPI endpoints + OpenAPI, real API-key auth, explicit CORS allowlist |
| v0.2.0 | Working Rust↔Python bindings | ✅ Shipped | `pyblastradius._core` extension module, real end-to-end analysis, first-ever working `import pyblastradius`; discovery engines still not implemented (see Platform Support) |
| v1.0.0 | Enterprise Edition | 📋 Planned | Q1 2027 |

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup
- Code style guidelines
- Testing requirements
- Commit message format
- Pull request process

## Code of Conduct

This project adheres to the Contributor Covenant. By participating, you are expected to uphold this code. Please report unacceptable behavior.

## License

This project is licensed under a Proprietary License. See [LICENSE](LICENSE) for details.

**Attribution Required**: Any use of this software must include attribution: "Powered by PyBlastRadius (https://github.com/Mullassery/PyBlastRadius)"

## Getting Help

- **Documentation**: [docs/](docs/)
- **Quick Start**: [docs/QUICK_START.md](docs/QUICK_START.md)
- **Architecture**: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- **Issues**: [GitHub Issues](https://github.com/Mullassery/PyBlastRadius/issues)
- **Email**: mullassery@gmail.com

## Citation

If you use PyBlastRadius in your research or production systems, please cite:

```bibtex
@software{pyblastradius2026,
  title={PyBlastRadius: Operational Blast Radius Intelligence Platform},
  author={Mullassery, Georgi},
  year={2026},
  url={https://github.com/Mullassery/PyBlastRadius}
}
```

## Roadmap

### Near-term (Q4 2026)
- [ ] v0.1 public MVP release
- [ ] Beta customer feedback program
- [ ] Kubernetes Operator for continuous discovery
- [ ] Helm chart for self-hosted deployment

### Medium-term (Q1 2027)
- [ ] v1.0 enterprise release
- [ ] ML-based failure prediction
- [ ] Neo4j backend for 100K+ node graphs
- [ ] GraphQL Federation for multi-service deployments

### Long-term (2027+)
- [ ] Multi-region cascade analysis
- [ ] Autonomous remediation recommendations
- [ ] Industry-specific impact templates
- [ ] GDPR/data-residency support

## Related Projects

Part of the Mullassery observability and data quality ecosystem:

- **[StatGuardian](https://github.com/Mullassery/StatGuardian)** — Data quality monitoring and lineage
- **[PyStreamMCP](https://github.com/Mullassery/PyStreamMCP)** — Streaming data intelligence
- **[PyDependencyCheck](https://github.com/Mullassery/PyDependencyCheck)** — Dependency scanning

## Authors

**Georgi Mammen Mullassery**
- GitHub: [@Mullassery](https://github.com/Mullassery)
- Email: mullassery@gmail.com

## Acknowledgments

Built on proven open-source foundations:
- [petgraph](https://github.com/petgraph/petgraph) — Graph algorithms
- [serde](https://serde.rs/) — Serialization
- [tokio](https://tokio.rs/) — Async runtime
- [OpenTelemetry](https://opentelemetry.io/) — Distributed tracing
- [dbt](https://www.getdbt.com/) — Data lineage standard

---

**Made with ⚡ by Georgi Mammen Mullassery**

[GitHub](https://github.com/Mullassery/PyBlastRadius) · [Documentation](docs/) · [Issues](https://github.com/Mullassery/PyBlastRadius/issues)

