nirvana-quant 1.0.0__py3-none-any.whl

nirvana/__init__.py

@@ -0,0 +1,75 @@
+"""
+NIRVANA: Chrono-Cancer Meta-Architecture for High-Dimensional Financial Risk & Network Dynamics
+================================================================================================
+A causal, manifold-based quantitative engine for financial time-series, volatility spillover,
+and systemic risk analysis across interconnected banking systems.
+
+Author: yinyusi65 & Nirvana Quant Team
+License: MIT / Academic Research
+"""
+
+__version__ = "1.0.0"
+
+from .manifold import Base12Manifold, DualClockCoordinates
+from .kalman import CausalOnlineKalman, MultivariateCausalKalman, CausalKalmanTVPRegressor
+from .tree import NirvanaTreeEngine, TrainingSample
+from .network import (
+    NirvanaConnectedness,
+    SystemicRiskReport,
+    DynamicSystemicRiskReport,
+    DEFAULT_ASSET_WEIGHTS,
+    DEFAULT_EXCHANGE_BANDS,
+)
+from .multiplex import MultiplexNetworkEngine
+from .multiverse import MultiverseReconstructor
+from .volatility import compute_parkinson, compute_garman_klass, compute_yang_zhang
+from .static import (
+    NirvanaStaticBooster,
+    StaticEconometricReport,
+    NirvanaTreeRegressor,
+    NirvanaTwoStageRegressor,
+    parse_formula,
+)
+from .stata import stata_regress, StataRegressionResult, stata_summarize, stata_pwcorr
+from .proof import (
+    prove_phase2_variable,
+    Phase2MultiverseProofReport,
+    rank_phase2_discovered_variables,
+    Phase2RankedVariablesReport,
+    DiscoveredVariableItem,
+)
+from . import domains
+
+__all__ = [
+    "Base12Manifold",
+    "DualClockCoordinates",
+    "CausalOnlineKalman",
+    "MultivariateCausalKalman",
+    "NirvanaTreeEngine",
+    "TrainingSample",
+    "NirvanaStaticBooster",
+    "StaticEconometricReport",
+    "NirvanaTreeRegressor",
+    "NirvanaTwoStageRegressor",
+    "parse_formula",
+    "stata_regress",
+    "StataRegressionResult",
+    "stata_summarize",
+    "stata_pwcorr",
+    "prove_phase2_variable",
+    "Phase2MultiverseProofReport",
+    "rank_phase2_discovered_variables",
+    "Phase2RankedVariablesReport",
+    "DiscoveredVariableItem",
+    "NirvanaConnectedness",
+    "SystemicRiskReport",
+    "DynamicSystemicRiskReport",
+    "DEFAULT_ASSET_WEIGHTS",
+    "DEFAULT_EXCHANGE_BANDS",
+    "MultiplexNetworkEngine",
+    "MultiverseReconstructor",
+    "compute_parkinson",
+    "compute_garman_klass",
+    "compute_yang_zhang",
+    "domains",
+]

nirvana/domains/__init__.py

@@ -0,0 +1,41 @@
+"""
+NIRVANA DOMAIN-SPECIFIC SPECIALIZED EXTENSION MODULES
+======================================================
+Domain modules for translating universal Nirvana causal graph dynamics into
+sector-specific actionable intelligence:
+- banking: Basel IV, SIFI, bank capital buffers, HOSE/HNX/UPCoM limits
+- cybersecurity: DDoS amplification, botnet hubs, BGP chokepoints
+- supply_chain: Bullwhip effect, sole-source bottleneck suppliers
+"""
+
+from .banking import (
+    DEFAULT_BANKING_TIERS,
+    DEFAULT_EXCHANGE_BANDS,
+    DEFAULT_ASSET_WEIGHTS,
+    classify_sifi_status,
+)
+from .cybersecurity import analyze_cyber_contagion
+from .supply_chain import analyze_supply_chain_risk
+from .consumer import (
+    DEFAULT_CONSUMER_CATEGORIES,
+    DEFAULT_EXPENDITURE_WEIGHTS,
+    analyze_consumer_dynamics,
+)
+from .substitute import (
+    DEFAULT_PROTEIN_SUBSTITUTE_ROLES,
+    analyze_substitution_thresholds,
+)
+
+__all__ = [
+    "DEFAULT_BANKING_TIERS",
+    "DEFAULT_EXCHANGE_BANDS",
+    "DEFAULT_ASSET_WEIGHTS",
+    "classify_sifi_status",
+    "analyze_cyber_contagion",
+    "analyze_supply_chain_risk",
+    "DEFAULT_CONSUMER_CATEGORIES",
+    "DEFAULT_EXPENDITURE_WEIGHTS",
+    "analyze_consumer_dynamics",
+    "DEFAULT_PROTEIN_SUBSTITUTE_ROLES",
+    "analyze_substitution_thresholds",
+]

nirvana/domains/banking.py

@@ -0,0 +1,77 @@
+"""
+Nirvana Domain Module: Banking & Financial Systems
+===================================================
+Domain-specific parameters, regulatory bands, asset weights, and structural tiers
+for Vietnamese commercial banks and Basel IV systemic risk analysis.
+"""
+
+from typing import Dict, List, Optional
+import numpy as np
+import pandas as pd
+
+
+# Structural Banking Tiers in the Vietnamese Banking System
+DEFAULT_BANKING_TIERS: Dict[str, List[str]] = {
+    "BIG4_STATE": ["VCB", "CTG", "BID"],
+    "TIER1_RETAIL_CORP": ["TCB", "VPB", "MBB", "ACB", "HDB", "VIB", "TPB", "SHB", "STB"],
+    "TIER2_COMMERCIAL": ["MSB", "OCB", "LPB", "EIB", "SSB", "NAB"],
+    "TIER3_REGIONAL_RESTRUCTURING": ["BAB", "BVB", "KLB", "NVB", "PGB", "SGB", "VAB", "VBB"],
+}
+
+# Statutory Exchange Price Limits (heteroskedasticity bounds)
+DEFAULT_EXCHANGE_BANDS: Dict[str, float] = {
+    # HNX (10% limit)
+    "NVB": 0.10, "BAB": 0.10,
+    # UPCoM (15% limit)
+    "BVB": 0.15, "SGB": 0.15, "PGB": 0.15, "VBB": 0.15,
+    "KLB": 0.15, "ABB": 0.15, "NAB": 0.15, "VAB": 0.15,
+    # All others default to HOSE (7% limit)
+}
+
+# Empirical 2024 Total Assets (Trillion VND) for all 27 Vietnamese commercial banks
+DEFAULT_ASSET_WEIGHTS: Dict[str, float] = {
+    # Big4 State Banks (~1,800 - 2,300 Trillion VND)
+    "BID": 2300.0, "CTG": 2000.0, "VCB": 1800.0,
+    # Tier-1 Joint-Stock Retail & Corporate (~600 - 900 Trillion VND)
+    "MBB": 900.0, "TCB": 850.0, "VPB": 820.0, "ACB": 720.0,
+    "STB": 670.0, "SHB": 630.0, "HDB": 600.0,
+    # Tier-2 Commercial (~200 - 450 Trillion VND)
+    "VIB": 410.0, "LPB": 380.0, "TPB": 360.0, "MSB": 270.0,
+    "SSB": 270.0, "OCB": 240.0, "EIB": 200.0, "NAB": 200.0,
+    # Tier-3 Regional & Restructuring (~35 - 160 Trillion VND)
+    "ABB": 160.0, "VAB": 110.0, "BAB": 100.0, "NVB": 90.0,
+    "KLB": 85.0, "BVB": 85.0, "PGB": 55.0, "SGB": 35.0, "VBB": 35.0,
+}
+
+
+def classify_sifi_status(
+    net_spillovers: Dict[str, float],
+    hub_scores: Optional[Dict[str, float]] = None,
+    asset_weights: Optional[Dict[str, float]] = None,
+    sifi_net_cutoff: float = 2.0,
+) -> pd.DataFrame:
+    """
+    Classifies banks into Systemically Important Financial Institutions (SIFIs)
+    based on Net Transmitted Risk (NET > 0) and Hub Centrality.
+    """
+    banks = list(net_spillovers.keys())
+    assets = asset_weights or DEFAULT_ASSET_WEIGHTS
+    
+    records = []
+    for b in banks:
+        net = net_spillovers.get(b, 0.0)
+        hub = (hub_scores or {}).get(b, 0.0)
+        asset = assets.get(b, 100.0)
+        
+        is_sifi = (net >= sifi_net_cutoff) or (hub >= 5.0 and asset >= 500.0)
+        records.append({
+            "bank": b,
+            "net_spillover": round(net, 2),
+            "hub_score": round(hub, 2),
+            "asset_trillion_vnd": asset,
+            "sifi_status": "SIFI_CRITICAL" if is_sifi else "NON_SIFI",
+            "recommended_capital_buffer": "1.50%" if is_sifi and asset > 1500 else ("1.00%" if is_sifi else "0.00%"),
+        })
+        
+    df = pd.DataFrame(records)
+    return df.sort_values(by="net_spillover", ascending=False).reset_index(drop=True)

nirvana/domains/consumer.py

@@ -0,0 +1,132 @@
+"""
+NIRVANA DOMAIN MODULE: CONSUMER & RETAIL ECONOMETRICS
+======================================================
+Translates Nirvana directed lead-lag networks and Base-12 harmonic manifolds
+into consumer economics intelligence:
+- Essential Consumer Staples vs. Discretionary / Luxury Goods
+- Base-12 Lunar Calendar & Seasonal Consumption Spikes (Tết, Back-to-school)
+- Cost-push Pass-through vs. Demand-pull Shock Propagation
+- Consumer Sentiment & Purchasing Power Elasticity
+"""
+
+from typing import Dict, List, Optional, Any
+import numpy as np
+import pandas as pd
+
+DEFAULT_CONSUMER_CATEGORIES: Dict[str, str] = {
+    # Consumer Staples (Hàng Tiêu dùng Thiết yếu - Co giãn cầu thấp)
+    "VNM": "Staples_Dairy",
+    "MSN": "Staples_Integrated_FMCG",
+    "SAB": "Staples_Beverages",
+    "KDC": "Staples_Food_Oils",
+    "QNS": "Staples_Sugar_Soymilk",
+    "DBC": "Staples_Protein_Agri",
+    "BAF": "Staples_Protein_3F",
+    
+    # Consumer Discretionary & Retail (Hàng Tiêu dùng Không thiết yếu & Bán lẻ - Co giãn cầu cao)
+    "MWG": "Discretionary_Retail_Electronics",
+    "PNJ": "Discretionary_Luxury_Jewelry",
+    "FRT": "Discretionary_Healthcare_Tech",
+    "DGW": "Discretionary_Distribution_ICT",
+    "VRE": "Discretionary_Retail_RealEstate",
+    "PET": "Discretionary_Distribution_Petro",
+}
+
+DEFAULT_EXPENDITURE_WEIGHTS: Dict[str, float] = {
+    "VNM": 85.0,  # Market Cap / Revenue scale proxy (Thousand Billion VND)
+    "MSN": 110.0,
+    "MWG": 70.0,
+    "PNJ": 35.0,
+    "SAB": 75.0,
+    "VRE": 45.0,
+    "FRT": 25.0,
+    "DGW": 12.0,
+    "KDC": 15.0,
+    "QNS": 18.0,
+    "DBC": 14.0,
+    "BAF": 8.0,
+}
+
+
+def analyze_consumer_dynamics(
+    report: Any,
+    categories: Optional[Dict[str, str]] = None,
+    expenditure_weights: Optional[Dict[str, float]] = None
+) -> Dict[str, Any]:
+    """
+    Translates systemic risk report into consumer & retail econometric insights.
+
+    Parameters:
+    - report: SystemicRiskReport from NirvanaConnectedness.fit()
+    - categories: Mapping of {ticker: category_name}
+    - expenditure_weights: Scale proxy for market footprint
+
+    Returns:
+    - Structured dictionary with category-level spillovers, demand leaders, and resilience rankings.
+    """
+    cats = categories or DEFAULT_CONSUMER_CATEGORIES
+    weights = expenditure_weights or DEFAULT_EXPENDITURE_WEIGHTS
+
+    net_spillovers = report.net_spillovers
+    hubs = report.eigenvector_hub
+    authorities = report.eigenvector_authority
+
+    # Aggregate by category: Staples vs Discretionary
+    staples_net: List[float] = []
+    discretionary_net: List[float] = []
+    category_summary: Dict[str, List[float]] = {}
+
+    for node, net_val in net_spillovers.items():
+        cat = cats.get(node, "Other")
+        category_summary.setdefault(cat, []).append(net_val)
+        if "Staples" in cat:
+            staples_net.append(net_val)
+        elif "Discretionary" in cat:
+            discretionary_net.append(net_val)
+
+    mean_staples = float(np.mean(staples_net)) if staples_net else 0.0
+    mean_discretionary = float(np.mean(discretionary_net)) if discretionary_net else 0.0
+
+    # Categorize roles:
+    # 1. Cost-Push / Pricing Power Transmitters (NET > 0 and high Hub)
+    pricing_leaders = [
+        node for node in report.top_transmitters
+        if "Staples" in cats.get(node, "")
+    ]
+
+    # 2. Purchasing Power Bellwethers (high Hub in Discretionary)
+    discretionary_bellwethers = [
+        node for node in report.top_transmitters
+        if "Discretionary" in cats.get(node, "")
+    ]
+
+    # 3. Demand Absorbers (NET < 0)
+    demand_absorbers = report.top_receivers
+
+    # 4. Resilience Ranking (Flight-to-Safety if present, else low authority)
+    resilience_ranking: List[str] = []
+    if hasattr(report, "flight_to_safety_index") and report.flight_to_safety_index:
+        resilience_ranking = sorted(
+            report.flight_to_safety_index.keys(),
+            key=lambda k: report.flight_to_safety_index[k],
+            reverse=True
+        )
+    else:
+        resilience_ranking = sorted(
+            authorities.keys(),
+            key=lambda k: authorities[k]
+        )
+
+    return {
+        "staples_mean_net_spillover": round(mean_staples, 2),
+        "discretionary_mean_net_spillover": round(mean_discretionary, 2),
+        "dominant_regime": (
+            "Cost-Push Inflation (Staples Leading)"
+            if mean_staples > mean_discretionary
+            else "Discretionary Demand-Pull (Discretionary Leading)"
+        ),
+        "pricing_power_leaders": pricing_leaders,
+        "discretionary_bellwethers": discretionary_bellwethers,
+        "most_vulnerable_demand_absorbers": demand_absorbers[:5],
+        "top_resilient_staples": [n for n in resilience_ranking if "Staples" in cats.get(n, "")][:5],
+    }

nirvana/domains/cybersecurity.py

@@ -0,0 +1,58 @@
+"""
+Nirvana Domain Module: Cybersecurity & Network Infrastructure Contagion
+========================================================================
+Applies Nirvana causal graph connectedness to:
+- Autonomous System (AS) / BGP route flapping and traffic spillover
+- DDoS amplification hub detection & botnet synchronization tracking
+- Subnet bottleneck / bridge identification (Betweenness centrality)
+- Vulnerability sink / target server identification (Authority centrality)
+"""
+
+from typing import Dict, List, Optional
+import numpy as np
+import pandas as pd
+
+
+def analyze_cyber_contagion(
+    spillover_report,
+    ip_or_node_metadata: Optional[Dict[str, Dict]] = None,
+    ddos_hub_cutoff: float = 4.0,
+) -> pd.DataFrame:
+    """
+    Translates a Nirvana systemic risk report into cybersecurity topology metrics:
+    - Attack / Amplification Hub: High out-degree shock transmitter
+    - Critical Target / Vulnerable Sink: High in-degree authority receiver
+    - Chokepoint / Bridge Node: High betweenness centrality router
+    """
+    nodes = list(spillover_report.net_spillovers.keys())
+    meta = ip_or_node_metadata or {}
+    
+    records = []
+    for node in nodes:
+        net = spillover_report.net_spillovers.get(node, 0.0)
+        hub = (spillover_report.eigenvector_hub or {}).get(node, 0.0)
+        auth = (spillover_report.eigenvector_authority or {}).get(node, 0.0)
+        bc = (spillover_report.betweenness_centrality or {}).get(node, 0.0)
+        
+        node_type = "UNKNOWN"
+        if hub >= ddos_hub_cutoff and net > 0:
+            node_type = "AMPLIFICATION_SOURCE / BOTNET_HUB"
+        elif auth >= ddos_hub_cutoff and net < 0:
+            node_type = "CRITICAL_TARGET / AT_RISK_SINK"
+        elif bc >= 10.0:
+            node_type = "INFRASTRUCTURE_CHOKEPOINT"
+        else:
+            node_type = "NORMAL_TRANSIT"
+            
+        records.append({
+            "node": node,
+            "net_flow_shock": round(net, 2),
+            "hub_score": round(hub, 2),
+            "sink_authority_score": round(auth, 2),
+            "betweenness_bottleneck": round(bc, 2),
+            "cyber_classification": node_type,
+            "action_priority": "URGENT_ISOLATE" if "AMPLIFICATION" in node_type or "CRITICAL_TARGET" in node_type else "MONITOR",
+        })
+        
+    df = pd.DataFrame(records)
+    return df.sort_values(by="hub_score", ascending=False).reset_index(drop=True)

nirvana/domains/substitute.py

@@ -0,0 +1,79 @@
+"""
+NIRVANA DOMAIN EXTENSION: MICRO-ECONOMETRIC PRODUCT SUBSTITUTION
+=================================================================
+Specialized domain module for analyzing cross-price elasticity,
+budget constraint binding thresholds, and consumer brand/product switching.
+
+Author: yinyusi65 & Nirvana Quant Team
+"""
+
+from typing import Any, Dict, List, Optional
+import numpy as np
+
+
+DEFAULT_PROTEIN_SUBSTITUTE_ROLES = {
+    "Pork_3F": "Anchor Good (Primary Household Staple)",
+    "Chicken_CP": "Close Substitute (Budget-Conscious Protein Alternative)",
+    "Eggs": "Secondary Macro-Buffer (Low-Cost Calorie Cushion)",
+}
+
+
+def analyze_substitution_thresholds(report: Any) -> Dict[str, Any]:
+    """
+    Extracts structural micro-econometric switching thresholds from
+    a fitted Nirvana StaticEconometricReport.
+
+    Parameters
+    ----------
+    report : StaticEconometricReport
+        The report object returned by NirvanaStaticBooster.fit().
+
+    Returns
+    -------
+    Dict[str, Any]
+        Dictionary containing extracted price ratio triggers, binding income
+        cutoffs, and economic interpretations.
+    """
+    threshold_rules = getattr(report, "top_substitution_thresholds", [])
+    feat_importances = getattr(report, "feature_importances", {})
+
+    # Detect dominant splitting features
+    top_driver = list(feat_importances.keys())[0] if feat_importances else "Unknown"
+
+    # Identify primary switching boundaries from rule descriptions
+    critical_price_ratio = None
+    binding_income_threshold = None
+
+    for rule in threshold_rules:
+        rule_lower = rule.lower()
+        if "ratio" in rule_lower and critical_price_ratio is None:
+            # Parse threshold number
+            try:
+                parts = rule.split("<=")
+                if len(parts) > 1:
+                    val_str = parts[1].split()[0]
+                    critical_price_ratio = float(val_str)
+            except Exception:
+                pass
+        elif "income" in rule_lower and binding_income_threshold is None:
+            try:
+                parts = rule.split("<=")
+                if len(parts) > 1:
+                    val_str = parts[1].split()[0]
+                    binding_income_threshold = float(val_str)
+            except Exception:
+                pass
+
+    return {
+        "primary_non_linear_driver": top_driver,
+        "critical_price_ratio_trigger": critical_price_ratio,
+        "binding_income_threshold_million_vnd": binding_income_threshold,
+        "r2_phase1_linear_baseline": getattr(report, "r2_phase1", 0.0),
+        "r2_phase2_nirvana_enhanced": getattr(report, "r2_phase2", 0.0),
+        "unexplained_variance_resolved_pct": getattr(report, "r2_relative_improvement_pct", 0.0),
+        "economic_regime": (
+            "Threshold-Driven Budget Substitution"
+            if getattr(report, "r2_gain", 0.0) > 0.15
+            else "Linear Proportional Substitution"
+        ),
+    }

nirvana/domains/supply_chain.py

@@ -0,0 +1,56 @@
+"""
+Nirvana Domain Module: Supply Chain & Industrial Contagion
+===========================================================
+Applies Nirvana causal graph connectedness to:
+- Bullwhip effect propagation across multi-tier supplier networks
+- Bottleneck supplier identification (Component shortage risk)
+- Lead-time volatility cascading across industrial sectors
+"""
+
+from typing import Dict, List, Optional
+import numpy as np
+import pandas as pd
+
+
+def analyze_supply_chain_risk(
+    spillover_report,
+    tier_levels: Optional[Dict[str, int]] = None,
+) -> pd.DataFrame:
+    """
+    Translates Nirvana connectedness metrics into supply chain risk indicators:
+    - Shock Originator (Upstream Bullwhip Emitter): High net transmitter
+    - Vulnerable Assembler (Downstream Receiver): High authority receiver
+    - Strategic Bottleneck: High betweenness bridging critical tiers
+    """
+    nodes = list(spillover_report.net_spillovers.keys())
+    tiers = tier_levels or {}
+    
+    records = []
+    for node in nodes:
+        net = spillover_report.net_spillovers.get(node, 0.0)
+        hub = (spillover_report.eigenvector_hub or {}).get(node, 0.0)
+        auth = (spillover_report.eigenvector_authority or {}).get(node, 0.0)
+        bc = (spillover_report.betweenness_centrality or {}).get(node, 0.0)
+        
+        tier = tiers.get(node, 1)
+        role = "REGULAR_SUPPLIER"
+        if hub >= 5.0 and net > 0:
+            role = "BULLWHIP_ORIGINATOR (UPSTREAM RISK)"
+        elif auth >= 5.0 and net < 0:
+            role = "HIGH_VULNERABILITY_ASSEMBLER"
+        elif bc >= 10.0:
+            role = "SOLE_SOURCE_BOTTLENECK"
+            
+        records.append({
+            "supplier_or_tier": node,
+            "tier_level": tier,
+            "net_spillover": round(net, 2),
+            "hub_emitter_score": round(hub, 2),
+            "vulnerability_sink_score": round(auth, 2),
+            "bottleneck_centrality": round(bc, 2),
+            "strategic_role": role,
+            "buffer_stock_recommendation": "INCREASE_SAFETY_STOCK" if "BULLWHIP" in role or "BOTTLENECK" in role else "STANDARD_JIT",
+        })
+        
+    df = pd.DataFrame(records)
+    return df.sort_values(by="bottleneck_centrality", ascending=False).reset_index(drop=True)

nirvana/experimental/__init__.py

@@ -0,0 +1,22 @@
+"""
+NIRVANA EXPERIMENTAL LAB
+========================
+Isolated incubator for frontier, non-production econometric research algorithms:
+- Multiverse Invariant Causal Feature Extraction (Champion Variable Discovery)
+- High-order interaction lattice exploration
+- Non-linear symbolic manifold distillation
+
+Author: yinyusi65
+"""
+
+from .multiverse_invariance import (
+    MultiverseChampionExtractor,
+    MultiverseChampionReport,
+    ChampionVariable,
+)
+
+__all__ = [
+    "MultiverseChampionExtractor",
+    "MultiverseChampionReport",
+    "ChampionVariable",
+]