cascai

Cascade AI — regime-aware HMM scoring for multi-agent systems. Detects behavioral regimes in agent runs and scores system health using Hidden Markov Models.

Install

pip install cascai

Quickstart

# Print installed version
cascai version

# Show current agent health status from stored runs
cascai status

# Score a specific run by ID
cascai score <run_id>

# Ingest a JSONL log file of agent runs into the database
cascai ingest path/to/runs.jsonl

# Render an HTML dashboard with regime analysis and health-score trend
cascai visualize

Known Limitations

Non-ASCII paths: The cascai CLI may fail to locate its database when installed in or run from a directory whose path contains non-ASCII characters (e.g. Hebrew file names). Workaround: install into a plain-ASCII path and set CASCAI_DB_PATH to point to your data directory explicitly. If the cascai console script itself won't launch, run python -m cascai.cli <command> instead (note: python -m cascai does not work — there is no cascai/__main__.py — the module path must be cascai.cli).

• Reverse-Effect Classifier: The Reverse-Effect Classifier module (cascai.reverse_effect) has accuracy roughly at base-rate (no meaningful improvement over random guessing). It is not production-ready and should not be relied upon for critical decision-making.

• Import-time telemetry: import cascai writes a small amount of module-load telemetry (~10 lines) to ~/.cascai/runs.jsonl (or $CASCAI_STATE_DIR/runs.jsonl if set) as a side effect of package initialization. This happens on any import, with no explicit user action. It does not affect functionality and contains no user data — only module-load timing markers.

• cascai score accuracy with standalone ingest: when using cascai ingest directly (without real Anthropic SDK interception), input_tokens is not captured and defaults to 0. Since the Cascai Equation's theta term depends on input_tokens variance, cascai score will return a constant equilibrium value (V≈5.0) regardless of actual agent health for standalone-ingested data. Use cascai status for accurate regime/health assessment in this case — it does not depend on input_tokens. cascai score is fully accurate only when used with real SDK-intercepted data.