# CausalSieve

> Zero-runtime-dependency C++20 SIMD engine (runtime CPUID AVX2+FMA dispatch on x86-64, native NEON on ARM64) for online multivariate causal discovery (exact Block-Schur conditional Granger, innovation precision whitening, online Hyvärinen-Smith LiNGAM orientation), anytime-valid Ville E-process alarms, multi-agent CausalBlackboard consensus, and 99.90%–99.98% token-compressed lossless-recoverable stream digests.

## Core Documentation

- [README & Quickstart](README.md): Overview, v0.2.0 benchmarks (`746.8k ticks/s` at `D=8`, `385.3k` at `D=16`, `154.2k` at `D=32` — `2,334×` vs `statsmodels` & `1,467×` vs `tigramite`, `71,514×` vs `statsmodels` at `D=64`; `#1` across all 645 real Kubernetes `RCAEval` RE1+RE2 outages with `75.7%` micro / `76.5%` macro AC@1 & `0.839/0.844` MRR beating `BARO`, `N-Sigma`, `CIRCA`; `0.0%` context overflow at 8k vs `100%` CSV/JSON overflow at 128k with `0.0` FP64 `slice://` recovery), and honest tradeoffs.
- [Full Reproducible Benchmarks](BENCHMARKS.md): Complete v0.2.0 tables, 5-stage optimization ladder, SHA-256 provenance across all 8 frozen JSONs, 645-case `RCAEval` RE1+RE2 breakdowns, Agent BPE Token & Adversarial Blackboard benchmark, and Tier-2 `D=4,096` firehose (`75.7M obs/s`, `100%` AC@1 vs `0%` baselines).
- [Full Technical Reference](llms-full.txt): Single-file Markdown reference covering math specifications, Python API, CLI, JSON-RPC 2.0 MCP server schemas, C99 ABI, and honest limits.
- [CausalSieve vs statsmodels, tigramite, sklearn & river](docs/vs-statsmodels-tigramite.md): Drop-in migration code, complexity analysis, and honest crossovers.
- [Kubernetes, Prometheus, OpenTelemetry & Streaming RCA Cookbook](docs/kubernetes-prometheus-rca.md): Recipes for Prometheus `/api/v1/query_range`, OpenTelemetry OTLP/JSON, NDJSON/JSONL, live `causalsieve watch`, and `RCAEval`.
- [LLM & Multi-Agent Telemetry Compression Guide](docs/llm-agent-telemetry-compression.md): Zero-install `uvx` MCP setup, `SKILL.md`, 99.90%–99.98% token reduction with `0.0` FP64 `slice://` recovery, and `CausalBlackboard`.
- [Agent Skill](skills/causalsieve/SKILL.md): Drop-in `agentskills.io` / `skills.sh` / Claude Code / Codex / Cursor skill (also mirrored at `SKILL.md`).
- [C99 ABI Header](csrc/causalsieve.h): Canonical C99 ABI (`CAUSALSIEVE_ABI_VERSION 1`) for Tier-1 `cs_engine_t` and Tier-2 `cs_screened_t`.

## Python Package & Interfaces

- [Native ctypes Bindings & High-Level API](python/causalsieve/_native.py): `CausalSieve`, `ScreenedSieve`, `analyze_csv`, zero-copy NumPy/`array('d')` buffer passing, zero runtime dependencies.
- [Drop-In Observability Adapters](python/causalsieve/adapters.py): Zero-hard-dep `analyze_dataframe` (Pandas/Polars/dict), `analyze_prometheus` (`/api/v1/query_range` JSON), `analyze_otlp_metrics` (OpenTelemetry OTLP/JSON gauge/sum/histogram), `analyze_jsonl` (NDJSON/JSONL), and `rcaeval_rca`.
- [Causal Digest & Lossless Recovery](python/causalsieve/digest.py): `build_digest`, `CausalDigest`, `StreamStore`, `recover_slice`, `recover_handle`, `slice://<stream_id>/<channel>/<start>..<end>`.
- [Multi-Agent Shared Blackboard](python/causalsieve/swarm.py): `CausalBlackboard`, immutable versioned `CausalSnapshot`, append-only objectively scored `HypothesisRecord`, and proper-scoring `ConsensusReport`.
- [CLI Entry Point](python/causalsieve/cli.py): Sub-30 ms startup CLI (`rca`, `digest`, `slice`, `counterfactual`, `watch`, `info`, `mcp`).
- [MCP Stdio Server](python/causalsieve/mcp_server.py): Zero-dependency JSON-RPC 2.0 MCP server (`uvx --from causalsieve causalsieve-mcp`) exposing `sieve_ingest_csv`, `sieve_push_ticks`, `sieve_causal_graph`, `sieve_counterfactual`, `sieve_recover_slice`, and `sieve_swarm_propose`.

## Quickstart Commands

- One-command install (zero runtime deps, prebuilt multi-ISA AVX2/NEON wheels): `pip install causalsieve`
- Zero-install MCP server (6 ms startup via uvx): `uvx --from causalsieve causalsieve-mcp --allowed-root /path/to/data`
- Install Agent Skill: `npx skills add pgg898200-ship-it/causalsieve`
- Check active runtime SIMD ISA & library path: `causalsieve info`
- Run root-cause analysis on CSV: `causalsieve rca metrics.csv --lag 2 --top-k 5`
- Emit token-budgeted digest: `causalsieve digest metrics.csv --tokens-budget 400`
- Stream live stdin CSV/JSONL alerts: `tail -f telemetry.jsonl | causalsieve watch --input-format jsonl --lag 2`
- Run counterfactual intervention: `causalsieve counterfactual metrics.csv --channel db_cpu --delta 3.0 --horizon 10`
- Recover exact FP64 slice: `causalsieve slice metrics.csv --channel db_cpu --start 490 --end 530`

## Optional

- [Interactive Zero-CDN Explorer](https://pgg898200-ship-it.github.io/causalsieve/): Offline/live browser simulator & frozen benchmark dashboard.
- [Operating Ledger & Verification Gates](COMPANY_STATE.md): Active hypotheses (H1–H6), verification gates, and bug-kill iterations.
- [License](LICENSE): MIT License.
