# activation-drift-monitor

## Overview

`activation-drift-monitor` is a reusable Python library for tracking activation-distribution drift between reference (training/known-good) behavior and live inference behavior. It provides:

- per-layer baseline profiling (running moments)
- per-layer drift scoring (mean-shift + variance-shift)
- global alert aggregation with warmup and cooldown controls
- optional PyTorch hook collection utilities
- a companion stdio MCP interface exposing the same monitor operations

The package is extracted from the validated activation-monitoring methodology used in this workspace's empirical pipeline.

## Installation

Canonical user flow:

1. `pip install omegaxiv`
2. `ox install activation-drift-monitor==0.1.0`

Additive MCP registration flow:

- `ox install activation-drift-monitor==0.1.0 --mcp`
- `ox install activation-drift-monitor==0.1.0 --mcp=codex`
- `ox install activation-drift-monitor==0.1.0 --mcp=claude`
- `ox install activation-drift-monitor==0.1.0 --mcp=all`

Maintainer/dev-only source install (not the canonical end-user path):

- `pip install ./packages/activation-drift-monitor`

Optional extras:

- PyTorch hooks: `pip install ./packages/activation-drift-monitor[torch]`
- FastMCP runtime: `pip install ./packages/activation-drift-monitor[mcp]`

## Configuration

Primary monitor parameters (via `ActivationDriftMonitor`):

- `warmup_batches`: number of baseline profile updates required before alerts can fire
- `sensitivity`: per-layer drift threshold
- `alert_cooldown`: batches to suppress repeated alerts after firing
- `global_threshold`: batch-level threshold for global alert status
- `min_std`: numerical floor for variance-derived normalization
- `weights`: blend for mean-shift and variance-shift terms

## Usage Examples

```python
from activation_drift_monitor import ActivationDriftMonitor

monitor = ActivationDriftMonitor(warmup_batches=3, sensitivity=1.8, alert_cooldown=2)

# Reference profiling phase
for _ in range(3):
    monitor.profile_reference("encoder.block1", [0.02, -0.01, 0.03, 0.01])

# Inference phase
result = monitor.evaluate_batch(
    {
        "encoder.block1": [0.90, 1.05, 0.87, 1.10],
        "encoder.block2": [0.01, 0.03, -0.02, 0.00],
    }
)

print(result.global_alert, result.global_score)
for layer, alert in result.layer_alerts.items():
    print(layer, alert.alert, alert.score.fused_score)
```

```python
from activation_drift_monitor.metrics import ood_metrics_from_scores, rbf_mmd2_from_gaussian

metrics = ood_metrics_from_scores(
    id_scores=[0.1, 0.2, 0.3, 0.4],
    ood_scores=[0.7, 0.8, 0.9, 1.0],
)
print(metrics["auroc"], metrics["threshold"])
print(rbf_mmd2_from_gaussian(mean_shift=0.5, var_ratio=1.5, gamma=1.0))
```

## MCP Companion Interface

The package ships an additive stdio MCP companion module at:

- `python -m activation_drift_monitor.mcp_server --mode stdio`

Exposed tools map directly to Python API behavior:

- `profile_reference`: wraps `ActivationDriftMonitor.profile_reference_batch`
- `evaluate_batch`: wraps `ActivationDriftMonitor.evaluate_batch`
- `reset_monitor`: wraps `ActivationDriftMonitor.reset`
- `get_state`: wraps `ActivationDriftMonitor.export_state`

Resource surface:

- `monitor://state`: serialized monitor state snapshot

Example local client config is available at `mcp_config.example.json`.

## Troubleshooting

- Alerts never trigger: reduce `warmup_batches` or `sensitivity`; verify baseline was profiled first.
- Too many alerts: increase `sensitivity` and/or `alert_cooldown`.
- PyTorch hook attach fails: install optional torch extra and confirm layer names are reachable.
- MCP server launches but client cannot use tools: verify stdio transport and that the client sends JSON lines with supported methods (`list_tools`, `call_tool`, `read_resource`).