Python SDK

Detect behavioral anomalies

Example status: illustrative, not runnable as written. The Python examples on this page are built on an embedded in-repo facade imported as core.eve_sdk (an EVE(...) object with govern_* methods). That module is not present in the current repository and is not published on any registry, so these snippets raise ModuleNotFoundError if run. They are kept because they show the intended governance flow. For code that runs today, use the published client: pip install eve-coreguard, then from eve_coreguard import CoreGuardClient and call client.evaluate(...), with offline evidence checking via client.verify_evidence(...) or the standalone verify_decision_record. See the CoreGuard integration guide and the Python SDK reference.

Watch an agent's behavior over a window and flag statistical deviations. EVE uses deterministic detectors (rolling / robust z-score, EWMA, CUSUM) and produces signed monitoring envelopes summarizing behavior over that window.

Prerequisites

The EVE embedded service facade (from core.eve_sdk import EVE) — monitoring runs in the service.
Synthetic activity to observe; no production credentials.

Installation

# Behavioral monitoring runs in the EVE service (Python).
pip install eve-coreguard   # for the hosted client

Runnable code

Anomaly detection observes governed activity and emits events plus a signed envelope. Conceptually:

# As governed calls flow through EVE, deterministic detectors track per-window
# statistics (rolling/robust z-score, EWMA, CUSUM). Deviations produce anomaly
# events, and the window is summarized in a signed monitoring envelope.

# anomaly event example:
#   {"detector": "robust_zscore", "z_score": 4.2, "escalation": "flag"}
# monitoring envelope example:
#   signed envelope summarizing agent behavior over the window

Wire the detectors to observe your agent's governed calls, then read the emitted anomaly events and the window envelope.

Expected result

Normal activity produces no anomaly events.
A sharp deviation (spike in call rate or argument size, for example) produces an anomaly event with the detector name, the score, and an escalation level.
The window is summarized in a signed monitoring envelope.

Evidence output

anomaly event {detector, z_score, escalation}
monitoring envelope with signature

Verification

The monitoring envelope is signed; verify it offline like any EVE evidence (see verify-evidence-offline.md).

Failure example

Statistical detectors flag deviations, but on their own they are advisory — a flagged anomaly does not block an action unless you wire it to a deterministic enforcement action (for example a CoreGuard decision, a budget, or a sequence rule).

Production considerations

Treat anomaly events as advisory signals; connect them to a deterministic enforcement control if you want them to block.
Tune detector windows and thresholds to your baseline; deterministic detectors will still flag legitimate but unusual bursts.
Retain signed monitoring envelopes as part of your review record.

Limitations

Behavioral anomaly detection is PILOT_READY. Detectors are deterministic statistical measures; they flag deviations and are advisory unless wired to a deterministic enforcement action.
Monitoring is observational; enforcement decisions are made by CoreGuard, sequence, and budget controls.

Next step

Wire anomalies to enforcement with block-a-prohibited-sequence.md or enforce-a-budget.md, and test candidate detector policies safely with test-a-shadow-policy.md.