devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/variance.py

@@ -0,0 +1,219 @@
+"""
+Sprint 4 – A2/I2 Byzantine safety: parameterised f_max and variance calibration.
+
+f_max(n, σ²_obs) = floor(n * (1 - 2*σ²_obs) / 3). Variance calibration produces
+a report (σ² per agent, σ²_obs, f_max). Rolling monitoring can emit VARIANCE_ALERT
+when f_max drops; when f_max_live=0, deterministic mode is forced.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Optional
+
+VARIANCE_ALERT_EVENT = "VARIANCE_ALERT"
+LIVE_STATE_FILE = "live_state.json"
+
+VARIANCE_DIR_NAME = "variance"
+VARIANCE_REPORT_FILE = "calibration_report.json"
+SIGMA_SQ_MAX_DEFAULT = 0.3  # Exclude peers with σ²_j > σ²_max
+
+
+def f_max(n: int, sigma_sq_obs: float) -> int:
+    """
+    Parameterised Byzantine bound: max tolerable faulty agents.
+    f_max(n, σ²_obs) = floor(n * (1 - 2*σ²_obs) / 3).
+    """
+    if n <= 0:
+        return 0
+    if sigma_sq_obs >= 0.5:
+        return 0
+    return max(0, int(n * (1.0 - 2.0 * sigma_sq_obs) / 3.0))
+
+
+@dataclass
+class VarianceReport:
+    """Result of a variance calibration run."""
+    sigma_sq_per_agent: Dict[str, float]
+    sigma_sq_obs: float
+    n: int
+    f_max: int
+    sigma_sq_max: float = SIGMA_SQ_MAX_DEFAULT
+
+    def to_dict(self) -> dict:
+        return {
+            "sigma_sq_per_agent": self.sigma_sq_per_agent,
+            "sigma_sq_obs": self.sigma_sq_obs,
+            "n": self.n,
+            "f_max": self.f_max,
+            "sigma_sq_max": self.sigma_sq_max,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "VarianceReport":
+        return cls(
+            sigma_sq_per_agent=dict(d.get("sigma_sq_per_agent", {})),
+            sigma_sq_obs=float(d.get("sigma_sq_obs", 0)),
+            n=int(d.get("n", 0)),
+            f_max=int(d.get("f_max", 0)),
+            sigma_sq_max=float(d.get("sigma_sq_max", SIGMA_SQ_MAX_DEFAULT)),
+        )
+
+
+def variance_calibrate(agent_variances: Dict[str, float]) -> VarianceReport:
+    """
+    Compute σ²_obs = (1/n) * sum(σ²_i), then f_max(n, σ²_obs).
+    """
+    n = len(agent_variances)
+    if n == 0:
+        return VarianceReport(
+            sigma_sq_per_agent={},
+            sigma_sq_obs=0.0,
+            n=0,
+            f_max=0,
+        )
+    sigma_sq_obs = sum(agent_variances.values()) / n
+    return VarianceReport(
+        sigma_sq_per_agent=dict(agent_variances),
+        sigma_sq_obs=sigma_sq_obs,
+        n=n,
+        f_max=f_max(n, sigma_sq_obs),
+    )
+
+
+def reputation_with_variance_penalty(
+    base_reputation: float,
+    sigma_sq_j: float,
+    sigma_sq_max: float = SIGMA_SQ_MAX_DEFAULT,
+    alpha: float = 0.5,
+) -> float:
+    """
+    Penalise reputation by variance: r_new = (1-α)*r_old + α * (1 - σ²_j/σ²_max).
+    If σ²_j > σ²_max, the peer should be excluded (return 0 or very low).
+    """
+    if sigma_sq_j >= sigma_sq_max:
+        return 0.0
+    variance_factor = 1.0 - (sigma_sq_j / sigma_sq_max)
+    return (1.0 - alpha) * base_reputation + alpha * variance_factor
+
+
+@dataclass
+class VarianceMonitorResult:
+    """Result of a variance rolling monitor run."""
+    f_max_live: int
+    previous_f_max: Optional[int]
+    sigma_sq_obs: float
+    alert_emitted: bool
+    deterministic_mode_forced: bool
+
+    def to_dict(self) -> dict:
+        return {
+            "f_max_live": self.f_max_live,
+            "previous_f_max": self.previous_f_max,
+            "sigma_sq_obs": self.sigma_sq_obs,
+            "alert_emitted": self.alert_emitted,
+            "deterministic_mode_forced": self.deterministic_mode_forced,
+        }
+
+
+def _now_iso() -> str:
+    import datetime
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+def run_variance_monitor(
+    gcc_dir: Path,
+    agent_variances: Optional[Dict[str, float]] = None,
+) -> VarianceMonitorResult:
+    """
+    Run rolling variance monitoring: compute current f_max (from fresh calibration
+    or last report), compare to previous, and persist live state.
+    - If f_max_live == 0 or f_max_live < previous_f_max, caller should emit VARIANCE_ALERT.
+    - When f_max_live == 0, deterministic_mode_forced is True (force deterministic mode).
+    """
+    store = VarianceStore(gcc_dir)
+    store.variance_dir.mkdir(parents=True, exist_ok=True)
+    live_path = store.variance_dir / LIVE_STATE_FILE
+
+    # Current report: from fresh calibration or last persisted report
+    if agent_variances is not None and len(agent_variances) > 0:
+        report = variance_calibrate(agent_variances)
+    else:
+        report = store.load_report()
+        if report is None:
+            report = VarianceReport(
+                sigma_sq_per_agent={},
+                sigma_sq_obs=0.0,
+                n=0,
+                f_max=0,
+            )
+
+    f_max_live = report.f_max
+    previous_f_max: Optional[int] = None
+    if live_path.exists():
+        try:
+            live = json.loads(live_path.read_text(encoding="utf-8"))
+            previous_f_max = live.get("last_f_max")
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    alert_emitted = (
+        f_max_live == 0
+        or (previous_f_max is not None and f_max_live < previous_f_max)
+    )
+    deterministic_mode_forced = f_max_live == 0
+
+    now = _now_iso()
+    live_state = {
+        "last_f_max": f_max_live,
+        "last_sigma_sq_obs": report.sigma_sq_obs,
+        "last_checked_at": now,
+        "deterministic_mode_forced": deterministic_mode_forced,
+    }
+    live_path.write_text(json.dumps(live_state, indent=2) + "\n", encoding="utf-8")
+
+    return VarianceMonitorResult(
+        f_max_live=f_max_live,
+        previous_f_max=previous_f_max,
+        sigma_sq_obs=report.sigma_sq_obs,
+        alert_emitted=alert_emitted,
+        deterministic_mode_forced=deterministic_mode_forced,
+    )
+
+
+def load_variance_live_state(gcc_dir: Path) -> Optional[dict]:
+    """Load variance live_state.json if present; None otherwise."""
+    path = gcc_dir / VARIANCE_DIR_NAME / LIVE_STATE_FILE
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def variance_deterministic_mode_forced(gcc_dir: Path) -> bool:
+    """True when f_max_live was 0 at last monitor run (A2: force deterministic mode)."""
+    live = load_variance_live_state(gcc_dir)
+    return bool(live and live.get("deterministic_mode_forced"))
+
+
+class VarianceStore:
+    """Persist and load variance calibration report under .GCC/variance/."""
+    def __init__(self, gcc_dir: Path) -> None:
+        self.variance_dir = gcc_dir / VARIANCE_DIR_NAME
+        self.report_path = self.variance_dir / VARIANCE_REPORT_FILE
+
+    def save_report(self, report: VarianceReport) -> None:
+        self.variance_dir.mkdir(parents=True, exist_ok=True)
+        self.report_path.write_text(
+            json.dumps(report.to_dict(), indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+    def load_report(self) -> Optional[VarianceReport]:
+        if not self.report_path.exists():
+            return None
+        return VarianceReport.from_dict(json.loads(self.report_path.read_text(encoding="utf-8")))

devtorch_core/wrapper/__init__.py

@@ -0,0 +1,52 @@
+"""
+devtorch_core.wrapper
+=====================
+LLM SDK wrapper layer (S7).
+
+Provides drop-in replacements for popular LLM SDK clients that transparently:
+
+1. Inject RACP context (system prompt + Θ coordination vector + context bundle)
+   into every LLM call.
+2. Capture reasoning (thinking blocks, RACP-tagged blocks) to the local .GCC/
+   reasoning store.
+3. Return clean, block-stripped responses to the caller.
+4. Degrade gracefully — if .GCC/ is missing or any DevTorch primitive fails,
+   a warning is logged and the LLM response is returned as-is.
+
+Quick start
+-----------
+::
+
+    # Anthropic
+    from devtorch_core.wrapper.anthropic import DevTorchAnthropic as Anthropic
+
+    # OpenAI
+    from devtorch_core.wrapper.openai import DevTorchOpenAI as OpenAI
+
+    # Google Gemini
+    from devtorch_core.wrapper.gemini import DevTorchGemini
+
+    # AWS Bedrock (Anthropic Claude)
+    from devtorch_core.wrapper.bedrock import DevTorchBedrock
+
+Environment variables
+---------------------
+DEVTORCH_DISABLE=1   Disable all injection and capture (pass-through mode).
+"""
+
+from .anthropic import DevTorchAnthropic
+from .openai import DevTorchOpenAI
+from .gemini import DevTorchGemini
+from .bedrock import DevTorchBedrock
+from .base import RACPInjector, CaptureOrchestrator, find_gcc_repo, is_disabled
+
+__all__ = [
+    "DevTorchAnthropic",
+    "DevTorchOpenAI",
+    "DevTorchGemini",
+    "DevTorchBedrock",
+    "RACPInjector",
+    "CaptureOrchestrator",
+    "find_gcc_repo",
+    "is_disabled",
+]