streamsieve 0.2.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 (54) hide show
  1. streamsieve-0.2.0/.claude-plugin/plugin.json +31 -0
  2. streamsieve-0.2.0/.cursor-plugin/plugin.json +31 -0
  3. streamsieve-0.2.0/LICENSE +103 -0
  4. streamsieve-0.2.0/MANIFEST.in +16 -0
  5. streamsieve-0.2.0/Makefile +63 -0
  6. streamsieve-0.2.0/NOTICE +13 -0
  7. streamsieve-0.2.0/PKG-INFO +276 -0
  8. streamsieve-0.2.0/README.md +244 -0
  9. streamsieve-0.2.0/SKILL.md +262 -0
  10. streamsieve-0.2.0/csrc/streamsieve_capi.cpp +356 -0
  11. streamsieve-0.2.0/csrc/streamsieve_capi.h +284 -0
  12. streamsieve-0.2.0/csrc/streamsieve_cli.cpp +601 -0
  13. streamsieve-0.2.0/csrc/streamsieve_core.hpp +2745 -0
  14. streamsieve-0.2.0/docs/architecture.md +468 -0
  15. streamsieve-0.2.0/docs/benchmarks.md +207 -0
  16. streamsieve-0.2.0/docs/comparisons/vs-multiagent-debate.md +30 -0
  17. streamsieve-0.2.0/docs/comparisons/vs-online-fdr.md +25 -0
  18. streamsieve-0.2.0/docs/comparisons/vs-river.md +33 -0
  19. streamsieve-0.2.0/docs/comparisons/vs-zscore-and-cusum.md +34 -0
  20. streamsieve-0.2.0/examples/README.md +69 -0
  21. streamsieve-0.2.0/examples/jsonl_diurnal_sre.py +70 -0
  22. streamsieve-0.2.0/examples/multi_agent_pipeline.py +93 -0
  23. streamsieve-0.2.0/examples/noaa_weather.csv +2923 -0
  24. streamsieve-0.2.0/examples/tailstate_scores.py +99 -0
  25. streamsieve-0.2.0/llms-full.txt +258 -0
  26. streamsieve-0.2.0/llms.txt +51 -0
  27. streamsieve-0.2.0/pyproject.toml +58 -0
  28. streamsieve-0.2.0/python/streamsieve/__init__.py +59 -0
  29. streamsieve-0.2.0/python/streamsieve/_native.py +758 -0
  30. streamsieve-0.2.0/python/streamsieve/adapters.py +457 -0
  31. streamsieve-0.2.0/python/streamsieve/causality.py +220 -0
  32. streamsieve-0.2.0/python/streamsieve/cli.py +266 -0
  33. streamsieve-0.2.0/python/streamsieve/lattice.py +321 -0
  34. streamsieve-0.2.0/python/streamsieve/mcp_server.py +1125 -0
  35. streamsieve-0.2.0/python/streamsieve/monitor.py +513 -0
  36. streamsieve-0.2.0/python/streamsieve/sifter.py +275 -0
  37. streamsieve-0.2.0/python/streamsieve/trust.py +256 -0
  38. streamsieve-0.2.0/python/streamsieve.egg-info/PKG-INFO +276 -0
  39. streamsieve-0.2.0/python/streamsieve.egg-info/SOURCES.txt +52 -0
  40. streamsieve-0.2.0/python/streamsieve.egg-info/dependency_links.txt +1 -0
  41. streamsieve-0.2.0/python/streamsieve.egg-info/entry_points.txt +3 -0
  42. streamsieve-0.2.0/python/streamsieve.egg-info/requires.txt +9 -0
  43. streamsieve-0.2.0/python/streamsieve.egg-info/top_level.txt +1 -0
  44. streamsieve-0.2.0/server.json +43 -0
  45. streamsieve-0.2.0/setup.cfg +4 -0
  46. streamsieve-0.2.0/setup.py +71 -0
  47. streamsieve-0.2.0/tests/test_adapters.py +80 -0
  48. streamsieve-0.2.0/tests/test_breaker_adversarial.py +1194 -0
  49. streamsieve-0.2.0/tests/test_causality_and_mcp.py +574 -0
  50. streamsieve-0.2.0/tests/test_estream.py +294 -0
  51. streamsieve-0.2.0/tests/test_lattice.py +174 -0
  52. streamsieve-0.2.0/tests/test_sifter.py +149 -0
  53. streamsieve-0.2.0/tests/test_trust.py +159 -0
  54. streamsieve-0.2.0/tests/test_v020_features.py +617 -0
@@ -0,0 +1,31 @@
1
+ {
2
+ "name": "streamsieve",
3
+ "displayName": "StreamSieve",
4
+ "version": "0.2.0",
5
+ "description": "SIMD C++20 multi-agent streaming inference: anytime-valid dual-resolution e-processes + online e-BH FDR control, echo-free CRDT belief fusion, zero-overlap VOI firehose attention, and delayed-label trust calibration with Ville quarantine.",
6
+ "author": {
7
+ "name": "StreamSieve Contributors"
8
+ },
9
+ "license": "Apache-2.0",
10
+ "keywords": [
11
+ "streaming",
12
+ "time-series",
13
+ "telemetry",
14
+ "multi-agent",
15
+ "e-values",
16
+ "anytime-valid",
17
+ "fdr",
18
+ "crdt",
19
+ "voi",
20
+ "conformal-prediction",
21
+ "mcp",
22
+ "simd"
23
+ ],
24
+ "skills": ".",
25
+ "mcpServers": {
26
+ "streamsieve": {
27
+ "command": "streamsieve",
28
+ "args": ["mcp"]
29
+ }
30
+ }
31
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "name": "streamsieve",
3
+ "version": "0.2.0",
4
+ "description": "SIMD C++20 multi-agent streaming inference: anytime-valid dual-resolution e-processes + online e-BH FDR control, echo-free CRDT belief fusion, zero-overlap VOI firehose attention, and delayed-label trust calibration with Ville quarantine.",
5
+ "author": {
6
+ "name": "StreamSieve Contributors"
7
+ },
8
+ "license": "Apache-2.0",
9
+ "keywords": [
10
+ "streaming",
11
+ "time-series",
12
+ "telemetry",
13
+ "multi-agent",
14
+ "e-values",
15
+ "anytime-valid",
16
+ "fdr",
17
+ "crdt",
18
+ "voi",
19
+ "conformal-prediction",
20
+ "mcp",
21
+ "simd"
22
+ ],
23
+ "skills": ".",
24
+ "mcpServers": {
25
+ "streamsieve": {
26
+ "type": "stdio",
27
+ "command": "streamsieve",
28
+ "args": ["mcp"]
29
+ }
30
+ }
31
+ }
@@ -0,0 +1,103 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work.
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other modifications
42
+ represent, as a whole, an original work of authorship.
43
+
44
+ "Contribution" shall mean any work of authorship, including
45
+ the original version of the Work and any modifications or additions
46
+ to that Work or Derivative Works thereof, that is intentionally
47
+ submitted to Licensor for inclusion in the Work by the copyright owner.
48
+
49
+ "Contributor" shall mean Licensor and any individual or Legal Entity
50
+ on behalf of whom a Contribution has been received by Licensor and
51
+ subsequently incorporated within the Work.
52
+
53
+ 2. Grant of Copyright License. Subject to the terms and conditions of
54
+ this License, each Contributor hereby grants to You a perpetual,
55
+ worldwide, non-exclusive, royalty-free, irrevocable copyright license
56
+ to reproduce, prepare Derivative Works of, publicly display, publicly
57
+ perform, sublicense, and distribute the Work and such Derivative Works
58
+ in Source or Object form.
59
+
60
+ 3. Grant of Patent License. Subject to the terms and conditions of
61
+ this License, each Contributor hereby grants to You a perpetual,
62
+ worldwide, non-exclusive, royalty-free, irrevocable (except as stated
63
+ in this section) patent license to make, have made, use, offer to sell,
64
+ sell, import, and otherwise transfer the Work.
65
+
66
+ 4. Redistribution. You may reproduce and distribute copies of the Work or
67
+ Derivative Works thereof in any medium, with or without modifications,
68
+ and in Source or Object form, provided that You meet the following
69
+ conditions:
70
+
71
+ (a) You must give any other recipients of the Work a copy of this
72
+ License; and
73
+ (b) You must cause any modified files to carry prominent notices
74
+ stating that You changed the files; and
75
+ (c) You must retain, in the Source form of any Derivative Works that
76
+ You distribute, all copyright notices, patent notices, and
77
+ attribution notices from the Source form of the Work; and
78
+ (d) If the Work includes a "NOTICE" text file as part of its
79
+ distribution, then any Derivative Works that You distribute must
80
+ include a readable copy of the attribution notices contained
81
+ within such NOTICE file.
82
+
83
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
84
+ any Contribution intentionally submitted for inclusion in the Work
85
+ by You to the Licensor shall be under the terms and conditions of
86
+ this License.
87
+
88
+ 6. Trademarks. This License does not grant permission to use the trade
89
+ names, trademarks, or service marks of the Licensor.
90
+
91
+ 7. Disclaimer of Warranty. Unless required by applicable law or agreed to
92
+ in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT
93
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
94
+
95
+ 8. Limitation of Liability. In no event and under no liability shall any
96
+ Contributor be liable to You for damages arising from the use of
97
+ this Work.
98
+
99
+ 9. Accepting Warranty or Additional Liability. While redistributing
100
+ the Work or Derivative Works thereof, You may choose to offer
101
+ support, warranty, or indemnity obligations.
102
+
103
+ END OF TERMS AND CONDITIONS
@@ -0,0 +1,16 @@
1
+ include LICENSE
2
+ include NOTICE
3
+ include README.md
4
+ include SKILL.md
5
+ include llms.txt
6
+ include llms-full.txt
7
+ include server.json
8
+ include Makefile
9
+ include pyproject.toml
10
+ include setup.py
11
+ recursive-include csrc *.h *.hpp *.cpp
12
+ recursive-include python *.py
13
+ recursive-include docs *.md
14
+ recursive-include examples *.py README.md noaa_weather.csv
15
+ recursive-include .claude-plugin *.json
16
+ recursive-include .cursor-plugin *.json
@@ -0,0 +1,63 @@
1
+ CXX ?= g++
2
+ CXXFLAGS ?= -std=c++20 -O3 -march=native -ffp-contract=off -Wall -Wextra -Wpedantic -fPIC
3
+ SANFLAGS := -std=c++20 -O1 -g -fno-omit-frame-pointer -fsanitize=address,undefined,float-cast-overflow -Wall -Wextra -Wpedantic -fPIC
4
+
5
+ UNAME_S := $(shell uname -s)
6
+ ifeq ($(UNAME_S),Darwin)
7
+ SHLIB_EXT := dylib
8
+ SHLIB_FLAGS := -dynamiclib
9
+ else
10
+ SHLIB_EXT := so
11
+ SHLIB_FLAGS := -shared
12
+ endif
13
+
14
+ BUILD_DIR := build
15
+ LIB_OUT := python/streamsieve/_libstreamsieve.$(SHLIB_EXT)
16
+ CLI_OUT := $(BUILD_DIR)/streamsieve
17
+ CPP_TEST := $(BUILD_DIR)/test_core_cpp
18
+ SAN_TEST := $(BUILD_DIR)/test_core_cpp_san
19
+
20
+ .PHONY: all lib cli test test-cpp test-san bench clean
21
+
22
+ all: lib cli
23
+
24
+ $(BUILD_DIR):
25
+ mkdir -p $(BUILD_DIR)
26
+
27
+ lib: $(LIB_OUT)
28
+
29
+ $(LIB_OUT): csrc/streamsieve_capi.cpp csrc/streamsieve_core.hpp csrc/streamsieve_capi.h
30
+ $(CXX) $(CXXFLAGS) $(SHLIB_FLAGS) csrc/streamsieve_capi.cpp -o $(LIB_OUT) -lm
31
+
32
+ cli: $(CLI_OUT)
33
+
34
+ $(CLI_OUT): csrc/streamsieve_cli.cpp csrc/streamsieve_core.hpp csrc/streamsieve_capi.h | $(BUILD_DIR)
35
+ $(CXX) $(CXXFLAGS) csrc/streamsieve_cli.cpp csrc/streamsieve_capi.cpp -o $(CLI_OUT) -lm
36
+
37
+ test-cpp: $(CPP_TEST) test-afterkey
38
+ ./$(CPP_TEST)
39
+
40
+ .PHONY: test-afterkey
41
+ test-afterkey: $(BUILD_DIR)/test_afterkey
42
+ ./$(BUILD_DIR)/test_afterkey
43
+
44
+ $(BUILD_DIR)/test_afterkey: afterkey/tests/test_afterkey.cpp afterkey/include/afterkey.hpp afterkey/include/afterkey_journal.hpp | $(BUILD_DIR)
45
+ $(CXX) $(CPPFLAGS) $(CXXFLAGS) -std=c++17 $< -o $@
46
+
47
+ $(CPP_TEST): tests/test_core_cpp.cpp csrc/streamsieve_core.hpp csrc/streamsieve_capi.h csrc/streamsieve_capi.cpp | $(BUILD_DIR)
48
+ $(CXX) $(CXXFLAGS) tests/test_core_cpp.cpp csrc/streamsieve_capi.cpp -o $(CPP_TEST) -lm
49
+
50
+ test-san: $(SAN_TEST)
51
+ ./$(SAN_TEST)
52
+
53
+ $(SAN_TEST): tests/test_core_cpp.cpp csrc/streamsieve_core.hpp csrc/streamsieve_capi.h csrc/streamsieve_capi.cpp | $(BUILD_DIR)
54
+ $(CXX) $(SANFLAGS) tests/test_core_cpp.cpp csrc/streamsieve_capi.cpp -o $(SAN_TEST) -lm
55
+
56
+ test: all test-cpp test-san
57
+ PYTHONPATH=python python3 -m unittest discover -s tests -p "test_*.py" -v
58
+
59
+ bench: all
60
+ PYTHONPATH=python .bench-venv/bin/python benchmarks/run_all.py
61
+
62
+ clean:
63
+ rm -rf $(BUILD_DIR) $(LIB_OUT)
@@ -0,0 +1,13 @@
1
+ streamsieve
2
+ Copyright 2026 StreamSieve Contributors
3
+
4
+ This product is licensed under the Apache License, Version 2.0 (see LICENSE).
5
+
6
+ Third-party example data attribution:
7
+ - examples/noaa_weather.csv: Public-domain NOAA weather dataset (Seattle and
8
+ New York daily observations, 2012-2015), sourced via Vega Datasets
9
+ (license: public domain / other-pd).
10
+
11
+ Runtime dependencies:
12
+ - None. The core C++20/AVX2 engine, native CLI, Python SDK, and stdio MCP
13
+ server have zero third-party runtime dependencies.
@@ -0,0 +1,276 @@
1
+ Metadata-Version: 2.4
2
+ Name: streamsieve
3
+ Version: 0.2.0
4
+ Summary: SIMD C++20 multi-agent streaming inference, anytime-valid e-process monitoring, VOI firehose sifting, and echo-free CRDT belief fusion.
5
+ License: Apache-2.0
6
+ Project-URL: Homepage, https://github.com/pgg898200-ship-it/streamsieve
7
+ Project-URL: Repository, https://github.com/pgg898200-ship-it/streamsieve
8
+ Project-URL: Documentation, https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/architecture.md
9
+ Project-URL: Benchmarks, https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/benchmarks.md
10
+ Project-URL: Issues, https://github.com/pgg898200-ship-it/streamsieve/issues
11
+ Keywords: streaming,time-series,multi-agent,e-values,e-process,anytime-valid,conformal-prediction,crdt,anomaly-detection,mcp,ai-agents,online-learning,simd
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: License :: OSI Approved :: Apache Software License
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: C++
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Classifier: Topic :: System :: Monitoring
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ License-File: NOTICE
24
+ Provides-Extra: numpy
25
+ Requires-Dist: numpy>=1.24; extra == "numpy"
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=8.0; extra == "dev"
28
+ Requires-Dist: numpy>=1.24; extra == "dev"
29
+ Requires-Dist: scipy>=1.11; extra == "dev"
30
+ Requires-Dist: river>=0.21; extra == "dev"
31
+ Dynamic: license-file
32
+
33
+ # StreamSieve
34
+
35
+ **Find which telemetry channels changed, then read the samples behind the alert.**
36
+
37
+ Put StreamSieve between a metrics collector and an alerting service or monitoring agent. Feed it one row of numeric measurements per tick. It returns a ranked brief with flagged channels, estimated change points and handles for reading back exact samples held in memory.
38
+
39
+ [Try the Python example](#try-it) · [Use the CLI or MCP server](#quickstart) · [Benchmark results](docs/benchmarks.md) · [Agent reference](llms.txt) · [Find a tool by task](PRODUCTS.md)
40
+
41
+ ![Two simulated latency streams over 256 ticks. Worker B shifts from 40–41 ms to 50–51 ms. StreamSieve flags B and returns the range ch:1@t=80..256.](docs/worker-latency.png)
42
+
43
+ ## Try it
44
+
45
+ Install the v0.1.0 wheel from GitHub Releases with CPython 3.9–3.13 on Linux x86-64 (glibc 2.17+, AVX2/FMA) or macOS on Apple Silicon (11+).
46
+
47
+ ```sh
48
+ python -m pip install --no-index --only-binary=:all: --find-links https://github.com/pgg898200-ship-it/streamsieve/releases/expanded_assets/v0.1.0 streamsieve==0.1.0
49
+ ```
50
+
51
+ Run this example in Python. It works with the release wheel and with the current source.
52
+
53
+ ```python
54
+ from streamsieve import EStream
55
+
56
+ # Two workers alternate between 40 and 41 ms. After 80 samples, B gains 10 ms.
57
+ rows = [[40 + t % 2, 40 + t % 2 + 10 * (t >= 80)] for t in range(256)]
58
+ with EStream(2, warmup=32, ring_capacity=256) as monitor:
59
+ monitor.update_batch(rows)
60
+ brief = monitor.brief(names=["worker_a_ms", "worker_b_ms"])
61
+ for item in brief["top"]:
62
+ if item["rejected_ebh"]:
63
+ print(item["name"], item["handle"], monitor.fetch_raw(item["handle"])[-1])
64
+ ```
65
+
66
+ ```text
67
+ worker_b_ms ch:1@t=80..256 (256, 51.0)
68
+ ```
69
+
70
+ Only worker B crosses the alert threshold. Its last retained sample is 51 ms at tick 256. Keep the monitor alive to resolve its handles. The ring retains the most recent `ring_capacity` samples per channel.
71
+
72
+ For continuous monitoring, keep an `EStream` per group of channels and update it as new rows arrive. A CLI call analyzes one input window. The stdio MCP server lets an agent call `sift_stream`, then `fetch_raw_ticks` against the same session. Current source adds JSONL input, seasonal adjustment, detrending and a scikit-learn adapter. [Build the current source](#build-the-current-source) · [Statistical assumptions and limits](#honest-limitations-where-not-to-use-streamsieve)
73
+
74
+ ## Catch up a slow reader
75
+
76
+ [Afterkey](https://github.com/pgg898200-ship-it/streamsieve/tree/main/afterkey) is the standalone C++17 change feed for dashboards and agents that poll at different rates. It returns the latest value or deletion for each changed key since a reader’s cursor. Try the [interactive demo](https://afterkey.tancurl3.chatgpt.site/) or compile the [StreamSieve channel-score example](https://github.com/pgg898200-ship-it/streamsieve/blob/main/afterkey/examples/streamsieve.cpp).
77
+
78
+ ## Route moving agents by zone
79
+
80
+ [EdgeChime](https://github.com/pgg898200-ship-it/streamsieve/tree/main/edgechime) emits the rectangular zones that each moving agent entered or left. It includes a dependency-free JavaScript API, an NDJSON CLI, and examples for Eclipse SUMO and Tiled. Compare it with a packed R-tree and a perimeter grid on two CPUs, including random jumps where the R-tree wins. [Live demo](https://huggingface.co/spaces/pgg-engineering/edgechime) · [Labeled replay](https://huggingface.co/datasets/pgg-engineering/edgechime-bench) · [Benchmark data](https://github.com/pgg898200-ship-it/streamsieve/blob/main/edgechime/bench/README.md).
81
+
82
+ ## Verified Benchmarks (`StreamSwarmBench`)
83
+
84
+ Measured live on an Intel Xeon 2.30 GHz Linux VM (2 vCPUs, AVX2+FMA, Python 3.12.16) against `river 0.27.0`, `scipy 1.18.1`, and `numpy 2.5.5`. Full structured output: [`benchmarks/results.json`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/benchmarks/results.json) | Detailed report: [`docs/benchmarks.md`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/benchmarks.md).
85
+
86
+ ### 1. Throughput, Incumbent Speedups & Startup Latency
87
+
88
+ | Workload | `streamsieve 0.2.0` | Incumbent Baseline | Verified Speedup |
89
+ |---|---:|---:|---:|
90
+ | Native 8-wide AVX2 CLI (`256 ch × 16,000 ticks`) | **255.67 M ch-ticks/s** (`16.02 ms`) | — | Native C++20 SIMD |
91
+ | Native 8-wide AVX2 CLI (`1,024 ch × 4,000 ticks`) | **191.20 M ch-ticks/s** (`21.42 ms`) | — | Native C++20 SIMD |
92
+ | Native 8-wide AVX2 CLI (`4,096 ch × 2,000 ticks`) | **146.69 M ch-ticks/s** (`55.85 ms`) | — | Native C++20 SIMD |
93
+ | Python batch vs `river.drift.ADWIN` (`64×2k`) | **1.21 ms** (`105.75 M/s`) | `32.62 ms` (`3.92 M/s`) | **26.9× faster** |
94
+ | Python batch vs `river.drift.PageHinkley` (`64×2k`) | **1.21 ms** (`105.75 M/s`) | `111.67 ms` (`1.15 M/s`) | **92.3× faster** |
95
+ | Python batch + online e-BH vs NumPy/SciPy z+BH (`256×4k`) | **7.58 ms** (`135.18 M/s`) | `79.92 ms` (`12.81 M/s`) | **10.55× faster** |
96
+ | Cold startup (CLI vs `import streamsieve`) | **3.87 ms** (CLI) / **25.30 ms** (`import`) | `1,791.01 ms` (`numpy+scipy+river`) | **70.8× faster** (`import`) / **463×** (CLI) |
97
+
98
+ ### 2. Continuous-Peeking Calibration, Zero-Mean Bursts & Non-Stationary Streams
99
+
100
+ | Benchmark (nominal $\alpha = 0.05$) | `streamsieve 0.2.0` | Naive `\|z\| > 3` | Peeking Welch+BH | `river.ADWIN(0.002)` | `river.PageHinkley` |
101
+ |---|---:|---:|---:|---:|---:|
102
+ | **Stationary Null FAR** (Gaussian / Student-$t(3)$ / LogNormal / $10^{10}$ DC+1000×) | **0.004 – 0.010** | 0.196 – 0.834 | 0.476 – 0.542 | 0.000 – 0.004 | 0.108 – 1.000 |
103
+ | **Non-Stationary Null FAR** (`Diurnal P=24` / `LinearTrend` / `RandomWalk` / `Both`) | **0.010 – 0.050** (`--season` / `--detrend`) | 0.000 – 0.645 | 0.835 – 1.000 | 0.000 – 1.000 | 1.000 |
104
+ | **256-Ch Mixed Firehose** (4 shifts + 4 bursts + 32 loud 5×): **Emp. FDR / F1** | **0.000 / 0.883** (`2.8 ms`); peeking **0.040 / 0.909** (`40.8 ms`) | 0.966 / 0.059 | 0.321 / 0.799 (`183.0 ms`) | 0.054 / 0.862 (`49.3 ms`) | — |
105
+ | **Zero-Mean `±3.5σ` Bursts** (256-ch): **Burst Recall / F1** | **0.65–0.70 / 0.897–0.900** | 0.30 / 0.102 | **0.00** / 0.578 | **0.00** / 0.667 | — |
106
+ | **64-Ch Diurnal (`P=24`, `6σ` wave) Firehose**: **Emp. FDR / F1 / Wall** | **0.000 / 0.799 / 1.7 ms** | — | 0.000 / 0.667 / `125.5 ms` | 0.000 / 0.618 / `11.6 ms` | — |
107
+ | **Sequential Stopping** ($H_0$ FAR / $H_1$ Power / Samples Saved) | **0.015 / 1.00 / 70.0%** | — | 0.440 / 1.00 / 74.7% | — | — |
108
+
109
+ ### 3. Multi-Agent Coordination, Token Compression & Real NOAA Weather
110
+
111
+ | Mechanism | `streamsieve` Engine | Verified Result vs Baseline |
112
+ |---|---|---|
113
+ | **Token Compression** (`1024 ch × 2000 ticks`, 15.4 MB CSV) | `EStream` | **3,844,353 → 325 tokens (99.99% / 11,829× reduction)** in `53.4 ms`, 1.00/1.00 Prec/Rec, 0 loud FPs, **`0.0` exact raw drill-down error** |
114
+ | **Anti-Echo Gossip** ($W = 8$ agents, 40 msgs/trial, 200 trials) | `EvidenceLattice` | **0.0% overwrite churn, 1.00× inflation** (Brier skill `+0.686`) vs 96.5% LWW churn / **10.39×** naive log-odds inflation |
115
+ | **Wire Budget** (256 unique findings across 8 hypotheses) | `EvidenceLattice` (`SSLT` v1) | **10,428 B binary** (`13,035` Base85 chars) vs `111,143 B` JSON debate (**10.7× smaller**) |
116
+ | **Firehose Attention** (2,048 ch, 256 sites, $W = 4$, 10 seeds) | `VOISifter` | **+0.702 Brier skill, 78.3% Recall@Top, 0.11% inter-agent overlap** vs `-0.010` round-robin / `-32.42` raw-mean |
117
+ | **Byzantine + Trust Flip** (4-epoch delay, flip @ 60, 20 seeds) | `TrustCalibrator` | **100.0% Byzantine quarantine**, post-flip Brier **0.1840** vs `0.2179` ExpWeights / `0.2539` mean vote |
118
+ | **Real NOAA Seattle `temp_max`** (1,461 days, 4:1 cost, 1-day delay) | `TrustCalibrator` | **30.39% asymmetric cost reduction** (`3.889` vs `5.587`) and **90.01%** empirical coverage on 90% AgACI intervals |
119
+
120
+ ---
121
+
122
+ ## Quickstart
123
+
124
+ ### Build the current source
125
+
126
+ The examples below use the v0.2.0 code on `main`. Install the Python SDK and its `streamsieve` command with Python 3.9+ and a C++20 compiler.
127
+
128
+ ```sh
129
+ git clone https://github.com/pgg898200-ship-it/streamsieve.git
130
+ cd streamsieve
131
+ python -m pip install .
132
+ streamsieve version
133
+ ```
134
+
135
+ On Unix, set `CXX=c++` if Python selects a compiler that is missing. For an x86-64 CPU without AVX2/FMA, set `STREAMSIEVE_NO_AVX2=1` before building. To build the separate native executable in the checkout, run `make all` and then `./build/streamsieve version`.
136
+
137
+ ### Read CSV, TSV or JSON Lines from the terminal
138
+
139
+ ```bash
140
+ # Each line is a flat JSON object with numeric metric fields
141
+ tail -n 2000 metrics.jsonl | streamsieve sift --season 24 --alpha 0.05 --json -
142
+
143
+ # Detrend linear ramps or random walks (1.0 = causal first difference)
144
+ cat cpu_trend.csv | streamsieve sift --detrend 1.0 --alpha 0.05 -
145
+
146
+ # Compact agent-ready brief on real NOAA telemetry (numeric columns 3-6)
147
+ cut -d, -f3-6 examples/noaa_weather.csv | streamsieve sift -
148
+
149
+ # Native AVX2 throughput self-benchmark & causality self-verification
150
+ streamsieve bench --channels 1024 --ticks 4000
151
+ streamsieve verify --json
152
+ ```
153
+
154
+ ### Python SDK and adapters
155
+
156
+ ```python
157
+ import streamsieve as ss
158
+
159
+ # 1. Anytime-valid firehose sift (with optional causal deseasonalizing/detrending) + lossless drill-down
160
+ est, brief = ss.sift_matrix(
161
+ matrix, names=col_names, alpha=0.05, season_period=24, detrend_alpha=0.0, ring_capacity=256
162
+ )
163
+ print(brief.to_compact_text()) # ~320 tokens regardless of channel count
164
+ raw_ticks = est.fetch_raw(brief["top"][0]["handle"]) # bit-exact raw (tick, float) tuples
165
+
166
+ # 2. Drop-in 1-line replacement for river.drift.ADWIN / PageHinkley (zero river dep!)
167
+ from streamsieve import EStreamDrift as ADWIN
168
+ det = ADWIN(alpha=0.05, season_period=24) # catches shifts + zero-mean +-3.5 sigma bursts
169
+ for x in stream:
170
+ if det.update(x).drift_detected:
171
+ print(f"Drift ({det.mode}) e={det.e_value:.1f}")
172
+
173
+ # 3. Drop-in zero-dependency scikit-learn OutlierMixin-compatible multivariate streaming detector
174
+ det_sk = ss.SklearnSieveDetector(alpha=0.05, warmup=32, season_period=24)
175
+ labels = det_sk.fit_predict(X_stream) # +1 calm, -1 anytime-valid e-BH anomaly
176
+ print(det_sk.rejected_channels_, det_sk.brief().to_compact_text())
177
+
178
+ # 4. Zero-echo CRDT multi-agent belief & Vovk-Wang e-value fusion
179
+ lat_a, lat_b = ss.EvidenceLattice(), ss.EvidenceLattice()
180
+ lat_a.observe("outage", "ch:3@t=180..600", llr=2.4, log_e=3.2, agent_id=0, timestamp_ns=100)
181
+ lat_b.observe("outage", "ch:3@t=180..600", llr=2.4, log_e=3.2, agent_id=1, timestamp_ns=200) # echo!
182
+ lat_a.merge(lat_b) # commutative, associative, idempotent
183
+ print(lat_a.query("outage")) # unique_evidence=1, echoes_suppressed=1
184
+
185
+ # 5. Zero-overlap hierarchical VOI attention + delayed-label Byzantine-safe TrustCalibrator
186
+ sifter = ss.VOISifter(n_channels=2048, n_sites=256, ticks_per_epoch=8)
187
+ sifter.set_noise_scales(channel_stds) # loud-channel immune
188
+ plan = sifter.allocate(budget_per_agent=4, n_agents=4)
189
+
190
+ tc = ss.TrustCalibrator(n_agents=4, conformal_alpha=0.10)
191
+ dec = tc.predict_scalar("day_42", [18.1, 17.8, 18.4, 999.0], underage_cost=4.0, overage_cost=1.0)
192
+ tc.resolve("day_42", outcome=18.2) # strictly causal delayed resolution
193
+ ```
194
+
195
+ See runnable cookbooks in [`examples/jsonl_diurnal_sre.py`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/examples/jsonl_diurnal_sre.py) and [`examples/multi_agent_pipeline.py`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/examples/multi_agent_pipeline.py).
196
+
197
+ ### MCP server and agent configuration
198
+
199
+ Run the zero-dependency JSON-RPC 2.0 stdio MCP server exposing **7 stateful tools** (`sift_stream` with `jsonl_text` / `csv_text` / `rows` / `json_data`, `fetch_raw_ticks`, `lattice_observe`, `lattice_merge`, `lattice_query`, `voi_allocate`, `trust_step`):
200
+
201
+ ```bash
202
+ streamsieve mcp
203
+ # or: python3 -m streamsieve.mcp_server
204
+ ```
205
+
206
+ Add to `.mcp.json` / Claude Desktop / Cursor MCP config:
207
+
208
+ ```json
209
+ {
210
+ "mcpServers": {
211
+ "streamsieve": {
212
+ "command": "streamsieve",
213
+ "args": ["mcp"]
214
+ }
215
+ }
216
+ }
217
+ ```
218
+
219
+ Plugin manifests and agent skill instructions are pre-packaged at [`SKILL.md`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/SKILL.md), [`.claude-plugin/plugin.json`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/.claude-plugin/plugin.json), and [`.cursor-plugin/plugin.json`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/.cursor-plugin/plugin.json).
220
+
221
+ ---
222
+
223
+ ## Score revised scalar forecasts
224
+
225
+ [RecastCRPS](https://github.com/pgg898200-ship-it/streamsieve/tree/main/integrations/recastcrps) scores an ensemble after a member revises or withdraws its point forecast. It also identifies the best and worst single-member withdrawals for an equal-weight panel in logarithmic time. A [worked example](https://github.com/pgg898200-ship-it/streamsieve/tree/main/integrations/recastcrps/examples) uses the same forecasts with `TrustCalibrator` and RecastCRPS and resolves both against an observed outcome. [Try the Hurricane Lee replay](https://huggingface.co/spaces/pgg-engineering/recastcrps).
226
+
227
+ ## Architecture: Four Co-Designed Strictly Causal Engines
228
+
229
+ ```mermaid
230
+ flowchart LR
231
+ RAW["High-Frequency Stream\n(CSV / JSONL / Matrix\nN ch × T ticks)"] --> E1["1. EStreamEngine\nCausal Detrend & Season Pre-Filter\n8-wide Cache-Tiled AVX2 SoA\nDual-Res E-Process + Online e-BH\nLossless Raw Ring"]
232
+ E1 -->|"Compact Brief (~320 tok)\n+ Raw Drill-Down Handles"| E3["3. VOISifter\nSite × Channel × Tick\nSparse-Burst LLR\nZero-Overlap Multi-Agent VOI"]
233
+ E1 -->|"Provenance-Tagged\nChannel E-Values"| E2["2. EvidenceLattice\nJoin-Semilattice CRDT\nBayes Log-Odds + Vovk-Wang E\nSSLT v1 Binary / Base85 Wire"]
234
+ E3 -->|"Non-Overlapping\nAgent Inspections"| E2
235
+ E2 -->|"Echo-Free Beliefs"| E4["4. TrustCalibrator\nCausal Delayed-Label Buffer\nNon-Negative Platt + Fixed-Share BOA\nVille Quarantine + Delayed AgACI"]
236
+ E4 -->|"Agent Trust Weights\n& Quarantine Masks"| E2
237
+ ```
238
+
239
+ Every engine obeys **bit-exact zero-lookahead causality** verified by [`assert_causal()`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/python/streamsieve/causality.py) (poisoning all future ticks $s > t$ with `+1e12`, `-1e12`, `NaN`, and `+Inf` produces `0.0` bit diff on outputs at $\le t$).
240
+
241
+ ---
242
+
243
+ ## Verification, Adversarial Testing & Honest Scope
244
+
245
+ - **Multi-Compiler + Sanitizer Verification:** `make all test-cpp test-san` builds GCC `-O3 -march=native -ffp-contract=off -Wall -Wextra -Wpedantic` (AVX2), strict `clang++ -Werror`, MSVC C++20 on Windows CI, and `-fsanitize=address,undefined,float-cast-overflow` (scalar) with **0 compiler warnings**, **0 sanitizer errors**, and **0-ULP bit-exact parity** across 8-wide/4-wide/scalar AVX2 `update_batch`, `update_row`, and `update_one`.
246
+ - **79/79 Zero-Dependency Python Tests + Adversarial Breaker Suite:** Runs unit tests, drop-in `river`/`sklearn` adapter tests, 27 adversarial torture tests ([`tests/test_breaker_adversarial.py`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/tests/test_breaker_adversarial.py)), and 23 v0.2.0 parity/causality/breaker-regression tests ([`tests/test_v020_features.py`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/tests/test_v020_features.py)) covering alternating `±1e308` warmup inputs, seasonal subtraction overflow, simultaneous `1e15` warmup spikes, strict RFC-8259 JSONL fuzzing, deeply nested JSON/bigint inputs, atomic MCP session swaps, and batch-size invariance.
247
+ - **Reproduce all benchmarks:**
248
+ ```bash
249
+ PYTHONPATH=python .bench-venv/bin/python benchmarks/run_all.py
250
+ ```
251
+
252
+ ### Honest Limitations (Where NOT to Use `streamsieve`)
253
+ - **Detrender choice (`detrend_alpha=1.0` vs `< 1.0`):** Use `detrend_alpha=1.0` (causal first difference) for arbitrarily steep linear trends and random walks (0-tick transient; detects slope breaks & bursts cleanly). Values `0 < detrend_alpha < 1` run a robust 5-sample-median-initialized EWMA high-pass filter suitable for slow drift (converging in `~3/alpha` ticks), not steep ramps.
254
+ - **Seasonal period & warmup budget:** Causal deseasonalization (`season_period=P`) freezes per-phase medians over at least `3 * P` warmup ticks (`eff_warmup = max(warmup, 3*P)`) and applies an analytical OOS variance scale correction; streams with time-varying periods or non-integer periods should be residualized externally before feeding `EStream`.
255
+ - **Short baselines on ultra-wide panels for rare bursts:** Online e-BH at $M = 1{,}000$ with 1 active channel requires $E \ge 20{,}000$; rare bursts ($p_b \le 0.05$) need enough pre-onset baseline ticks ($n_0$) for the universal-inference Beta-Binomial denominator to separate the rate, or hierarchical triage via `VOISifter`.
256
+ - **Single-tick Python loops:** Calling `EStream.update_row()` one row at a time from Python incurs `ctypes` per-call overhead (`4.97 M ch-ticks/s`, still `1.27×` faster than `river.ADWIN`). Batch rows with `update_batch()` (`70–135 M/s`) or use the native CLI/C ABI (`147–256 M/s`).
257
+ - **Sybil provenance forgery:** `EvidenceLattice` prevents accidental or gossip-induced double counting when identical observations carry identical content-hashed `provenance_id`s; deliberate Sybil adversaries forging fresh IDs are mitigated by `TrustCalibrator` Ville quarantine.
258
+
259
+ ---
260
+
261
+ ## Documentation & Comparisons
262
+
263
+
264
+ - **Technical Specification & Math:** [`docs/architecture.md`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/architecture.md)
265
+ - **Full Benchmark Report (`StreamSwarmBench`):** [`docs/benchmarks.md`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/benchmarks.md) | [`benchmarks/results.json`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/benchmarks/results.json)
266
+ - **Runnable Cookbooks:** [`examples/README.md`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/examples/README.md)
267
+ - **Honest Head-to-Head Comparisons:**
268
+ - [`streamsieve` vs `river` (ADWIN / Page-Hinkley)](https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/comparisons/vs-river.md)
269
+ - [`streamsieve` vs Rolling Z-Scores, Welch t-Tests & CUSUM](https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/comparisons/vs-zscore-and-cusum.md)
270
+ - [`streamsieve` vs Multi-Agent Debate & LWW Blackboards](https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/comparisons/vs-multiagent-debate.md)
271
+ - [`streamsieve` Online e-BH vs BH / BY / Bonferroni](https://github.com/pgg898200-ship-it/streamsieve/blob/main/docs/comparisons/vs-online-fdr.md)
272
+ - **Agent / LLM Machine Index:** [`llms.txt`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/llms.txt) | [`llms-full.txt`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/llms-full.txt) | [`SKILL.md`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/SKILL.md)
273
+
274
+ ## License
275
+
276
+ Apache License 2.0 — see [`LICENSE`](https://github.com/pgg898200-ship-it/streamsieve/blob/main/LICENSE).