grg 0.2.2__py3-none-any.whl

grg/__init__.py

@@ -0,0 +1,111 @@
+"""
+GRG (Geometric Reasoning Governor) — Real-time structural integrity monitoring for LLM inference.
+
+A Python package for monitoring and governing the structural integrity of LLM outputs
+during token generation using Alpha-Drift Velocity (V_alpha) tracking.
+
+Key Components:
+- AlphaMomentumTracker: Core GRG class for real-time EMA-smoothed alpha tracking
+- SGO Metrics: Structural Geometry Optimization metrics for evaluating binary-outcome systems
+- Configuration: Profile-based configuration for different sensitivity requirements
+
+Usage:
+    from grg import AlphaMomentumTracker, evaluate_structural_geometry
+    from grg.config import get_config
+
+    # Real-time GRG tracking
+    tracker = AlphaMomentumTracker()
+    for token_logprob in token_stream:
+        alpha = compute_structural_alpha(token_logprob)
+        tracker.push(alpha)
+        stats = tracker.get_stats()
+        if stats["is_collapsing"]:
+            # Trigger thermal damping or e-stop
+            pass
+
+    # Offline SGO evaluation
+    results = evaluate_structural_geometry(positive_outcomes, negative_outcomes)
+    print(f"Structural Alpha: {results['structural_alpha']:.4f}")
+    print(f"Ranking Score: {results['ranking_score']:.4f}")
+"""
+
+from grg.early_warning import EarlyWarningSystem, EWIReading
+from grg.config import get_config
+from grg.metrics import (
+    RANKING_PROFILES,
+    # Trackers (GRG Core)
+    AlphaMomentumTracker,
+    StructuralTracker,
+    # Utility
+    apply_utility_transformation,
+    calculate_cofactor_matrix,
+    # Entropy & Probability
+    calculate_entropy,
+    calculate_moment_sgo_metrics,
+    # Structural Metrics
+    calculate_normalized_structure_metrics,
+    calculate_positive_alpha_penalty,
+    calculate_probability_sgo_matrix,
+    # Ranking & Diagnostics
+    calculate_ranking_score,
+    calculate_regime_aware_ideal,
+    calculate_sgo_divergence,
+    compute_distributional_concentration,
+    # Core SGO Matrix Functions
+    compute_sgo_matrix,
+    evaluate_balance_diagnostics,
+    evaluate_cofactors_norm_diff_diagnostics,
+    # Distributional Analysis
+    evaluate_distributional_geometry,
+    evaluate_structural_geometry,
+    extract_matrix_alpha,
+)
+
+from grg.intervention import (
+    CandidateBatch,
+    GenerationResult,
+    InterventionConfig,
+    InterventionSampler,
+    TokenTelemetry,
+)
+
+__all__ = [
+    # Core SGO Matrix Functions
+    "compute_sgo_matrix",
+    "calculate_moment_sgo_metrics",
+    "evaluate_structural_geometry",
+    # Structural Metrics
+    "calculate_normalized_structure_metrics",
+    "extract_matrix_alpha",
+    "calculate_cofactor_matrix",
+    "calculate_regime_aware_ideal",
+    # Ranking & Diagnostics
+    "calculate_ranking_score",
+    "calculate_positive_alpha_penalty",
+    "evaluate_balance_diagnostics",
+    "evaluate_cofactors_norm_diff_diagnostics",
+    # Entropy & Probability
+    "calculate_entropy",
+    "calculate_probability_sgo_matrix",
+    "calculate_sgo_divergence",
+    # Distributional Analysis
+    "evaluate_distributional_geometry",
+    "compute_distributional_concentration",
+    # Utility
+    "apply_utility_transformation",
+    # Trackers (GRG Core)
+    "AlphaMomentumTracker",
+    "StructuralTracker",
+    # Ranking Profiles
+    "RANKING_PROFILES",
+    # Config
+    "get_config",
+    # Intervention Sampler
+    "InterventionSampler",
+    "InterventionConfig",
+    "GenerationResult",
+    "TokenTelemetry",
+    "CandidateBatch",
+    "EarlyWarningSystem",
+    "EWIReading",
+]

grg/cli.py

@@ -0,0 +1,473 @@
+"""CLI for GRG (Geometric Reasoning Governor) — System stats analysis and GRG monitoring."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import click
+import numpy as np
+import psutil
+
+from grg import (
+    AlphaMomentumTracker,
+    calculate_entropy,
+    calculate_moment_sgo_metrics,
+    evaluate_structural_geometry,
+    get_config,
+)
+
+
+def collect_system_stats() -> dict[str, Any]:
+    """Collect comprehensive system statistics."""
+    # CPU
+    cpu_percent = psutil.cpu_percent(interval=0.1, percpu=True)
+    cpu_freq = psutil.cpu_freq()
+    cpu_count_logical = psutil.cpu_count(logical=True)
+    cpu_count_physical = psutil.cpu_count(logical=False)
+
+    # Memory
+    mem = psutil.virtual_memory()
+    swap = psutil.swap_memory()
+
+    # Disk
+    disk = psutil.disk_usage("/")
+
+    # Network
+    net_io = psutil.net_io_counters()
+
+    # Process
+    process = psutil.Process()
+    proc_mem = process.memory_info()
+    proc_cpu = process.cpu_percent(interval=0.1)
+
+    # GPU (if available)
+    gpu_info = []
+    try:
+        import pynvml  # type: ignore[import-not-found]
+
+        pynvml.nvmlInit()
+        device_count = pynvml.nvmlDeviceGetCount()
+        for i in range(device_count):
+            handle = pynvml.nvmlDeviceGetHandleByIndex(i)
+            name = pynvml.nvmlDeviceGetName(handle)
+            mem_info = pynvml.nvmlDeviceGetMemoryInfo(handle)
+            util = pynvml.nvmlDeviceGetUtilizationRates(handle)
+            temp = pynvml.nvmlDeviceGetTemperature(handle, pynvml.NVML_TEMPERATURE_GPU)
+            gpu_info.append(
+                {
+                    "index": i,
+                    "name": name.decode() if isinstance(name, bytes) else name,
+                    "memory_total_mb": mem_info.total / 1024**2,
+                    "memory_used_mb": mem_info.used / 1024**2,
+                    "memory_free_mb": mem_info.free / 1024**2,
+                    "utilization_gpu": util.gpu,
+                    "utilization_memory": util.memory,
+                    "temperature_c": temp,
+                }
+            )
+    except Exception:
+        pass  # GPU monitoring optional
+
+    return {
+        "cpu": {
+            "percent_per_core": cpu_percent,
+            "percent_total": sum(cpu_percent) / len(cpu_percent) if cpu_percent else 0,
+            "frequency_mhz": cpu_freq.current if cpu_freq else None,
+            "count_logical": cpu_count_logical,
+            "count_physical": cpu_count_physical,
+        },
+        "memory": {
+            "total_gb": mem.total / 1024**3,
+            "available_gb": mem.available / 1024**3,
+            "used_gb": mem.used / 1024**3,
+            "percent": mem.percent,
+        },
+        "swap": {
+            "total_gb": swap.total / 1024**3,
+            "used_gb": swap.used / 1024**3,
+            "percent": swap.percent,
+        },
+        "disk": {
+            "total_gb": disk.total / 1024**3,
+            "used_gb": disk.used / 1024**3,
+            "free_gb": disk.free / 1024**3,
+            "percent": (disk.used / disk.total) * 100,
+        },
+        "network": {
+            "bytes_sent": net_io.bytes_sent,
+            "bytes_recv": net_io.bytes_recv,
+            "packets_sent": net_io.packets_sent,
+            "packets_recv": net_io.packets_recv,
+        },
+        "process": {
+            "pid": process.pid,
+            "memory_rss_mb": proc_mem.rss / 1024**2,
+            "memory_vms_mb": proc_mem.vms / 1024**2,
+            "cpu_percent": proc_cpu,
+            "num_threads": process.num_threads(),
+        },
+        "gpu": gpu_info,
+    }
+
+
+def simulate_alpha_from_system_stats(stats: dict[str, Any], window_size: int = 20) -> list[float]:
+    """
+    Simulate a sequence of alpha values from system stats.
+    This is a placeholder for actual LLM token-level alpha computation.
+    In practice, alpha would be computed from SGO matrix on token logprobs.
+    """
+    # Create synthetic alpha sequence based on system load patterns
+    cpu_load = stats["cpu"]["percent_total"] / 100.0
+    mem_load = stats["memory"]["percent"] / 100.0
+
+    # Base alpha inversely related to system stress
+    base_alpha = 1.0 - (0.4 * cpu_load + 0.3 * mem_load)
+    base_alpha = max(0.1, min(0.95, base_alpha))
+
+    # Generate a sequence with some drift and noise
+    np.random.seed(42)  # Reproducible for demo
+    alphas = []
+    current = base_alpha
+    for _ in range(window_size * 2):
+        # Add some drift (simulating token generation)
+        drift = np.random.normal(-0.001, 0.005)  # Slight negative drift
+        noise = np.random.normal(0, 0.01)
+        current = max(0.05, min(0.98, current + drift + noise))
+        alphas.append(current)
+
+    return alphas
+
+
+def run_grg_analysis(
+    stats: dict[str, Any], profile: str = "default", verbose: bool = False
+) -> dict[str, Any]:
+    """Run GRG analysis on system stats."""
+    grg_config = get_config.get_grg_config(profile)
+    window_size = grg_config.get("window_size", 20)
+    ema_weight = grg_config.get("ema_weight", 0.3)
+
+    # Simulate alpha sequence (in practice, this comes from token logprobs)
+    alphas = simulate_alpha_from_system_stats(stats, window_size)
+
+    # Initialize GRG tracker
+    tracker = AlphaMomentumTracker(window_size=window_size, alpha_ema=ema_weight)
+
+    remediation_actions: list[dict[str, Any]] = []
+    tracker_states: list[dict[str, Any]] = []
+
+    results: dict[str, Any] = {
+        "profile": profile,
+        "grg_config": grg_config,
+        "alpha_sequence": alphas,
+        "tracker_states": tracker_states,
+        "final_stats": None,
+        "remediation_actions": remediation_actions,
+    }
+
+    # Process each alpha
+    for i, alpha in enumerate(alphas):
+        tracker.push(alpha)
+        state = tracker.get_stats()
+        tracker_states.append(
+            {
+                "step": i,
+                "alpha": alpha,
+                "ema_alpha": state["alpha"],
+                "v_alpha": state["v_alpha"],
+                "m_alpha": state["m_alpha"],
+                "horizon": state["horizon"],
+                "is_collapsing": state["is_collapsing"],
+                "is_stable": state["is_stable"],
+            }
+        )
+
+        # Check for remediation triggers
+        if state["is_collapsing"] and not remediation_actions:
+            remediation_actions.append(
+                {
+                    "step": i,
+                    "trigger": "collapse_detected",
+                    "action": "thermal_damping",
+                    "v_alpha": state["v_alpha"],
+                    "recommended_temp": max(0.0, 0.7 * (1.0 + 10.0 * state["v_alpha"])),
+                }
+            )
+        elif (
+            state["horizon"] < grg_config.get("e_stop_horizon", 5)
+            and state["horizon"] > 0
+            and not any(a["action"] == "e_stop" for a in results["remediation_actions"])
+        ):
+            results["remediation_actions"].append(
+                {
+                    "step": i,
+                    "trigger": "horizon_breach",
+                    "action": "structural_e_stop",
+                    "horizon": state["horizon"],
+                    "message": (
+                        "Grounding check failed. Halting generation to prevent "
+                        "structural hallucination."
+                    ),
+                }
+            )
+
+    results["final_stats"] = tracker.get_stats()
+
+    return results
+
+
+def run_sgo_analysis(stats: dict[str, Any], verbose: bool = False) -> dict[str, Any]:
+    """Run SGO structural geometry analysis on system stats."""
+    # Create synthetic positive/negative outcomes from system metrics
+    cpu_load = stats["cpu"]["percent_total"] / 100.0
+    mem_load = stats["memory"]["percent"] / 100.0
+    disk_load = stats["disk"]["percent"] / 100.0
+
+    # Positive outcomes: healthy metrics (low load = good)
+    positive_outcomes = np.array(
+        [
+            1.0 - cpu_load,
+            1.0 - mem_load,
+            1.0 - disk_load,
+            stats["cpu"]["count_physical"] / 16.0,  # Normalized CPU cores
+            stats["memory"]["available_gb"] / 32.0,  # Normalized available memory
+        ]
+    )
+    positive_outcomes = np.clip(positive_outcomes, 0.01, 1.0)
+
+    # Negative outcomes: stress indicators
+    negative_outcomes = np.array(
+        [
+            cpu_load,
+            mem_load,
+            disk_load,
+            0.1,  # Baseline stress
+        ]
+    )
+    negative_outcomes = np.clip(negative_outcomes, 0.01, 1.0)
+
+    # Run structural geometry evaluation
+    results = evaluate_structural_geometry(
+        positive_outcomes=positive_outcomes,
+        negative_outcomes=negative_outcomes,
+        utility_power=1.1,
+        ranking_profile="conservative",
+        regime_aware=True,
+    )
+
+    # Also run moment SGO metrics
+    # Create outcome units (each metric as a "unit")
+    outcome_units = [positive_outcomes, -negative_outcomes]
+    moment_results = calculate_moment_sgo_metrics(outcome_units, utility_power=1.1)
+
+    # Entropy
+    all_outcomes = np.concatenate([positive_outcomes, -negative_outcomes])
+    entropy = calculate_entropy(all_outcomes)
+
+    return {
+        "structural_geometry": results,
+        "moment_sgo": moment_results,
+        "entropy": entropy,
+        "summary": {
+            "structural_alpha": results["structural_alpha"],
+            "ranking_score": results["ranking_score"],
+            "normalized_structure_term": results["normalized_structure_term"],
+            "entropy": entropy,
+            "is_structurally_sound": results.get("is_structurally_sound", False),
+            "energy_ratio": results.get("energy_ratio", 0.0),
+            "credibility": results.get("credibility", 0.0),
+        },
+    }
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="grg")
+def main() -> None:
+    """GRG (Geometric Reasoning Governor) — Real-time structural integrity
+    monitoring for LLM inference.
+
+    This CLI provides system stats analysis through the lens of GRG/SGO
+    metrics, useful for monitoring system health and demonstrating the
+    GRG framework.
+    """
+    pass
+
+
+@main.command()
+@click.option(
+    "--profile",
+    "-p",
+    default="default",
+    help="GRG profile to use (default, high_sensitivity, low_latency, rag_grounded)",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output JSON file path")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--pretty", is_flag=True, help="Pretty print JSON output")
+def analyze(profile: str, output: str | None, verbose: bool, pretty: bool) -> None:
+    """Analyze system stats with GRG and SGO metrics."""
+    click.echo("🔍 Collecting system statistics...")
+    stats = collect_system_stats()
+
+    click.echo("📊 Running SGO structural geometry analysis...")
+    sgo_results = run_sgo_analysis(stats, verbose)
+
+    click.echo(f"🧠 Running GRG Alpha-drift tracking (profile: {profile})...")
+    grg_results = run_grg_analysis(stats, profile, verbose)
+
+    # Combine results
+    combined = {
+        "system_stats": stats,
+        "sgo_analysis": sgo_results,
+        "grg_analysis": grg_results,
+        "summary": {
+            "system_health": _assess_system_health(stats, sgo_results, grg_results),
+            "structural_alpha": sgo_results["summary"]["structural_alpha"],
+            "ranking_score": sgo_results["summary"]["ranking_score"],
+            "grg_state": grg_results["final_stats"],
+            "remediation_actions": grg_results["remediation_actions"],
+        },
+    }
+
+    # Output
+    indent = 2 if pretty else None
+    json_str = json.dumps(combined, indent=indent, default=str)
+
+    if output:
+        Path(output).write_text(json_str)
+        click.echo(f"✅ Results written to {output}")
+    else:
+        click.echo(json_str)
+
+    # Print human-readable summary
+    if verbose:
+        _print_summary(combined)
+
+
+@main.command()
+@click.option("--profile", "-p", default="default", help="GRG profile to use")
+@click.option("--steps", "-s", default=50, help="Number of simulation steps")
+@click.option("--output", "-o", type=click.Path(), help="Output JSON file path")
+def simulate(profile: str, steps: int, output: str | None) -> None:
+    """Run a simulated GRG tracking session with synthetic alpha decay."""
+    grg_config = get_config.get_grg_config(profile)
+    window_size = grg_config.get("window_size", 20)
+    ema_weight = grg_config.get("ema_weight", 0.3)
+
+    tracker = AlphaMomentumTracker(window_size=window_size, alpha_ema=ema_weight)
+
+    # Simulate alpha decay (mimicking hallucination onset)
+    np.random.seed(123)
+    alphas = []
+    current = 0.9
+    for i in range(steps):
+        # Gradual decay with noise
+        if i < steps // 3:
+            drift = np.random.normal(-0.001, 0.003)
+        elif i < 2 * steps // 3:
+            drift = np.random.normal(-0.005, 0.008)  # Accelerating decay
+        else:
+            drift = np.random.normal(-0.015, 0.015)  # Rapid collapse
+        current = max(0.0, min(1.0, current + drift))
+        alphas.append(current)
+        tracker.push(current)
+
+    final_stats = tracker.get_stats()
+
+    results = {
+        "profile": profile,
+        "steps": steps,
+        "alpha_sequence": alphas,
+        "final_stats": final_stats,
+        "collapse_detected": final_stats["is_collapsing"],
+        "structural_horizon": final_stats["horizon"],
+    }
+
+    indent = 2
+    json_str = json.dumps(results, indent=indent, default=str)
+
+    if output:
+        Path(output).write_text(json_str)
+        click.echo(f"✅ Simulation results written to {output}")
+    else:
+        click.echo(json_str)
+
+
+@main.command()
+@click.option("--profile", "-p", default="default", help="GRG profile to display")
+def config(profile: str) -> None:
+    """Show current GRG configuration."""
+    grg_config = get_config.get_grg_config(profile)
+    global_config = get_config._data["global"]
+
+    click.echo(f"📋 GRG Configuration (profile: {profile})")
+    click.echo("=" * 50)
+    click.echo(f"Global ranking_profile: {global_config.get('ranking_profile', 'N/A')}")
+    click.echo()
+    click.echo("GRG Settings:")
+    for key, value in grg_config.items():
+        click.echo(f"  {key}: {value}")
+
+
+@main.command()
+def profiles() -> None:
+    """List available GRG profiles."""
+    profiles_data = get_config._data.get("profiles", {})
+    click.echo("📋 Available GRG Profiles:")
+    click.echo("=" * 50)
+    for name, data in profiles_data.items():
+        grg = data.get("grg", {})
+        click.echo(f"  {name}:")
+        for key, value in grg.items():
+            click.echo(f"    {key}: {value}")
+        click.echo()
+
+
+def _assess_system_health(stats: dict, sgo: dict, grg: dict) -> str:
+    """Assess overall system health from metrics."""
+    cpu = stats["cpu"]["percent_total"]
+    mem = stats["memory"]["percent"]
+    alpha = sgo["summary"]["structural_alpha"]
+    collapsing = grg["final_stats"]["is_collapsing"]
+
+    if collapsing:
+        return "CRITICAL - Structural collapse detected"
+    elif cpu > 80 or mem > 85 or alpha < 0.3:
+        return "DEGRADED - High resource pressure"
+    elif cpu > 60 or mem > 70 or alpha < 0.5:
+        return "STRESSED - Elevated resource usage"
+    else:
+        return "HEALTHY - Normal operation"
+
+
+def _print_summary(results: dict[str, Any]) -> None:
+    """Print human-readable summary."""
+    summary = results["summary"]
+    sgo = results["sgo_analysis"]["summary"]
+    grg = results["grg_analysis"]["final_stats"]
+
+    click.echo("\n" + "=" * 60)
+    click.echo("📋 GRG/SGO ANALYSIS SUMMARY")
+    click.echo("=" * 60)
+    click.echo(f"System Health: {summary['system_health']}")
+    click.echo(f"Structural Alpha: {summary['structural_alpha']:.4f}")
+    click.echo(f"Ranking Score: {summary['ranking_score']:.4f}")
+    click.echo(f"Entropy: {sgo['entropy']:.4f}")
+    click.echo(f"Energy Ratio: {sgo['energy_ratio']:.4f}")
+    click.echo(f"Credibility: {sgo['credibility']:.4f}")
+    click.echo()
+    click.echo("GRG State:")
+    click.echo(f"  Alpha (EMA): {grg['alpha']:.4f}")
+    click.echo(f"  V_alpha: {grg['v_alpha']:.6f}")
+    click.echo(f"  M_alpha: {grg['m_alpha']:.6f}")
+    click.echo(f"  Horizon: {grg['horizon']:.1f} tokens")
+    click.echo(f"  Collapsing: {grg['is_collapsing']}")
+    click.echo(f"  Stable: {grg['is_stable']}")
+
+    if summary["remediation_actions"]:
+        click.echo()
+        click.echo("🚨 Remediation Actions Triggered:")
+        for action in summary["remediation_actions"]:
+            click.echo(f"  Step {action['step']}: {action['action']} ({action['trigger']})")
+
+
+if __name__ == "__main__":
+    main()

grg/config/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
+      }
+    }
+  }
+}