causalsieve 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. causalsieve-0.1.0/.claude-plugin/marketplace.json +29 -0
  2. causalsieve-0.1.0/.claude-plugin/plugin.json +28 -0
  3. causalsieve-0.1.0/BENCHMARKS.md +138 -0
  4. causalsieve-0.1.0/CITATION.cff +27 -0
  5. causalsieve-0.1.0/CONTRIBUTING.md +72 -0
  6. causalsieve-0.1.0/LICENSE +21 -0
  7. causalsieve-0.1.0/MANIFEST.in +25 -0
  8. causalsieve-0.1.0/Makefile +98 -0
  9. causalsieve-0.1.0/NOTICE +65 -0
  10. causalsieve-0.1.0/PKG-INFO +229 -0
  11. causalsieve-0.1.0/README.md +163 -0
  12. causalsieve-0.1.0/SECURITY.md +53 -0
  13. causalsieve-0.1.0/SKILL.md +163 -0
  14. causalsieve-0.1.0/csrc/causalsieve.cpp +2109 -0
  15. causalsieve-0.1.0/csrc/causalsieve.h +233 -0
  16. causalsieve-0.1.0/csrc/causalsieve_core.hpp +1206 -0
  17. causalsieve-0.1.0/csrc/cli_main.cpp +479 -0
  18. causalsieve-0.1.0/csrc/test_core_cpp.cpp +1033 -0
  19. causalsieve-0.1.0/llms-full.txt +293 -0
  20. causalsieve-0.1.0/llms.txt +36 -0
  21. causalsieve-0.1.0/pyproject.toml +90 -0
  22. causalsieve-0.1.0/python/causalsieve/__init__.py +113 -0
  23. causalsieve-0.1.0/python/causalsieve/__init__.pyi +131 -0
  24. causalsieve-0.1.0/python/causalsieve/__main__.py +8 -0
  25. causalsieve-0.1.0/python/causalsieve/_native.py +1976 -0
  26. causalsieve-0.1.0/python/causalsieve/adapters.py +1063 -0
  27. causalsieve-0.1.0/python/causalsieve/cli.py +432 -0
  28. causalsieve-0.1.0/python/causalsieve/digest.py +852 -0
  29. causalsieve-0.1.0/python/causalsieve/mcp_server.py +968 -0
  30. causalsieve-0.1.0/python/causalsieve/py.typed +0 -0
  31. causalsieve-0.1.0/python/causalsieve/swarm.py +657 -0
  32. causalsieve-0.1.0/python/causalsieve.egg-info/PKG-INFO +229 -0
  33. causalsieve-0.1.0/python/causalsieve.egg-info/SOURCES.txt +44 -0
  34. causalsieve-0.1.0/python/causalsieve.egg-info/dependency_links.txt +1 -0
  35. causalsieve-0.1.0/python/causalsieve.egg-info/entry_points.txt +3 -0
  36. causalsieve-0.1.0/python/causalsieve.egg-info/requires.txt +14 -0
  37. causalsieve-0.1.0/python/causalsieve.egg-info/top_level.txt +1 -0
  38. causalsieve-0.1.0/server.json +46 -0
  39. causalsieve-0.1.0/setup.cfg +4 -0
  40. causalsieve-0.1.0/setup.py +293 -0
  41. causalsieve-0.1.0/skills/causalsieve/SKILL.md +163 -0
  42. causalsieve-0.1.0/tests/test_adapters.py +500 -0
  43. causalsieve-0.1.0/tests/test_causality_and_numeric.py +393 -0
  44. causalsieve-0.1.0/tests/test_digest_and_mcp.py +424 -0
  45. causalsieve-0.1.0/tests/test_exact_oracle.py +311 -0
  46. causalsieve-0.1.0/tests/test_rca_and_orientation.py +272 -0
@@ -0,0 +1,29 @@
1
+ {
2
+ "name": "causalsieve",
3
+ "owner": {
4
+ "name": "CausalSieve Contributors"
5
+ },
6
+ "metadata": {
7
+ "description": "Sub-millisecond SIMD online multivariate causal discovery, root-cause localization, and token-compressed telemetry digests for AI agents.",
8
+ "version": "0.1.0"
9
+ },
10
+ "plugins": [
11
+ {
12
+ "name": "causalsieve",
13
+ "source": "./",
14
+ "description": "Zero-dependency SIMD online causal discovery, exogenous root-cause localization, counterfactual do-interventions, and lossless-recoverable telemetry digests (CLI + MCP stdio server + Agent Skill).",
15
+ "version": "0.1.0",
16
+ "license": "MIT",
17
+ "homepage": "https://pgg898200-ship-it.github.io/causalsieve/",
18
+ "repository": "https://github.com/pgg898200-ship-it/causalsieve",
19
+ "keywords": [
20
+ "causal-discovery",
21
+ "root-cause-analysis",
22
+ "granger-causality",
23
+ "observability",
24
+ "prometheus",
25
+ "mcp"
26
+ ]
27
+ }
28
+ ]
29
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "causalsieve",
3
+ "version": "0.1.0",
4
+ "description": "Zero-dependency SIMD online multivariate causal discovery, exogenous root-cause localization, counterfactual do-interventions, and 95-99.95% token-compressed lossless-recoverable telemetry digests.",
5
+ "author": {
6
+ "name": "CausalSieve Contributors"
7
+ },
8
+ "homepage": "https://pgg898200-ship-it.github.io/causalsieve/",
9
+ "repository": "https://github.com/pgg898200-ship-it/causalsieve",
10
+ "license": "MIT",
11
+ "keywords": [
12
+ "causal-discovery",
13
+ "root-cause-analysis",
14
+ "granger-causality",
15
+ "prometheus",
16
+ "observability",
17
+ "time-series",
18
+ "mcp",
19
+ "simd"
20
+ ],
21
+ "skills": "./skills/",
22
+ "mcpServers": {
23
+ "causalsieve": {
24
+ "command": "causalsieve-mcp",
25
+ "args": []
26
+ }
27
+ }
28
+ }
@@ -0,0 +1,138 @@
1
+ # CausalSieve Benchmarks & Optimization Log
2
+
3
+ Every number below was measured live on the exact compiled binaries anchored by SHA-256. Zero numbers are estimated except the single explicitly marked `statsmodels` `D=64` row (linearly extrapolated from 200 timed pairs out of 4,032).
4
+
5
+ ## Provenance & Hardware
6
+
7
+ - **CPU:** Intel Xeon @ 2.30 GHz (2 logical cores, AVX2 + FMA, Ubuntu 24.04 Linux)
8
+ - **Compiler:** `g++ 13.3.0` (`-std=c++20 -O3 -mavx2 -mfma -Wall -Wextra -Werror`)
9
+ - **Active SIMD ISA:** `avx2+fma`
10
+ - **Frozen `build/libcausalsieve.so` SHA-256:** `69e960d01e22f976a907e6de4f35ccadc048f07b8ac11f1dae481eaab5cdc6e6`
11
+ - **Frozen `build/libcausalsieve_scalar.so` SHA-256:** `a38bcb0d3ad6aa1c9f034e4bf5bd31ce20f5700df1ef37750d401b5c871984b9`
12
+ - **Incumbent Versions:** `Python 3.12.16`, `numpy 2.5.5`, `scipy 1.18.1`, `statsmodels 0.15.0`, `tigramite 5.2.10.1`, `scikit-learn 1.9.1`, `river 0.27.0`, `pandas 3.1.1`
13
+ - **Frozen Result Artifacts:** [`benchmarks/results/`](benchmarks/results/)
14
+
15
+ ---
16
+
17
+ ## 1. Head-to-Head Wall-Clock Speed (`benchmarks/results/speed.json`)
18
+
19
+ Workload: `T = 500` multivariate ticks, VAR lag `p = 2`, full ingest + full `D×D` conditional Granger + `D×D` precision matrix.
20
+
21
+ | `D` | CausalSieve batch (ms) | Steady-State Rate | `D×D` Graph Query (ms) | NumPy Batch Refits | `statsmodels` VAR+Granger | `tigramite` PCMCI | `sklearn` LW+IsoF | `sklearn` GraphLassoCV | `river` Online |
22
+ |---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
23
+ | **8** | **3.19** | **592,390 ticks/s** (`1.69 µs`) | 0.028 | 2.53 ms (`0.80×`*) | 118.63 ms (**37.2×**) | 667.67 ms (**209.6×**) | 198.10 ms (**62.2×**) | 127.50 ms (**40.0×**) | 60.89 ms (**19.1×**) |
24
+ | **16** | **6.36** | **287,259 ticks/s** (`3.48 µs`) | 0.031 | 5.92 ms (`0.93×`*) | 626.12 ms (**98.4×**) | 3,292.51 ms (**517.6×**) | 197.29 ms (**31.0×**) | 248.00 ms (**39.0×**) | 144.98 ms (**22.8×**) |
25
+ | **32** | **12.12** | **101,490 ticks/s** (`9.85 µs`) | 0.043 | 300.40 ms (**24.8×**) | 24,069.70 ms (**1,986.5×**) | 15,670.00 ms (**1,293.3×**) | 198.25 ms (**16.4×**) | 417.66 ms (**34.5×**) | 420.54 ms (**34.7×**) |
26
+ | **64** | **38.45** | **26,675 ticks/s** (`37.49 µs`) | 0.088 | 613.29 ms (**16.0×**) | 1,879,070 ms† (**48,875×**) | >60 s (skipped) | 227.38 ms (**5.9×**) | skipped | 1,528.30 ms (**39.8×**) |
27
+
28
+ - \*Crossover disclosure: At `D <= 16`, a single offline NumPy batch refit without online per-tick scoring takes `2.53–5.92 ms` vs CausalSieve's full streaming + `ctypes` initialization (`3.19–6.36 ms`). At `D >= 32`, Block-Schur eliminates $D$ full $K \times K$ Cholesky refits ($O(D^2 p^2)$ vs $O(D^4 p^3)$), producing a **24.8×** speedup over NumPy and **1,987×** over `statsmodels`.
29
+ - †Extrapolated linearly from 200 timed pairs out of 4,032 (`extrapolated: true` in `speed.json`).
30
+
31
+ ---
32
+
33
+ ## 2. Compounding Optimization Ladder (`benchmarks/results/optimization_log.json`)
34
+
35
+ Workload: `T = 1,000` ticks, `p = 2` + full `D×D` conditional Granger + precision matrix, with exact parity verified against the batch FP64 oracle (`< 3e-12`) and scalar vs AVX2+FMA (`max |delta F| = 5.51e-14` at `D=16`, `1.87e-13` at `D=32`).
36
+
37
+ | Stage | Description | `D=16` ms (Cum. Speedup) | `D=32` ms (Cum. Speedup) |
38
+ |---:|---|---:|---:|
39
+ | 1 | `statsmodels` VAR + conditional Granger baseline | 671.76 ms (`1.0×`) | 23,497.88 ms (`1.0×`) |
40
+ | 2 | Batch NumPy/SciPy ridge-VAR + exact reduced refits | 8.45 ms (`79.5×`) | 360.26 ms (`65.2×`) |
41
+ | 3 | CausalSieve C++20 scalar (`libcausalsieve_scalar.so`, fused `push_batch`) | 10.61 ms (`63.3×`) | 29.67 ms (`792.0×`) |
42
+ | 4 | CausalSieve C++20 `avx2+fma` single-tick Python `ctypes` loop | 19.54 ms (`34.4×`*) | 28.45 ms (`825.9×`) |
43
+ | 5 | CausalSieve C++20 `avx2+fma` fused C-loop (`push_batch`) | **8.55 ms (`78.6×`)** | **17.54 ms (`1,340.1×`)** |
44
+
45
+ - AVX2+FMA speedup over scalar C++20: **1.24×** (`D=16`), **1.69×** (`D=32`) — and up to **1.85×–2.01×** on Tier-2 `D=2,048..4,096` streaming loops.
46
+ - \*Honest Python FFI note: Per-tick Python `ctypes` loop adds ~11 ms per 1,000 ticks compared to fused `push_batch`.
47
+
48
+ ---
49
+
50
+ ## 3. 100-Episode Multi-Regime Synthetic RCA (`benchmarks/results/synthetic_rca.json`)
51
+
52
+ 5 regimes × 20 independent seeds = **100 episodes**. Mean token compression: `22,758.0 -> 27.2` tokens (**99.88% reduction**).
53
+
54
+ | Method | Overall AC@1 | Overall AC@3 | Overall MRR | Mean ms/ep | Lagged Amp | Instant Non-Gauss | Nonlinear Sat | D=64 Decoys | ERDDAP `1e10` |
55
+ |---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
56
+ | **`causalsieve`** (default) | **0.730** | **0.960** | **0.830** | **13.30** | **1.000** | 0.650 (AC@3=1.0) | 0.000 | **1.000** | **1.000** |
57
+ | **`causalsieve_hinge`** | 0.720 | 0.890 | 0.822 | 27.25 | 0.850 | 0.550 | **0.450** | 0.850 | 0.900 |
58
+ | `unshielded_online_rls` | 0.690 | 0.970 | 0.817 | 14.04 | 0.950 | 0.500 | 0.000 | 1.000 | 1.000 |
59
+ | `sklearn_isolation_forest` | 0.380 | 0.940 | 0.615 | 2,906.89 | 0.500 | **0.700** | 0.000 | 0.300 | 0.400 |
60
+ | `pairwise_granger_z` | 0.290 | 0.930 | 0.589 | 44.86 | 0.300 | 0.350 | 0.000 | 0.700 | 0.100 |
61
+ | `rolling_mad_z` | 0.090 | 0.590 | 0.366 | 2.25 | 0.000 | 0.450 | 0.000 | 0.000 | 0.000 |
62
+ | `raw_max_z` | 0.000 | 0.610 | 0.303 | 0.58 | 0.000 | 0.000 | 0.000 | 0.000 | 0.000 |
63
+
64
+ ---
65
+
66
+ ## 4. High-Dimensional Tier-2 Loud-Decoy Firehose (`benchmarks/results/sift_scale.json`)
67
+
68
+ `T = 500`, 10 seeds per dimension `D`, 20% heteroscedastic `3.5×`-noise decoy channels + planted 3-hop amplified causal cascade (`active_m = 32`).
69
+
70
+ | `D` | CausalSieve Throughput | Channel-Obs / sec | CausalSieve AC@1 / AC@3 / MRR | Raw Max-Z AC@1 | Rolling-MAD Z AC@1 | Naive Variance AC@1 |
71
+ |---:|---:|---:|---:|---:|---:|---:|
72
+ | **128** | **138,399 ticks/s** | 17.72M obs/s | **1.00 / 1.00 / 1.000** | 0.00 | 0.00 | 0.00 |
73
+ | **512** | **67,656 ticks/s** | 34.64M obs/s | **1.00 / 1.00 / 1.000** | 0.00 | 0.00 | 0.00 |
74
+ | **2,048** | **33,334 ticks/s** | 68.27M obs/s | **1.00 / 1.00 / 1.000** | 0.00 | 0.00 | 0.00 |
75
+ | **4,096** | **19,577 ticks/s** | **80.19M obs/s** | **1.00 / 1.00 / 1.000** | 0.00 | 0.00 | 0.00 |
76
+
77
+ ---
78
+
79
+ ## 5. Real Kubernetes Microservice Outages (`RCAEval`, `benchmarks/results/rcaeval.json`)
80
+
81
+ Source: `https://huggingface.co/datasets/phamquiluan/RCAEval` (RE1 Online Boutique `re1ob` & Sock Shop `re1ss`, 50 real Kubernetes incidents across 10 services × 5 fault types `cpu`, `mem`, `disk`, `delay`, `loss`, exact SHA-256 recorded for every case).
82
+
83
+ - **Zero-Leakage Split Protocol:** Pre-registered Latin-square split: `rep == 1` = DEV (10 cases, used once to catch real-world flat-memory-page NaN bug and verify symmetric comparator contract); `reps 2..5` = **SEALED HOLDOUT (40 cases, executed once with zero retuning)**.
84
+ - **Token Compression:** `131,705 -> 64.9` tokens (**99.951% reduction**) on SEALED HOLDOUT.
85
+
86
+ ### SEALED HOLDOUT (`n = 40` real Kubernetes cases — Zero Retuning)
87
+
88
+ | Method | AC@1 | AC@3 | AC@5 | Avg@5 | MRR | Mean ms/case |
89
+ |---|---:|---:|---:|---:|---:|---:|
90
+ | **`causalsieve`** (symmetric baseline) | **0.675** (27/40) | **0.925** (37/40) | **1.000** (40/40) | **0.880** | **0.804** | **33.3 ms** |
91
+ | **`causalsieve_blind`** (zero `inject_time`) | **0.650** (26/40) | 0.750 (30/40) | 0.900 (36/40) | 0.780 | **0.746** | **30.1 ms** |
92
+ | `pairwise_granger_z` | 0.600 (24/40) | 0.875 (35/40) | 0.900 (36/40) | 0.805 | 0.741 | 162.0 ms |
93
+ | `rolling_mad_z` (Baro-style) | 0.525 (21/40) | 0.900 (36/40) | 0.925 (37/40) | 0.815 | 0.712 | 3.6 ms |
94
+ | `raw_max_z` (3-sigma) | 0.400 (16/40) | 0.875 (35/40) | 92.5% (37/40) | 0.755 | 0.624 | 1.1 ms |
95
+ | `sklearn_isolation_forest` | 0.350 (14/40) | 0.600 (24/40) | 0.725 (29/40) | 0.565 | 0.520 | 5,661.3 ms |
96
+
97
+ ### SEALED HOLDOUT Breakdown by System & Fault Type (`n = 40`)
98
+
99
+ | Slice | `causalsieve` AC@1 (MRR) | `causalsieve_blind` AC@1 (MRR) | `pairwise_granger_z` AC@1 (MRR) | `rolling_mad_z` AC@1 (MRR) | `raw_max_z` AC@1 (MRR) |
100
+ |---|---:|---:|---:|---:|---:|
101
+ | **Online Boutique (`RE1-OB`, n=20)** | **0.600 (0.764)** | **0.600 (0.707)** | 0.350 (0.566) | 0.350 (0.574) | 0.350 (0.569) |
102
+ | **Sock Shop (`RE1-SS`, n=20)** | 0.750 (0.843) | 0.700 (0.785) | **0.850 (0.917)** | 0.700 (0.850) | 0.450 (0.679) |
103
+ | **`mem` (n=8)** | **1.000 (1.000)** | 0.750 (0.875) | **1.000 (1.000)** | 0.375 (0.625) | 0.375 (0.573) |
104
+ | **`cpu` (n=8)** | **0.875 (0.938)** | 0.750 (0.875) | 0.500 (0.729) | 0.625 (0.792) | 0.500 (0.750) |
105
+ | **`delay` (n=8)** | 0.625 (0.754) | **0.750 (0.806)** | 0.500 (0.750) | **0.750 (0.833)** | 0.500 (0.656) |
106
+ | **`disk` (n=8)** | **0.500 (0.729)** | 0.500 (0.646) | 0.500 (0.688) | **0.500 (0.729)** | 0.375 (0.604) |
107
+ | **`loss` (n=8)** | 0.375 (0.598) | 0.500 (0.528) | **0.500 (0.643)** | 0.375 (0.519) | 0.250 (0.538) |
108
+
109
+ ### DEV Split Reference (`rep == 1`, `n = 10`)
110
+
111
+ | Method | AC@1 | AC@3 | AC@5 | Avg@5 | MRR | Mean ms/case |
112
+ |---|---:|---:|---:|---:|---:|---:|
113
+ | **`causalsieve_blind`** | **0.800** | **1.000** | **1.000** | **0.960** | **0.900** | **29.6 ms** |
114
+ | **`causalsieve`** | **0.800** | 0.900 | 0.900 | 0.860 | 0.850 | **33.7 ms** |
115
+ | `pairwise_granger_z` | 0.500 | 0.900 | 0.900 | 0.820 | 0.714 | 161.9 ms |
116
+ | `raw_max_z` | 0.400 | 0.900 | 1.000 | 0.820 | 0.670 | 1.1 ms |
117
+ | `rolling_mad_z` | 0.300 | 0.900 | 0.900 | 0.780 | 0.613 | 3.6 ms |
118
+ | `sklearn_isolation_forest` | 0.200 | 0.400 | 0.600 | 0.380 | 0.363 | 5,602.0 ms |
119
+
120
+ ---
121
+
122
+ ## 6. High-Dimensional 64-Service Real Kubernetes Outages (`RCAEval` Train Ticket `RE1-TT`, `benchmarks/results/rcaeval_trainticket.json`)
123
+
124
+ Zero-leakage, zero-tuning evaluation across **25 real Train Ticket incidents** (5 services × 5 fault types `cpu`, `mem`, `disk`, `delay`, `loss`, `rep = 2`), with **`D = 198..238` metrics (mean `217.1`)** across **64 services/pods** (41 microservices + 23 DB sidecars) and `T = 721..961` ticks. Token compression: **`346,742 -> 63.8` tokens (`99.982%` reduction)**.
125
+
126
+ | Method | AC@1 | AC@3 | AC@5 | Avg@5 | MRR | Mean Rank | Mean ms/case |
127
+ |---|---:|---:|---:|---:|---:|---:|---:|
128
+ | **`causalsieve_tier1`** (`lag=2`, symmetric) | **0.480** (12/25) | **0.840** (21/25) | **0.880** (22/25) | **0.768** | **0.669** | **4.44** | 375.0 ms |
129
+ | **`causalsieve_tier1_blind`** (`lag=2`, zero `inject_time`) | **0.480** (12/25) | 0.600 (15/25) | 0.680 (17/25) | 0.600 | **0.589** | 5.00 | 341.3 ms |
130
+ | `raw_max_z` (3-sigma, symmetric) | 0.160 (4/25) | 0.440 (11/25) | 0.840 (21/25) | 0.480 | 0.378 | 5.72 | 3.1 ms |
131
+ | `pairwise_granger_z` (top-48 MAD pre-screen†) | 0.200 (5/25) | 0.320 (8/25) | 0.600 (15/25) | 0.376 | 0.344 | 10.20 | 148.1 ms (`2,127 ms` uncapped†) |
132
+ | `rolling_mad_z` (Baro-style, symmetric) | 0.120 (3/25) | 0.440 (11/25) | 0.720 (18/25) | 0.416 | 0.343 | 6.72 | 8.6 ms |
133
+ | **`causalsieve_tier2`** (`ScreenedSieve M=32`, blind) | 0.160 (4/25) | 0.320 (8/25) | 0.440 (11/25) | 0.304 | 0.288 | 12.64 | **4.28 ms** |
134
+ | `sklearn_isolation_forest` | 0.040 (1/25) | 0.080 (2/25) | 0.120 (3/25) | 0.080 | 0.130 | 18.72 | 20,360.0 ms |
135
+
136
+ - †Directly timing 1,000 bivariate pairs out of 44,310 on `D=218` extrapolates to `2,127.3 ms/case` uncapped (`5.7×` slower than full dense Tier-1, `497×` slower than Tier-2).
137
+ - **Honest Tier-2 Post-Mortem Tradeoff Disclosed:** `causalsieve_tier2` (`4.28 ms/case`, `4,757×` faster than `IsolationForest`) promoted the true root service into its Top-32 active set on **23/25 (92%)** cases and beat every baseline on MRR for `disk` (`0.473`), `delay` (`0.350`), and `loss` (`0.472`). However, on full post-mortem replay of `T=961` gradual-ramp traces (`cpu`/`mem`), its fixed `ring_cap=512` retains only ~31 pre-fault ticks, so Tier-2 is best suited for live online alerting near fault onset, whereas full Tier-1 (`375 ms/case`) dominates post-mortem replay at `D ≈ 200–250` (**2.4×–12×** higher AC@1 than all incumbents, **100%** AC@1 blind on `mem`).
138
+
@@ -0,0 +1,27 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use CausalSieve in research, engineering, or benchmarks, please cite it as below."
3
+ type: software
4
+ title: "CausalSieve: Zero-Dependency SIMD Online Multivariate Causal Discovery, Exogenous Root-Cause Localization, and Lossless-Recoverable Stream Digests"
5
+ version: "0.1.0"
6
+ date-released: "2026-11-22"
7
+ license: MIT
8
+ repository-code: "https://github.com/pgg898200-ship-it/causalsieve"
9
+ url: "https://pgg898200-ship-it.github.io/causalsieve/"
10
+ authors:
11
+ - name: "CausalSieve Contributors"
12
+ keywords:
13
+ - causal-discovery
14
+ - granger-causality
15
+ - root-cause-analysis
16
+ - streaming-time-series
17
+ - lingam
18
+ - e-process
19
+ - simd
20
+ - mcp
21
+ abstract: >-
22
+ CausalSieve is a zero-runtime-dependency C++20 SIMD and Python streaming
23
+ engine for online multivariate causal discovery, precision-whitened exogenous
24
+ root-cause localization, exact Block-Schur conditional Granger causality,
25
+ online non-Gaussian contemporaneous orientation, anytime-valid Ville
26
+ E-process alarms, counterfactual do-interventions, and 95-99.95%
27
+ token-compressed stream digests with bit-exact FP64 slice recovery.
@@ -0,0 +1,72 @@
1
+ # Contributing to CausalSieve
2
+
3
+ Contributions, bug reports, reproducible benchmarks, and ecosystem adapters are
4
+ welcome. CausalSieve enforces strict engineering invariants across the C++20
5
+ core, C99 ABI, and Python surface.
6
+
7
+ ## Engineering Invariants
8
+
9
+ 1. **Zero Runtime Python Dependencies:**
10
+ `pyproject.toml` MUST keep `dependencies = []`. Core bindings, CLI, MCP
11
+ server, and ecosystem adapters (`analyze_dataframe`, `analyze_prometheus`,
12
+ `rcaeval_rca`) must run on bare stdlib Python 3.10+ without requiring
13
+ `numpy`, `pandas`, `polars`, or `scipy` (use duck typing / `__array_interface__`
14
+ for optional zero-copy acceleration).
15
+ 2. **Strict Causality (Zero Look-Ahead):**
16
+ Any feature, imputation, normalization, or scoring change at tick `t` must be
17
+ bit-identical regardless of observations at ticks `> t`. Verified by
18
+ `tests/test_causality_and_numeric.py` and `tests/breaker_audit.py`.
19
+ 3. **Mathematical Exactness & Memory Safety:**
20
+ Tier-1 Block-Schur Granger and precision updates must match exact batch FP64
21
+ SVD refits within `< 1e-10` and pass ASan + UBSan with zero findings.
22
+ 4. **C99 ABI Stability:**
23
+ All exported symbols in `csrc/causalsieve.h` must remain C99-compatible,
24
+ thread-safe across independent engine instances, and mirrored in `setup.py`
25
+ MSVC exports and `python/causalsieve/_native.py`.
26
+ 5. **Honest Benchmarks & Clean-Room Hygiene:**
27
+ Report failures, crossovers, and limits alongside wins. Never commit private
28
+ paths, credentials, or external datasets under `benchmarks/data/`.
29
+
30
+ ## Local Development Setup
31
+
32
+ ```sh
33
+ # 1. Build C++20 shared libraries, native CLI, and ASan/UBSan test binaries
34
+ make all
35
+
36
+ # 2. Install Python package in editable mode (or build a wheel)
37
+ pip install -e ".[dev]"
38
+
39
+ # 3. Verify active SIMD ISA and library path
40
+ causalsieve info
41
+ ```
42
+
43
+ ## Verification Checklist (Run Before Opening a PR)
44
+
45
+ ```sh
46
+ # C++20 ASan + UBSan + AVX2/scalar parity suite
47
+ make test
48
+
49
+ # Python unit, exact-oracle, causality, RCA, digest, and MCP tests
50
+ pytest tests/ -v
51
+
52
+ # Adversarial breaker audit (numerical torture, MCP red-team, clean-room scan)
53
+ pytest tests/breaker_audit.py -v
54
+
55
+ # Linting and strict static typing
56
+ ruff check python/causalsieve setup.py
57
+ mypy --strict --ignore-missing-imports python/causalsieve
58
+
59
+ # Standalone wheel build & bare-venv smoke test
60
+ CAUSALSIEVE_PORTABLE=1 python -m build --wheel --sdist
61
+ ```
62
+
63
+ ## Pull Request Process
64
+
65
+ 1. Open an issue or PR describing the motivation, design tradeoff, and test
66
+ coverage.
67
+ 2. Keep changes focused and include deterministic unit tests covering edge cases
68
+ (such as `NaN`/`Inf`, empty inputs, flat channels, or boundary dimensions).
69
+ 3. Update `SKILL.md` and `skills/causalsieve/SKILL.md` together if public CLI,
70
+ MCP, or Python adapter signatures change.
71
+ 4. By submitting a contribution, you agree that your work is licensed under the
72
+ MIT License (see [LICENSE](LICENSE)).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 CausalSieve Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,25 @@
1
+ include LICENSE
2
+ include NOTICE
3
+ include README.md
4
+ include BENCHMARKS.md
5
+ include SKILL.md
6
+ include llms.txt
7
+ include llms-full.txt
8
+ include CITATION.cff
9
+ include SECURITY.md
10
+ include CONTRIBUTING.md
11
+ include server.json
12
+ include pyproject.toml
13
+ include setup.py
14
+ include Makefile
15
+
16
+ recursive-include csrc *.h *.hpp *.cpp
17
+ recursive-include python/causalsieve *.py *.pyi py.typed
18
+ recursive-include skills *.md
19
+ recursive-include .claude-plugin *.json
20
+
21
+ prune build
22
+ prune dist
23
+ prune benchmarks/data
24
+
25
+ global-exclude *.pyc *.pyo __pycache__ *.so *.dylib *.dll .DS_Store
@@ -0,0 +1,98 @@
1
+ UNAME_S := $(shell uname -s)
2
+ UNAME_M := $(shell uname -m)
3
+
4
+ ifeq ($(origin CXX),default)
5
+ ifeq ($(UNAME_S),Darwin)
6
+ CXX := clang++
7
+ else
8
+ CXX := g++
9
+ endif
10
+ endif
11
+
12
+ CXXFLAGS := -std=c++20 -Wall -Wextra -Werror -fno-math-errno -fno-trapping-math
13
+
14
+ ifeq ($(UNAME_S),Darwin)
15
+ SHLIB_EXT := dylib
16
+ SHLIB_FLAGS = -dynamiclib -install_name @rpath/$(notdir $@)
17
+ DL_LIB :=
18
+ else
19
+ SHLIB_EXT := so
20
+ SHLIB_FLAGS := -shared
21
+ DL_LIB := -ldl
22
+ endif
23
+
24
+ ifeq ($(CAUSALSIEVE_PORTABLE),1)
25
+ SIMD_FLAGS := -O3
26
+ ASAN_SIMD_FLAGS :=
27
+ ifneq ($(filter x86_64 amd64,$(UNAME_M)),)
28
+ SCALAR_FLAGS := -O3 -DCAUSALSIEVE_FORCE_SCALAR -mno-avx2 -mno-fma
29
+ else
30
+ SCALAR_FLAGS := -O3 -DCAUSALSIEVE_FORCE_SCALAR
31
+ endif
32
+ else ifneq ($(filter x86_64 amd64,$(UNAME_M)),)
33
+ SIMD_FLAGS := -O3 -mavx2 -mfma
34
+ ASAN_SIMD_FLAGS := -mavx2 -mfma
35
+ SCALAR_FLAGS := -O3 -DCAUSALSIEVE_FORCE_SCALAR -mno-avx2 -mno-fma
36
+ else ifneq ($(filter arm64 aarch64,$(UNAME_M)),)
37
+ SIMD_FLAGS := -O3
38
+ ASAN_SIMD_FLAGS :=
39
+ SCALAR_FLAGS := -O3 -DCAUSALSIEVE_FORCE_SCALAR
40
+ else
41
+ SIMD_FLAGS := -O3
42
+ ASAN_SIMD_FLAGS :=
43
+ SCALAR_FLAGS := -O3 -DCAUSALSIEVE_FORCE_SCALAR
44
+ endif
45
+
46
+ ASAN_FLAGS := $(strip -O2 -g $(ASAN_SIMD_FLAGS) -fsanitize=address,undefined -fno-omit-frame-pointer)
47
+
48
+ BUILD_DIR := build
49
+ SRC_DIR := csrc
50
+
51
+ SHLIB := $(BUILD_DIR)/libcausalsieve.$(SHLIB_EXT)
52
+ SHLIB_SCALAR := $(BUILD_DIR)/libcausalsieve_scalar.$(SHLIB_EXT)
53
+ HEADERS := $(SRC_DIR)/causalsieve.h $(SRC_DIR)/causalsieve_core.hpp
54
+
55
+ .PHONY: all test test-asan bench clean
56
+
57
+ all: $(SHLIB) \
58
+ $(SHLIB_SCALAR) \
59
+ $(BUILD_DIR)/causalsieve-bin \
60
+ $(BUILD_DIR)/test_core_cpp_asan \
61
+ $(BUILD_DIR)/test_core_cpp_opt \
62
+ $(BUILD_DIR)/test_core_cpp_scalar
63
+
64
+ $(BUILD_DIR):
65
+ mkdir -p $(BUILD_DIR)
66
+
67
+ $(SHLIB): $(SRC_DIR)/causalsieve.cpp $(HEADERS) | $(BUILD_DIR)
68
+ $(CXX) $(CXXFLAGS) $(SIMD_FLAGS) -fPIC $(SHLIB_FLAGS) -I$(SRC_DIR) $(SRC_DIR)/causalsieve.cpp -o $@ -lm
69
+
70
+ $(SHLIB_SCALAR): $(SRC_DIR)/causalsieve.cpp $(HEADERS) | $(BUILD_DIR)
71
+ $(CXX) $(CXXFLAGS) $(SCALAR_FLAGS) -fPIC $(SHLIB_FLAGS) -I$(SRC_DIR) $(SRC_DIR)/causalsieve.cpp -o $@ -lm
72
+
73
+ $(BUILD_DIR)/causalsieve-bin: $(SRC_DIR)/cli_main.cpp $(SRC_DIR)/causalsieve.cpp $(HEADERS) | $(BUILD_DIR)
74
+ $(CXX) $(CXXFLAGS) $(SIMD_FLAGS) -I$(SRC_DIR) $(SRC_DIR)/cli_main.cpp $(SRC_DIR)/causalsieve.cpp -o $@ -lm
75
+
76
+ $(BUILD_DIR)/test_core_cpp_asan: $(SRC_DIR)/test_core_cpp.cpp $(SRC_DIR)/causalsieve.cpp $(HEADERS) | $(BUILD_DIR)
77
+ $(CXX) $(CXXFLAGS) $(ASAN_FLAGS) -I$(SRC_DIR) $(SRC_DIR)/test_core_cpp.cpp $(SRC_DIR)/causalsieve.cpp -o $@ $(DL_LIB) -lm
78
+
79
+ $(BUILD_DIR)/test_core_cpp_opt: $(SRC_DIR)/test_core_cpp.cpp $(SRC_DIR)/causalsieve.cpp $(HEADERS) | $(BUILD_DIR)
80
+ $(CXX) $(CXXFLAGS) $(SIMD_FLAGS) -I$(SRC_DIR) $(SRC_DIR)/test_core_cpp.cpp $(SRC_DIR)/causalsieve.cpp -o $@ $(DL_LIB) -lm
81
+
82
+ $(BUILD_DIR)/test_core_cpp_scalar: $(SRC_DIR)/test_core_cpp.cpp $(SRC_DIR)/causalsieve.cpp $(HEADERS) | $(BUILD_DIR)
83
+ $(CXX) $(CXXFLAGS) $(SCALAR_FLAGS) -I$(SRC_DIR) $(SRC_DIR)/test_core_cpp.cpp $(SRC_DIR)/causalsieve.cpp -o $@ $(DL_LIB) -lm
84
+
85
+ test-asan: $(BUILD_DIR)/test_core_cpp_asan
86
+ ./$(BUILD_DIR)/test_core_cpp_asan
87
+
88
+ test: all
89
+ ./$(BUILD_DIR)/test_core_cpp_asan
90
+ ./$(BUILD_DIR)/test_core_cpp_opt --parity-so ./$(SHLIB) ./$(SHLIB_SCALAR) --bench
91
+ ./$(BUILD_DIR)/test_core_cpp_scalar --bench
92
+
93
+ bench: $(BUILD_DIR)/test_core_cpp_opt $(BUILD_DIR)/test_core_cpp_scalar
94
+ ./$(BUILD_DIR)/test_core_cpp_opt --bench
95
+ ./$(BUILD_DIR)/test_core_cpp_scalar --bench
96
+
97
+ clean:
98
+ rm -rf $(BUILD_DIR)
@@ -0,0 +1,65 @@
1
+ CausalSieve
2
+ Copyright (c) 2026 CausalSieve Contributors
3
+
4
+ This software is licensed under the MIT License (see LICENSE).
5
+
6
+ ===========================================================================
7
+ Academic & Methodological Attributions
8
+ ===========================================================================
9
+
10
+ CausalSieve is an independent clean-room C++20 and zero-dependency Python
11
+ implementation building upon foundational published results in time-series
12
+ causality, online estimation, robust statistics, sequential testing, and
13
+ error-bounded stream compression:
14
+
15
+ 1. Vector Autoregression & Conditional Granger Causality
16
+ - C. W. J. Granger, "Investigating Causal Relations by Econometric Models
17
+ and Cross-spectral Methods," Econometrica, 37(3):424-438, 1969.
18
+ - C. A. Sims, "Macroeconomics and Reality," Econometrica, 48(1):1-48, 1980.
19
+ - Block-Schur complement exact leave-one-block-out ridge objective identity
20
+ over recursively maintained inverse Gram matrices (Sherman-Morrison /
21
+ Recursive Least Squares).
22
+
23
+ 2. Contemporaneous Non-Gaussian Causal Orientation (LiNGAM)
24
+ - S. Shimizu, P. O. Hoyer, A. Hyvarinen, and A. Kerminen, "A Linear
25
+ Non-Gaussian Acyclic Model for Causal Discovery," JMLR, 7:2003-2030, 2006.
26
+ - A. Hyvarinen and S. M. Smith, "Pairwise Likelihood Ratios for Estimation
27
+ of Non-Gaussian Structural Equation Models," JMLR, 14:111-152, 2013.
28
+
29
+ 3. Robust M-Estimation & Bounded-Influence Regression
30
+ - P. J. Huber, "Robust Estimation of a Location Parameter," Annals of
31
+ Mathematical Statistics, 35(1):73-101, 1964.
32
+ - C. L. Mallows, "On Some Topics in Robustness," Bell Laboratories Technical
33
+ Memorandum, 1975.
34
+
35
+ 4. Anytime-Valid Sequential Testing & E-Processes
36
+ - J. Ville, "Etude critique de la notion de collectif," Gauthier-Villars,
37
+ 1939.
38
+ - A. Ramdas, P. Grunwald, V. Vovk, and G. Shafer, "Game-Theoretic Statistics
39
+ and Safe Anytime-Valid Inference," Statistical Science, 38(4):576-601, 2023.
40
+ - E. Hazan, A. Agarwal, and S. Kale, "Logarithmic Regret Algorithms for
41
+ Online Convex Optimization" (Online Newton Step), Machine Learning,
42
+ 69(2-3):169-192, 2007.
43
+
44
+ 5. Randomized Inverse Drift Verification
45
+ - R. Freivalds, "Fast Probabilistic Algorithms," Mathematical Foundations
46
+ of Computer Science, LNCS 74:57-69, 1979.
47
+
48
+ 6. Error-Bounded Piecewise Linear Stream Compression
49
+ - H. Elmeleegy, A. K. Elmagarmid, E. Cecchet, W. G. Aref, and W. Zwaenepoel,
50
+ "Online Piece-Wise Linear Approximation of Numerical Streams with
51
+ Precision Guarantees" (Swing Filter), PVLDB, 2(1):145-156, 2009.
52
+
53
+ ===========================================================================
54
+ Benchmark Dataset & Open-Source Comparator Attributions
55
+ ===========================================================================
56
+
57
+ - RCAEval Kubernetes Microservice Failure Benchmark (evaluation dataset only,
58
+ not bundled in distributions):
59
+ L. Pham et al., "RCAEval: A Benchmark for Root Cause Analysis of Microservice
60
+ Systems," Proceedings of the ACM Web Conference (WWW), 2025.
61
+ Dataset source: https://huggingface.co/datasets/phamquiluan/RCAEval
62
+
63
+ - Open-source benchmark comparators (invoked exclusively in optional benchmark
64
+ scripts under benchmarks/; NOT runtime dependencies and NOT bundled):
65
+ NumPy, SciPy, pandas, statsmodels, tigramite, scikit-learn, and river.