GRG — Geometric Reasoning Governor

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

pip install grg

For development:

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

---

Quick Start

Python API

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

# 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:

{
  "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

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

# 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

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

# 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)

# 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)

# 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

# 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

# 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

# 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)

{
  "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:

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 for details.

---

Citation

If you use GRG in research, please cite:

@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

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.