grg 0.2.1__py3-none-any.whl

grg/__init__.py

@@ -0,0 +1,124 @@
+"""
+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.agent_governor import (
+    AgentTrajectoryGovernor,
+    GovernorAction,
+    AgentStepTelemetry,
+    GovernorDecision,
+)
+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,
+    compute_structural_alpha,
+    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",
+    "compute_structural_alpha",
+    "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",
+    # Agent Trajectory Governor
+    "AgentTrajectoryGovernor",
+    "GovernorAction",
+    "AgentStepTelemetry",
+    "GovernorDecision",
+]

grg/agent_governor.py

@@ -0,0 +1,375 @@
+"""
+Agent Trajectory Governor (GRG for Autonomous AI Agents).
+
+Applies Structural Geometric Optimization (SGO) and Kinematic Momentum Tracking
+to multi-turn autonomous agent trajectories.
+
+Monitors turn-by-turn health, detects loops, dead-ends, and error cascades
+turns in advance of budget exhaustion, and triggers targeted interventions:
+- Hint injection (re-anchoring)
+- State rollback (pruning failed turns)
+- Early stop (saving wasted inference budget)
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Sequence
+
+import numpy as np
+
+from .metrics import AlphaMomentumTracker, calculate_moment_sgo_metrics
+
+
+class GovernorAction(str, Enum):
+    """Recommended governor action for current agent turn."""
+    PROCEED = "PROCEED"              # Trajectory healthy, continue normal execution
+    WARN = "WARN"                    # Minor degradation, log warning
+    HINT = "HINT"                    # Inject reflection prompt / counter-bias
+    ROLLBACK = "ROLLBACK"            # Prune recent failing turns, reset state
+    ABORT = "ABORT"                  # Structural collapse detected, terminate trajectory
+
+
+@dataclass
+class AgentStepTelemetry:
+    """Telemetry captured from an agent at turn t."""
+    step_index: int
+    action_type: str = "tool_call"   # "tool_call", "thought", "final_answer"
+    tool_name: str | None = None
+    tool_args: dict[str, Any] | str | None = None
+    tool_success: bool = True
+    error_message: str | None = None
+    semantic_progress: float = 0.5   # Progress towards goal in [0.0, 1.0]
+    tokens_consumed: int = 0
+    extra_metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class GovernorDecision:
+    """Governor evaluation output for turn t."""
+    step_index: int
+    action: GovernorAction
+    alpha: float                     # Current structural health alpha in [0, 1]
+    v_alpha: float                   # Velocity of alpha change (EMA)
+    m_alpha: float                   # Momentum / acceleration of change (EMA)
+    horizon_turns: float             # Predicted turns before health drops below floor
+    rho_pn_sq: float                 # SGO win/loss coupling correlation squared
+    e_p: float                       # Positive utility expectation
+    e_n: float                       # Negative utility expectation
+    repetition_score: float          # Call repetition metric [0, 1]
+    message: str                     # Human/LLM-readable diagnostic explanation
+    suggested_hint: str | None = None
+    rollback_turns: int = 0
+
+
+class AgentTrajectoryGovernor:
+    """
+    Multi-Turn Agent Trajectory Governor using SGO and Momentum Kinematics.
+
+    Evaluates (P_u, N_u) utility pairs per turn:
+    - P_u (Positive Utility): Goal alignment, novelty, successful execution.
+    - N_u (Negative Utility): Execution errors, parameter looping, stagnation.
+
+    Tracks trajectory dynamics using AlphaMomentumTracker and Moment SGO metrics.
+    """
+
+    def __init__(
+        self,
+        window_size: int = 10,
+        alpha_ema: float = 0.35,
+        safety_floor: float = 0.15,
+        panic_threshold: float = -0.04,
+        repetition_threshold: float = 0.75,
+        hint_horizon: float = 4.0,
+        abort_horizon: float = 1.5,
+        min_steps_before_abort: int = 3,
+    ):
+        self.window_size = window_size
+        self.alpha_ema = alpha_ema
+        self.safety_floor = safety_floor
+        self.panic_threshold = panic_threshold
+        self.repetition_threshold = repetition_threshold
+        self.hint_horizon = hint_horizon
+        self.abort_horizon = abort_horizon
+        self.min_steps_before_abort = min_steps_before_abort
+
+        self.tracker = AlphaMomentumTracker(window_size=window_size, alpha_ema=alpha_ema)
+        self.history: list[AgentStepTelemetry] = []
+        self.outcomes: list[tuple[float, float]] = []  # (P_u, N_u) pairs
+        self.decisions: list[GovernorDecision] = []
+        self.consecutive_warnings: int = 0
+        self.consecutive_hints: int = 0
+
+    def reset(self) -> None:
+        """Reset governor state for a new agent trajectory."""
+        self.tracker = AlphaMomentumTracker(window_size=self.window_size, alpha_ema=self.alpha_ema)
+        self.history.clear()
+        self.outcomes.clear()
+        self.decisions.clear()
+        self.consecutive_warnings = 0
+        self.consecutive_hints = 0
+
+    def _normalize_args(self, args: dict[str, Any] | str | None) -> str:
+        """Convert tool arguments to a stable string representation for exact equality."""
+        if args is None:
+            return ""
+        if isinstance(args, str):
+            return args.strip()
+        try:
+            return json.dumps(args, sort_keys=True)
+        except Exception:
+            return str(args)
+
+    def _extract_arg_values(self, args: dict[str, Any] | str | None) -> str:
+        """Extract argument values to compare similarity without JSON key boilerplate."""
+        if args is None:
+            return ""
+        if isinstance(args, str):
+            return args.strip()
+        if isinstance(args, dict):
+            return " ".join(str(v) for v in args.values()).strip()
+        return str(args).strip()
+
+    def _compute_repetition_penalty(
+        self, current: AgentStepTelemetry, history: list[AgentStepTelemetry] | None = None
+    ) -> float:
+        """
+        Check for repetitive or oscillating tool calls in recent history.
+        Returns penalty in [0.0, 1.0].
+        """
+        hist = self.history if history is None else history
+        if not hist or current.tool_name is None:
+            return 0.0
+
+        current_norm = self._normalize_args(current.tool_args)
+        current_vals = self._extract_arg_values(current.tool_args)
+        lookback = min(len(hist), self.window_size)
+        recent = hist[-lookback:]
+
+        max_sim = 0.0
+        exact_matches = 0
+
+        for past in reversed(recent):
+            if past is current or past.step_index == current.step_index:
+                continue
+            if past.tool_name != current.tool_name:
+                continue
+
+            past_norm = self._normalize_args(past.tool_args)
+            if current_norm == past_norm:
+                exact_matches += 1
+                max_sim = max(max_sim, 1.0)
+            else:
+                past_vals = self._extract_arg_values(past.tool_args)
+                ratio = difflib.SequenceMatcher(None, current_vals, past_vals).ratio()
+                max_sim = max(max_sim, ratio)
+
+        if exact_matches >= 2:
+            return 1.0
+        if exact_matches == 1:
+            return 0.75
+        if max_sim >= 0.90:
+            return 0.50
+        return 0.0
+
+    def _compute_step_utilities(
+        self, step: AgentStepTelemetry, rep_penalty: float
+    ) -> tuple[float, float]:
+        """
+        Derive positive (P_u) and negative (N_u) utility for this turn.
+        """
+        # 1. Positive utility: goal progress scaled by execution success and novelty
+        base_progress = max(0.0, min(1.0, float(step.semantic_progress)))
+        if step.tool_success:
+            p_u = base_progress * (1.0 - 0.5 * rep_penalty)
+            # Extra reward for completed goal or milestone
+            if step.action_type == "final_answer":
+                p_u += 0.5
+        else:
+            # Failed tool call provides minimal positive learning signal
+            p_u = base_progress * 0.15
+
+        # 2. Negative utility: failure penalty + repetition + stall
+        n_u = 0.0
+        if not step.tool_success:
+            n_u += 1.0
+        if rep_penalty > 0:
+            n_u += rep_penalty * 1.5
+        if step.error_message:
+            n_u += 0.5
+        if step.semantic_progress < 0.15:
+            n_u += 0.25
+
+        return (max(0.0, p_u), max(0.0, n_u))
+
+    def step(self, telemetry: AgentStepTelemetry) -> GovernorDecision:
+        """
+        Record a step and evaluate trajectory health.
+        Returns GovernorDecision with recommended action.
+        """
+        rep_score = self._compute_repetition_penalty(telemetry, self.history)
+        p_u, n_u = self._compute_step_utilities(telemetry, rep_score)
+        self.history.append(telemetry)
+        self.outcomes.append((p_u, n_u))
+
+        # Evaluate SGO metrics over recent window
+        window_outcomes = self.outcomes[-self.window_size:]
+        if len(window_outcomes) < 2:
+            # Single observation has geometric cosine of 1.0 trivially; requires >= 2 samples
+            rho_pn_sq = 0.0
+            e_p = float(p_u)
+            e_n = float(n_u)
+        else:
+            # Build Moment SGO units: positive returns > 0, negative returns < 0
+            sgo_units: list[np.ndarray] = []
+            for p, n in window_outcomes:
+                if p > 0 and n > 0:
+                    sgo_units.append(np.array([p, -n], dtype=float))
+                elif p > 0:
+                    sgo_units.append(np.array([p], dtype=float))
+                elif n > 0:
+                    sgo_units.append(np.array([-n], dtype=float))
+                else:
+                    sgo_units.append(np.array([0.0], dtype=float))
+
+            try:
+                sgo_metrics = calculate_moment_sgo_metrics(sgo_units)
+                rho_pn_sq = float(sgo_metrics["rho_pn_sq"])
+                e_p = float(sgo_metrics["e_p"])
+                e_n = float(sgo_metrics["e_n"])
+            except Exception:
+                rho_pn_sq = 0.0
+                e_p = float(p_u)
+                e_n = float(n_u)
+
+        # SGO Structural Alpha for Agent:
+        # Bounded in [0, 1]. High when P > N and P, N are decoupled.
+        # Degrades when N >> P or when failure co-occurs repeatedly with stall (rho_pn_sq -> 1).
+        balance_ratio = e_p / (e_p + e_n + 1e-8)
+        coupling_discount = 1.0 - 0.7 * min(1.0, rho_pn_sq)
+        raw_alpha = float(balance_ratio * coupling_discount)
+        step_alpha = max(0.0, min(1.0, raw_alpha))
+
+        # Push to kinematic tracker
+        self.tracker.push(step_alpha)
+        stats = self.tracker.get_stats(v_panic=self.panic_threshold, floor=self.safety_floor)
+
+        v_alpha = float(stats["v_alpha"])
+        m_alpha = float(stats["m_alpha"])
+        horizon = float(stats["horizon"])
+
+        # Decision Policy Logic
+        action = GovernorAction.PROCEED
+        hint: str | None = None
+        rollback_turns = 0
+        reason: list[str] = []
+
+        # Check for immediate hard loop
+        failed_repeat = (not telemetry.tool_success) and (rep_score >= 0.75)
+        if failed_repeat:
+            reason.append(f"Failing tool call '{telemetry.tool_name}' repeated.")
+
+        # Kinematic checks
+        if stats["is_collapsing"] or v_alpha < self.panic_threshold:
+            reason.append(f"Rapid health velocity collapse (V_α={v_alpha:.3f} < {self.panic_threshold}).")
+
+        if m_alpha < self.panic_threshold / 2.0 and v_alpha < 0:
+            reason.append(f"Accelerating trajectory decay (M_α={m_alpha:.3f}).")
+
+        if horizon <= self.hint_horizon and horizon < 900:
+            reason.append(f"Remaining safe horizon low (H={horizon:.1f} turns).")
+
+        # Determine GovernorAction level
+        can_abort = len(self.history) >= self.min_steps_before_abort
+        if can_abort and (
+            step_alpha < self.safety_floor
+            or (horizon <= self.abort_horizon and v_alpha < -0.05)
+            or self.consecutive_hints >= 3
+        ):
+            action = GovernorAction.ABORT
+            msg = f"ABORT: Trajectory collapsed (α={step_alpha:.3f}, H={horizon:.1f}). " + " ".join(reason)
+        elif (
+            m_alpha < self.panic_threshold
+            or (rep_score >= 1.0 and not telemetry.tool_success)
+            or (self.consecutive_hints >= 1 and failed_repeat)
+            or (self.consecutive_warnings >= 2 and v_alpha < self.panic_threshold)
+        ):
+            action = GovernorAction.ROLLBACK
+            rollback_turns = min(3, max(1, len(self.history) - 1))
+            msg = f"ROLLBACK: Severe stagnation or loop detected (α={step_alpha:.3f}, M_α={m_alpha:.3f}). " + " ".join(reason)
+            hint = self._build_reflection_hint(telemetry)
+        elif horizon <= self.hint_horizon or v_alpha < self.panic_threshold or failed_repeat or (not can_abort and step_alpha < self.safety_floor):
+            action = GovernorAction.HINT
+            self.consecutive_hints += 1
+            msg = f"HINT: Trajectory degrading (α={step_alpha:.3f}, V_α={v_alpha:.3f}, H={horizon:.1f}). " + " ".join(reason)
+            hint = self._build_reflection_hint(telemetry)
+        elif v_alpha < self.panic_threshold / 2.0 or rep_score >= 0.5:
+            action = GovernorAction.WARN
+            self.consecutive_warnings += 1
+            msg = f"WARN: Trajectory softening (α={step_alpha:.3f}, V_α={v_alpha:.3f}). " + " ".join(reason)
+        else:
+            action = GovernorAction.PROCEED
+            self.consecutive_warnings = 0
+            self.consecutive_hints = 0
+            msg = f"PROCEED: Trajectory healthy (α={step_alpha:.3f}, V_α={v_alpha:.3f}, H={horizon:.1f})."
+
+        decision = GovernorDecision(
+            step_index=telemetry.step_index,
+            action=action,
+            alpha=step_alpha,
+            v_alpha=v_alpha,
+            m_alpha=m_alpha,
+            horizon_turns=horizon,
+            rho_pn_sq=rho_pn_sq,
+            e_p=e_p,
+            e_n=e_n,
+            repetition_score=rep_score,
+            message=msg,
+            suggested_hint=hint,
+            rollback_turns=rollback_turns,
+        )
+        self.decisions.append(decision)
+        return decision
+
+    def _build_reflection_hint(self, step: AgentStepTelemetry) -> str:
+        """Construct an actionable prompt reflection hint for the agent."""
+        if step.tool_name == "write_file" and step.tool_success:
+            return "File changes written successfully. Next step: call run_tests() to verify your fix."
+
+        parts = ["CRITICAL GOVERNANCE ALERT: Trajectory is degenerating."]
+        if step.tool_name:
+            parts.append(f"- Tool '{step.tool_name}' failed or repeated without forward progress.")
+        if step.error_message:
+            short_err = step.error_message[:120].strip()
+            parts.append(f"- Last error: {short_err}")
+        parts.append("- Mandate: Do NOT repeat the exact same command or query.")
+        parts.append("- Mandate: Check available files with list_files(), inspect code with read_file(), or run verification tests.")
+        return " ".join(parts)
+
+    def get_summary(self) -> dict[str, Any]:
+        """Trajectory governance diagnostic summary."""
+        total_steps = len(self.history)
+        if total_steps == 0:
+            return {"total_steps": 0, "status": "NO_STEPS"}
+
+        alphas = [d.alpha for d in self.decisions]
+        actions = [d.action.value for d in self.decisions]
+        aborted = any(d.action == GovernorAction.ABORT for d in self.decisions)
+        rollbacks = sum(1 for d in self.decisions if d.action == GovernorAction.ROLLBACK)
+        hints = sum(1 for d in self.decisions if d.action == GovernorAction.HINT)
+
+        return {
+            "total_steps": total_steps,
+            "final_alpha": alphas[-1] if alphas else 0.0,
+            "min_alpha": min(alphas) if alphas else 0.0,
+            "mean_alpha": float(np.mean(alphas)) if alphas else 0.0,
+            "aborted": aborted,
+            "rollback_count": rollbacks,
+            "hint_count": hints,
+            "action_counts": {
+                act: actions.count(act) for act in {a.value for a in GovernorAction}
+            },
+        }