Q&A: Configuring SurpriseDetector — strategy selection, thresholds, and CognitiveCycle wiring

[web3guru888]

Configuration and wiring questions for SurpriseDetector (Phase 13.4, issue #377).

Q1: Which detection strategy should I use?

Use case	Recommended strategy
Environment with fixed observation scale	THRESHOLD
General purpose, world model improves over time	Z_SCORE (default)
Heavy-tailed / non-Gaussian surprise distribution	IQR
Multi-dimensional observation space	ISOLATION_FOREST

Start with Z_SCORE (default) unless you have domain knowledge suggesting otherwise.

---

Q2: What Z-score thresholds should I set?

Default values: z_low=1.5, z_medium=2.5, z_high=3.5 (standard deviation multiples).

Sensitivity	z_low	z_medium	z_high	Notes
Very sensitive	1.0	2.0	3.0	More HIGH alerts, faster gating
Default	1.5	2.5	3.5	Balanced
Conservative	2.0	3.0	4.5	Fewer false positives

---

Q3: What does alert_cooldown_steps do?

alert_cooldown_steps=50 prevents AlertCallback from firing on every single HIGH-severity step during a sustained anomaly burst. After one callback fires at step N, the next callback won't fire until step N+50, even if severity stays HIGH.

Increase if callbacks are expensive (e.g. network calls). Decrease for faster alerting.

---

Q4: How do I wire SurpriseDetector into CognitiveCycle?

from asi.cognitive_cycle import CognitiveCycle
from asi.surprise_detector import build_surprise_detector, DetectorConfig, DetectionStrategy

# 1. Build detector
cfg = DetectorConfig(strategy=DetectionStrategy.Z_SCORE, z_high=3.5)
detector = build_surprise_detector(world_model=wm, config=cfg)

# 2. Register alert callbacks
async def on_high(episode):
    metrics.asi_surprise_high_episodes_total.inc()

await detector.register_callback(SeverityLevel.HIGH, on_high)

# 3. Inject into cycle
cycle = CognitiveCycle(
    ...,
    surprise_detector=detector,
    curiosity_module=curiosity,
)

---

Q5: What happens if I set enabled=False?

detect() immediately returns a SurpriseEpisode with severity=NORMAL and score=0.0, without calling WorldModel.surprise(). No callbacks fire, no curiosity gating occurs. Zero overhead.

---

Q6: Can I register multiple callbacks for the same severity?

Yes. All callbacks registered at or below the episode's severity level fire concurrently:

await detector.register_callback(SeverityLevel.MEDIUM, log_medium)
await detector.register_callback(SeverityLevel.HIGH,   page_oncall)

# When severity=HIGH: both log_medium and page_oncall fire
# When severity=MEDIUM: only log_medium fires

---

Q7: How do I visualise surprise detections in Grafana?

# panels
- title: Surprise detection rate by severity
  type: timeseries
  targets:
    - expr: rate(asi_surprise_detections_total[1m])
      legendFormat: "{{severity}}"

- title: Window mean surprise
  type: gauge
  targets:
    - expr: asi_surprise_window_mean

- title: HIGH episode count
  type: stat
  targets:
    - expr: asi_surprise_high_episodes_total