grg 0.2.2__py3-none-any.whl

grg/config.py

@@ -0,0 +1,120 @@
+"""Centralized configuration loader for GRG (Geometric Reasoning Governor)."""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG_PATH = Path("config/grg-config.json")
+
+
+def resolve_config_path() -> Path:
+    """Find the config file regardless of current working directory."""
+    env_path = os.getenv("GRG_CONFIG")
+    if env_path:
+        return Path(env_path)
+
+    # 1. Try relative to CWD
+    cwd_path = Path.cwd() / DEFAULT_CONFIG_PATH
+    if cwd_path.exists():
+        return cwd_path
+
+    # 2. Try relative to this file (grg/config.py -> ./grg-config.json in same dir)
+    module_path = Path(__file__).parent / "grg-config.json"
+    if module_path.exists():
+        return module_path
+
+    # 3. Try relative to this file's parent (grg/config.py ->
+    # ../config/grg-config.json for installed packages)
+    package_path = Path(__file__).parent / "config" / "grg-config.json"
+    if package_path.exists():
+        return package_path
+
+    # 4. Try package data location (for development mode from src/)
+    dev_path = Path(__file__).parent.parent / "config" / "grg-config.json"
+    if dev_path.exists():
+        return dev_path
+
+    return DEFAULT_CONFIG_PATH
+
+
+def load_config() -> dict[str, Any]:
+    """Load the GRG configuration from file or return defaults."""
+    # Global Defaults
+    config = {
+        "global": {
+            "ranking_profile": "conservative",
+            "grg": {
+                "window_size": 20,
+                "ema_weight": 0.3,
+                "warmup_steps": 50,
+                "lr_slash_factor": 0.1,
+                "lr_restore_factor": 1.0,
+                "thermal_damping_min_temp": 0.01,
+                "e_stop_horizon": 5,
+                "collapse_v_alpha_threshold": -0.02,
+                "stability_v_alpha_threshold": 0.005,
+                "trajectory_window_size": 500,
+                "trajectory_window_step": 50,
+                "v_alpha_panic_threshold": -0.02,
+                "alpha_safety_floor": 0.10,
+            },
+        },
+        "profiles": {},
+    }
+
+    config_path = resolve_config_path()
+
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                user_config = json.load(f)
+                if "global" in user_config or "profiles" in user_config:
+                    # New hierarchical format
+                    if "global" in user_config:
+                        config["global"].update(user_config["global"])
+                    if "profiles" in user_config:
+                        config["profiles"].update(user_config["profiles"])
+                else:
+                    # Legacy flat format - merge into global
+                    config["global"].update(user_config)
+        except Exception:
+            # Silently fall back to defaults if config fails to load
+            pass
+
+    return config
+
+
+# Global config instance
+_config_data = load_config()
+
+
+class ConfigWrapper:
+    """Helper to access config with legacy support and profile awareness."""
+
+    def __init__(self, data: dict[str, Any]):
+        self._data = data
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Legacy access to global settings."""
+        return self._data["global"].get(key, default)
+
+    def get_profile(self, profile_name: str) -> dict[str, Any]:
+        """Get profile merged with global defaults."""
+        profile = self._data["global"].copy()
+        profile.update(self._data["profiles"].get(profile_name, {}))
+        return profile
+
+    def get_grg_config(self, profile_name: str | None = None) -> dict[str, Any]:
+        """Get GRG settings merged: global.grg -> profile.grg."""
+        grg = dict(self._data["global"].get("grg", {}))
+        if profile_name:
+            profile_grg = self._data["profiles"].get(profile_name, {}).get("grg", {})
+            grg.update(profile_grg)
+        return grg
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data["global"][key]
+
+
+get_config = ConfigWrapper(_config_data)

grg/early_warning.py

@@ -0,0 +1,272 @@
+"""Real-time streaming early warning + intervention system.
+
+Combines macro (AlphaMomentumTracker velocity/momentum) with micro
+(rolling rho_pn_sq decoupling) into a single EWI score. Streams each
+reading to a JSONL log and fires intervention callbacks on threshold
+crossing — before the trend fully manifests.
+
+Usage:
+    from grg.early_warning import EarlyWarningSystem
+
+    def my_intervention(reading):
+        print(f"INTERVENTION: {reading['ewi']:.4f} at step {reading['step']}")
+
+    ews = EarlyWarningSystem(
+        intervention_fn=my_intervention,
+        log_path="reports/ewi_stream.jsonl",
+    )
+    for value in live_feed:
+        ews.push(value)
+"""
+import json
+import os
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass, asdict
+from typing import Callable, Optional, List
+
+import numpy as np
+
+from grg.metrics import AlphaMomentumTracker, calculate_moment_sgo_metrics
+
+
+@dataclass
+class EWIReading:
+    step: int
+    timestamp: float
+    alpha: float
+    v_alpha: float
+    m_alpha: float
+    rho_pn_sq: float
+    ewi: float
+    warning: bool
+    collapse: bool
+    intervention_fired: bool
+
+
+class EarlyWarningSystem:
+    """Streaming early warning + intervention system.
+
+    Parameters
+    ----------
+    window_size : int
+        AlphaMomentumTracker window size.
+    alpha_ema : float
+        EMA smoothing for alpha.
+    k : int
+        Chunk size for rolling rho_pn_sq.
+    lambda_ : float
+        Weight for fragility (rho_pn_sq).
+    mu : float
+        Weight for negative velocity.
+    nu : float
+        Weight for negative momentum.
+    threshold : float
+        EWI threshold for intervention.
+    intervention_fn : callable, optional
+        Called with EWIReading when EWI crosses threshold.
+    log_path : str, optional
+        Path to JSONL log file for streaming output.
+    """
+
+    def __init__(
+        self,
+        window_size: int = 20,
+        alpha_ema: float = 0.3,
+        k: int = 3,
+        lambda_: float = 2.0,
+        mu: float = 3.0,
+        nu: float = 0.5,
+        safety_floor: float = 0.10,
+        panic_threshold: float = -0.02,
+        e_stop_horizon: float = 3.0,
+        threshold: float = 8.0,
+        intervention_fn: Optional[Callable] = None,
+        max_deltas: int = 200,
+        thread_safe: bool = True,
+        fsync_log: bool = False,
+        log_path: Optional[str] = None,
+    ):
+        self.tracker = AlphaMomentumTracker(window_size=window_size, alpha_ema=alpha_ema)
+        self.k = k
+        self.lambda_ = lambda_
+        self.mu = mu
+        self.nu = nu
+        self.safety_floor = safety_floor
+        self.panic_threshold = panic_threshold
+        self.e_stop_horizon = e_stop_horizon
+        self.threshold = threshold
+        self.intervention_fn = intervention_fn
+        self.log_path = log_path
+
+        self._deltas: deque = deque(maxlen=max_deltas)
+        self._prev_alpha: Optional[float] = None
+        self._step: int = 0
+        self._last_warning: bool = False
+        self._readings: List[EWIReading] = []
+        self._lock = threading.Lock() if thread_safe else None
+        self._fsync_log = fsync_log
+
+        if log_path:
+            os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
+            # Truncate on start
+            with open(log_path, "w"):
+                pass
+
+    def _rolling_rho(self) -> float:
+        """Compute rho_pn_sq over the last k deltas."""
+        deltas = list(self._deltas)
+        if len(deltas) < self.k:
+            return 0.0
+        n_chunks = len(deltas) // self.k
+        if n_chunks < 1:
+            return 0.0
+        trimmed = np.array(deltas[: n_chunks * self.k]).reshape(n_chunks, self.k)
+        units = [row.tolist() for row in trimmed]
+        try:
+            m = calculate_moment_sgo_metrics(units, utility_power=1.1)
+            return float(m["rho_pn_sq"])
+        except Exception:
+            return 0.0
+
+    def push(self, value: float) -> EWIReading:
+        if self._lock is not None:
+            with self._lock:
+                return self._push(value)
+        return self._push(value)
+
+    def _push(self, value: float) -> EWIReading:
+        """Push a new value through the system. Returns the EWI reading."""
+        self.tracker.push(value)
+        s = self.tracker.get_stats(v_panic=self.panic_threshold, floor=self.safety_floor)
+
+        # Track deltas for rolling rho
+        if self._prev_alpha is not None:
+            self._deltas.append(value - self._prev_alpha)
+        self._prev_alpha = value
+
+        rho = self._rolling_rho()
+
+        # EWI components
+        vel_warning = self.mu * max(0.0, -s["v_alpha"])
+        mom_warning = self.nu * max(0.0, -s["m_alpha"])
+        fragility = self.lambda_ * rho
+        ewi = vel_warning + mom_warning + fragility
+
+        collapse = self.tracker.should_stop(
+            safety_floor=self.safety_floor, panic_threshold=self.panic_threshold, e_stop_horizon=self.e_stop_horizon
+        )
+
+        warning = ewi >= self.threshold
+        intervention_fired = False
+
+        reading = EWIReading(
+            step=self._step,
+            timestamp=time.time(),
+            alpha=s["alpha"],
+            v_alpha=s["v_alpha"],
+            m_alpha=s["m_alpha"],
+            rho_pn_sq=rho,
+            ewi=ewi,
+            warning=warning,
+            collapse=collapse,
+            intervention_fired=False,
+        )
+
+        # Fire intervention on threshold crossing (rising edge)
+        if warning and not self._last_warning:
+            reading.intervention_fired = True
+            if self.intervention_fn is not None:
+                try:
+                    self.intervention_fn(reading)
+                except Exception as e:
+                    print(f"[EarlyWarning] Intervention callback error: {e}")
+
+        self._last_warning = warning
+        self._step += 1
+
+        # Stream to log (push, not batch)
+        if self.log_path:
+            with open(self.log_path, "a") as f:
+                f.write(json.dumps(asdict(reading)) + "\n")
+                f.flush()
+                if self._fsync_log:
+                    os.fsync(f.fileno())
+
+        self._readings.append(reading)
+        return reading
+
+    def reset(self) -> None:
+        if self._lock is not None:
+            with self._lock:
+                self._reset_unlocked()
+                return
+        self._reset_unlocked()
+
+    def _reset_unlocked(self) -> None:
+        self.tracker = AlphaMomentumTracker(window_size=self.tracker.window_size, alpha_ema=self.tracker.alpha_ema)
+        self._deltas.clear()
+        self._prev_alpha = None
+        self._step = 0
+        self._last_warning = False
+        self._readings.clear()
+
+    def push_many(self, values) -> list:
+        return [self.push(float(v)) for v in values]
+
+    def get_history(self) -> List[EWIReading]:
+        return list(self._readings)
+
+    def summary(self) -> dict:
+        warnings = [r for r in self._readings if r.warning]
+        interventions = [r for r in self._readings if r.intervention_fired]
+        return {
+            "total_steps": self._step,
+            "warning_steps": len(warnings),
+            "intervention_count": len(interventions),
+            "first_warning_step": warnings[0].step if warnings else None,
+            "max_ewi": max((r.ewi for r in self._readings), default=0.0),
+            "final_alpha": self._readings[-1].alpha if self._readings else None,
+        }
+
+
+# ------------------------------------------------------------------
+# Demo: stream exponential series through the system
+# ------------------------------------------------------------------
+
+def demo():
+    import numpy as np
+
+    def intervention_handler(reading: EWIReading):
+        print(f"  >>> INTERVENTION FIRED at step {reading.step}: "
+              f"EWI={reading.ewi:.4f} (alpha={reading.alpha:.4f}, "
+              f"v={reading.v_alpha:.4f}, rho={reading.rho_pn_sq:.4f})")
+
+    series = {
+        "decay": [float(np.exp(-0.03 * t)) for t in range(50)],
+        "growth": [float(1.0 - np.exp(-0.03 * t)) for t in range(50)],
+        "zigzag": [float(0.5 * np.sin(0.3 * t)) for t in range(50)],
+    }
+
+    for name, vals in series.items():
+        print(f"\n{'=' * 60}")
+        print(f"  Streaming: {name}")
+        print(f"{'=' * 60}")
+        ews = EarlyWarningSystem(
+            intervention_fn=intervention_handler,
+            log_path=f"reports/ewi_{name}.jsonl",
+            threshold=0.05,
+        )
+        for v in vals:
+            ews.push(v)
+        sm = ews.summary()
+        print(f"  Summary: {sm['total_steps']} steps, "
+              f"{sm['warning_steps']} warnings, "
+              f"{sm['intervention_count']} interventions, "
+              f"first warning at step {sm['first_warning_step']}, "
+              f"max EWI={sm['max_ewi']:.4f}")
+
+
+if __name__ == "__main__":
+    demo()

grg/grg-config.json

@@ -0,0 +1,90 @@
+{
+  "global": {
+    "ranking_profile": "conservative",
+    "grg": {
+      "window_size": 20,
+      "ema_weight": 0.3,
+      "warmup_steps": 50,
+      "lr_slash_factor": 0.1,
+      "lr_restore_factor": 1.0,
+      "thermal_damping_min_temp": 0.01,
+      "e_stop_horizon": 5,
+      "collapse_v_alpha_threshold": -0.02,
+      "stability_v_alpha_threshold": 0.005,
+      "trajectory_window_size": 500,
+      "trajectory_window_step": 50,
+      "v_alpha_panic_threshold": -0.02,
+      "alpha_safety_floor": 0.10
+    }
+  },
+  "profiles": {
+    "default": {
+      "grg": {
+        "window_size": 20,
+        "ema_weight": 0.3,
+        "warmup_steps": 50,
+        "lr_slash_factor": 0.1,
+        "lr_restore_factor": 1.0,
+        "thermal_damping_min_temp": 0.01,
+        "e_stop_horizon": 5,
+        "collapse_v_alpha_threshold": -0.02,
+        "stability_v_alpha_threshold": 0.005,
+        "trajectory_window_size": 500,
+        "trajectory_window_step": 50,
+        "v_alpha_panic_threshold": -0.02,
+        "alpha_safety_floor": 0.10
+      }
+    },
+    "high_sensitivity": {
+      "grg": {
+        "window_size": 16,
+        "ema_weight": 0.4,
+        "warmup_steps": 30,
+        "lr_slash_factor": 0.2,
+        "lr_restore_factor": 1.0,
+        "thermal_damping_min_temp": 0.02,
+        "e_stop_horizon": 3,
+        "collapse_v_alpha_threshold": -0.015,
+        "stability_v_alpha_threshold": 0.003,
+        "trajectory_window_size": 300,
+        "trajectory_window_step": 30,
+        "v_alpha_panic_threshold": -0.01,
+        "alpha_safety_floor": 0.15
+      }
+    },
+    "low_latency": {
+      "grg": {
+        "window_size": 12,
+        "ema_weight": 0.5,
+        "warmup_steps": 20,
+        "lr_slash_factor": 0.5,
+        "lr_restore_factor": 1.0,
+        "thermal_damping_min_temp": 0.01,
+        "e_stop_horizon": 2,
+        "collapse_v_alpha_threshold": -0.025,
+        "stability_v_alpha_threshold": 0.008,
+        "trajectory_window_size": 200,
+        "trajectory_window_step": 20,
+        "v_alpha_panic_threshold": -0.03,
+        "alpha_safety_floor": 0.08
+      }
+    },
+    "rag_grounded": {
+      "grg": {
+        "window_size": 24,
+        "ema_weight": 0.25,
+        "warmup_steps": 100,
+        "lr_slash_factor": 0.1,
+        "lr_restore_factor": 1.0,
+        "thermal_damping_min_temp": 0.005,
+        "e_stop_horizon": 8,
+        "collapse_v_alpha_threshold": -0.01,
+        "stability_v_alpha_threshold": 0.002,
+        "trajectory_window_size": 1000,
+        "trajectory_window_step": 100,
+        "v_alpha_panic_threshold": -0.005,
+        "alpha_safety_floor": 0.20
+      }
+    }
+  }
+}