alignscope 0.1.0__tar.gz

alignscope-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python distribution to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/alignscope
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout Source
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build hatchling
+      - name: Build a binary wheel and a source tarball
+        run: python -m build --sdist --wheel --outdir dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

alignscope-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+- Core Python SDK for zero-code instrumentation of MARL environments (`alignscope.wrap`).
+- Real-time dashboard featuring Force-Directed Agent Topology, Event Timeline, and cooperative metrics.
+- Universal environment adapters for PettingZoo, MPE, and SMAC.
+- Seamless metric forwarding integrations for Weights & Biases and MLflow.
+- Offline replay streaming functionality for CSV, JSON, NPZ, and TensorBoard logs.
+- Automated anomaly detection engine identifying agent defections and coalition breakages in real-time.

alignscope-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install the package
+COPY pyproject.toml .
+COPY alignscope/ alignscope/
+COPY frontend/ frontend/
+COPY README.md .
+
+RUN pip install --no-cache-dir .
+
+# Expose dashboard port
+EXPOSE 8000
+
+# Default: start in demo mode
+CMD ["alignscope", "start", "--demo", "--port", "8000"]

alignscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nithisha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alignscope-0.1.0/MOTIVATION.md

@@ -0,0 +1,32 @@
+# Why AlignScope Matters for Alignment Research
+
+AI alignment is not just a single-agent problem. As multi-agent reinforcement learning (MARL) systems grow in complexity — agents learning to cooperate, specialize, and form coalitions — we need tools to **observe** alignment as it emerges.
+
+AlignScope is a scientific instrument for this phenomenon.
+
+## The Measurement Gap
+
+You can't study what you can't see.
+
+Most MARL training pipelines produce experience logs and reward curves that tell you *whether* an agent won, but not *how* alignment formed — or when it broke. The three questions that matter most to alignment research are currently invisible in standard tooling:
+
+1. **Are agents specializing?** When agents commit to consistent roles, that's not just strategy — that's the beginning of role-based trust, the same dynamic that makes cells differentiate in an organism. AlignScope measures this as **role stability** via Shannon entropy.
+
+2. **Are agents reciprocating?** When Agent A gathers resources for Agent B, and B captures objectives for A, that's the seed of coalition — individuals learning to form cooperative wholes. AlignScope measures this as the **reciprocity index**.
+
+3. **When does alignment fail?** The most scientifically valuable moment in any training run is not when everything works — it's the exact tick when an agent defects. That moment reveals what the alignment was actually built on, and how fragile it was. AlignScope's **defection detector** flags these moments so researchers can inspect what changed.
+
+## What This Enables
+
+With AlignScope, a researcher can:
+
+- Watch coalition clusters form in real-time in the topology graph and see which role combinations naturally attract
+- Identify which training configurations produce stable alignment vs. fragile cooperation that breaks under pressure
+- Compare episodes side-by-side using alignment metric histories rather than just reward curves
+- Build intuition about organic alignment by *seeing* it happen, not reconstructing it from logs
+
+## Environment Agnostic
+
+AlignScope works with **any** MARL environment. Whether you're training agents in grid worlds, competitive games, robotics simulations, or social dilemma environments — if your agents have roles, teams, and interactions, AlignScope can visualize their alignment dynamics.
+
+This is not observability for observability's sake. It's a scientific instrument for studying emergent cooperation in artificial intelligence.

alignscope-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: alignscope
+Version: 0.1.0
+Summary: Real-time alignment observability for multi-agent reinforcement learning
+Project-URL: Homepage, https://github.com/raghavarajunithisha-lab/AlignScopeV1
+Project-URL: Documentation, https://github.com/raghavarajunithisha-lab/AlignScopeV1#readme
+Project-URL: Repository, https://github.com/raghavarajunithisha-lab/AlignScopeV1
+Author-email: Nithisha <nithisha2201@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: alignment,dashboard,marl,multi-agent,observability,reinforcement-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: rich>=13.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: all
+Requires-Dist: mlflow>=2.0; extra == 'all'
+Requires-Dist: pettingzoo>=1.22; extra == 'all'
+Requires-Dist: ray[rllib]>=2.0; extra == 'all'
+Requires-Dist: wandb>=0.15; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: mlflow
+Requires-Dist: mlflow>=2.0; extra == 'mlflow'
+Provides-Extra: pettingzoo
+Requires-Dist: pettingzoo>=1.22; extra == 'pettingzoo'
+Provides-Extra: pymarl
+Provides-Extra: rllib
+Requires-Dist: ray[rllib]>=2.0; extra == 'rllib'
+Provides-Extra: wandb
+Requires-Dist: wandb>=0.15; extra == 'wandb'
+Description-Content-Type: text/markdown
+
+# AlignScope 🔬
+
+[![PyPI version](https://badge.fury.io/py/alignscope.svg)](https://badge.fury.io/py/alignscope)
+[![Build Status](https://github.com/raghavarajunithisha-lab/AlignScopeV1/actions/workflows/publish.yml/badge.svg)](https://github.com/raghavarajunithisha-lab/AlignScopeV1/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**An open-source observability SDK and real-time streaming dashboard designed to monitor and debug Multi-Agent Reinforcement Learning (MARL) systems.**
+
+AlignScope gives machine learning engineers and researchers instant, zero-code visual feedback on complex multi-agent dynamics—including coalition formation, role specialization, reciprocity collapses, and defection events—without needing to manually parse through thousands of lines of terminal logs.
+
+---
+
+## 🎯 Why This Matters
+
+Debugging multi-agent AI ecosystems is notoriously difficult. Standard MLOps tools like Weights & Biases (W&B) and MLflow are optimized for **scalar metrics** (loss, reward curves) but fall short when answering spatial or behavioral questions:
+
+- *Why did the agent defect?*
+- *When exactly did the cooperative coalition break down?*
+- *Are agents actually specializing into useful roles, or just exploiting the environment?*
+
+**AlignScope solves this by providing real-time topological graphs and event timelines** specifically engineered for multi-agent anomalies. It translates raw, high-frequency environment steps into actionable, human-readable alignment metrics.
+
+### Key Capabilities
+
+*   **Zero-code Integration**: One line (`alignscope.wrap(env)`) instruments any standard PettingZoo or RLlib environment.
+*   **Real-Time Streaming**: High-performance WebSocket backend streams data to a 60fps D3.js and Canvas frontend.
+*   **Automated Anomaly Detection**: Dynamically identifies defection, stability drops, and coalition fragmentation using continuous rolling averages.
+*   **No Vendor Lock-in**: Automatically forwards intercepted telemetry back out to Weights & Biases and MLflow for persisted logging.
+
+---
+
+## 🏗️ Architecture Overview
+
+AlignScope is designed as a decoupled, full-stack monitoring solution:
+
+1.  **The SDK (Python)**: A lightweight, non-blocking telemetry tracker that normalizes raw environment step data, computes real-time alignment metrics (reciprocity, stability, convergence), and flags anomalous behavior.
+2.  **The Backend (FastAPI + WebSockets)**: A robust server that manages high-frequency incoming telemetry and broadcasts it to connected clients.
+3.  **The Dashboard (Vanilla JS + D3.js)**: A dark-mode, browser-based UI featuring:
+    *   **Force-Directed Agent Topology**: Visualizing agent relationships, teams, and defections dynamically.
+    *   **Zoomable Event Timeline**: A high-performance canvas timeline pinpointing the exact training tick where cooperation fails.
+
+---
+
+## 💼 Core Use Cases
+
+**For ML Engineers:**
+*   **Reduce Debugging Time**: Identify exactly when and why training instability occurs without waiting for the full epoc to finish.
+*   **Track Systemic Collapse**: Monitor reciprocity and role stability drops to catch model collapse early.
+*   **Offline Log Replay**: Stream huge offline CSV, JSON, NPZ, or TensorBoard training runs through the dashboard for retroactive analysis.
+
+**For Researchers:**
+*   **Study Emergent Behavior**: Measure actual role specialization (Shannon entropy) and goal convergence (Cosine similarity).
+*   **Validate Alignment**: Visually confirm that your agents are forming expected coalitions in environments like SMAC (StarCraft II) or MPE.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install AlignScope directly via PyPI:
+
+```bash
+pip install alignscope
+```
+
+### Starting the Dashboard
+
+Launch the real-time visualization server:
+
+```bash
+alignscope start
+```
+
+Open **http://localhost:8000** and watch agents interact live.
+
+
+## Why AlignScope?
+
+Training MARL agents is hard. Understanding *why* they succeed or fail is harder. Most researchers rely on reward curves and terminal logs — but those don't tell you:
+
+- **When** did cooperation break down?
+- **Which** agent defected, and why?
+- **How** are coalitions forming and dissolving over time?
+- **Are** agents actually specializing into useful roles?
+
+AlignScope answers all of these questions **visually and in real time**.
+
+### Key Advantages
+
+| Advantage | Description |
+|-----------|-------------|
+| **Zero-code integration** | One line (`alignscope.wrap(env)`) to instrument any PettingZoo environment |
+| **Environment agnostic** | Works with PettingZoo, SMAC, RLlib, EPyMARL, or any custom env |
+| **Real-time dashboard** | Watch agents move, form coalitions, and defect as training runs |
+| **Scientific precision** | Pinpoints the exact tick where cooperation fails |
+| **No vendor lock-in** | Forwards metrics to W&B and MLflow automatically if installed |
+| **Offline replay** | Replay saved CSV, JSON, NPZ, TensorBoard, or W&B logs into the dashboard |
+
+
+## Supported MARL Environments
+
+AlignScope is designed to work with **any** multi-agent system. Here are the environments with dedicated adapters:
+
+### 1. PettingZoo (Cooperative & Classic Games)
+
+PettingZoo is the most widely used MARL framework. AlignScope wraps **any** PettingZoo environment — AEC or Parallel API — with a single line.
+
+```python
+import alignscope
+from pettingzoo.butterfly import knights_archers_zombies_v10
+
+# 1. Initialize your environment
+env = knights_archers_zombies_v10.env()
+
+# 2. Add one line to wrap it with AlignScope
+env = alignscope.wrap(env)  
+
+# 3. Run your standard training loop!
+env.reset()
+for agent in env.agent_iter():
+    obs, reward, term, trunc, info = env.last()
+    action = env.action_space(agent).sample() if not (term or trunc) else None
+    env.step(action)
+```
+
+*(See `examples/` for templates using RLlib, SMAC, and offline log replay.)*
+
+---
+
+## 🤝 Contributing & Support
+
+We welcome contributions! Whether it's adding a new environment adapter, optimizing the frontend canvas renderer, or designing new alignment metrics.
+
+For support, issues, or professional inquiries, please [open an issue](https://github.com/raghavarajunithisha-lab/AlignScopeV1/issues) or reach out directly:
+📧 **nithisha2201@gmail.com**
+
+*Designed and maintained by Nithisha.*

alignscope-0.1.0/README.md

@@ -0,0 +1,138 @@
+# AlignScope 🔬
+
+[![PyPI version](https://badge.fury.io/py/alignscope.svg)](https://badge.fury.io/py/alignscope)
+[![Build Status](https://github.com/raghavarajunithisha-lab/AlignScopeV1/actions/workflows/publish.yml/badge.svg)](https://github.com/raghavarajunithisha-lab/AlignScopeV1/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**An open-source observability SDK and real-time streaming dashboard designed to monitor and debug Multi-Agent Reinforcement Learning (MARL) systems.**
+
+AlignScope gives machine learning engineers and researchers instant, zero-code visual feedback on complex multi-agent dynamics—including coalition formation, role specialization, reciprocity collapses, and defection events—without needing to manually parse through thousands of lines of terminal logs.
+
+---
+
+## 🎯 Why This Matters
+
+Debugging multi-agent AI ecosystems is notoriously difficult. Standard MLOps tools like Weights & Biases (W&B) and MLflow are optimized for **scalar metrics** (loss, reward curves) but fall short when answering spatial or behavioral questions:
+
+- *Why did the agent defect?*
+- *When exactly did the cooperative coalition break down?*
+- *Are agents actually specializing into useful roles, or just exploiting the environment?*
+
+**AlignScope solves this by providing real-time topological graphs and event timelines** specifically engineered for multi-agent anomalies. It translates raw, high-frequency environment steps into actionable, human-readable alignment metrics.
+
+### Key Capabilities
+
+*   **Zero-code Integration**: One line (`alignscope.wrap(env)`) instruments any standard PettingZoo or RLlib environment.
+*   **Real-Time Streaming**: High-performance WebSocket backend streams data to a 60fps D3.js and Canvas frontend.
+*   **Automated Anomaly Detection**: Dynamically identifies defection, stability drops, and coalition fragmentation using continuous rolling averages.
+*   **No Vendor Lock-in**: Automatically forwards intercepted telemetry back out to Weights & Biases and MLflow for persisted logging.
+
+---
+
+## 🏗️ Architecture Overview
+
+AlignScope is designed as a decoupled, full-stack monitoring solution:
+
+1.  **The SDK (Python)**: A lightweight, non-blocking telemetry tracker that normalizes raw environment step data, computes real-time alignment metrics (reciprocity, stability, convergence), and flags anomalous behavior.
+2.  **The Backend (FastAPI + WebSockets)**: A robust server that manages high-frequency incoming telemetry and broadcasts it to connected clients.
+3.  **The Dashboard (Vanilla JS + D3.js)**: A dark-mode, browser-based UI featuring:
+    *   **Force-Directed Agent Topology**: Visualizing agent relationships, teams, and defections dynamically.
+    *   **Zoomable Event Timeline**: A high-performance canvas timeline pinpointing the exact training tick where cooperation fails.
+
+---
+
+## 💼 Core Use Cases
+
+**For ML Engineers:**
+*   **Reduce Debugging Time**: Identify exactly when and why training instability occurs without waiting for the full epoc to finish.
+*   **Track Systemic Collapse**: Monitor reciprocity and role stability drops to catch model collapse early.
+*   **Offline Log Replay**: Stream huge offline CSV, JSON, NPZ, or TensorBoard training runs through the dashboard for retroactive analysis.
+
+**For Researchers:**
+*   **Study Emergent Behavior**: Measure actual role specialization (Shannon entropy) and goal convergence (Cosine similarity).
+*   **Validate Alignment**: Visually confirm that your agents are forming expected coalitions in environments like SMAC (StarCraft II) or MPE.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install AlignScope directly via PyPI:
+
+```bash
+pip install alignscope
+```
+
+### Starting the Dashboard
+
+Launch the real-time visualization server:
+
+```bash
+alignscope start
+```
+
+Open **http://localhost:8000** and watch agents interact live.
+
+
+## Why AlignScope?
+
+Training MARL agents is hard. Understanding *why* they succeed or fail is harder. Most researchers rely on reward curves and terminal logs — but those don't tell you:
+
+- **When** did cooperation break down?
+- **Which** agent defected, and why?
+- **How** are coalitions forming and dissolving over time?
+- **Are** agents actually specializing into useful roles?
+
+AlignScope answers all of these questions **visually and in real time**.
+
+### Key Advantages
+
+| Advantage | Description |
+|-----------|-------------|
+| **Zero-code integration** | One line (`alignscope.wrap(env)`) to instrument any PettingZoo environment |
+| **Environment agnostic** | Works with PettingZoo, SMAC, RLlib, EPyMARL, or any custom env |
+| **Real-time dashboard** | Watch agents move, form coalitions, and defect as training runs |
+| **Scientific precision** | Pinpoints the exact tick where cooperation fails |
+| **No vendor lock-in** | Forwards metrics to W&B and MLflow automatically if installed |
+| **Offline replay** | Replay saved CSV, JSON, NPZ, TensorBoard, or W&B logs into the dashboard |
+
+
+## Supported MARL Environments
+
+AlignScope is designed to work with **any** multi-agent system. Here are the environments with dedicated adapters:
+
+### 1. PettingZoo (Cooperative & Classic Games)
+
+PettingZoo is the most widely used MARL framework. AlignScope wraps **any** PettingZoo environment — AEC or Parallel API — with a single line.
+
+```python
+import alignscope
+from pettingzoo.butterfly import knights_archers_zombies_v10
+
+# 1. Initialize your environment
+env = knights_archers_zombies_v10.env()
+
+# 2. Add one line to wrap it with AlignScope
+env = alignscope.wrap(env)  
+
+# 3. Run your standard training loop!
+env.reset()
+for agent in env.agent_iter():
+    obs, reward, term, trunc, info = env.last()
+    action = env.action_space(agent).sample() if not (term or trunc) else None
+    env.step(action)
+```
+
+*(See `examples/` for templates using RLlib, SMAC, and offline log replay.)*
+
+---
+
+## 🤝 Contributing & Support
+
+We welcome contributions! Whether it's adding a new environment adapter, optimizing the frontend canvas renderer, or designing new alignment metrics.
+
+For support, issues, or professional inquiries, please [open an issue](https://github.com/raghavarajunithisha-lab/AlignScopeV1/issues) or reach out directly:
+📧 **nithisha2201@gmail.com**
+
+*Designed and maintained by Nithisha.*

alignscope-0.1.0/alignscope/__init__.py

@@ -0,0 +1,150 @@
+"""
+AlignScope — Real-time alignment observability for multi-agent RL.
+
+Usage:
+    import alignscope
+
+    # Initialize a tracking run
+    alignscope.init(project="my-experiment")
+
+    # In your training loop, add one line:
+    alignscope.log(step, agents, obs, actions, rewards)
+
+    # Or start the dashboard server:
+    alignscope.start(port=8000, demo=True)
+
+    # Framework-specific integrations:
+    alignscope.patch("rllib")           # Auto-patch RLlib
+    env = alignscope.wrap(env)          # Wrap PettingZoo env
+"""
+
+from typing import Optional, Union
+
+__version__ = "0.1.0"
+
+from alignscope.sdk import AlignScopeTracker
+
+# Module-level singleton tracker
+_tracker: Optional[AlignScopeTracker] = None
+
+
+def init(
+    project: str = "default",
+    server_url: str = "ws://localhost:8000/ws/sdk",
+    preset: Optional[str] = None,
+    paradigm: Optional[dict] = None,
+    metrics: Optional[list] = None,
+    events: Optional[list] = None,
+    topology: Optional[dict] = None,
+    config: Optional[dict] = None,
+    forward_wandb: bool = True,
+    forward_mlflow: bool = True,
+) -> AlignScopeTracker:
+    """
+    Initialize an AlignScope tracking session.
+
+    Args:
+        project: Name for this experiment run
+        server_url: WebSocket URL of the AlignScope dashboard server
+        config: Optional environment config (teams, roles, etc.)
+        forward_wandb: If True and wandb is installed, forward metrics to W&B
+        forward_mlflow: If True and mlflow is installed, forward metrics to MLflow
+
+    Returns:
+        AlignScopeTracker instance
+    """
+    global _tracker
+    _tracker = AlignScopeTracker(
+        project=project,
+        server_url=server_url,
+        preset=preset,
+        paradigm=paradigm,
+        metrics=metrics,
+        events=events,
+        topology=topology,
+        config=config,
+        forward_wandb=forward_wandb,
+        forward_mlflow=forward_mlflow,
+    )
+    return _tracker
+
+
+def log(
+    step: int,
+    agents = None,
+    obs: object = None,
+    actions: object = None,
+    rewards: object = None,
+    **kwargs,
+) -> None:
+    """
+    Log one step of multi-agent data. This is the Tier 2 one-line API.
+
+    Args:
+        step: Current timestep / tick number
+        agents: Agent states — list of dicts or framework-specific format
+        obs: Observations (auto-normalized from framework format)
+        actions: Actions taken (auto-normalized)
+        rewards: Rewards received (auto-normalized)
+        **kwargs: Additional data to attach to this step
+    """
+    global _tracker
+    if _tracker is None:
+        # Auto-init with defaults if not explicitly initialized
+        init()
+    _tracker.log(step, agents=agents, obs=obs, actions=actions, rewards=rewards, **kwargs)
+
+
+def report(tick: int, agent: Union[str, int], metrics: dict) -> None:
+    """Dynamically report custom metrics for an agent."""
+    global _tracker
+    if _tracker is None:
+        init()
+    _tracker.report(tick, agent, metrics)
+
+
+def event(tick: int, type: str, agent: Union[str, int], detail: str, severity: float = 0.5) -> None:
+    """Dynamically report custom events."""
+    global _tracker
+    if _tracker is None:
+        init()
+    _tracker.event(tick, type, agent, detail, severity)
+
+
+def start(port: int = 8000, host: str = "0.0.0.0", demo: bool = False) -> None:
+    """
+    Start the AlignScope dashboard server.
+
+    Args:
+        port: Port to serve on (default 8000)
+        host: Host to bind to (default 0.0.0.0)
+        demo: If True, run the built-in demo simulator
+    """
+    from alignscope.server import run_server
+    run_server(host=host, port=port, demo=demo)
+
+
+def patch(framework: str) -> None:
+    """
+    Auto-patch a MARL framework for zero-code integration (Tier 1).
+
+    Args:
+        framework: One of "rllib", "pettingzoo", "pymarl"
+    """
+    from alignscope.patches import apply_patch
+    apply_patch(framework)
+
+
+def wrap(env, **kwargs):
+    """
+    Wrap a PettingZoo environment for automatic logging (Tier 3).
+
+    Args:
+        env: A PettingZoo environment instance
+        **kwargs: Additional config passed to the wrapper
+
+    Returns:
+        Wrapped environment that auto-logs to AlignScope
+    """
+    from alignscope.patches.pettingzoo import AlignScopeWrapper
+    return AlignScopeWrapper(env, **kwargs)