Metadata-Version: 2.4
Name: mrv-lib
Version: 0.0.2
Summary: Market Regime Validity Library for Model Risk Governance
Author-email: Kai Zheng <kaizhengnz@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://mrv-lib.org
Project-URL: Bug Tracker, https://github.com/modelguard-lab/mrv-lib/issues
Project-URL: Repository, https://github.com/modelguard-lab/mrv-lib
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-learn
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# mrv-lib: Market Regime Validity Library

**The Gold Standard for Model Risk Diagnostics in Non-Stationary Markets.**

mrv-lib is an open-source Python library designed to quantify and diagnose the stability of market regime identification models. Built upon the theoretical framework of **Inference Collapse** and **Ordinal Robustness**, it provides financial institutions with a rigorous toolset to meet Basel IV and SR 11-7 model risk governance requirements.

## Why mrv-lib?

Traditional market regime models often suffer from **"Stability Illusions."** A model may appear robust at daily resolutions but fail to capture structural shifts during high-frequency intraday stress events. mrv-lib exposes these vulnerabilities by measuring:

- **Representation Sensitivity:** How sensitive are your regime labels to feature engineering and preprocessing?
- **Resolution Dissonance:** Does your model's daily output contradict its high-frequency signals?
- **Identifiability Boundaries:** Is the market currently in a "Zone of Collapse" where absolute labels are mathematically unreliable?

## Key Features

### 1. Sensitivity Diagnostic (RSS)

Automated stress-testing of regime labels across multiple feature sets (Representation) and temporal scales (Resolution). It calculates the **RSS (Representation Stability Score)** to quantify model robustness.

### 2. Identifiability Index

Calculates the **Identifiability Index** (\\(\mathcal{I}\\)) based on structural drift and regime separation. It identifies the "Phase Boundaries" where model inference begins to collapse.

### 3. Ordinal Robustness

When absolute labels (ARI) collapse, mrv-lib measures **Ordinal Consistency** (Spearman's Rho) to determine if the risk ranking remains valid for fail-safe hedging.

## Installation

```bash
pip install mrv-lib
```

## Quick Start

```python
import mrv_lib as mrv
import pandas as pd

# Load your market data (OHLCV)
data = pd.read_csv("market_data.csv")

# Initialize the diagnostic scanner
scanner = mrv.Scanner(resolution=['5m', '1h', '1d'])

# Run representation stability test
results = scanner.run_representation_test(data, model="HMM")

# Get the RSS (Representation Stability Score)
print(f"Model RSS: {results.rss_score}")

# Detect Identifiability Boundaries
boundary = mrv.detect_boundary(data)
if boundary.is_collapsed:
    print(f"Warning: Entering Inference Collapse Zone. Identifiability Index: {boundary.index}")
```

## Command-Line Interface

After installation, you can run diagnostics from the shell:

```bash
mrv-lib market_data.csv --resolution 5m 1h 1d --model HMM
```

## Project Layout

```
mrv-lib/
├── src/
│   └── mrv_lib/
│       ├── __init__.py
│       └── core.py
├── tests/
├── README.md
├── LICENSE
└── pyproject.toml
```

## Theoretical Foundation

The methodology of mrv-lib is documented in a series of peer-reviewed research papers:

- **Regime Labels Are Not Representation-Invariant:** Evidence of instability across feature sets.
- **Regime Labels Are Not Resolution-Invariant:** Documentation of the 14-hour lag in daily risk reporting.
- **Inference Collapse and Ordinal Robustness:** Defining the phase boundaries of market state identification.

For academic citations, please refer to the [documentation](https://github.com/modelguard-lab/mrv-lib#readme).

## Commercial Support & SaaS

For enterprise-grade features including real-time alerting, Basel IV Compliance Reporting, and the Fail-Safe Actuator engine, please visit [ModelGuard.co.nz](https://modelguard.co.nz).

- **ModelGuard Sentinel:** Real-time monitoring for institutional trading desks.
- **ModelGuard Advisory:** Professional consulting for RBNZ/APRA regulatory alignment.

## Maintainers

Maintained by **ModelGuard Lab**. Lead Architect: **Kai Zheng**.

## License

mrv-lib is released under the **MIT License**. See [LICENSE](LICENSE) for details.
