Metadata-Version: 2.4
Name: cascai
Version: 0.2.0
Summary: Cascade AI — regime-aware HMM scoring for multi-agent systems
License-Expression: MIT
Project-URL: Homepage, https://github.com/YoavBadusa22/Cascai-producct-main
Project-URL: Source, https://github.com/YoavBadusa22/Cascai-producct-main
Keywords: ai,hmm,multi-agent,scoring,cascade
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: plotly
Requires-Dist: hmmlearn
Dynamic: license-file

# 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

```bash
pip install cascai
```

## Quickstart

```bash
# 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.
