alignscope 0.1.0__py3-none-any.whl

alignscope/_frontend/js/topology.js

@@ -0,0 +1,368 @@
+/**
+ * AlignScope — Topology Graph (D3.js Force-Directed)
+ *
+ * Renders agents as nodes and their relationships as edges.
+ * Coalition clusters form visually via D3 force simulation parameters.
+ *
+ * Nodes: colored by team (from config), sized by role stability
+ * Edges: opacity = reciprocity strength, width = total interactions
+ * Defectors: pulsing animation, pushed to periphery
+ *
+ * All team colors and role shapes are dynamically assigned from config.
+ */
+
+const TopologyGraph = {
+    svg: null,
+    simulation: null,
+    config: null,
+    width: 0,
+    height: 0,
+    nodes: [],
+    links: [],
+    nodeElements: null,
+    linkElements: null,
+    labelElements: null,
+
+    // D3 symbol types palette — assigned dynamically to roles
+    shapePalette: [
+        d3.symbolCircle,
+        d3.symbolDiamond,
+        d3.symbolSquare,
+        d3.symbolTriangle,
+        d3.symbolStar,
+        d3.symbolCross,
+        d3.symbolWye,
+    ],
+
+    // Computed mappings (built from config)
+    roleShapes: {},
+    roleSize: {},
+
+    init(config) {
+        this.config = config;
+
+        // Build role → shape mapping dynamically from config
+        const roles = config.roles || [];
+        this.roleShapes = {};
+        this.roleSize = {};
+        roles.forEach((role, idx) => {
+            this.roleShapes[role] = this.shapePalette[idx % this.shapePalette.length];
+            this.roleSize[role] = 55 + (idx % 4) * 5;  // slight size variation
+        });
+
+        const container = document.getElementById('topology-container');
+        this.width = container.clientWidth;
+        this.height = container.clientHeight;
+
+        this.svg = d3.select('#topology-svg')
+            .attr('width', this.width)
+            .attr('height', this.height);
+
+        // Clear any previous content
+        this.svg.selectAll('*').remove();
+
+        // Create layer groups (links behind nodes)
+        this.svg.append('g').attr('class', 'links-layer');
+        this.svg.append('g').attr('class', 'nodes-layer');
+        this.svg.append('g').attr('class', 'labels-layer');
+
+        // Initialize force simulation
+        this.simulation = d3.forceSimulation()
+            .force('charge', d3.forceManyBody()
+                .strength(-120)
+                .distanceMax(250))
+            .force('center', d3.forceCenter(this.width / 2, this.height / 2))
+            .force('collision', d3.forceCollide().radius(22))
+            .force('x', d3.forceX(this.width / 2).strength(0.03))
+            .force('y', d3.forceY(this.height / 2).strength(0.03))
+            .alphaDecay(0.01)
+            .on('tick', () => this.ticked());
+
+        this.updateBadge(0);
+    },
+
+    /**
+     * Get team color from config or fallback to AlignScope palette.
+     */
+    getTeamColor(teamIdx) {
+        return AlignScope.getTeamColor(teamIdx);
+    },
+
+    /**
+     * Get a slightly darker team color for stroke.
+     */
+    getTeamStroke(teamIdx) {
+        const color = this.getTeamColor(teamIdx);
+        // Darken by mixing toward black
+        return this._darkenColor(color, 0.2);
+    },
+
+    _darkenColor(hex, amount) {
+        // Simple hex darkening
+        let c = hex.replace('#', '');
+        if (c.length === 3) c = c[0]+c[0]+c[1]+c[1]+c[2]+c[2];
+        const r = Math.max(0, Math.round(parseInt(c.substr(0,2), 16) * (1 - amount)));
+        const g = Math.max(0, Math.round(parseInt(c.substr(2,2), 16) * (1 - amount)));
+        const b = Math.max(0, Math.round(parseInt(c.substr(4,2), 16) * (1 - amount)));
+        return `rgb(${r},${g},${b})`;
+    },
+
+    update(data) {
+        if (!this.svg) return;
+
+        const agents = data.agents || [];
+        const relationships = data.relationships || [];
+        const metrics = data.metrics?.agent_metrics || {};
+        const groupBy = this.config?.topology?.groupBy || 'team';
+
+        // Build node data
+        const nodeIds = new Set(agents.map(a => a.agent_id));
+        this.nodes = agents.map(a => {
+            const existing = this.simulation?.nodes()?.find(n => n.id === a.agent_id);
+            const m = metrics[a.agent_id] || metrics[String(a.agent_id)] || {};
+            return {
+                id: a.agent_id,
+                team: a[groupBy] !== undefined ? a[groupBy] : a.team,
+                role: a.role,
+                isDefector: a.is_defector,
+                coalitionId: a.coalition_id,
+                roleStability: m.role_stability || 1.0,
+                x: existing?.x || this.width / 2 + (Math.random() - 0.5) * 100,
+                y: existing?.y || this.height / 2 + (Math.random() - 0.5) * 100,
+                vx: existing?.vx || 0,
+                vy: existing?.vy || 0,
+            };
+        });
+
+        // Build link data
+        this.links = relationships
+            .filter(r => r.weight > 0 && nodeIds.has(r.source) && nodeIds.has(r.target))
+            .map(r => ({
+                source: r.source,
+                target: r.target,
+                weight: r.weight,
+                reciprocity: r.reciprocity,
+                sameTeam: r.same_team,
+            }));
+
+        this.render();
+        this.updateBadge(agents.length);
+
+        this.simulation.nodes(this.nodes);
+        this.simulation
+            .force('link', d3.forceLink(this.links)
+                .id(d => d.id)
+                .distance(d => {
+                    const base = 100;
+                    return Math.max(40, base - d.weight * 5);
+                })
+                .strength(d => {
+                    return d.sameTeam ? 0.3 + d.reciprocity * 0.4 : 0.05;
+                }))
+            .alpha(0.15)
+            .restart();
+    },
+
+    render() {
+        const linksLayer = this.svg.select('.links-layer');
+        const nodesLayer = this.svg.select('.nodes-layer');
+        const labelsLayer = this.svg.select('.labels-layer');
+
+        // --- Links ---
+        this.linkElements = linksLayer.selectAll('.link-line')
+            .data(this.links, d => `${d.source.id || d.source}-${d.target.id || d.target}`);
+
+        this.linkElements.exit().remove();
+
+        const linkEnter = this.linkElements.enter()
+            .append('line')
+            .attr('class', 'link-line');
+
+        this.linkElements = linkEnter.merge(this.linkElements)
+            .attr('stroke-width', d => Math.max(0.5, Math.min(3, d.weight * 0.3)))
+            .attr('stroke-opacity', d => Math.max(0.08, Math.min(0.6, d.reciprocity * 0.8)))
+            .attr('stroke', d => d.sameTeam ? 'var(--text-muted)' : 'var(--border-subtle)');
+
+        // --- Nodes ---
+        this.nodeElements = nodesLayer.selectAll('.node-group')
+            .data(this.nodes, d => d.id);
+
+        this.nodeElements.exit().remove();
+
+        const nodeEnter = this.nodeElements.enter()
+            .append('g')
+            .attr('class', 'node-group')
+            .style('cursor', 'pointer')
+            .on('click', (event, d) => {
+                AlignScope.selectAgent(d.id);
+                this.highlightAgent(d.id);
+            })
+            .call(d3.drag()
+                .on('start', (event, d) => this.dragStarted(event, d))
+                .on('drag', (event, d) => this.dragged(event, d))
+                .on('end', (event, d) => this.dragEnded(event, d)));
+
+        nodeEnter.append('path').attr('class', 'node-shape');
+
+        this.nodeElements = nodeEnter.merge(this.nodeElements);
+
+        // Update node appearance — colors and shapes from config
+        this.nodeElements.select('.node-shape')
+            .attr('d', d => {
+                const size = this.roleSize[d.role] || 60;
+                const scaledSize = size * (0.8 + d.roleStability * 0.6);
+                const shape = this.roleShapes[d.role] || d3.symbolCircle;
+                return d3.symbol().type(shape).size(scaledSize)();
+            })
+            .attr('fill', d => {
+                if (d.isDefector) return 'var(--color-defection)';
+                return this.getTeamColor(d.team);
+            })
+            .attr('stroke', d => {
+                if (d.isDefector) return 'var(--color-defection)';
+                return this.getTeamStroke(d.team);
+            })
+            .attr('stroke-width', 1.5)
+            .attr('opacity', d => d.isDefector ? 0.7 : 0.9)
+            .classed('node-defector', d => d.isDefector);
+
+        // --- Labels ---
+        this.labelElements = labelsLayer.selectAll('.node-label')
+            .data(this.nodes, d => d.id);
+
+        this.labelElements.exit().remove();
+
+        const labelEnter = this.labelElements.enter()
+            .append('text')
+            .attr('class', 'node-label')
+            .attr('text-anchor', 'middle')
+            .attr('dy', -12);
+
+        this.labelElements = labelEnter.merge(this.labelElements)
+            .text(d => d.id);
+    },
+
+    ticked() {
+        if (this.linkElements) {
+            this.linkElements
+                .attr('x1', d => d.source.x)
+                .attr('y1', d => d.source.y)
+                .attr('x2', d => d.target.x)
+                .attr('y2', d => d.target.y);
+        }
+
+        if (this.nodeElements) {
+            this.nodeElements
+                .attr('transform', d => {
+                    d.x = Math.max(20, Math.min(this.width - 20, d.x));
+                    d.y = Math.max(20, Math.min(this.height - 20, d.y));
+                    return `translate(${d.x},${d.y})`;
+                });
+        }
+
+        if (this.labelElements) {
+            this.labelElements
+                .attr('x', d => d.x)
+                .attr('y', d => d.y);
+        }
+    },
+
+    dragStarted(event, d) {
+        if (!event.active) this.simulation.alphaTarget(0.1).restart();
+        d.fx = d.x;
+        d.fy = d.y;
+    },
+
+    dragged(event, d) {
+        d.fx = event.x;
+        d.fy = event.y;
+    },
+
+    dragEnded(event, d) {
+        if (!event.active) this.simulation.alphaTarget(0);
+        d.fx = null;
+        d.fy = null;
+    },
+
+    highlightAgent(agentId) {
+        if (!this.nodeElements) return;
+
+        this.nodeElements.select('.node-shape')
+            .attr('stroke-width', d => d.id === agentId ? 3 : 1.5)
+            .attr('stroke', d => {
+                if (d.id === agentId) return 'var(--text-primary)';
+                if (d.isDefector) return 'var(--color-defection)';
+                return this.getTeamStroke(d.team);
+            });
+
+        if (this.linkElements) {
+            this.linkElements
+                .attr('stroke-opacity', d => {
+                    const srcId = d.source.id ?? d.source;
+                    const tgtId = d.target.id ?? d.target;
+                    if (srcId === agentId || tgtId === agentId) {
+                        return 0.8;
+                    }
+                    return Math.max(0.05, Math.min(0.3, d.reciprocity * 0.4));
+                })
+                .attr('stroke-width', d => {
+                    const srcId = d.source.id ?? d.source;
+                    const tgtId = d.target.id ?? d.target;
+                    if (srcId === agentId || tgtId === agentId) {
+                        return Math.max(1.5, d.weight * 0.5);
+                    }
+                    return Math.max(0.5, Math.min(3, d.weight * 0.3));
+                });
+        }
+    },
+
+    clearSelection() {
+        if (!this.nodeElements) return;
+        this.nodeElements.select('.node-shape')
+            .attr('stroke-width', 1.5)
+            .attr('stroke', d => {
+                if (d.isDefector) return 'var(--color-defection)';
+                return this.getTeamStroke(d.team);
+            });
+
+        if (this.linkElements) {
+            this.linkElements
+                .attr('stroke-opacity', d => Math.max(0.08, Math.min(0.6, d.reciprocity * 0.8)))
+                .attr('stroke-width', d => Math.max(0.5, Math.min(3, d.weight * 0.3)));
+        }
+    },
+
+    updateBadge(count) {
+        document.getElementById('topology-badge').textContent =
+            `${count} node${count !== 1 ? 's' : ''}`;
+    },
+
+    resize() {
+        const container = document.getElementById('topology-container');
+        this.width = container.clientWidth;
+        this.height = container.clientHeight;
+
+        if (this.svg) {
+            this.svg
+                .attr('width', this.width)
+                .attr('height', this.height);
+        }
+
+        if (this.simulation) {
+            this.simulation
+                .force('center', d3.forceCenter(this.width / 2, this.height / 2))
+                .force('x', d3.forceX(this.width / 2).strength(0.03))
+                .force('y', d3.forceY(this.height / 2).strength(0.03))
+                .alpha(0.3)
+                .restart();
+        }
+    },
+
+    reset() {
+        if (this.svg) this.svg.selectAll('.links-layer *, .nodes-layer *, .labels-layer *').remove();
+        this.nodes = [];
+        this.links = [];
+        if (this.simulation) this.simulation.nodes([]);
+        this.updateBadge(0);
+    },
+};

alignscope/adapters.py

@@ -0,0 +1,169 @@
+from typing import Dict, Any
+
+def extract_mpe_state(env, agent_id: str) -> Dict[str, Any]:
+    """
+    Extracts continuous (x, y) coordinates from PettingZoo MPE physics engine.
+    MPE agents have state.p_pos = [x, y].
+    """
+    try:
+        # Aces environments often expose the raw wrapped env
+        raw_env = getattr(env, "env", env)
+        if hasattr(raw_env, "unwrapped"):
+            raw_env = raw_env.unwrapped
+            
+        if hasattr(raw_env, "world"):
+            # Multi-Particle Environment (MPE)
+            for internal_agent in raw_env.world.agents:
+                # MPE raw agents are usually just named "agent 0", "adversary 0"
+                if agent_id.replace("_", " ") in internal_agent.name or internal_agent.name.replace(" ", "_") in agent_id:
+                    return {
+                        "x": float(internal_agent.state.p_pos[0]),
+                        "y": float(internal_agent.state.p_pos[1])
+                    }
+    except Exception:
+        pass
+    
+    # Fallback if properties not found
+    return {"x": 0.0, "y": 0.0}
+
+
+def extract_kaz_state(env, agent_id: str) -> Dict[str, Any]:
+    """
+    Extracts grid coordinates from PettingZoo Knights-Archers-Zombies (KAZ).
+    Also accurately identifies the role based on the agent name.
+    """
+    role = "agent"
+    if "knight" in agent_id.lower():
+        role = "knight"
+    elif "archer" in agent_id.lower():
+        role = "archer"
+    elif "zombie" in agent_id.lower():
+        role = "zombie"
+
+    pos = {"x": 0.0, "y": 0.0}
+    try:
+        raw_env = getattr(env, "env", env)
+        if hasattr(raw_env, "unwrapped"):
+            raw_env = raw_env.unwrapped
+
+        # KAZ internal objects are kept in lists like env.knights, env.archers
+        collection = []
+        if role == "knight" and hasattr(raw_env, "knights"):
+            collection = raw_env.knights
+        elif role == "archer" and hasattr(raw_env, "archers"):
+            collection = raw_env.archers
+        elif role == "zombie" and hasattr(raw_env, "zombies"):
+            collection = raw_env.zombies
+
+        # We try to match the index if agent_id ends with a number (e.g., "knight_0")
+        try:
+            idx = int(agent_id.split("_")[-1])
+            if idx < len(collection):
+                obj = collection[idx]
+                if hasattr(obj, "position"): # Usually [x, y] in KAZ
+                    pos["x"] = float(obj.position[0])
+                    pos["y"] = float(obj.position[1])
+        except (ValueError, IndexError):
+            pass
+
+    except Exception:
+        pass
+
+    return {
+        "role": role,
+        "x": pos["x"],
+        "y": pos["y"]
+    }
+
+def extract_smac_state(env, agent_id: str) -> Dict[str, Any]:
+    """
+    Extracts unit type, position, health, and shield from SMAC (StarCraft Multi-Agent Challenge).
+    
+    SMAC exposes per-unit data via env.get_unit_by_id() or the internal
+    controller's allies/enemies lists.
+    """
+    role = "marine"  # Default SMAC unit
+    pos = {"x": 0.0, "y": 0.0}
+    health = 0.0
+    shield = 0.0
+
+    try:
+        raw_env = getattr(env, "env", env)
+        if hasattr(raw_env, "unwrapped"):
+            raw_env = raw_env.unwrapped
+
+        # Extract agent index
+        try:
+            idx = int(agent_id.split("_")[-1])
+        except (ValueError, IndexError):
+            idx = 0
+
+        # SMAC StarCraft2Env exposes allies via controller
+        if hasattr(raw_env, "agents") and hasattr(raw_env, "get_unit_by_id"):
+            unit = raw_env.get_unit_by_id(idx)
+            if unit is not None:
+                pos["x"] = float(unit.pos.x) if hasattr(unit, "pos") else 0.0
+                pos["y"] = float(unit.pos.y) if hasattr(unit, "pos") else 0.0
+                health = float(unit.health) / float(unit.health_max) if hasattr(unit, "health_max") and unit.health_max > 0 else 0.0
+                shield = float(unit.shield) / float(unit.shield_max) if hasattr(unit, "shield_max") and unit.shield_max > 0 else 0.0
+
+                # Infer role from unit type
+                unit_type = getattr(unit, "unit_type", None)
+                type_map = {
+                    0: "marine", 1: "marauder", 2: "medivac",
+                    48: "marine", 49: "marauder", 50: "reaper",
+                    51: "ghost", 73: "zealot", 74: "stalker",
+                    75: "sentry", 76: "high_templar", 77: "colossus",
+                }
+                if unit_type is not None:
+                    role = type_map.get(unit_type, f"unit_{unit_type}")
+
+        # Fallback: try the _obs property or controller
+        elif hasattr(raw_env, "controller") or hasattr(raw_env, "_sc2_env"):
+            # Newer SMAC versions
+            sc2_env = getattr(raw_env, "_sc2_env", raw_env)
+            if hasattr(sc2_env, "get_ally_units"):
+                allies = sc2_env.get_ally_units()
+                if idx < len(allies):
+                    unit = allies[idx]
+                    pos["x"] = float(getattr(unit, "x", 0))
+                    pos["y"] = float(getattr(unit, "y", 0))
+                    health = float(getattr(unit, "health", 0)) / max(float(getattr(unit, "health_max", 1)), 1)
+                    role = "ally"
+
+    except Exception:
+        pass
+
+    return {
+        "role": role,
+        "x": pos["x"],
+        "y": pos["y"],
+        "health": health,
+        "shield": shield,
+    }
+
+
+def try_extract_env_state(env, agent_id: str) -> Dict[str, Any]:
+    """
+    Master adapter router. Detects environment type and routes to the correct extractor.
+    """
+    env_name = str(env).lower()
+    
+    # Check for MPE
+    if "mpe" in env_name or "simple_" in env_name:
+        return extract_mpe_state(env, agent_id)
+        
+    # Check for Knights Archers Zombies
+    if "knights_archers_zombies" in env_name or "kaz" in env_name:
+        return extract_kaz_state(env, agent_id)
+    
+    # Check for SMAC (StarCraft Multi-Agent Challenge)
+    if "starcraft" in env_name or "smac" in env_name or "sc2" in env_name:
+        return extract_smac_state(env, agent_id)
+
+    # Check for SMAC by attribute detection (env_name may not contain keywords)
+    raw = getattr(env, "unwrapped", env)
+    if hasattr(raw, "get_unit_by_id") or hasattr(raw, "_sc2_env"):
+        return extract_smac_state(env, agent_id)
+        
+    return {"x": 0.0, "y": 0.0}

alignscope/cli.py

@@ -0,0 +1,99 @@
+"""
+AlignScope — CLI
+
+Commands:
+    alignscope start [--port 8000] [--demo]   Start the dashboard server
+    alignscope patch <framework>               Auto-patch a MARL framework
+    alignscope share                          Create a public tunnel (ngrok)
+    alignscope version                        Print version
+"""
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.group()
+def main():
+    """🔬 AlignScope — MARL Alignment Observability"""
+    pass
+
+
+@main.command()
+@click.option("--port", default=8000, help="Port to serve on")
+@click.option("--host", default="0.0.0.0", help="Host to bind to")
+@click.option("--demo", is_flag=True, help="Run built-in demo simulator")
+def start(port: int, host: str, demo: bool):
+    """Start the AlignScope dashboard server."""
+    from alignscope.server import run_server
+
+    console.print()
+    console.print("[bold cyan]🔬 AlignScope[/] starting...", highlight=False)
+    console.print()
+
+    run_server(host=host, port=port, demo=demo)
+
+
+@main.command()
+@click.argument("framework", type=click.Choice(["rllib", "pettingzoo", "pymarl"]))
+def patch(framework: str):
+    """Auto-patch a MARL framework for zero-code integration."""
+    from alignscope.patches import apply_patch
+
+    console.print(f"\n[bold cyan]🔬 AlignScope[/] patching [bold]{framework}[/]...\n")
+
+    success = apply_patch(framework)
+
+    if success:
+        console.print(f"[green]✓[/] [bold]{framework}[/] successfully patched!")
+        console.print(f"  Your training code needs [bold]zero changes[/].")
+        console.print(f"  Just run [cyan]alignscope start[/] in another terminal,")
+        console.print(f"  then run your training script as normal.\n")
+    else:
+        console.print(f"[red]✗[/] Failed to patch {framework}.")
+        console.print(f"  Is it installed? Try: [cyan]pip install alignscope[{framework}][/]\n")
+
+
+@main.command()
+@click.option("--port", default=8000, help="Local port to tunnel")
+def share(port: int):
+    """Create a public URL to share your dashboard with teammates."""
+    try:
+        from pyngrok import ngrok
+
+        console.print(f"\n[bold cyan]🔬 AlignScope[/] creating public tunnel...\n")
+
+        tunnel = ngrok.connect(port, "http")
+        public_url = tunnel.public_url
+
+        console.print(f"[green]✓[/] Dashboard is now publicly accessible:")
+        console.print(f"  [bold link={public_url}]{public_url}[/]")
+        console.print(f"\n  Share this URL with your team.")
+        console.print(f"  Press [bold]Ctrl+C[/] to stop sharing.\n")
+
+        try:
+            ngrok.get_tunnels()
+            input("  Press Enter to stop sharing...")
+        except KeyboardInterrupt:
+            pass
+        finally:
+            ngrok.disconnect(tunnel.public_url)
+            console.print("\n[yellow]Tunnel closed.[/]\n")
+
+    except ImportError:
+        console.print(
+            "\n[red]✗[/] ngrok is not installed.\n"
+            "  Install it with: [cyan]pip install pyngrok[/]\n"
+        )
+
+
+@main.command()
+def version():
+    """Print AlignScope version."""
+    from alignscope import __version__
+    console.print(f"AlignScope v{__version__}")
+
+
+if __name__ == "__main__":
+    main()