alignscope 0.1.0__py3-none-any.whl

alignscope/detector.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+"""
+AlignScope — Defection & Anomaly Detector
+
+Monitors alignment metrics over time and flags moments when
+an agent breaks from its coalition. These are the scientifically
+interesting events in alignment research — the exact tick where
+cooperation fails.
+
+Detection methods:
+1. Direct defection events from the data source
+2. Metric-based anomalies: sudden drops in reciprocity or role stability
+3. Coalition fragmentation: when coalition sizes shrink unexpectedly
+
+Environment-agnostic: works with any data source that provides
+the standard AlignScope tick/metrics format.
+"""
+
+
+class DefectionDetector:
+    """Accumulates metric history and detects alignment anomalies."""
+
+    def __init__(
+        self,
+        reciprocity_drop_threshold: float = 0.3,
+        stability_drop_threshold: float = 0.2,
+        lookback_window: int = 10,
+    ):
+        self.reciprocity_drop_threshold = reciprocity_drop_threshold
+        self.stability_drop_threshold = stability_drop_threshold
+        self.lookback_window = lookback_window
+
+        self.metric_history: list[dict] = []
+        self.all_events: list[dict] = []
+
+    def analyze(self, tick_data: dict, metrics: dict) -> list[dict]:
+        """
+        Analyze one tick for defection and anomaly events.
+
+        Args:
+            tick_data: Raw game state from any compatible data source
+            metrics: Computed alignment metrics from AlignmentMetrics
+
+        Returns:
+            List of detected events (may be empty)
+        """
+        events = []
+        tick = tick_data["tick"]
+
+        # 1. Forward direct defection events from data source
+        for defection in tick_data.get("defection_events", []):
+            event = {
+                "tick": tick,
+                "type": "defection",
+                "agent_id": defection["agent_id"],
+                "team": defection["team"],
+                "severity": defection["severity"],
+                "description": (
+                    f"Agent {defection['agent_id']} (team {defection.get('team', '?')}, "
+                    f"{defection.get('previous_role', 'unknown')}) defected. "
+                    f"Reason: {defection.get('reason', 'no reason provided')}"
+                ),
+                "details": defection,
+            }
+            events.append(event)
+
+        # 2. Check for reciprocity drops (metric-based anomalies)
+        if len(self.metric_history) >= self.lookback_window:
+            reciprocity_events = self._detect_reciprocity_anomalies(
+                tick, metrics
+            )
+            events.extend(reciprocity_events)
+
+        # 3. Check for role stability drops
+        if len(self.metric_history) >= self.lookback_window:
+            stability_events = self._detect_stability_anomalies(
+                tick, metrics
+            )
+            events.extend(stability_events)
+
+        # 4. Check coalition fragmentation
+        coalition_events = self._detect_coalition_changes(tick, metrics)
+        events.extend(coalition_events)
+
+        # Store for history
+        self.metric_history.append(metrics)
+        self.all_events.extend(events)
+
+        return events
+
+    def _detect_reciprocity_anomalies(
+        self, tick: int, current: dict
+    ) -> list[dict]:
+        """Detect sudden drops in pair reciprocity."""
+        events = []
+        current_pairs = {
+            (p["agent_a"], p["agent_b"]): p["reciprocity"]
+            for p in current.get("pair_metrics", [])
+        }
+
+        for pair, current_val in current_pairs.items():
+            historical = []
+            for past in self.metric_history[-self.lookback_window:]:
+                for p in past.get("pair_metrics", []):
+                    if (p["agent_a"], p["agent_b"]) == pair:
+                        historical.append(p["reciprocity"])
+
+            if historical:
+                avg_historical = sum(historical) / len(historical)
+                drop = avg_historical - current_val
+
+                if drop > self.reciprocity_drop_threshold:
+                    events.append({
+                        "tick": tick,
+                        "type": "reciprocity_drop",
+                        "agent_id": pair[0],
+                        "partner_id": pair[1],
+                        "severity": round(min(1.0, drop / 0.5), 3),
+                        "description": (
+                            f"Reciprocity between agents {pair[0]} and {pair[1]} "
+                            f"dropped from {avg_historical:.2f} to {current_val:.2f}"
+                        ),
+                        "team": None,
+                    })
+
+        return events
+
+    def _detect_stability_anomalies(
+        self, tick: int, current: dict
+    ) -> list[dict]:
+        """Detect sudden role stability drops for individual agents."""
+        events = []
+        current_agents = current.get("agent_metrics", {})
+
+        for aid, metrics in current_agents.items():
+            current_stability = metrics["role_stability"]
+
+            historical = []
+            for past in self.metric_history[-self.lookback_window:]:
+                past_agents = past.get("agent_metrics", {})
+                if aid in past_agents:
+                    historical.append(past_agents[aid]["role_stability"])
+
+            if historical:
+                avg_historical = sum(historical) / len(historical)
+                drop = avg_historical - current_stability
+
+                if drop > self.stability_drop_threshold:
+                    events.append({
+                        "tick": tick,
+                        "type": "stability_drop",
+                        "agent_id": aid,
+                        "severity": round(min(1.0, drop / 0.4), 3),
+                        "description": (
+                            f"Agent {aid} role stability dropped from "
+                            f"{avg_historical:.2f} to {current_stability:.2f} — "
+                            f"possible role confusion or strategic shift"
+                        ),
+                        "team": metrics.get("team"),
+                    })
+
+        return events
+
+    def _detect_coalition_changes(
+        self, tick: int, current: dict
+    ) -> list[dict]:
+        """
+        Detect coalition fragmentation.
+
+        FIX: Removed the 'prev_coalitions > 0' guard that was preventing
+        events from firing after coalitions first dropped to 0.
+
+        Before:
+            curr_coalitions < prev_coalitions AND prev_coalitions > 0
+            → Once coalitions hit 0 they could never drop further,
+              so no events fired after the first fragmentation.
+
+        After:
+            curr_coalitions < prev_coalitions
+            → Fires every time the count drops, regardless of floor value.
+        """
+        events = []
+
+        if not self.metric_history:
+            return events
+
+        prev = self.metric_history[-1]
+        prev_teams = prev.get("team_metrics", {})
+        curr_teams = current.get("team_metrics", {})
+
+        for tid in curr_teams:
+            if tid in prev_teams:
+                prev_coalitions = prev_teams[tid].get("active_coalitions", 0)
+                curr_coalitions = curr_teams[tid].get("active_coalitions", 0)
+
+                # FIX: removed "and prev_coalitions > 0"
+                if (isinstance(prev_coalitions, int)
+                        and isinstance(curr_coalitions, int)
+                        and curr_coalitions < prev_coalitions):
+                    lost = prev_coalitions - curr_coalitions
+                    events.append({
+                        "tick": tick,
+                        "type": "coalition_fragmentation",
+                        "agent_id": None,
+                        "team": tid,
+                        "severity": round(min(1.0, lost / 2.0), 3),
+                        "description": (
+                            f"Team {tid} lost {lost} coalition(s): "
+                            f"{prev_coalitions} → {curr_coalitions}"
+                        ),
+                    })
+
+        return events
+
+    def get_summary(self) -> dict:
+        """Return aggregate defection statistics."""
+        if not self.all_events:
+            return {
+                "total_events": 0,
+                "defections": 0,
+                "reciprocity_drops": 0,
+                "stability_drops": 0,
+                "coalition_fragmentations": 0,
+                "avg_severity": 0,
+            }
+
+        by_type = {}
+        for e in self.all_events:
+            t = e["type"]
+            by_type[t] = by_type.get(t, 0) + 1
+
+        avg_sev = sum(e.get("severity", 0) for e in self.all_events) / len(self.all_events)
+
+        return {
+            "total_events": len(self.all_events),
+            "defections": by_type.get("defection", 0),
+            "reciprocity_drops": by_type.get("reciprocity_drop", 0),
+            "stability_drops": by_type.get("stability_drop", 0),
+            "coalition_fragmentations": by_type.get("coalition_fragmentation", 0),
+            "avg_severity": round(avg_sev, 3),
+        }

alignscope/integrations/__init__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+"""
+AlignScope — Integration Bridges
+
+Auto-detects installed ML observability tools (W&B, MLflow) and
+forwards alignment metrics to them. This ensures zero vendor lock-in —
+AlignScope adds to your existing stack, never replaces it.
+"""
+
+
+def detect_integrations() -> dict[str, bool]:
+    """Check which ML tools are available."""
+    available = {}
+
+    try:
+        import wandb
+        available["wandb"] = True
+    except ImportError:
+        available["wandb"] = False
+
+    try:
+        import mlflow
+        available["mlflow"] = True
+    except ImportError:
+        available["mlflow"] = False
+
+    return available

alignscope/integrations/mlflow_bridge.py

@@ -0,0 +1,70 @@
+"""
+AlignScope — MLflow Bridge
+
+If the user has MLflow installed and an active run, AlignScope
+automatically logs alignment metrics as MLflow metrics.
+
+Zero vendor lock-in: AlignScope enriches MLflow — never replaces it.
+"""
+
+
+class MlflowBridge:
+    """Forwards AlignScope metrics to an active MLflow run."""
+
+    def __init__(self):
+        self._mlflow = None
+        self._active = False
+
+        try:
+            import mlflow
+            self._mlflow = mlflow
+
+            # Check for active run
+            if mlflow.active_run() is not None:
+                self._active = True
+                print("[AlignScope] ✓ Detected active MLflow run — forwarding metrics")
+            else:
+                print("[AlignScope] MLflow installed but no active run. "
+                      "Call mlflow.start_run() first to enable forwarding.")
+        except ImportError:
+            pass
+
+    def log(self, step: int, metrics: dict, events: list):
+        """Forward alignment metrics to MLflow."""
+        if not self._active or not self._mlflow:
+            return
+
+        # Re-check for active run
+        if self._mlflow.active_run() is None:
+            return
+
+        try:
+            log_data = {
+                "alignscope.overall_alignment": metrics.get("overall_alignment_score", 0),
+            }
+
+            team_metrics = metrics.get("team_metrics", {})
+            for tid, tm in team_metrics.items():
+                prefix = f"alignscope.team_{tid}"
+                log_data[f"{prefix}.role_stability"] = tm.get("avg_role_stability", 0)
+                log_data[f"{prefix}.coalitions"] = tm.get("active_coalitions", 0)
+                log_data[f"{prefix}.defectors"] = tm.get("defector_count", 0)
+
+            self._mlflow.log_metrics(log_data, step=step)
+
+        except Exception:
+            pass
+
+    def finish(self, summary: dict):
+        """Log final summary params to MLflow."""
+        if not self._active or not self._mlflow:
+            return
+
+        try:
+            params = {
+                f"alignscope_{k}": str(v)
+                for k, v in summary.items()
+            }
+            self._mlflow.log_params(params)
+        except Exception:
+            pass

alignscope/integrations/wandb_bridge.py

@@ -0,0 +1,81 @@
+"""
+AlignScope — Weights & Biases Bridge
+
+If the user has W&B installed and an active run, AlignScope
+automatically forwards alignment metrics as W&B custom metrics.
+This means they see AlignScope data right alongside their reward
+curves in the W&B dashboard.
+
+Zero vendor lock-in: AlignScope never replaces W&B — it adds to it.
+"""
+
+
+class WandbBridge:
+    """Forwards AlignScope metrics to an active W&B run."""
+
+    def __init__(self):
+        self._wandb = None
+        self._active = False
+
+        try:
+            import wandb
+            self._wandb = wandb
+
+            # Check if there's an active run
+            if wandb.run is not None:
+                self._active = True
+                print("[AlignScope] ✓ Detected active W&B run — forwarding metrics")
+            else:
+                print("[AlignScope] W&B installed but no active run. "
+                      "Call wandb.init() first to enable forwarding.")
+        except ImportError:
+            pass
+
+    def log(self, step: int, metrics: dict, events: list):
+        """Forward alignment metrics to W&B."""
+        if not self._active or not self._wandb:
+            return
+
+        # Re-check for active run (may have been initialized after AlignScope)
+        if self._wandb.run is None:
+            return
+
+        try:
+            # Log overall alignment score
+            log_data = {
+                "alignscope/overall_alignment": metrics.get("overall_alignment_score", 0),
+            }
+
+            # Log per-team metrics
+            team_metrics = metrics.get("team_metrics", {})
+            for tid, tm in team_metrics.items():
+                prefix = f"alignscope/team_{tid}"
+                log_data[f"{prefix}/role_stability"] = tm.get("avg_role_stability", 0)
+                log_data[f"{prefix}/coalitions"] = tm.get("active_coalitions", 0)
+                log_data[f"{prefix}/defectors"] = tm.get("defector_count", 0)
+
+            # Log event counts
+            if events:
+                by_type = {}
+                for e in events:
+                    t = e.get("type", "unknown")
+                    by_type[t] = by_type.get(t, 0) + 1
+
+                for etype, count in by_type.items():
+                    log_data[f"alignscope/events/{etype}"] = count
+
+            self._wandb.log(log_data, step=step)
+
+        except Exception:
+            pass  # Never crash
+
+    def finish(self, summary: dict):
+        """Log final summary to W&B."""
+        if not self._active or not self._wandb or self._wandb.run is None:
+            return
+
+        try:
+            for key, value in summary.items():
+                self._wandb.run.summary[f"alignscope/{key}"] = value
+        except Exception:
+            pass