consequence-gate 0.1.0__py3-none-any.whl

consequence_gate/__init__.py

@@ -0,0 +1,3 @@
+"""consequence-gate: speculative outcome-simulation layer for AI agent tool calls."""
+
+__version__ = "0.1.0"

consequence_gate/backtest/harness.py

@@ -0,0 +1,43 @@
+"""
+Offline backtest harness: replays historical JSONL tool-call traces
+through a simulator + evaluator, WITHOUT re-executing anything, to
+measure the four-quadrant FP/FN/TN/steer-recovery breakdown against
+the trace's recorded existing_gate_decision and actual_execution_status.
+"""
+
+import json
+from typing import Callable, Dict, Iterable, List
+
+
+def load_traces(path: str) -> List[Dict]:
+    traces = []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                traces.append(json.loads(line))
+    return traces
+
+
+def run_backtest(traces: Iterable[Dict], simulate_and_evaluate: Callable[[Dict], str]) -> List[Dict]:
+    """
+    simulate_and_evaluate: function(trace) -> decision string ("ALLOW"/"DENY"/"ASK"/"STEER")
+    Returns per-trace records annotated with quadrant classification.
+    """
+    results = []
+    for trace in traces:
+        new_decision = simulate_and_evaluate(trace)
+        old_decision = trace.get("existing_gate_decision", "ALLOW")
+        outcome = trace.get("actual_execution_status", "UNKNOWN")
+
+        if old_decision == "ALLOW" and new_decision in ("DENY", "STEER", "ASK") and outcome != "SUCCESS":
+            quadrant = "FALSE_NEGATIVE_CAUGHT"
+        elif old_decision in ("DENY", "ASK") and new_decision == "ALLOW":
+            quadrant = "FALSE_POSITIVE_RELIEVED"
+        elif old_decision == "ALLOW" and new_decision == "ALLOW":
+            quadrant = "TRUE_NEGATIVE"
+        else:
+            quadrant = "OTHER"
+
+        results.append({**trace, "simulated_decision": new_decision, "quadrant": quadrant})
+    return results

consequence_gate/backtest/reporter.py

@@ -0,0 +1,20 @@
+"""
+Generates the four-quadrant FP/FN breakdown report from backtest results.
+"""
+
+from collections import Counter
+from typing import Dict, List
+
+
+def generate_report(results: List[Dict]) -> Dict:
+    counts = Counter(r["quadrant"] for r in results)
+    total = len(results)
+    return {
+        "total_traces": total,
+        "true_negative": counts.get("TRUE_NEGATIVE", 0),
+        "false_negative_caught": counts.get("FALSE_NEGATIVE_CAUGHT", 0),
+        "false_positive_relieved": counts.get("FALSE_POSITIVE_RELIEVED", 0),
+        "other": counts.get("OTHER", 0),
+        "false_negative_rate": counts.get("FALSE_NEGATIVE_CAUGHT", 0) / total if total else 0.0,
+        "false_positive_relief_rate": counts.get("FALSE_POSITIVE_RELIEVED", 0) / total if total else 0.0,
+    }

consequence_gate/cli.py

@@ -0,0 +1,75 @@
+"""
+CLI entry point for consequence-gate.
+"""
+
+import argparse
+import json
+import sys
+from consequence_gate import __version__
+from consequence_gate.backtest.harness import load_traces, run_backtest
+from consequence_gate.backtest.reporter import generate_report
+
+
+def default_evaluator(trace: dict) -> str:
+    """Heuristic evaluator for CLI demo and trace analysis."""
+    tool = trace.get("tool_name", "")
+    args = trace.get("tool_args", {})
+
+    tool_lower = tool.lower()
+    args_str = str(args).lower()
+
+    if any(k in tool_lower for k in ("delete", "drop", "purge", "truncate")) or any(
+        k in args_str for k in ("drop ", "delete from", "truncate ", "purge")
+    ):
+        return "DENY"
+    if "transfer" in tool.lower() or "pay" in tool.lower():
+        amount = args.get("amount", 0)
+        if isinstance(amount, (int, float)) and amount > 5000:
+            return "ASK"
+    return "ALLOW"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="consequence-gate",
+        description="Speculative outcome-simulation gate & trace backtesting for AI agent tool calls.",
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Backtest subcommand
+    bt_parser = subparsers.add_parser("backtest", help="Run offline backtesting on a JSONL trace file")
+    bt_parser.add_argument("file", help="Path to JSONL file containing recorded agent traces")
+    bt_parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+
+    args = parser.parse_args()
+
+    if args.command == "backtest":
+        try:
+            traces = load_traces(args.file)
+            results = run_backtest(traces, default_evaluator)
+            report = generate_report(results)
+
+            if args.json:
+                print(json.dumps(report, indent=2))
+            else:
+                print("\n================ CONSEQUENCE GATE BACKTEST REPORT ================")
+                print(f"Total Traces Evaluated:      {report['total_traces']}")
+                print(f"True Negatives:              {report['true_negative']}")
+                print(f"False Negatives Caught:      {report['false_negative_caught']}")
+                print(f"False Positives Relieved:    {report['false_positive_relieved']}")
+                print(f"Other / Unclassified:        {report['other']}")
+                print("-----------------------------------------------------------------")
+                print(f"False Negative Catch Rate:   {report['false_negative_rate']:.2%}")
+                print(f"False Positive Relief Rate:  {report['false_positive_relief_rate']:.2%}")
+                print("=================================================================\n")
+        except Exception as e:
+            print(f"Error executing backtest: {e}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

consequence_gate/core/circuit_breaker.py

@@ -0,0 +1,56 @@
+"""
+SteerCircuitBreaker: idempotency-locked retry cap for STEER decisions.
+
+Design contract (see project history / design notes):
+- The idempotency token is derived ONCE from the transaction's own natural
+  key (e.g. claim_id, table+filter hash) -- never regenerated per retry.
+  A fresh UUID per attempt defeats duplicate-execution protection.
+- Responses are cached per token, so a retry with the same natural key
+  returns the cached result instead of re-executing (Stripe-style contract).
+- Retry count is tracked server-side per token, with a hard cap. Once
+  exceeded, the breaker forces ASK (human escalation) regardless of how
+  good the steering guidance is -- this is a backstop against
+  loop-thrashing, independent of guidance quality.
+"""
+
+from typing import Any, Dict
+from .models import GateDecision, EvaluationResult
+
+
+class SteerCircuitBreaker:
+    def __init__(self, max_retries: int = 2):
+        self.max_retries = max_retries
+        self._attempts: Dict[str, int] = {}
+        self._responses: Dict[str, EvaluationResult] = {}
+
+    def token_for(self, natural_key: str) -> str:
+        return f"steer_{natural_key}"
+
+    def resolve(self, natural_key: str, confidence: float,
+                base_steer: Dict[str, Any]) -> EvaluationResult:
+        token = self.token_for(natural_key)
+
+        if token in self._responses:
+            return self._responses[token]
+
+        attempt = self._attempts.get(token, 0)
+
+        if attempt >= self.max_retries:
+            result = EvaluationResult(
+                decision=GateDecision.ASK,
+                confidence=confidence,
+                reason=f"Steer circuit breaker tripped ({attempt}/{self.max_retries}). Escalating to human.",
+            )
+            self._responses[token] = result
+            return result
+
+        self._attempts[token] = attempt + 1
+        base_steer.setdefault("suggested_args", {})["idempotency_key"] = token
+
+        result = EvaluationResult(
+            decision=GateDecision.STEER,
+            confidence=confidence,
+            reason=f"Steered to safer path (attempt {attempt + 1}/{self.max_retries}).",
+            steer_payload=base_steer,
+        )
+        return result

consequence_gate/core/evaluator.py

@@ -0,0 +1,27 @@
+"""
+BlastRadiusEvaluator: generic threshold evaluation for simulated deltas.
+Domain simulators typically implement their own evaluate() with
+domain-specific rules, but this provides a reusable default.
+"""
+
+from .models import SimulatedStateDelta, GateDecision
+
+
+class BlastRadiusEvaluator:
+    def __init__(self, max_irreversible_value: float = 1000.0,
+                 min_confidence_for_autopass: float = 0.85):
+        self.max_irreversible_value = max_irreversible_value
+        self.min_confidence_for_autopass = min_confidence_for_autopass
+
+    def evaluate(self, delta: SimulatedStateDelta) -> GateDecision:
+        if delta.confidence < self.min_confidence_for_autopass:
+            return GateDecision.ASK
+
+        breach = any(abs(v) > self.max_irreversible_value
+                      for v in delta.numeric_deltas.values())
+
+        if delta.irreversibility_score >= 0.9 and breach:
+            return GateDecision.STEER
+        if breach:
+            return GateDecision.ASK
+        return GateDecision.ALLOW

consequence_gate/core/models.py

@@ -0,0 +1,35 @@
+"""
+Core data models shared across all domain simulators.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class GateDecision(str, Enum):
+    ALLOW = "ALLOW"
+    DENY = "DENY"
+    ASK = "ASK"
+    STEER = "STEER"
+
+
+@dataclass
+class SimulatedStateDelta:
+    """Generic projected-outcome envelope. Domain simulators subclass or
+    populate this with their own numeric_deltas / side-effect semantics."""
+    tool_name: str
+    proposed_args: Dict[str, Any]
+    numeric_deltas: Dict[str, float] = field(default_factory=dict)
+    irreversibility_score: float = 0.0   # 0.0 fully reversible -> 1.0 irreversible
+    confidence: float = 0.0              # 0.0 -> 1.0, simulator's own confidence in this projection
+    simulated_side_effects: List[str] = field(default_factory=list)
+    natural_key: Optional[str] = None    # stable identity for idempotency (NOT a random token)
+
+
+@dataclass
+class EvaluationResult:
+    decision: GateDecision
+    confidence: float
+    reason: str
+    steer_payload: Optional[Dict[str, Any]] = None

consequence_gate/integrations/examples/run_langgraph.py

@@ -0,0 +1,60 @@
+"""
+Example: Use consequence-gate with LangGraph agents via middleware.
+
+Usage:
+    python -m consequence_gate.integrations.examples.run_langgraph
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+
+from consequence_gate.integrations.langgraph_hook import create_financial_gate_middleware
+
+
+@tool
+def process_claim(amount: float, claim_id: str, currency: str = "INR", payout_method: str = "standard_ach") -> str:
+    """Process a claim payout."""
+    return f"Processed claim {claim_id} for {amount} {currency} via {payout_method}"
+
+
+def main():
+    # Create middleware
+    middleware = create_financial_gate_middleware(
+        daily_tier_limit_inr=25000.0,
+        instant_wire_threshold=10000.0,
+        max_retries=2,
+        context_provider=lambda state: {
+            "account_rolling_24h_spend": 0.0,
+            "kyc_verified": True,
+        },
+    )
+
+    # Create agent with middleware
+    agent = create_agent(
+        model="claude-sonnet-4",
+        tools=[process_claim],
+        middleware=[middleware],
+    )
+
+    print("LangGraph example:")
+    print("Agent created with consequence-gate middleware")
+    print()
+    print("Try this invocation:")
+    print('agent.invoke({"messages": [("user", "Process claim for 50,000 INR")]})')
+    print()
+    print("Expected behavior:")
+    print("- The agent will propose a tool call: process_claim(amount=50000, ...)")
+    print("- The middleware will intercept and simulate the outcome")
+    print("- Since 50,000 INR exceeds the 25,000 INR tier limit, the middleware will return:")
+    print('  ToolMessage(content="STEER_GUIDANCE: Cannot process full 50,000 INR...")')
+    print("- The agent will see this as the tool result and can retry with a safer alternative")
+
+
+if __name__ == "__main__":
+    main()

consequence_gate/integrations/examples/run_mcp_proxy.py

@@ -0,0 +1,100 @@
+"""
+Example: Run consequence-gate as an MCP proxy.
+
+This script demonstrates how to run the MCP proxy in front of a downstream
+MCP server. The proxy intercepts tools/call requests, runs consequence
+simulation, and either allows, denies, asks, or steers the call.
+
+Usage:
+    # Financial disbursement gate
+    python -m consequence_gate.integrations.examples.run_mcp_proxy financial \\
+        --downstream-command "npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb" \\
+        --daily-tier-limit 25000 \\
+        --instant-wire-threshold 10000
+
+    # Database deletion gate
+    python -m consequence_gate.integrations.examples.run_mcp_proxy database \\
+        --downstream-command "npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb" \\
+        --max-autonomous-delete-rows 100
+
+    # Communications blast gate
+    python -m consequence_gate.integrations.examples.run_mcp_proxy communications \\
+        --downstream-command "npx -y @modelcontextprotocol/server-sendgrid" \\
+        --max-autonomous-recipients 10000
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from consequence_gate.integrations.mcp_proxy import (
+    create_financial_mcp_proxy,
+    create_database_mcp_proxy,
+    create_communications_mcp_proxy,
+)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Run consequence-gate MCP proxy")
+    subparsers = parser.add_subparsers(dest="domain", required=True)
+
+    # Financial subcommand
+    financial_parser = subparsers.add_parser("financial", help="Financial disbursement gate")
+    financial_parser.add_argument("--downstream-command", required=True, help="Downstream MCP server command")
+    financial_parser.add_argument("--daily-tier-limit", type=float, default=25000.0)
+    financial_parser.add_argument("--instant-wire-threshold", type=float, default=10000.0)
+    financial_parser.add_argument("--max-retries", type=int, default=2)
+
+    # Database subcommand
+    db_parser = subparsers.add_parser("database", help="Database deletion gate")
+    db_parser.add_argument("--downstream-command", required=True, help="Downstream MCP server command")
+    db_parser.add_argument("--max-autonomous-delete-rows", type=int, default=100)
+    db_parser.add_argument("--max-retries", type=int, default=2)
+
+    # Communications subcommand
+    comm_parser = subparsers.add_parser("communications", help="Communications blast gate")
+    comm_parser.add_argument("--downstream-command", required=True, help="Downstream MCP server command")
+    comm_parser.add_argument("--max-autonomous-recipients", type=int, default=10000)
+    comm_parser.add_argument("--canary-min-size", type=int, default=100)
+    comm_parser.add_argument("--max-retries", type=int, default=2)
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    downstream_command = args.downstream_command.split()
+
+    if args.domain == "financial":
+        proxy = create_financial_mcp_proxy(
+            downstream_command=downstream_command,
+            daily_tier_limit_inr=args.daily_tier_limit,
+            instant_wire_threshold=args.instant_wire_threshold,
+            max_retries=args.max_retries,
+        )
+    elif args.domain == "database":
+        proxy = create_database_mcp_proxy(
+            downstream_command=downstream_command,
+            max_autonomous_delete_rows=args.max_autonomous_delete_rows,
+            max_retries=args.max_retries,
+        )
+    elif args.domain == "communications":
+        proxy = create_communications_mcp_proxy(
+            downstream_command=downstream_command,
+            max_autonomous_recipients=args.max_autonomous_recipients,
+            canary_min_size=args.canary_min_size,
+            max_retries=args.max_retries,
+        )
+    else:
+        raise ValueError(f"Unknown domain: {args.domain}")
+
+    print(f"Starting consequence-gate MCP proxy ({args.domain} domain)...", file=sys.stderr)
+    print(f"Downstream command: {' '.join(downstream_command)}", file=sys.stderr)
+    print("Reading from stdin, writing to stdout...", file=sys.stderr)
+
+    proxy.run()
+
+
+if __name__ == "__main__":
+    main()

consequence_gate/integrations/langgraph_hook.py

@@ -0,0 +1,197 @@
+"""
+LangGraph integration: middleware that wraps tool calls with consequence gating.
+
+Two patterns supported:
+1. @wrap_tool_call decorator - intercepts tool execution in LangGraph agents
+2. Custom ToolNode wrapper - for StateGraph workflows with explicit ToolNode
+
+Reference:
+- Agent Middleware: https://www.langchain.com/blog/agent-middleware
+- wrap_tool_call: https://mcpservers.org/agent-skills/langchain-ai/langchain-middleware
+- ToolNode: https://reference.langchain.com/python/langgraph.prebuilt/tool_node/ToolNode
+"""
+
+from typing import Any, Callable, Dict, Optional
+import json
+
+try:
+    from langchain_core.messages import ToolMessage
+    from langchain.tools.tool_node import ToolCallRequest
+except ImportError:
+    ToolMessage = None
+    ToolCallRequest = None
+
+from ..core.models import GateDecision, EvaluationResult
+from ..core.circuit_breaker import SteerCircuitBreaker
+from ..simulators.financial import FinancialDeltaPredictor
+from ..simulators.database import DataDeletionSimulator
+from ..simulators.communications import OutboundCommunicationSimulator
+
+
+def create_consequence_middleware(
+    simulator_fn: Callable[[str, Dict[str, Any], Dict[str, Any]], Any],
+    evaluator_fn: Callable[[Any, SteerCircuitBreaker], EvaluationResult],
+    circuit_breaker: Optional[SteerCircuitBreaker] = None,
+    context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+):
+    """
+    Factory for creating a LangGraph middleware that wraps tool calls.
+
+    Usage:
+        from langchain.agents import create_agent
+        from consequence_gate.integrations.langgraph_hook import create_consequence_middleware
+
+        middleware = create_consequence_middleware(
+            simulator_fn=financial_simulator,
+            evaluator_fn=evaluator,
+            circuit_breaker=SteerCircuitBreaker(),
+        )
+
+        agent = create_agent(
+            model="claude-sonnet-4",
+            tools=[my_tool],
+            middleware=[middleware],
+        )
+    """
+    from langchain.agents.middleware import wrap_tool_call
+
+    breaker = circuit_breaker or SteerCircuitBreaker(max_retries=2)
+    context_fn = context_provider or (lambda state: {})
+
+    @wrap_tool_call
+    def consequence_gate_wrapper(request: ToolCallRequest, handler):
+        """
+        Wrap tool calls to run consequence simulation before execution.
+
+        Args:
+            request: ToolCallRequest with tool_call dict and state
+            handler: function to call to actually execute the tool
+
+        Returns:
+            Tool execution result, or raises exception for DENY,
+            or returns ToolMessage with guidance for STEER.
+        """
+        tool_call = request.tool_call
+        tool_name = tool_call.get("name", "unknown")
+        arguments = tool_call.get("args", {})
+        state = request.state or {}
+        context = context_fn(state)
+
+        # Extract natural key for idempotency
+        natural_key = arguments.get("claim_id") or arguments.get("transaction_ref") or f"{tool_name}:{json.dumps(arguments, sort_keys=True)}"
+
+        # Run simulation + evaluation
+        delta = simulator_fn(tool_name, arguments, context)
+        result = evaluator_fn(delta, breaker)
+
+        if result.decision == GateDecision.ALLOW:
+            # Pass through - tool executes normally
+            return handler(request)
+
+        if result.decision == GateDecision.DENY:
+            # Hard block - raise exception that becomes a ToolMessage error
+            raise ValueError(f"BLOCKED: {result.reason}")
+
+        if result.decision == GateDecision.ASK:
+            # Human approval required - for now, raise exception with escalation message
+            # In production, this would integrate with LangGraph's interrupt() or a human-in-the-loop system
+            raise ValueError(f"ESCALATION_REQUIRED: {result.reason}")
+
+        if result.decision == GateDecision.STEER:
+            # Return ToolMessage with guidance - agent sees this as the tool result
+            steer_payload = result.steer_payload or {}
+            guidance = steer_payload.get("guidance", result.reason)
+            suggested_tool = steer_payload.get("suggested_tool")
+            suggested_args = steer_payload.get("suggested_args", {})
+            idempotency_key = suggested_args.get("idempotency_key")
+            if idempotency_key:
+                guidance += f" [idempotency_key={idempotency_key}]"
+
+            error_text = (
+                f"STEER_GUIDANCE: {guidance}\\n"
+                f"Suggested alternative: {suggested_tool} with args {suggested_args}"
+            )
+            return ToolMessage(content=error_text, tool_call_id=tool_call.get("id", ""), name=tool_name, status="error")
+
+        # Should not reach here
+        return handler(request)
+
+    return consequence_gate_wrapper
+
+
+# Convenience factory functions
+
+def create_financial_gate_middleware(
+    daily_tier_limit_inr: float = 25000.0,
+    instant_wire_threshold: float = 10000.0,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+):
+    """Factory for financial gate middleware."""
+    predictor = FinancialDeltaPredictor(
+        daily_tier_limit_inr=daily_tier_limit_inr,
+        instant_wire_threshold=instant_wire_threshold,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return predictor.evaluate(delta, circuit_breaker)
+
+    return create_consequence_middleware(
+        simulator_fn=predictor.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )
+
+
+def create_database_gate_middleware(
+    max_autonomous_delete_rows: int = 100,
+    db_conn=None,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+):
+    """Factory for database gate middleware."""
+    simulator = DataDeletionSimulator(
+        max_autonomous_delete_rows=max_autonomous_delete_rows,
+        db_conn=db_conn,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return simulator.evaluate(delta, circuit_breaker)
+
+    return create_consequence_middleware(
+        simulator_fn=simulator.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )
+
+
+def create_communications_gate_middleware(
+    max_autonomous_recipients: int = 10000,
+    canary_min_size: int = 100,
+    canary_max_bounce_rate: float = 0.05,
+    canary_max_complaint_rate: float = 0.01,
+    max_retries: int = 2,
+    context_provider: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
+):
+    """Factory for communications gate middleware."""
+    simulator = OutboundCommunicationSimulator(
+        max_autonomous_recipients=max_autonomous_recipients,
+        canary_min_size=canary_min_size,
+        canary_max_bounce_rate=canary_max_bounce_rate,
+        canary_max_complaint_rate=canary_max_complaint_rate,
+    )
+    breaker = SteerCircuitBreaker(max_retries=max_retries)
+
+    def evaluator(delta, circuit_breaker):
+        return simulator.evaluate(delta, circuit_breaker)
+
+    return create_consequence_middleware(
+        simulator_fn=simulator.simulate,
+        evaluator_fn=evaluator,
+        circuit_breaker=breaker,
+        context_provider=context_provider,
+    )