# CausalSieve CausalSieve ranks possible sources of a multivariate telemetry incident. Use it after an alert when several metrics changed and a responder needs an investigation order. The Python adapters accept a Prometheus range-query matrix, OpenTelemetry metrics, JSON Lines, or a numeric table. The CLI can read CSV. For a Prometheus response, call `sieve, digest = analyze_prometheus(payload)` and read `[row.name for row in digest.root_causes]`. Each candidate retains its metric name and labels. Check the leading candidates against traces and deployment history. Close the returned sieve when you finish using it. ## Core Documentation - [README and runnable example](README.md#try-a-prometheus-incident) shows the input and JSON output for a simulated database delay that propagates to an API. - [Benchmark results](BENCHMARKS.md) reports service-ranking accuracy on RCAEval incidents, run times, and comparisons with 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. - [Runnable Prometheus incident example](examples/prometheus_incident.py) accepts a saved `/api/v1/query_range` matrix or generates an offline fixture. Its JSON output contains the tick count, series count and ranked metric names. - [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:////..`. - [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.