devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/deltaf.py

@@ -0,0 +1,97 @@
+"""
+Sprint 5 – A4: Δf (sensitivity) estimation runner, report artifact, expiry.
+
+Publish Δf in Ωᵢ (capability) or separate store; used for privacy accounting.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+DELTAF_DIR_NAME = "deltaf"
+DELTAF_REPORT_NAME = "deltaf_report.json"
+DELTAF_EXPIRY_DAYS_DEFAULT = 90
+
+
+@dataclass
+class DeltaFReport:
+    """Δf estimation report (global or per-concept)."""
+    delta_f: float
+    concept: Optional[str] = None
+    expiry_date: Optional[str] = None  # ISO date
+    computed_at: Optional[str] = None  # ISO timestamp
+
+    def to_dict(self) -> dict:
+        d = {"delta_f": self.delta_f}
+        if self.concept is not None:
+            d["concept"] = self.concept
+        if self.expiry_date is not None:
+            d["expiry_date"] = self.expiry_date
+        if self.computed_at is not None:
+            d["computed_at"] = self.computed_at
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DeltaFReport":
+        return cls(
+            delta_f=float(d["delta_f"]),
+            concept=d.get("concept"),
+            expiry_date=d.get("expiry_date"),
+            computed_at=d.get("computed_at"),
+        )
+
+
+def run_deltaf_estimation(
+    sensitivities: list,
+    concept: Optional[str] = None,
+) -> DeltaFReport:
+    """
+    Placeholder Δf estimation: derive from sensitivity numerical values or use default.
+    In production would use proper sensitivity analysis (e.g. global L2 sensitivity).
+    """
+    delta_f = 1.0  # placeholder
+    for s in sensitivities:
+        if isinstance(s, dict) and "numerical_value" in s and s["numerical_value"] is not None:
+            delta_f = max(delta_f, abs(float(s["numerical_value"])))
+    return DeltaFReport(delta_f=delta_f, concept=concept)
+
+
+class DeltaFStore:
+    """Persist Δf report and optionally publish to Ωᵢ."""
+    def __init__(self, gcc_dir: Path) -> None:
+        self.deltaf_dir = gcc_dir / DELTAF_DIR_NAME
+        self.report_path = self.deltaf_dir / DELTAF_REPORT_NAME
+
+    def ensure_dir(self) -> None:
+        self.deltaf_dir.mkdir(parents=True, exist_ok=True)
+
+    def save_report(self, report: DeltaFReport, computed_at: str, expiry_days: int = DELTAF_EXPIRY_DAYS_DEFAULT) -> None:
+        """Save report with computed_at and expiry_date."""
+        import datetime as _dt
+        report.computed_at = computed_at
+        try:
+            d = _dt.datetime.fromisoformat(computed_at.replace("Z", "+00:00"))
+            report.expiry_date = (d + _dt.timedelta(days=expiry_days)).date().isoformat()
+        except Exception:
+            report.expiry_date = None
+        self.ensure_dir()
+        self.report_path.write_text(json.dumps(report.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+    def load_report(self) -> Optional[DeltaFReport]:
+        if not self.report_path.exists():
+            return None
+        return DeltaFReport.from_dict(json.loads(self.report_path.read_text(encoding="utf-8")))
+
+    def is_expired(self) -> bool:
+        """True if report exists and expiry_date is in the past."""
+        r = self.load_report()
+        if r is None or r.expiry_date is None:
+            return False
+        import datetime as _dt
+        try:
+            return _dt.date.fromisoformat(r.expiry_date) < _dt.date.today()
+        except Exception:
+            return False

devtorch_core/disclosure.py

@@ -0,0 +1,50 @@
+"""
+Sprint 5 – A4: Textual disclosure policy, [PRIVATE] suppression, fixed-length padding, receiver mandate.
+
+[PRIVATE] marker rules (category/count suppression); fixed-length padding; receiver non-zero constraint.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional
+
+PRIVATE_MARKER = "[PRIVATE]"
+DEFAULT_PADDING_LENGTH = 32
+DEFAULT_PADDING_CHAR = "█"
+
+
+@dataclass
+class DisclosurePolicy:
+    """Configuration for disclosure and padding."""
+    suppress_private: bool = True
+    padding_length: int = DEFAULT_PADDING_LENGTH
+    padding_char: str = DEFAULT_PADDING_CHAR
+    receiver_mandate_nonzero: bool = True  # [PRIVATE] must be treated as non-zero in downstream metadata
+
+    def redact_private(self, text: str) -> str:
+        """Replace [PRIVATE] spans with fixed-length padding."""
+        if not self.suppress_private:
+            return text
+        # Replace each [PRIVATE] ... (until next [PRIVATE] or end) or bare [PRIVATE] with padding
+        placeholder = self.padding_char * self.padding_length
+        # Match [PRIVATE] optionally followed by content until next [PRIVATE] or end of string
+        pattern = r"\[PRIVATE\](?:\s*[^\[]*?)?(?=\[PRIVATE\]|$)"
+        return re.sub(pattern, placeholder, text, flags=re.DOTALL)
+
+    def count_private_markers(self, text: str) -> int:
+        """Count occurrences of [PRIVATE] for receiver mandate (non-zero constraint)."""
+        return len(re.findall(re.escape(PRIVATE_MARKER), text))
+
+
+def apply_disclosure_policy(text: str, policy: Optional[DisclosurePolicy] = None) -> str:
+    """Apply disclosure policy: suppress [PRIVATE] with padding."""
+    if policy is None:
+        policy = DisclosurePolicy()
+    return policy.redact_private(text)
+
+
+def receiver_mandate_private_count(text: str) -> int:
+    """Return count of [PRIVATE] markers; downstream must treat as non-zero (do not ignore)."""
+    return len(re.findall(re.escape(PRIVATE_MARKER), text))

devtorch_core/divergence/__init__.py

@@ -0,0 +1,3 @@
+from .detector import DivergenceSignal, DivergenceDetector
+
+__all__ = ["DivergenceSignal", "DivergenceDetector"]

devtorch_core/divergence/detector.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import dataclasses
+import json
+from pathlib import Path
+from typing import List, Optional
+
+_SENSITIVITIES_FILE = "sensitivities/events.jsonl"
+_SEVERITY_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
+_CONFIDENCE_GAP_THRESHOLD = 0.35
+
+
+@dataclasses.dataclass
+class DivergenceSignal:
+    """
+    A detected divergence between agents on a specific concept.
+
+    signal_type:
+      A — conflicting decisions (commit messages contradict each other)
+      B — confidence gap ≥0.35 between two agents on the same concept
+      C — disclosure mismatch (e.g. PUBLIC vs PRIVATE)
+      D — missing coverage (agent has no reasoning for a concept another agent flagged)
+      E — consensus contradiction (new signal conflicts with a durable consensus commit)
+    """
+    signal_type: str   # "A" | "B" | "C" | "D" | "E"
+    severity: str      # "HIGH" | "MEDIUM" | "LOW"
+    concept: str
+    agent_ids: List[str]
+    description: str
+    evidence: dict
+
+
+class DivergenceDetector:
+    """Detect reasoning divergence across agents for a given concept."""
+
+    def __init__(self, repo) -> None:
+        self._repo = repo
+        self._gcc_dir = repo.gcc_dir
+
+    def detect(self, concept: str) -> List[DivergenceSignal]:
+        events = self._load_events(concept)
+        if len(events) < 2:
+            return []
+
+        signals: List[DivergenceSignal] = []
+        signals.extend(self._check_confidence_gap(concept, events))
+        signals.extend(self._check_disclosure_mismatch(concept, events))
+        signals.extend(self._check_consensus_contradiction(concept, events))
+
+        signals.sort(key=lambda s: _SEVERITY_ORDER.get(s.severity, 99))
+        return signals
+
+    def _load_events(self, concept: str) -> List[dict]:
+        path = self._gcc_dir / _SENSITIVITIES_FILE
+        if not path.exists():
+            return []
+        results = []
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                d = json.loads(line)
+                if d.get("target_concept") == concept:
+                    results.append(d)
+            except json.JSONDecodeError:
+                continue
+        return results
+
+    def _check_confidence_gap(self, concept: str, events: List[dict]) -> List[DivergenceSignal]:
+        """Signal B: two agents differ in confidence by ≥0.35."""
+        by_agent: dict[str, List[float]] = {}
+        for ev in events:
+            agent = ev.get("agent_id") or ev.get("source_node", "unknown")
+            by_agent.setdefault(agent, []).append(float(ev.get("confidence", 0.0)))
+
+        if len(by_agent) < 2:
+            return []
+
+        agent_means = {a: sum(cs) / len(cs) for a, cs in by_agent.items()}
+        agents = list(agent_means.keys())
+        signals = []
+        for i in range(len(agents)):
+            for j in range(i + 1, len(agents)):
+                gap = abs(agent_means[agents[i]] - agent_means[agents[j]])
+                if gap >= _CONFIDENCE_GAP_THRESHOLD:
+                    signals.append(DivergenceSignal(
+                        signal_type="B",
+                        severity="MEDIUM",
+                        concept=concept,
+                        agent_ids=[agents[i], agents[j]],
+                        description=f"Confidence gap {gap:.2f} on '{concept}': "
+                                    f"{agents[i]}={agent_means[agents[i]]:.2f}, "
+                                    f"{agents[j]}={agent_means[agents[j]]:.2f}",
+                        evidence={
+                            f"{agents[i]}_mean_confidence": round(agent_means[agents[i]], 4),
+                            f"{agents[j]}_mean_confidence": round(agent_means[agents[j]], 4),
+                            "gap": round(gap, 4),
+                        },
+                    ))
+        return signals
+
+    def _check_disclosure_mismatch(self, concept: str, events: List[dict]) -> List[DivergenceSignal]:
+        """Signal C: agents disagree on disclosure level — always HIGH severity."""
+        by_agent: dict[str, set] = {}
+        for ev in events:
+            agent = ev.get("agent_id") or ev.get("source_node", "unknown")
+            by_agent.setdefault(agent, set()).add(ev.get("disclosure_level", "PROTECTED"))
+
+        # Take the most restrictive disclosure level per agent
+        all_levels: dict[str, str] = {
+            agent: max(levels, key=lambda l: {"PRIVATE": 2, "PROTECTED": 1, "PUBLIC": 0}.get(l, 0))
+            for agent, levels in by_agent.items()
+        }
+
+        if len(all_levels) < 2:
+            return []
+
+        unique_levels = set(all_levels.values())
+        if len(unique_levels) <= 1:
+            return []
+
+        return [DivergenceSignal(
+            signal_type="C",
+            severity="HIGH",
+            concept=concept,
+            agent_ids=list(all_levels.keys()),
+            description=f"Disclosure mismatch on '{concept}': " +
+                        ", ".join(f"{a}={l}" for a, l in all_levels.items()),
+            evidence=dict(all_levels),
+        )]
+
+    def _check_consensus_contradiction(self, concept: str, events: List[dict]) -> List[DivergenceSignal]:
+        """Signal E: new sensitivity contradicts an existing consensus commit."""
+        consensus_path = self._gcc_dir / "consolidations"
+        if not consensus_path.exists():
+            return []
+
+        signals = []
+        for f in consensus_path.glob("*.json"):
+            try:
+                record = json.loads(f.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                continue
+            if record.get("concept") != concept:
+                continue
+            if record.get("state") not in ("resolved", "auto_resolved"):
+                continue
+            resolved_at = record.get("resolved_at", "")
+            post_consensus = [
+                ev for ev in events
+                if ev.get("created_at", "") > resolved_at
+            ]
+            if post_consensus:
+                signals.append(DivergenceSignal(
+                    signal_type="E",
+                    severity="HIGH",
+                    concept=concept,
+                    agent_ids=list({
+                        ev.get("agent_id") or ev.get("source_node", "unknown")
+                        for ev in post_consensus
+                    }),
+                    description=f"{len(post_consensus)} new signals on '{concept}' after consensus at {resolved_at[:19]}",
+                    evidence={"consensus_record_id": record.get("record_id", ""), "post_consensus_count": len(post_consensus)},
+                ))
+        return signals

devtorch_core/gateway/__init__.py

@@ -0,0 +1,32 @@
+"""
+devtorch_core.gateway
+=====================
+Enterprise org gateway — multi-tenant proxy with SSO, governance policy
+enforcement, central API key management, and metrics webhooks.
+
+This is the enterprise counterpart to the local proxy (devtorch_core/proxy/).
+It runs in the company's own cloud and handles multiple developers simultaneously.
+
+Exports:
+    GovernancePolicy  — policy dataclass
+    PolicyEngine      — request/response enforcement
+    SSOValidator      — JWT / SSO token validation
+    MetricsWebhook    — push aggregate metrics to external webhook
+    GatewayServer     — multi-tenant org proxy server
+"""
+from __future__ import annotations
+
+from .key_manager import KeyManager
+from .policy import GovernancePolicy, PolicyEngine
+from .sso import SSOValidator
+from .metrics_webhook import MetricsWebhook
+from .server import GatewayServer
+
+__all__ = [
+    "GovernancePolicy",
+    "PolicyEngine",
+    "SSOValidator",
+    "MetricsWebhook",
+    "KeyManager",
+    "GatewayServer",
+]

devtorch_core/gateway/key_manager.py

@@ -0,0 +1,124 @@
+"""
+devtorch_core.gateway.key_manager
+=================================
+Centralised org LLM API key management for the enterprise gateway.
+
+The KeyManager keeps provider keys in memory only (never writes to disk), and
+masks them in string representations so they are not accidentally leaked in
+logs or tracebacks.
+
+Backward compatibility:
+    Keys may be supplied directly via the GatewayServer constructor, loaded
+    from environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY), or
+    provided as a dictionary to KeyManager.  Constructor-supplied keys take
+    precedence over the environment.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+
+# Provider names used by the gateway.
+ANTHROPIC = "anthropic"
+OPENAI = "openai"
+
+# Default environment variable names for each provider.
+_ENV_VARS = {
+    ANTHROPIC: "ANTHROPIC_API_KEY",
+    OPENAI: "OPENAI_API_KEY",
+}
+
+
+class KeyManager:
+    """
+    In-memory store and rotator for org LLM API keys.
+
+    Parameters
+    ----------
+    keys:
+        Optional mapping of provider name -> API key.  Missing providers are
+        backfilled from environment variables.  Use an empty dict to force
+        environment-only loading.
+    env_var_map:
+        Optional mapping of provider name -> environment variable name to use
+        instead of the defaults.
+    """
+
+    def __init__(
+        self,
+        keys: Optional[dict[str, str]] = None,
+        env_var_map: Optional[dict[str, str]] = None,
+    ) -> None:
+        self._env_var_map = {**_ENV_VARS, **(env_var_map or {})}
+        self._keys: dict[str, str] = {}
+
+        # Seed from explicit keys first (normalise provider names to lowercase).
+        if keys:
+            for provider, key in keys.items():
+                self._keys[provider.lower()] = key
+
+        # Backfill from environment variables where not already provided.
+        for provider, env_var in self._env_var_map.items():
+            provider_lower = provider.lower()
+            if provider_lower not in self._keys:
+                value = os.environ.get(env_var, "")
+                if value:
+                    self._keys[provider_lower] = value
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_key(self, provider: str) -> str:
+        """
+        Return the API key for *provider*, or an empty string if not configured.
+
+        *provider* is normalised to lowercase.
+        """
+        return self._keys.get(provider.lower(), "")
+
+    def rotate_key(self, provider: str, new_key: str) -> str:
+        """
+        Replace the stored key for *provider* with *new_key*.
+
+        Returns the previous key (or empty string if none existed).
+        """
+        provider = provider.lower()
+        previous = self._keys.get(provider, "")
+        self._keys[provider] = new_key
+        return previous
+
+    def set_key(self, provider: str, key: str) -> None:
+        """
+        Alias for rotate_key that does not return the previous value.
+        """
+        self.rotate_key(provider, key)
+
+    def has_key(self, provider: str) -> bool:
+        """Return True if a non-empty key is configured for *provider*."""
+        return bool(self.get_key(provider))
+
+    def providers(self) -> list[str]:
+        """Return the list of providers that currently have a key configured."""
+        return [p for p, k in self._keys.items() if k]
+
+    # ------------------------------------------------------------------
+    # Safety / introspection
+    # ------------------------------------------------------------------
+
+    def _mask(self, key: str) -> str:
+        """Return a masked representation of *key* (last 4 chars only)."""
+        if not key:
+            return ""
+        if len(key) <= 4:
+            return "****"
+        return f"{'*' * (len(key) - 4)}{key[-4:]}"
+
+    def __repr__(self) -> str:
+        masked = {p: self._mask(k) for p, k in self._keys.items()}
+        return f"{self.__class__.__name__}({masked!r})"
+
+    def __str__(self) -> str:
+        providers = self.providers()
+        return f"{self.__class__.__name__}(providers={providers})"