Metadata-Version: 2.4
Name: grg
Version: 0.2.1
Summary: Geometric Reasoning Governor (GRG) — Real-time structural integrity monitoring for LLM inference with Alpha-Drift Velocity tracking
Author-email: Nick Rotich <nick@example.com>
License: MIT
Keywords: llm,governor,structural-integrity,alpha-drift,hallucination-detection,token-monitoring,rag,sgo,geometric-reasoning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Dynamic: license-file

# GRG — Geometric Reasoning Governor

[![PyPI version](https://img.shields.io/pypi/v/grg.svg)](https://pypi.org/project/grg/)
[![Python versions](https://img.shields.io/pypi/pyversions/grg.svg)](https://pypi.org/project/grg/)
[![License](https://img.shields.io/pypi/l/grg.svg)](https://opensource.org/licenses/MIT)

**Real-time structural integrity monitoring for LLM inference using Alpha-Drift Velocity tracking.**

---

## Overview

The **Geometric Reasoning Governor (GRG)** is a governance layer for Large Language Models that monitors the structural integrity of generated output in real-time during token generation. It detects hallucination onset, logical collapse, and grounding loss by tracking **Structural Alpha (α)** and its **drift velocity (V_α)** — the rate of change in structural integrity per token.

When the model starts to drift, GRG applies three corrective interventions:

| Intervention | Trigger | Action |
|--------------|---------|--------|
| **Thermal Damping** | V_α < 0 | Dynamically reduce sampling temperature toward 0.0 (greedy decoding) |
| **Structural E-Stop** | α < α_critical (default 0.35) | Halt generation immediately, emit safe fallback |
| **Adversarial Reset** | V_α < V_panic or σ_α > 0.15 | Flush context, compress history, trigger fresh RAG grounding |

---

## Mathematical Foundation

### Structural Alpha (α)

Structural Alpha measures the "rigidity" of a model's reasoning — how well its outputs maintain logical consistency with the grounding context. It is derived from the **Structural Geometry Optimization (SGO)** cofactor matrix:

```
α = C₂₀ (cofactor at row 3, column 1)
```

This captures the structural tension between failure rate and success magnitude in the SGO framework.

### Alpha-Drift Velocity (V_α)

```
V_α(t) = dα/dt ≈ (α(t) - α(t-Δt)) / Δt
```

Computed via Exponential Moving Average (EMA) for noise resilience.

### Structural Horizon (H_s)

Predicted tokens remaining before logical collapse:

```
H_s = (α(t) - α_floor) / |V_α(t)|    (for V_α < 0)
```

---

## Installation

```bash
pip install grg
```

For development:

```bash
git clone https://github.com/moinonin/grg.git
cd grg
make install-dev
```

---

## Quick Start

### Python API

```python
from grg import AlphaMomentumTracker, evaluate_structural_geometry, get_config
import numpy as np

# 1. Real-time GRG tracking during token generation
tracker = AlphaMomentumTracker(window_size=20, alpha_ema=0.3)

for token_logprob in token_stream:
    # Compute structural alpha from token logprobs (via SGO matrix)
    alpha = compute_structural_alpha(token_logprob)  # Your implementation
    tracker.push(alpha)
    
    stats = tracker.get_stats()
    if stats["is_collapsing"]:
        # Trigger thermal damping
        temperature = max(0.0, base_temp * (1.0 + 10.0 * stats["v_alpha"]))
    if stats["horizon"] < 5:
        # Trigger E-Stop
        halt_generation()

# 2. Offline SGO evaluation of model outputs
positive_outcomes = np.array([0.8, 0.9, 0.7, 0.85])   # Grounded tokens
negative_outcomes = np.array([0.2, 0.15, 0.3])        # Hallucinated tokens

results = evaluate_structural_geometry(
    positive_outcomes=positive_outcomes,
    negative_outcomes=negative_outcomes,
    ranking_profile="conservative",
    regime_aware=True,
)

print(f"Structural Alpha: {results['structural_alpha']:.4f}")
print(f"Ranking Score: {results['ranking_score']:.4f}")
print(f"Entropy: {results['entropy']:.4f}")
print(f"Structurally Sound: {results['is_structurally_sound']}")
```

### CLI Usage

```bash
# Analyze system stats with GRG/SGO metrics
grg analyze --profile default --pretty

# Run simulated GRG tracking session
grg simulate --profile high_sensitivity --steps 100 --output simulation.json

# View configuration
grg config --profile rag_grounded

# List available profiles
grg profiles
```

---

## Configuration

GRG uses profile-based configuration via `grg-config.json`:

```json
{
  "global": {
    "ranking_profile": "conservative",
    "grg": {
      "window_size": 20,
      "ema_weight": 0.3,
      "warmup_steps": 50,
      "v_alpha_panic_threshold": -0.02,
      "alpha_safety_floor": 0.10,
      "e_stop_horizon": 5,
      "collapse_v_alpha_threshold": -0.02,
      "stability_v_alpha_threshold": 0.005
    }
  },
  "profiles": {
    "default": { "grg": { ... } },
    "high_sensitivity": { "grg": { "window_size": 16, "ema_weight": 0.4, ... } },
    "low_latency": { "grg": { "window_size": 12, "ema_weight": 0.5, ... } },
    "rag_grounded": { "grg": { "window_size": 24, "ema_weight": 0.25, ... } }
  }
}
```

### Profiles

| Profile | Use Case | Key Settings |
|---------|----------|--------------|
| `default` | General purpose | Balanced window (20), EMA (0.3) |
| `high_sensitivity` | Adversarial RAG, high-stakes | Smaller window (16), higher EMA (0.4), stricter thresholds |
| `low_latency` | Real-time inference, low overhead | Small window (12), high EMA (0.5), fast response |
| `rag_grounded` | Long-form RAG generation | Large window (24), low EMA (0.25), conservative thresholds |

---

## Core Concepts

### SGO (Structural Geometry Optimization)

GRG builds on the SGO framework for evaluating binary-outcome systems. The SGO matrix captures the moment coupling between positive and negative outcomes:

```
M = E[ [1, P_u, N_u]^T [1, P_u, N_u] ]
```

Where:
- `P_u` = sum of positive magnitudes in unit u (transformed by utility power)
- `N_u` = sum of negative magnitudes in unit u (transformed)

The **cofactor matrix** of M yields the structural alpha (α), which GRG tracks in real-time.

### AlphaMomentumTracker

The core GRG class providing:

- **EMA-smoothed alpha** — noise-resistant structural integrity
- **V_α (velocity)** — first derivative, drift direction and speed
- **M_α (momentum)** — second derivative, acceleration of collapse
- **Structural Horizon** — predicted safe tokens remaining
- **Collapse/Stability flags** — boolean triggers for interventions

```python
tracker = AlphaMomentumTracker(window_size=20, alpha_ema=0.3)
tracker.push(alpha_value)
stats = tracker.get_stats()
# {
#   "alpha": 0.72,           # EMA-smoothed structural integrity
#   "v_alpha": -0.015,       # Drift velocity (negative = decaying)
#   "m_alpha": -0.002,       # Momentum (negative = accelerating decay)
#   "horizon": 48.3,         # Predicted safe tokens remaining
#   "is_collapsing": True,   # V_α < panic_threshold
#   "is_stable": False       # |V_α| < threshold and α > floor
# }
```

### Ranking Profiles

Three built-in profiles for different risk tolerances:

| Profile | Structure Weight | Expectancy Weight | Best For |
|---------|------------------|-------------------|----------|
| `conservative` | 0.60 | 0.05 | High-stakes, safety-critical |
| `balanced` | 0.50 | 0.07 | General purpose |
| `aggressive` | 0.35 | 0.25 | Performance-oriented, trading |

---

## API Reference

### GRG Trackers

#### `AlphaMomentumTracker(window_size=20, alpha_ema=0.3)`
- `push(alpha: float)` — Add observation
- `get_stats(v_panic=None, floor=None)` — Get current state
- `get_structural_horizon(floor=0.75)` — Predict remaining safe tokens

#### `StructuralTracker(window_size=10)` — *Deprecated*
Legacy tracker without EMA smoothing. Use `AlphaMomentumTracker`.

### SGO Metrics

#### `evaluate_structural_geometry(...)`
Main evaluation function. Returns 40+ metrics including:
- `structural_alpha`, `ranking_score`, `entropy`
- `normalized_structure_term`, `energy_ratio`, `credibility`
- `n_matrix`, `ideal_matrix`, `cofactors`, `ideal_cofactors`
- `expectancy`, `normalized_expectancy`, `diagnostics`

#### `compute_sgo_matrix(outcome_units, utility_power=1.1)`
Theoretical moment matrix E[[1, P_u, N_u] [1, P_u, N_u]^T].

#### `calculate_moment_sgo_metrics(outcome_units, utility_power=1.1)`
Decoupled ideal matrix, ρ_pn, Frobenius error, cofactor consistency.

#### `evaluate_distributional_geometry(...)`
Soft-binned magnitude-segment analysis.

#### `compute_distributional_concentration(outcomes, deciles=10)`
Tail-risk concentration across magnitude deciles.

### Configuration

#### `get_config`
- `get(key, default)` — Global setting
- `get_profile(name)` — Full profile with globals merged
- `get_grg_config(profile_name)` — GRG settings only (global + profile)

---

## Development

### Setup

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Or use Make
make install-dev
```

### Make Targets

```bash
make help           # Show all targets
make install        # Install package
make install-dev    # Install with dev dependencies
make test           # Run tests with coverage
make lint           # Run ruff linting
make format         # Auto-format with ruff
make typecheck      # Run mypy type checking
make check          # Run all checks (lint + typecheck + test)
make build          # Build distribution packages
make clean          # Remove build artifacts
make cli            # Run CLI demo
```

### Testing

```bash
# Run all tests
pytest

# With coverage
pytest --cov=grg --cov-report=term-missing

# Specific test file
pytest tests/test_metrics.py -v
```

---

## Project Structure

```
grg/
├── pyproject.toml          # Package metadata, dependencies, tool config
├── README.md               # This file
├── Makefile                # Development targets
├── LICENSE                 # MIT License
├── src/
│   └── grg/
│       ├── __init__.py     # Public exports
│       ├── metrics.py      # Core SGO metrics + AlphaMomentumTracker
│       ├── config.py       # Configuration loader
│       ├── config/
│       │   └── grg-config.json  # GRG profiles
│       └── cli.py          # CLI entry point
├── tests/
│   ├── __init__.py
│   ├── test_metrics.py     # SGO metrics tests
│   ├── test_trackers.py    # AlphaMomentumTracker tests
│   └── test_config.py      # Config tests
└── docs/                   # Documentation (optional)
```

---

## Use Cases

1. **LLM Hallucination Detection** — Monitor V_α during generation to catch drift early
2. **RAG Grounding Verification** — Ensure retrieved context maintains structural integrity
3. **Model Comparison** — Compare structural sustainability across models via SVP
4. **Adversarial Robustness** — Detect and reset on adversarial prompt attacks
5. **Offline Evaluation** — SGO metrics for model selection and benchmarking
6. **System Health Monitoring** — CLI analyzes system stats through GRG lens (demo)

---

## GRG Agent (`examples/grg_agent/`)

An autonomous coding agent guided by GRG quality gates. Uses multi-provider LLM support (Ollama local, Hermes Proxy remote) to generate, verify, and iterate on code until it passes execution tests.

### Quick Start (Ollama)

```bash
# 1. Pull a model (if not already available)
ollama pull gemma4:12b

# 2. Run the agent on a coding task
cd examples/grg_agent
python -m grg_agent.hermes_skill "Create a webhook delivery service with retries and dead-letter handling" --provider ollama --model gemma4:12b
```

### Using Make Targets (from repo root)

```bash
# Quick test with default model
make grg-test

# Run with Ollama (local) - specify task and model
make grg-ollama TASK="implement binary search in Python" MODEL="gemma4:12b"

# Run with Hermes Proxy (remote API providers)
make grg-hermes TASK="implement binary search in Python" MODEL="nvidia/nemotron-3-ultra-550b-a55b"

# Auto-detect provider
make grg-auto TASK="implement binary search in Python"

# List available Ollama models
make grg-ollama-models
```

### Full Pipeline: NL → Spec → Plan → Execute → Runbook

```bash
# Generate validated spec from natural language
make grg-spec PROMPT="Create a webhook delivery service..." PROVIDER=ollama

# Generate plan from spec
make grg-plan SPEC=path/to/spec.yaml

# Execute plan with GRG quality gates
make grg-run PLAN=path/to/plan.json PROVIDER=ollama

# Verify runbook completeness
make grg-verify RUNBOOK=RUNBOOK.json

# Full end-to-end pipeline
make grg-full PROMPT="Create a webhook delivery service..." PROVIDER=ollama

# Clean generated artifacts (foreign/ directory)
make grg-clean
```

### Key Features

| Feature | Description |
|---------|-------------|
| **Multi-provider** | Ollama (local, free, logprobs) + Hermes Proxy (remote APIs) |
| **GRG Quality Gates** | Composite confidence = model_prob × α × (1 + max(0, Vα)) |
| **Diversity Control** | Temperature scheduling, cosine similarity filtering, strategy rotation |
| **Verification** | Syntax check, execution test, type checking (mypy) |
| **Isolation** | Generated code written to `foreign/` directory, never touches native project |
| **Runbook Output** | COMMAND_RUNWAY Layer 3 execution log (RUNBOOK.md + RUNBOOK.json) |

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      GRG AGENT                                   │
│  ┌─────────┐ ┌─────────┐ ┌─────────────────────────┐           │
│  │ PLANNER │ │ MONITOR │ │ DIVERSITY CONTROLLER    │           │
│  └────┬────┘ └────┬────┘ └───────────┬────────────┘           │
│       │         │                    │                        │
│       ▼         ▼                    ▼                        │
│  ┌─────────────────────────────────────────────────┐           │
│  │       MULTI-PROVIDER LLM CLIENT                 │           │
│  │  ┌──────────────┐    ┌──────────────────────┐  │           │
│  │  │ OllamaClient │    │ HermesProxyClient   │  │           │
│  │  │ (local:11434)│    │ (proxy:8465)        │  │           │
│  │  └──────────────┘    └──────────────────────┘  │           │
│  └─────────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────────┘
```

---

## HFT Trading Example (`examples/hft/`)

A complete high-frequency trading example demonstrating GRG applied to real-time BTC price streams from Hyperliquid.

### Features
- **Three modes**: `sim` (simulation), `dry` (live feed, no execution), `live` (real trading)
- **Real-time GRG tracking** on BTC price percentage changes (basis points)
- **Config-driven** — all parameters in `examples/hft/user_data/trader_config.json`
- **SQLite trade logging** — full GRG state at entry/exit + PnL + signals
- **Risk management** — daily loss limit, max drawdown, Kelly sizing, stop/take-profit

### Quick Start

```bash
# Simulation (no network needed)
python examples/hft/btc_momentum_tracker.py --simulate --duration 60

# Dry-run: live Hyperliquid feed, NO trades executed
# Set in config: "mode": "dry", "dry_run": true
python examples/hft/btc_momentum_tracker.py

# Live trading (requires API credentials)
# Set in config: "mode": "live", "dry_run": false
python examples/hft/btc_momentum_tracker.py
```

### Quick Start with Make

```bash
# Simulation (no network needed)
make sim              # 60-second simulation
make sim-fast         # 10-second simulation

# Dry-run: live Hyperliquid feed, NO trades executed
# Set in config: "mode": "dry", "dry_run": true
make dry

# Live trading (requires API credentials)
# Set in config: "mode": "live", "dry_run": false
make live

# Database
make hft-db           # Show recent trades with PnL/win rate
make hft-db-clean     # Remove trades database
```

### Configuration (`examples/hft/user_data/trader_config.json`)
```json
{
  "exchange": {
    "name": "hyperliquid",
    "mode": "sim",
    "dry_run": false,
    "ws_url": "wss://api.hyperliquid.xyz/ws",
    "rate_limit_ms": 100
  },
  "symbol": "BTC",
  "grg": {
    "profile": "high_sensitivity",
    "window_size": 16,
    "ema_weight": 0.4,
    "v_panic_threshold": -0.01,
    "alpha_safety_floor": 0.15
  },
  "strategy": {
    "v_alpha_entry_threshold": 0.001,
    "m_alpha_entry_threshold": 0.0005,
    "alpha_min_entry": 0.2,
    "v_alpha_exit_threshold": -0.0005,
    "m_alpha_exit_threshold": -0.0002,
    "alpha_critical": 0.1,
    "horizon_critical": 5.0,
    "stop_loss_bps": 10.0,
    "take_profit_bps": 30.0
  },
  "risk": {
    "total_capital": 100000.0,
    "max_leverage": 10.0,
    "max_position_pct": 0.05,
    "max_daily_loss_pct": 0.02,
    "max_drawdown_pct": 0.10,
    "kelly_fraction": 0.25,
    "base_risk_bps": 10.0
  },
  "database": { "path": "examples/hft/user_data/trades.db" }
}
```

### Terminal Output (Key Numbers)
```
[  10.5s] SIM:BTC   +0.044548% | α=+1.5434 Vα=+0.691303 Mα=+0.322194 Hₛ=∞ 🟢 STABLE  📈 LONG [LONG] PnL:+0.17%
```
| Field | Meaning | Action Threshold |
|-------|---------|------------------|
| **α** | Structural integrity | `< 0.1` = emergency exit |
| **Vα** | Trend velocity | `> 0.001` = long, `< -0.001` = short |
| **Mα** | Momentum/conviction | Sign flip = exit |
| **Hₛ** | Steps until collapse | `< 5` = reduce/exit |
| **🔴/🟢** | Collapse/Stable | 🔴 = exit immediately |

### Trade Database
SQLite at `examples/hft/user_data/trades.db` with full GRG state at entry/exit:
```python
from examples.hft.database import TradeDatabase
db = TradeDatabase('examples/hft/user_data/trades.db')
trades = db.get_recent_trades(10)
print(f"Total PnL: {db.get_total_pnl()*100:.4f}%")
print(f"Win rate: {db.get_win_rate():.1f}%")
```

### Project Structure (Updated)
```
grg/
├── examples/
│   └── hft/
│       ├── user_data/
│       │   ├── trader_config.json   # All config
│       │   └── trades.db            # SQLite (auto-created)
│       ├── config.py                # Typed config loader
│       ├── strategy.py              # HFTStrategy + risk mgmt
│       ├── database.py              # SQLite logger
│       └── btc_momentum_tracker.py  # Entry point
```

---

## Theoretical Applications Across Domains

GRG is fundamentally a **real-time structural integrity monitor for any binary-outcome stochastic process**. The core insight: *any system that produces success/failure outcomes with magnitudes can be modeled as an SGO process, and its structural alpha drift predicts catastrophic failure.*

### Financial Trading & Risk
| Application | Practicality | How It Works |
|-------------|--------------|--------------|
| **Strategy degradation monitor** | ★★★★★ | Each trade = outcome unit; α drift = strategy rot; E-Stop = halt trading |
| **Regime change detection** | ★★★★★ | V_α spike + σ_α spike = market regime shift; trigger re-calibration |
| **Tail-risk early warning** | ★★★★☆ | Co-factor C23 (α) captures win/loss coupling; collapse = correlated losses |
| **Position sizing via H_s** | ★★★★☆ | Structural Horizon → max position duration before expected drawdown |
| **Portfolio correlation monitor** | ★★★☆☆ | Multi-asset SGO matrix; cross-asset α drift = correlation breakdown |
| **Backtest overfitting detector** | ★★★★☆ | High in-sample α but low out-of-sample H_s = overfit |

### Control Systems & Robotics
| Application | Practicality | How It Works |
|-------------|--------------|--------------|
| **Safety-critical intervention** | ★★★★★ | Robot episode outcomes → α; V_α < V_panic = emergency stop |
| **Sim-to-real gap monitor** | ★★★★☆ | Track α in sim vs real; drift = domain shift; Adversarial Reset = domain randomization |
| **Policy degradation in deployment** | ★★★★☆ | Continuous α monitoring; Thermal Damping = increase exploration noise decay |
| **RL exploration scheduler** | ★★★★☆ | V_α > 0 → increase ε (exploring); V_α < 0 → decrease ε (exploiting) |

### Software Engineering & CI/CD
| Application | Practicality | How It Works |
|-------------|--------------|--------------|
| **Test suite health monitor** | ★★★★☆ | Each test = outcome (pass/fail + duration); α drift = flakiness creep |
| **Build reliability predictor** | ★★★★☆ | H_s = expected builds before catastrophic failure; schedule maintenance |
| **Deployment risk scoring** | ★★★☆☆ | Pre-deploy α from canary tests; low α = block deploy |
| **Technical debt accumulation** | ★★★☆☆ | Code changes = episodes; negative outcomes = bugs/reverts; α = codebase health |

### Healthcare & Medical AI
| Application | Practicality | How It Works |
|-------------|--------------|--------------|
| **Diagnostic model drift** | ★★★★★ | Each prediction = outcome; α monitors calibration drift in production |
| **Clinical trial monitoring** | ★★★★☆ | Patient outcomes = units; α drift = treatment efficacy decay / safety signal |
| **ICU early warning** | ★★★★★ | Vital sign trajectories = episodes; V_α = physiological collapse predictor |
| **Drug manufacturing QC** | ★★★★☆ | Batch outcomes = units; α = process stability; E-Stop = quarantine batch |

### Cybersecurity & Fraud
| Application | Practicality | How It Works |
|-------------|--------------|--------------|
| **Model adversarial robustness** | ★★★★☆ | σ_α spike = adversarial input; Adversarial Reset = re-verify with ensemble |
| **Fraud pattern drift** | ★★★★☆ | Transaction outcomes (legit/fraud + amount); α drift = new fraud pattern |
| **Intrusion detection health** | ★★★☆☆ | Alert outcomes (TP/FP/FN); α = detector reliability; Thermal Damping = threshold tuning |

### Scientific Computing & Simulation
| Application | Practicality | How It Works |
|-------------|--------------|--------------|
| **Numerical solver stability** | ★★★★☆ | Iteration outcomes (converge/diverge + residual); α = solver health |
| **MCMC convergence monitor** | ★★★★☆ | Sample quality = outcomes; α = effective sample size proxy; H_s = remaining burn-in |
| **Physics simulation validity** | ★★★☆☆ | Conservation law violations = negative outcomes; α = simulation fidelity |

### Cross-Cutting Meta-Applications

**A. Model Selection & Benchmarking (Structural Validation Profiling)**
- Run GRG on 1000+ prompts per model → compute median H_s, mean V_α
- Rank models by **reliability ceiling** not just accuracy
- Identify "correct but brittle" models (high accuracy, low H_s)

**B. Hyperparameter Optimization via GRG**
- Treat hyperparameter search as episodes
- α = validation performance stability
- V_α = sensitivity to hyperparameter changes
- Optimize for max H_s (robustness) not just peak accuracy

**C. Ensemble Weighting by Structural Health**
- Each ensemble member has real-time α
- Weight ∝ α × (1 + V_α)  (healthy + improving members get more weight)
- Auto-prune members with α < α_critical

**D. Continuous Learning Gatekeeper**
- Before model update: compute α on holdout
- If new model's α < old model's α - δ → reject update
- If V_α during A/B test < V_panic → immediate rollback

**E. Regulatory Compliance Dashboard**
- Export α, V_α, H_s per decision for audit
- Prove "model was structurally sound at inference time"
- Demonstrate guardrails were active (Thermal Damping logs, E-Stop events)

---

## Implementation Roadmap for New Domains

1. **Define "outcome unit"** — What constitutes one episode? (trade, prediction, test, patient, etc.)
2. **Define positive/negative magnitudes** — What's the payoff structure?
3. **Calibrate thresholds** — Use historical data to set V_panic, α_floor, H_s thresholds per domain
4. **Choose profile** — conservative/balanced/aggressive based on cost of false positive vs false negative
5. **Integrate interventions** — Map Thermal Damping/E-Stop/Adversarial Reset to domain actions
6. **Audit trail** — Log α, V_α, H_s per decision for compliance/debugging

---

## Practicality Assessment Matrix

| Domain | Data Availability | Real-time Need | Regulatory Pressure | **Overall** |
|--------|-------------------|----------------|---------------------|-------------|
| LLM Inference | ✅ High | ✅ Critical | ✅ Growing | ⭐⭐⭐⭐⭐ |
| HFT/Trading | ✅ High | ✅ Microsecond | ✅ High | ⭐⭐⭐⭐⭐ |
| Robotics/Safety | ✅ High | ✅ Millisecond | ✅ Critical | ⭐⭐⭐⭐⭐ |
| Medical AI | ✅ Medium | ✅ High | ✅✅✅ Critical | ⭐⭐⭐⭐ |
| CI/CD | ✅ High | ✅ Medium | ❌ Low | ⭐⭐⭐ |
| Fraud/Cyber | ✅ High | ✅ High | ✅ High | ⭐⭐⭐⭐ |
| Scientific Computing | ✅ Medium | ❌ Batch | ❌ Low | ⭐⭐ |
| Education | ✅ Medium | ✅ Medium | ❌ Low | ⭐⭐⭐ |

---

## Related Work

- **Karakana** — The parent framework from which GRG was extracted
- **SGO (Structural Geometry Optimization)** — The mathematical foundation
- **Spec-Forge** — Specification-driven development pipeline used in Karakana

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

## Citation

If you use GRG in research, please cite:

```bibtex
@software{grg2024,
  title = {Geometric Reasoning Governor (GRG)},
  author = {Nick Rotich},
  year = {2024},
  url = {https://github.com/moinonin/grg}
}
```
## Early Warning System

`grg.early_warning.EarlyWarningSystem` provides a streaming structural-collapse detector
based on the same moment-matrix / coupling-ratio machinery as GRG. It consumes a scalar
value stream (e.g. returns in basis points) and emits `EWIReading` records with:

- `warning` — structural fragility detected
- `collapse` — collapse flag
- `intervention_fired` — intervention trigger
- `ewi` — early-warning index
- `rho_pn_sq` — scale-invariant coupling ratio

```python
from grg import EarlyWarningSystem

ews = EarlyWarningSystem()  # optimal defaults
for value in stream:
    reading = ews.push(value)
    if reading.intervention_fired:
        # short / exit long
        ...
    if reading.warning is False and ews...:
        ...
```

Optimal defaults: `window_size=20, alpha_ema=0.3, k=3, lambda_=2.0, mu=3.0,
nu=0.5, safety_floor=0.10, panic_threshold=-0.02, e_stop_horizon=3.0, threshold=8.0`.
