mrv-lib 0.0.1__tar.gz

mrv_lib-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modelguard-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mrv_lib-0.0.1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: mrv-lib
+Version: 0.0.1
+Summary: Market Regime Validity Library for Model Risk Governance
+Author-email: Kai Zheng <kaizhengnz@gmail.com>
+License: 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: License :: OSI Approved :: MIT License
+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.

mrv_lib-0.0.1/README.md

@@ -0,0 +1,104 @@
+# 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.

mrv_lib-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mrv-lib"
+version = "0.0.1"
+authors = [
+  { name = "Kai Zheng", email = "kaizhengnz@gmail.com" },
+]
+description = "Market Regime Validity Library for Model Risk Governance"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+  "numpy",
+  "pandas",
+  "scipy",
+  "scikit-learn",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "black", "ruff"]
+
+[project.urls]
+Homepage = "https://mrv-lib.org"
+"Bug Tracker" = "https://github.com/modelguard-lab/mrv-lib/issues"
+Repository = "https://github.com/modelguard-lab/mrv-lib"
+
+[project.scripts]
+mrv-lib = "mrv_lib.core:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

mrv_lib-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mrv_lib-0.0.1/src/mrv_lib/__init__.py

@@ -0,0 +1,25 @@
+"""
+mrv-lib: Market Regime Validity Library.
+
+Model risk diagnostics in non-stationary markets — Representation Stability,
+Identifiability Boundaries, and Ordinal Robustness.
+"""
+
+from mrv_lib.core import (
+    BoundaryResult,
+    RepresentationTestResult,
+    Scanner,
+    detect_boundary,
+    ordinal_consistency,
+    ari_score,
+)
+
+__all__ = [
+    "Scanner",
+    "RepresentationTestResult",
+    "detect_boundary",
+    "BoundaryResult",
+    "ordinal_consistency",
+    "ari_score",
+]
+__version__ = "0.0.1"

mrv_lib-0.0.1/src/mrv_lib/core.py

@@ -0,0 +1,353 @@
+"""
+mrv_lib.core — Sensitivity diagnostics, identifiability boundary, ordinal metrics, and CLI.
+
+- Scanner / RepresentationTestResult: representation and resolution stability (RSS).
+- detect_boundary / BoundaryResult: Identifiability Index and collapse zone.
+- ordinal_consistency / ari_score: ordinal robustness when ARI collapses.
+- main: command-line entry point (mrv-lib).
+"""
+
+import argparse
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+import numpy as np
+import pandas as pd
+
+
+# ---------------------------------------------------------------------------
+# Representation stability (RSS)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RepresentationTestResult:
+    """Result of run_representation_test; holds RSS and per-resolution scores."""
+
+    rss_score: float
+    resolution_scores: dict
+    representation_scores: Optional[dict] = None
+
+
+class Scanner:
+    """
+    Diagnostic scanner for regime label stability across resolutions and representations.
+    """
+
+    def __init__(
+        self,
+        resolution: Optional[List[str]] = None,
+        feature_sets: Optional[List[str]] = None,
+    ):
+        """
+        Parameters
+        ----------
+        resolution : list of str, optional
+            Temporal resolutions to test, e.g. ['5m', '1h', '1d'].
+        feature_sets : list of str, optional
+            Feature set names for representation sensitivity; defaults to standard OHLCV-derived sets.
+        """
+        self.resolution = resolution or ["1h", "1d"]
+        self.feature_sets = feature_sets or ["returns", "volatility", "volume"]
+
+    def run_representation_test(
+        self,
+        data: pd.DataFrame,
+        model: str = "HMM",
+        **kwargs,
+    ) -> RepresentationTestResult:
+        """
+        Run representation stability test across resolutions and feature sets.
+
+        Parameters
+        ----------
+        data : DataFrame
+            OHLCV market data (columns expected: open, high, low, close, volume or similar).
+        model : str
+            Regime model type, e.g. "HMM". Used for extensibility.
+        **kwargs
+            Passed to internal model fit (e.g. n_states for HMM).
+
+        Returns
+        -------
+        RepresentationTestResult
+            Contains rss_score and per-resolution / per-representation scores.
+        """
+        data = _ensure_ohlcv(data)
+        resolution_scores = {}
+        for res in self.resolution:
+            resolution_scores[res] = _score_at_resolution(data, res, model, **kwargs)
+        representation_scores = {}
+        for fs in self.feature_sets:
+            representation_scores[fs] = _score_representation(data, fs, model, **kwargs)
+
+        rss = _compute_rss(resolution_scores, representation_scores)
+        return RepresentationTestResult(
+            rss_score=rss,
+            resolution_scores=resolution_scores,
+            representation_scores=representation_scores,
+        )
+
+
+def _ensure_ohlcv(data: pd.DataFrame) -> pd.DataFrame:
+    """Normalize column names to lower-case open/high/low/close/volume if present."""
+    df = data.copy()
+    cols = {c.lower(): c for c in df.columns}
+    for name in ["open", "high", "low", "close", "volume"]:
+        if name in cols and df.columns[df.columns.get_loc(cols[name])] != name:
+            df = df.rename(columns={cols[name]: name})
+    if "close" not in df.columns and len(df.columns) >= 4:
+        df.columns = ["open", "high", "low", "close"] + list(df.columns[4:])
+    return df
+
+
+def _score_at_resolution(
+    data: pd.DataFrame,
+    resolution: str,
+    model: str,
+    **kwargs,
+) -> float:
+    """
+    Placeholder: score stability at a given temporal resolution.
+    In production, resample data to resolution and compare regime consistency.
+    """
+    close = data["close"] if "close" in data.columns else data.iloc[:, 3]
+    returns = close.pct_change().dropna()
+    if returns.empty or returns.std() == 0:
+        return 0.0
+    vol = returns.std()
+    vol_norm = min(vol * 10, 1.0)
+    return float(1.0 - vol_norm)
+
+
+def _score_representation(
+    data: pd.DataFrame,
+    feature_set: str,
+    model: str,
+    **kwargs,
+) -> float:
+    """
+    Placeholder: score stability across feature set (representation).
+    In production, fit regime model on different feature sets and compare labels.
+    """
+    return 0.75
+
+
+def _compute_rss(
+    resolution_scores: dict,
+    representation_scores: dict,
+) -> float:
+    """
+    Representation Stability Score: aggregate of resolution and representation stability.
+    RSS in [0, 1]; higher = more robust.
+    """
+    r_scores = list(resolution_scores.values()) if resolution_scores else [0.0]
+    rep_scores = list(representation_scores.values()) if representation_scores else [0.0]
+    all_scores = r_scores + rep_scores
+    return float(np.clip(np.mean(all_scores), 0.0, 1.0))
+
+
+# ---------------------------------------------------------------------------
+# Identifiability boundary
+# ---------------------------------------------------------------------------
+
+DEFAULT_COLLAPSE_THRESHOLD = 0.3
+
+
+@dataclass
+class BoundaryResult:
+    """
+    Result of identifiability boundary detection.
+
+    Attributes
+    ----------
+    index : float
+        Identifiability Index (I); higher = more identifiable regime.
+    is_collapsed : bool
+        True if index below threshold (Inference Collapse Zone).
+    threshold : float
+        Threshold used for is_collapsed.
+    """
+
+    index: float
+    is_collapsed: bool
+    threshold: float = DEFAULT_COLLAPSE_THRESHOLD
+
+
+def detect_boundary(
+    data: pd.DataFrame,
+    threshold: float = DEFAULT_COLLAPSE_THRESHOLD,
+    window: Optional[int] = None,
+) -> BoundaryResult:
+    """
+    Detect identifiability boundary: compute Identifiability Index (I) and
+    whether the market is in a "Zone of Collapse".
+
+    Parameters
+    ----------
+    data : DataFrame
+        OHLCV market data.
+    threshold : float
+        Index below this value is considered collapsed (default 0.3).
+    window : int, optional
+        Rolling window for drift/separation; default uses 20% of length.
+
+    Returns
+    -------
+    BoundaryResult
+        .index (Identifiability Index), .is_collapsed, .threshold.
+    """
+    df = data.copy()
+    if "close" not in df.columns and len(df.columns) >= 4:
+        df = df.rename(columns={df.columns[3]: "close"})
+    close = df["close"] if "close" in df.columns else df.iloc[:, 3]
+    close = pd.Series(close).dropna()
+    n = len(close)
+    if n < 2:
+        return BoundaryResult(index=0.0, is_collapsed=True, threshold=threshold)
+
+    w = window or max(int(0.2 * n), 2)
+    returns = close.pct_change().dropna()
+    if len(returns) < w:
+        return BoundaryResult(index=0.0, is_collapsed=True, threshold=threshold)
+
+    vol = returns.rolling(w).std().dropna()
+    if vol.empty or vol.iloc[-1] == 0:
+        drift = 0.0
+    else:
+        vol_early = vol.iloc[: len(vol) // 2].mean()
+        vol_late = vol.iloc[len(vol) // 2 :].mean()
+        drift = abs(vol_late - vol_early) / (vol.mean() + 1e-10)
+        drift = min(drift, 1.0)
+
+    identifiability_index = float(np.clip(1.0 - drift, 0.0, 1.0))
+    if np.isnan(identifiability_index):
+        identifiability_index = 0.0
+    is_collapsed = identifiability_index < threshold
+
+    return BoundaryResult(
+        index=identifiability_index,
+        is_collapsed=is_collapsed,
+        threshold=threshold,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Ordinal robustness (metrics)
+# ---------------------------------------------------------------------------
+
+def ordinal_consistency(
+    y_true: Union[np.ndarray, pd.Series],
+    y_pred: Union[np.ndarray, pd.Series],
+) -> float:
+    """
+    Ordinal Consistency: Spearman's rank correlation between true and predicted
+    regime order. Valid when ARI is low but ranking for hedging remains meaningful.
+
+    Parameters
+    ----------
+    y_true : array-like
+        True regime labels or risk ordering (numeric).
+    y_pred : array-like
+        Predicted regime labels or risk ordering (numeric).
+
+    Returns
+    -------
+    float
+        Spearman's Rho in [-1, 1]; higher = more ordinal consistency.
+    """
+    from scipy.stats import spearmanr
+
+    y_true = np.asarray(y_true).ravel()
+    y_pred = np.asarray(y_pred).ravel()
+    if len(y_true) != len(y_pred) or len(y_true) < 2:
+        return 0.0
+    rho, _ = spearmanr(y_true, y_pred)
+    return float(np.clip(rho, -1.0, 1.0) if not np.isnan(rho) else 0.0)
+
+
+def ari_score(
+    y_true: Union[np.ndarray, pd.Series],
+    y_pred: Union[np.ndarray, pd.Series],
+) -> float:
+    """
+    Adjusted Rand Index for absolute label agreement.
+    Use ordinal_consistency when ARI collapses but ranking still matters.
+
+    Parameters
+    ----------
+    y_true : array-like
+        True cluster/regime labels (integer).
+    y_pred : array-like
+        Predicted cluster/regime labels (integer).
+
+    Returns
+    -------
+    float
+        ARI in [-1, 1]; 1 = perfect match.
+    """
+    try:
+        from sklearn.metrics import adjusted_rand_score
+    except ImportError:
+        return 0.0
+    y_true = np.asarray(y_true).ravel().astype(int)
+    y_pred = np.asarray(y_pred).ravel().astype(int)
+    if len(y_true) != len(y_pred) or len(y_true) < 2:
+        return 0.0
+    return float(adjusted_rand_score(y_true, y_pred))
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="mrv-lib",
+        description=(
+            "Market Regime Validity diagnostics: "
+            "Representation Stability (RSS) and Identifiability Index."
+        ),
+    )
+    parser.add_argument(
+        "csv",
+        help="Path to OHLCV market data CSV file.",
+    )
+    parser.add_argument(
+        "-r",
+        "--resolution",
+        nargs="+",
+        default=["5m", "1h", "1d"],
+        help="Temporal resolutions to test, e.g. 5m 1h 1d (default: 5m 1h 1d).",
+    )
+    parser.add_argument(
+        "-m",
+        "--model",
+        default="HMM",
+        help="Regime model type label (passed through to Scanner; default: HMM).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    """Command-line entry point. Example: mrv-lib market_data.csv --resolution 5m 1h 1d --model HMM."""
+    args = _parse_args(argv)
+
+    data = pd.read_csv(args.csv)
+
+    scanner = Scanner(resolution=args.resolution)
+    results = scanner.run_representation_test(data, model=args.model)
+
+    boundary = detect_boundary(data)
+
+    print(f"File: {args.csv}")
+    print(f"Resolutions: {args.resolution}")
+    print(f"Model: {args.model}")
+    print(f"RSS (Representation Stability Score): {results.rss_score:.4f}")
+    print(
+        f"Identifiability Index: {boundary.index:.4f} "
+        f"(threshold={boundary.threshold:.2f})"
+    )
+    if boundary.is_collapsed:
+        print("Status: COLLAPSED (Inference Collapse Zone)")
+    else:
+        print("Status: STABLE (outside collapse zone)")

mrv_lib-0.0.1/src/mrv_lib.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: mrv-lib
+Version: 0.0.1
+Summary: Market Regime Validity Library for Model Risk Governance
+Author-email: Kai Zheng <kaizhengnz@gmail.com>
+License: 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: License :: OSI Approved :: MIT License
+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.

mrv_lib-0.0.1/src/mrv_lib.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/mrv_lib/__init__.py
+src/mrv_lib/core.py
+src/mrv_lib.egg-info/PKG-INFO
+src/mrv_lib.egg-info/SOURCES.txt
+src/mrv_lib.egg-info/dependency_links.txt
+src/mrv_lib.egg-info/entry_points.txt
+src/mrv_lib.egg-info/requires.txt
+src/mrv_lib.egg-info/top_level.txt
+tests/test_core.py

mrv_lib-0.0.1/src/mrv_lib.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mrv_lib-0.0.1/src/mrv_lib.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mrv-lib = mrv_lib.core:main

mrv_lib-0.0.1/src/mrv_lib.egg-info/requires.txt

@@ -0,0 +1,10 @@
+numpy
+pandas
+scipy
+scikit-learn
+
+[dev]
+pytest
+pytest-cov
+black
+ruff

mrv_lib-0.0.1/src/mrv_lib.egg-info/top_level.txt

@@ -0,0 +1 @@
+mrv_lib

mrv_lib-0.0.1/tests/test_core.py

@@ -0,0 +1,69 @@
+"""Tests for mrv_lib.core: Scanner, detect_boundary, ordinal_consistency."""
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from mrv_lib import (
+    BoundaryResult,
+    RepresentationTestResult,
+    Scanner,
+    detect_boundary,
+    ordinal_consistency,
+)
+
+
+def _ohlcv_df(n: int = 100) -> pd.DataFrame:
+    np.random.seed(42)
+    close = np.cumsum(np.random.randn(n)) + 100.0
+    open_ = np.roll(close, 1)
+    open_[0] = close[0]
+    high = np.maximum(open_, close) + np.abs(np.random.randn(n)) * 0.5
+    low = np.minimum(open_, close) - np.abs(np.random.randn(n)) * 0.5
+    volume = np.random.randint(1000, 10000, n)
+    return pd.DataFrame({
+        "open": open_,
+        "high": high,
+        "low": low,
+        "close": close,
+        "volume": volume,
+    })
+
+
+def test_scanner_run_representation_test_returns_result():
+    data = _ohlcv_df(50)
+    scanner = Scanner(resolution=["1h", "1d"])
+    result = scanner.run_representation_test(data, model="HMM")
+    assert isinstance(result, RepresentationTestResult)
+    assert 0 <= result.rss_score <= 1
+    assert "1h" in result.resolution_scores
+    assert "1d" in result.resolution_scores
+
+
+def test_detect_boundary_returns_boundary_result():
+    data = _ohlcv_df(50)
+    boundary = detect_boundary(data)
+    assert isinstance(boundary, BoundaryResult)
+    assert 0 <= boundary.index <= 1
+    assert boundary.is_collapsed == (boundary.index < boundary.threshold)
+
+
+def test_detect_boundary_short_series_collapsed():
+    data = _ohlcv_df(3)
+    boundary = detect_boundary(data)
+    assert boundary.is_collapsed is True
+    assert boundary.index == 0.0
+
+
+def test_ordinal_consistency_perfect_correlation():
+    y = np.array([1, 2, 3, 4, 5])
+    assert ordinal_consistency(y, y) == pytest.approx(1.0)
+
+
+def test_ordinal_consistency_reverse_correlation():
+    y = np.array([1, 2, 3, 4, 5])
+    assert ordinal_consistency(y, -y) == pytest.approx(-1.0)
+
+
+def test_ordinal_consistency_short_returns_zero():
+    assert ordinal_consistency([1], [2]) == 0.0