Metadata-Version: 2.4
Name: flovo
Version: 0.1.0
Summary: FLoVo: Flatland-Loop-Void risk framework for financial networks (H^k Risk Stratification)
Project-URL: Homepage, https://github.com/roguetrainer/flovo
Project-URL: Documentation, https://roguetrainer.github.io/flovo
Project-URL: Repository, https://github.com/roguetrainer/flovo
Project-URL: Paper 426 (Beyond Basel), https://doi.org/10.5281/zenodo.20701683
Project-URL: Paper 429 (Fund Manager), https://doi.org/10.5281/zenodo.20702221
Author-email: "Ian R. C. Buckley" <ian.r.c.buckley@gmail.com>
License: MIT
Keywords: ALM,Betti numbers,FLoVo,Flatland,H^k risk stratification,Loop risk,Void risk,XVA,financial networks,macroprudential,portfolio risk,sheaf cohomology,systemic risk,topology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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 :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: compute
Requires-Dist: thermion>=0.1; extra == 'compute'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: finance
Requires-Dist: econiac>=0.1; extra == 'finance'
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == 'torch'
Description-Content-Type: text/markdown

# FLoVo: Flatland-Loop-Void Risk Framework

**H^k Risk Stratification for Financial Networks**

FLoVo is a Python framework for measuring three strata of financial risk that existing regulatory frameworks (Basel III, VaR, mean-variance optimisation) cannot simultaneously address.

## The Three Strata

### Flatland (H⁰): Solvency Risk
**Question:** Can the institution pay its debts?

**Measured by:** NAV, funding ratio, CET1 capital ratio  
**Existing instruments:** Basel III capital requirements  
**Status:** Adequately regulated

### Loop (H¹): Liquidity/Topology Risk
**Question:** Can it unwind without cascading?

**Measured by:** β₁ (number of independent funding loops), ρ = β₁/m (load factor), β*(ρ) (critical threshold)  
**Critical threshold:** ρ* ≈ 0.931  
**Existing instruments:** LCR, NSFR, LDI  
**Status:** Partially addressed — miss network-level loops

### Void (H²): Systemic Topology Risk
**Question:** Can the network resolve itself?

**Measured by:** β₂ (irresolvable conflict cycle count), ΔΔβ₂(i) (marginal contribution per institution)  
**Existing instruments:** G-SIB buffer (proxy only)  
**Status:** NOT regulated — missing from all frameworks

## Historical Void Events

All appeared safe on Flatland and Loop metrics until catastrophic failure:

- **LTCM (1998):** Spread trade topology irresolvable; Fed consortium required
- **Lehman/2008:** Repo collateral chain conflicts; bilateral resolution impossible
- **UK LDI Crisis (2022):** Correlated pension fund gilt margin calls; Bank of England intervention required

## Quick Start

```python
from flovo import FLoVoProfile
import networkx as nx

# Create or load an exposure graph (nodes=institutions, edges=exposures)
graph = nx.Graph()
# ... add nodes and edges ...

# Compute FLoVo profile
profile = FLoVoProfile.from_graph(graph, nav=1000.0, liabilities=500.0)

# Access risk metrics
print(profile.flatland())          # Solvency
print(profile.loop())              # Loop risk + regime
print(profile.void())              # Void risk (requires econiac integration)

# Risk summary
print(profile.risk_summary())
```

## Installation

```bash
pip install flovo
```

### With Full Features (including Void risk)

```bash
pip install flovo[finance]  # econiac.forge integration for β₂ computation
```

## API Reference

### FLoVoProfile

Main entry point for risk assessment.

- `from_graph(graph, nav, liabilities)`: Create profile from exposure graph
- `flatland`: Solvency metrics (H⁰)
- `loop`: Loop risk metrics (H¹)
- `void`: Void risk metrics (H²) — requires econiac
- `risk_summary()`: One-line risk assessment

### Loop Metrics

- `beta_1(graph)`: Compute β₁ (independent funding loops)
- `load_factor(beta_1, num_edges)`: Compute ρ = β₁/m
- `beta_star(rho)`: Compute β*(ρ) = (3/8)ln(1/(1-ρ))
- Risk regimes: SAT (<30%), MUSHY (30-70%), UNSAT (70-95%), CRITICAL (>95%)

### Void Metrics (Requires econiac.forge)

- `beta_2(B2_matrix)`: Compute β₂ from conflict matrix
- `delta_beta_2(institution, B2)`: Compute ΔΔβ₂(i) — marginal systemic contribution

## References

- **Paper 426** (Beyond Basel): doi:10.5281/zenodo.20701683
  - Regulatory framework for systemic topology risk

- **Paper 429** (The Cohomological Fund Manager): doi:10.5281/zenodo.20702221
  - FLoVo application to asset allocation, ALM, and portfolio management

- **Paper 430** (The Topology of Intermediation): doi:10.5281/zenodo.20702223
  - FLoVo application to broker-dealers and prime brokerage

- **Paper 431** (CCPs Reconsidered): doi:10.5281/zenodo.20702225
  - FLoVo application to central counterparties and default waterfalls

## License

MIT License

## Author

Ian R. C. Buckley (ian.r.c.buckley@gmail.com)
