stream-velocity 0.1.0__tar.gz

stream_velocity-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: CI Test Suite
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Run unit tests
+        run: python -m unittest discover -s tests -v
+
+      - name: Run SLA benchmark
+        run: python tests/benchmark_latency.py
+
+      - name: Run memory benchmark
+        run: python tests/benchmark_memory.py

stream_velocity-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.DS_Store
+.venv/
+venv/
+.opencode/
+.cursor/

stream_velocity-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+# A small, self-contained image that installs the library and runs its
+# benchmarks. Built on Alpine Linux so the image itself stays lightweight.
+
+FROM python:3.11-alpine
+
+WORKDIR /app
+
+# Copy the project files into the image.
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+COPY tests ./tests
+
+# Install the library from source.
+RUN pip install --no-cache-dir .
+
+# When the container starts, run the speed benchmark to confirm it stays fast.
+CMD ["python", "tests/benchmark_latency.py"]

stream_velocity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Woo Chan Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stream_velocity-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: stream-velocity
+Version: 0.1.0
+Summary: A zero-dependency, bounded-memory Python library for sub-5ms sliding-window transaction velocity aggregations.
+Project-URL: Homepage, https://github.com/lee14257/stream-velocity
+Project-URL: Repository, https://github.com/lee14257/stream-velocity
+Author: Woo Chan Lee
+License-Expression: MIT
+License-File: LICENSE
+Keywords: feature-store,fintech,fraud-detection,streaming,velocity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# stream-velocity
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://img.shields.io/github/actions/workflow/status/lee14257/stream-velocity/test.yml?branch=main)](https://github.com/lee14257/stream-velocity/actions/workflows/test.yml)
+
+`stream-velocity` is a small, dependency-free Python library that answers one question in real time: **"how many events happened in the last few minutes, and how much did they total?"** — per account, card, or any other entity.
+
+It exists because small fraud and risk teams often need this exact check but can't justify a Redis cluster or a $10k/month streaming platform. `stream-velocity` gives them a fast, in-process alternative that uses a fixed amount of memory no matter how much data flows through it.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+> A public PyPI release is in progress. Until then, install from source as shown above.
+
+## Quick Start
+
+```python
+from stream_velocity import VelocityTracker
+
+# Track a 5-minute window, split into 5-second buckets
+tracker = VelocityTracker(window_seconds=300, bucket_seconds=5)
+
+# Record incoming events for an account
+tracker.record_event(entity_id="acc_990142", amount=150.00)
+tracker.record_event(entity_id="acc_990142", amount=45.50)
+tracker.record_event(entity_id="acc_990142", amount=210.00)
+
+# Read the current rolling totals
+velocity = tracker.get_velocity("acc_990142")
+
+print(velocity.count)        # 3
+print(velocity.sum_amount)   # 405.5
+```
+
+## API Reference
+
+### `VelocityTracker`
+
+The main entry point. Tracks rolling velocity across many entities.
+
+```python
+VelocityTracker(
+    window_seconds=300,
+    bucket_seconds=5,
+    idle_timeout=None,
+    cleanup_interval=60.0,
+)
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `window_seconds` | `int` | `300` | Length of the rolling window, in seconds. |
+| `bucket_seconds` | `int` | `5` | Width of each bucket, in seconds. `window_seconds` must be evenly divisible by `bucket_seconds`. |
+| `idle_timeout` | `float` or `None` | `None` | Drop an entity if it records no events for this many seconds. `None` disables eviction. Should be at least `window_seconds`. |
+| `cleanup_interval` | `float` | `60.0` | How often (seconds) the idle sweep runs automatically. |
+
+**Methods**
+
+- `record_event(entity_id, amount=0.0, timestamp=None)` → `None` — record one event.
+  - `timestamp` defaults to the current time; pass an explicit value for replay or testing.
+- `get_velocity(entity_id, timestamp=None)` → `VelocityResult` — current rolling totals for an entity. Returns zeros if the entity is unknown or has been evicted.
+- `cleanup(now=None)` → `None` — immediately drop entities idle longer than `idle_timeout`. The sweep also runs automatically every `cleanup_interval` seconds.
+- `len(tracker)` → `int` — number of entities currently tracked.
+
+### `VelocityResult`
+
+A frozen (immutable) dataclass returned by `get_velocity`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `entity_id` | `str` | The entity the result is for. |
+| `window_seconds` | `int` | The window length used. |
+| `count` | `int` | Number of events in the window. |
+| `sum_amount` | `float` | Sum of `amount` values in the window. |
+
+### `BucketedRingBuffer` (lower-level)
+
+The underlying single-entity counter. Prefer `VelocityTracker` unless you need to manage one entity manually.
+
+```python
+buffer = BucketedRingBuffer(window_seconds=300, bucket_seconds=5)
+buffer.record(timestamp=1_000_000.0, amount=10.0)
+metrics = buffer.get_metrics(current_timestamp=1_000_010.0)  # {"window_seconds": 300, "count": 1, "sum_amount": 10.0}
+```
+
+## Features
+
+- **No dependencies** — pure Python 3.9+, no database, no C extensions.
+- **Always fast** — updates and lookups take the same time whether you process 10 or 10 million events (this is what "O(1)" means).
+- **Fixed memory** — counters are created once and reused forever, so memory use stays flat no matter how many events arrive.
+- **Bounded tracking** — set `idle_timeout` to drop idle entities automatically, so millions of distinct accounts don't grow memory forever.
+- **Low latency** — reads stay under 5 ms while processing 100,000+ events.
+
+## Limitations
+
+- **Single process** — the tracker lives in memory and is not shared across processes or machines. Run one instance per worker, or pair it with an external store for distributed setups.
+- **Not persistent** — state is lost on restart; there is no disk or external storage.
+- **Not thread-safe** — use one tracker per thread or worker, or add external locking if you share a tracker across threads.
+
+## How It Works
+
+A rolling window is split into a fixed number of buckets. For a 5-minute window with 5-second buckets, that's 60 buckets.
+
+- **Finding the bucket** — an event's timestamp maps to a bucket with one division: `slot = (timestamp // bucket_seconds) % num_buckets`.
+- **Reusing buckets** — as time passes, expired buckets are wiped clean and reused, so the total number of buckets never changes.
+- **Running totals** — two totals (count and amount) are kept up to date on every write, so reading the answer means just returning the totals — no scanning.
+
+```
+ events ──► slot = (timestamp // 5) % 60
+              │
+              ▼
+   ┌───┬───┬───┬───┬───┬───┬───┐
+   │ 0 │ 1 │ 2 │...│ 57│ 58│ 59│  ◄── fixed ring of buckets, reused forever
+   └───┴───┴───┴───┴───┴───┴───┘
+```
+
+Only counts and sums are stored — no raw transaction details.
+
+## Benchmarks
+
+### Latency
+
+```bash
+python3 tests/benchmark_latency.py
+```
+
+Representative output (Apple M-series MacBook Air, Python 3.10). Absolute timings vary by machine; the `< 5.0 ms` SLA is enforced in CI on every push.
+
+```
+--- Running stream-velocity benchmark: 100,000 events ---
+Total write time for 100,000 events: 61.88 ms
+Average write latency per event: 0.62 µs
+Read query latency: 0.0418 ms
+Aggregation result: 100000 events, $1,000,000.00
+SLA Target Passed: Query execution < 5.0 ms
+```
+
+### Memory
+
+```bash
+python3 tests/benchmark_memory.py
+```
+
+The library creates its counters once and reuses them, so memory stays flat as events pile up. A typical 5-minute window uses only a few kilobytes — far below the 100 MB ceiling a lightweight fraud service can run within.
+
+## Docker
+
+A minimal Alpine image installs the library and runs the speed benchmark:
+
+```bash
+docker build -t stream-velocity .
+docker run --rm stream-velocity
+```
+
+## Development
+
+Run the test suite and benchmarks:
+
+```bash
+python3 -m unittest discover -s tests
+python3 tests/benchmark_latency.py
+python3 tests/benchmark_memory.py
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

stream_velocity-0.1.0/README.md

@@ -0,0 +1,171 @@
+# stream-velocity
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://img.shields.io/github/actions/workflow/status/lee14257/stream-velocity/test.yml?branch=main)](https://github.com/lee14257/stream-velocity/actions/workflows/test.yml)
+
+`stream-velocity` is a small, dependency-free Python library that answers one question in real time: **"how many events happened in the last few minutes, and how much did they total?"** — per account, card, or any other entity.
+
+It exists because small fraud and risk teams often need this exact check but can't justify a Redis cluster or a $10k/month streaming platform. `stream-velocity` gives them a fast, in-process alternative that uses a fixed amount of memory no matter how much data flows through it.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+> A public PyPI release is in progress. Until then, install from source as shown above.
+
+## Quick Start
+
+```python
+from stream_velocity import VelocityTracker
+
+# Track a 5-minute window, split into 5-second buckets
+tracker = VelocityTracker(window_seconds=300, bucket_seconds=5)
+
+# Record incoming events for an account
+tracker.record_event(entity_id="acc_990142", amount=150.00)
+tracker.record_event(entity_id="acc_990142", amount=45.50)
+tracker.record_event(entity_id="acc_990142", amount=210.00)
+
+# Read the current rolling totals
+velocity = tracker.get_velocity("acc_990142")
+
+print(velocity.count)        # 3
+print(velocity.sum_amount)   # 405.5
+```
+
+## API Reference
+
+### `VelocityTracker`
+
+The main entry point. Tracks rolling velocity across many entities.
+
+```python
+VelocityTracker(
+    window_seconds=300,
+    bucket_seconds=5,
+    idle_timeout=None,
+    cleanup_interval=60.0,
+)
+```
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `window_seconds` | `int` | `300` | Length of the rolling window, in seconds. |
+| `bucket_seconds` | `int` | `5` | Width of each bucket, in seconds. `window_seconds` must be evenly divisible by `bucket_seconds`. |
+| `idle_timeout` | `float` or `None` | `None` | Drop an entity if it records no events for this many seconds. `None` disables eviction. Should be at least `window_seconds`. |
+| `cleanup_interval` | `float` | `60.0` | How often (seconds) the idle sweep runs automatically. |
+
+**Methods**
+
+- `record_event(entity_id, amount=0.0, timestamp=None)` → `None` — record one event.
+  - `timestamp` defaults to the current time; pass an explicit value for replay or testing.
+- `get_velocity(entity_id, timestamp=None)` → `VelocityResult` — current rolling totals for an entity. Returns zeros if the entity is unknown or has been evicted.
+- `cleanup(now=None)` → `None` — immediately drop entities idle longer than `idle_timeout`. The sweep also runs automatically every `cleanup_interval` seconds.
+- `len(tracker)` → `int` — number of entities currently tracked.
+
+### `VelocityResult`
+
+A frozen (immutable) dataclass returned by `get_velocity`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `entity_id` | `str` | The entity the result is for. |
+| `window_seconds` | `int` | The window length used. |
+| `count` | `int` | Number of events in the window. |
+| `sum_amount` | `float` | Sum of `amount` values in the window. |
+
+### `BucketedRingBuffer` (lower-level)
+
+The underlying single-entity counter. Prefer `VelocityTracker` unless you need to manage one entity manually.
+
+```python
+buffer = BucketedRingBuffer(window_seconds=300, bucket_seconds=5)
+buffer.record(timestamp=1_000_000.0, amount=10.0)
+metrics = buffer.get_metrics(current_timestamp=1_000_010.0)  # {"window_seconds": 300, "count": 1, "sum_amount": 10.0}
+```
+
+## Features
+
+- **No dependencies** — pure Python 3.9+, no database, no C extensions.
+- **Always fast** — updates and lookups take the same time whether you process 10 or 10 million events (this is what "O(1)" means).
+- **Fixed memory** — counters are created once and reused forever, so memory use stays flat no matter how many events arrive.
+- **Bounded tracking** — set `idle_timeout` to drop idle entities automatically, so millions of distinct accounts don't grow memory forever.
+- **Low latency** — reads stay under 5 ms while processing 100,000+ events.
+
+## Limitations
+
+- **Single process** — the tracker lives in memory and is not shared across processes or machines. Run one instance per worker, or pair it with an external store for distributed setups.
+- **Not persistent** — state is lost on restart; there is no disk or external storage.
+- **Not thread-safe** — use one tracker per thread or worker, or add external locking if you share a tracker across threads.
+
+## How It Works
+
+A rolling window is split into a fixed number of buckets. For a 5-minute window with 5-second buckets, that's 60 buckets.
+
+- **Finding the bucket** — an event's timestamp maps to a bucket with one division: `slot = (timestamp // bucket_seconds) % num_buckets`.
+- **Reusing buckets** — as time passes, expired buckets are wiped clean and reused, so the total number of buckets never changes.
+- **Running totals** — two totals (count and amount) are kept up to date on every write, so reading the answer means just returning the totals — no scanning.
+
+```
+ events ──► slot = (timestamp // 5) % 60
+              │
+              ▼
+   ┌───┬───┬───┬───┬───┬───┬───┐
+   │ 0 │ 1 │ 2 │...│ 57│ 58│ 59│  ◄── fixed ring of buckets, reused forever
+   └───┴───┴───┴───┴───┴───┴───┘
+```
+
+Only counts and sums are stored — no raw transaction details.
+
+## Benchmarks
+
+### Latency
+
+```bash
+python3 tests/benchmark_latency.py
+```
+
+Representative output (Apple M-series MacBook Air, Python 3.10). Absolute timings vary by machine; the `< 5.0 ms` SLA is enforced in CI on every push.
+
+```
+--- Running stream-velocity benchmark: 100,000 events ---
+Total write time for 100,000 events: 61.88 ms
+Average write latency per event: 0.62 µs
+Read query latency: 0.0418 ms
+Aggregation result: 100000 events, $1,000,000.00
+SLA Target Passed: Query execution < 5.0 ms
+```
+
+### Memory
+
+```bash
+python3 tests/benchmark_memory.py
+```
+
+The library creates its counters once and reuses them, so memory stays flat as events pile up. A typical 5-minute window uses only a few kilobytes — far below the 100 MB ceiling a lightweight fraud service can run within.
+
+## Docker
+
+A minimal Alpine image installs the library and runs the speed benchmark:
+
+```bash
+docker build -t stream-velocity .
+docker run --rm stream-velocity
+```
+
+## Development
+
+Run the test suite and benchmarks:
+
+```bash
+python3 -m unittest discover -s tests
+python3 tests/benchmark_latency.py
+python3 tests/benchmark_memory.py
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

stream_velocity-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stream-velocity"
+version = "0.1.0"
+description = "A zero-dependency, bounded-memory Python library for sub-5ms sliding-window transaction velocity aggregations."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Woo Chan Lee" }
+]
+keywords = ["fraud-detection", "streaming", "velocity", "feature-store", "fintech"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lee14257/stream-velocity"
+Repository = "https://github.com/lee14257/stream-velocity"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stream_velocity"]

stream_velocity-0.1.0/src/stream_velocity/__init__.py

@@ -0,0 +1,5 @@
+from .tracker import VelocityTracker, VelocityResult
+from .ring_buffer import BucketedRingBuffer
+
+__version__ = "0.1.0"
+__all__ = ["VelocityTracker", "VelocityResult", "BucketedRingBuffer"]

stream_velocity-0.1.0/src/stream_velocity/ring_buffer.py

@@ -0,0 +1,88 @@
+from typing import Dict, Any
+
+class BucketedRingBuffer:
+    """
+    Fixed-memory ring buffer using time-bucketed aggregation for constant-time O(1)
+    velocity calculations over a sliding time window.
+
+    Writes map timestamps to a slot index via integer division (O(1)). Reads return
+    pre-computed running totals after lazily expiring stale buckets, making both
+    operations constant-time regardless of the number of buckets in the window.
+    """
+    __slots__ = (
+        'window_seconds', 'bucket_seconds', 'num_buckets',
+        'counts', 'sums', 'last_bucket_idx',
+        'running_count', 'running_sum', 'trailing_bucket',
+    )
+
+    def __init__(self, window_seconds: int = 300, bucket_seconds: int = 5):
+        if window_seconds % bucket_seconds != 0:
+            raise ValueError("window_seconds must be evenly divisible by bucket_seconds")
+
+        self.window_seconds = window_seconds
+        self.bucket_seconds = bucket_seconds
+        self.num_buckets = window_seconds // bucket_seconds
+
+        self.counts = [0] * self.num_buckets
+        self.sums = [0.0] * self.num_buckets
+        self.last_bucket_idx = [-1] * self.num_buckets
+
+        self.running_count = 0
+        self.running_sum = 0.0
+        self.trailing_bucket = -1
+
+    def _get_current_slot(self, timestamp: float) -> tuple[int, int]:
+        total_buckets = int(timestamp // self.bucket_seconds)
+        slot_idx = total_buckets % self.num_buckets
+        return slot_idx, total_buckets
+
+    def _evict_stale(self, current_total_buckets: int) -> None:
+        min_valid_bucket = current_total_buckets - self.num_buckets + 1
+
+        # First observation: nothing can be stale yet, so fast-forward the
+        # trailing edge instead of scanning an empty buffer bucket-by-bucket.
+        if self.trailing_bucket == -1:
+            self.trailing_bucket = min_valid_bucket - 1
+            return
+
+        # Out-of-order guard: never regress the trailing edge backwards.
+        if min_valid_bucket <= self.trailing_bucket:
+            return
+
+        while self.trailing_bucket < min_valid_bucket:
+            self.trailing_bucket += 1
+            slot_idx = self.trailing_bucket % self.num_buckets
+            if self.last_bucket_idx[slot_idx] == self.trailing_bucket:
+                self.running_count -= self.counts[slot_idx]
+                self.running_sum -= self.sums[slot_idx]
+                self.counts[slot_idx] = 0
+                self.sums[slot_idx] = 0.0
+                self.last_bucket_idx[slot_idx] = -1
+
+    def record(self, timestamp: float, amount: float = 0.0) -> None:
+        slot_idx, total_buckets = self._get_current_slot(timestamp)
+        self._evict_stale(total_buckets)
+
+        # Evict stale data if slot belongs to a previous window iteration.
+        if self.last_bucket_idx[slot_idx] != total_buckets:
+            if self.last_bucket_idx[slot_idx] != -1:
+                self.running_count -= self.counts[slot_idx]
+                self.running_sum -= self.sums[slot_idx]
+            self.counts[slot_idx] = 0
+            self.sums[slot_idx] = 0.0
+            self.last_bucket_idx[slot_idx] = total_buckets
+
+        self.counts[slot_idx] += 1
+        self.sums[slot_idx] += amount
+        self.running_count += 1
+        self.running_sum += amount
+
+    def get_metrics(self, current_timestamp: float) -> Dict[str, Any]:
+        current_total_buckets = int(current_timestamp // self.bucket_seconds)
+        self._evict_stale(current_total_buckets)
+
+        return {
+            "window_seconds": self.window_seconds,
+            "count": self.running_count,
+            "sum_amount": self.running_sum,
+        }

stream_velocity-0.1.0/src/stream_velocity/tracker.py

@@ -0,0 +1,125 @@
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional
+from .ring_buffer import BucketedRingBuffer
+
+
+@dataclass(frozen=True)
+class VelocityResult:
+    """A snapshot of one entity's rolling-window velocity at a point in time."""
+
+    entity_id: str
+    window_seconds: int
+    count: int
+    sum_amount: float
+
+
+class VelocityTracker:
+    """
+    In-memory manager that tracks rolling velocity across many entities.
+
+    Memory is reclaimed lazily: when `idle_timeout` is set, any entity that has
+    not recorded an event for `idle_timeout` seconds is dropped on the next
+    `cleanup()` call or the periodic automatic sweep. This keeps the registry
+    bounded instead of growing forever with distinct entities.
+
+    `idle_timeout` should be at least as large as `window_seconds`; by the time
+    an entity has been idle for a full window, its counters are already empty,
+    so dropping it loses no current-velocity information.
+    """
+
+    def __init__(
+        self,
+        window_seconds: int = 300,
+        bucket_seconds: int = 5,
+        idle_timeout: Optional[float] = None,
+        cleanup_interval: float = 60.0,
+    ):
+        if idle_timeout is not None and idle_timeout <= 0:
+            raise ValueError("idle_timeout must be greater than 0")
+
+        self.window_seconds = window_seconds
+        self.bucket_seconds = bucket_seconds
+        self.idle_timeout = idle_timeout
+        self.cleanup_interval = cleanup_interval
+
+        self.entities: Dict[str, BucketedRingBuffer] = {}
+        self._last_seen: Dict[str, float] = {}
+        self._last_cleanup: float = 0.0
+
+    def __len__(self) -> int:
+        return len(self.entities)
+
+    def record_event(
+        self,
+        entity_id: str,
+        amount: float = 0.0,
+        timestamp: Optional[float] = None,
+    ) -> None:
+        if timestamp is None:
+            timestamp = time.time()
+
+        self._maybe_cleanup(timestamp)
+
+        ring = self.entities.get(entity_id)
+        if ring is None:
+            ring = BucketedRingBuffer(
+                window_seconds=self.window_seconds,
+                bucket_seconds=self.bucket_seconds,
+            )
+            self.entities[entity_id] = ring
+
+        ring.record(timestamp=timestamp, amount=amount)
+        self._last_seen[entity_id] = timestamp
+
+    def get_velocity(
+        self,
+        entity_id: str,
+        timestamp: Optional[float] = None,
+    ) -> VelocityResult:
+        if timestamp is None:
+            timestamp = time.time()
+
+        self._maybe_cleanup(timestamp)
+
+        ring = self.entities.get(entity_id)
+        if ring is None:
+            return VelocityResult(
+                entity_id=entity_id,
+                window_seconds=self.window_seconds,
+                count=0,
+                sum_amount=0.0,
+            )
+
+        metrics = ring.get_metrics(current_timestamp=timestamp)
+        return VelocityResult(
+            entity_id=entity_id,
+            window_seconds=metrics["window_seconds"],
+            count=metrics["count"],
+            sum_amount=metrics["sum_amount"],
+        )
+
+    def cleanup(self, now: Optional[float] = None) -> None:
+        """Drop entities that have been idle longer than `idle_timeout`."""
+        if self.idle_timeout is None:
+            return
+        if now is None:
+            now = time.time()
+
+        expired = [
+            entity_id
+            for entity_id, seen in self._last_seen.items()
+            if now - seen > self.idle_timeout
+        ]
+        for entity_id in expired:
+            del self.entities[entity_id]
+            del self._last_seen[entity_id]
+
+        self._last_cleanup = now
+
+    def _maybe_cleanup(self, now: float) -> None:
+        if self.idle_timeout is None:
+            return
+        if now - self._last_cleanup < self.cleanup_interval:
+            return
+        self.cleanup(now)

stream_velocity-0.1.0/tests/benchmark_latency.py

@@ -0,0 +1,34 @@
+import time
+from stream_velocity import VelocityTracker
+
+def run_benchmark(event_count=100000):
+    tracker = VelocityTracker(window_seconds=300, bucket_seconds=5)
+    entity_id = "bench_user_1"
+    start_time = time.time()
+
+    print(f"--- Running stream-velocity benchmark: {event_count:,} events ---")
+    
+    t0 = time.perf_counter()
+    for i in range(event_count):
+        tracker.record_event(entity_id=entity_id, amount=10.0, timestamp=start_time + (i * 0.001))
+    t1 = time.perf_counter()
+
+    write_total_ms = (t1 - t0) * 1000
+    avg_write_us = (write_total_ms / event_count) * 1000
+
+    t2 = time.perf_counter()
+    metrics = tracker.get_velocity(entity_id=entity_id, timestamp=start_time + 100)
+    t3 = time.perf_counter()
+
+    query_latency_ms = (t3 - t2) * 1000
+
+    print(f"Total write time for {event_count:,} events: {write_total_ms:.2f} ms")
+    print(f"Average write latency per event: {avg_write_us:.2f} µs")
+    print(f"Read query latency: {query_latency_ms:.4f} ms")
+    print(f"Aggregation result: {metrics.count} events, ${metrics.sum_amount:,.2f}")
+
+    assert query_latency_ms < 5.0, f"SLA Violation: Query took {query_latency_ms:.2f}ms (target <5ms)"
+    print("SLA Target Passed: Query execution < 5.0 ms")
+
+if __name__ == "__main__":
+    run_benchmark()

stream_velocity-0.1.0/tests/benchmark_memory.py

@@ -0,0 +1,75 @@
+"""
+Prove that stream-velocity uses a fixed amount of memory, no matter how many
+events it processes.
+
+The idea is simple: the library sets up a fixed number of "buckets" when it
+starts (one bucket for each slice of the time window). As time moves forward,
+old buckets are wiped clean and reused, so nothing new is ever allocated.
+
+This script records a small number of events, measures the memory in use, then
+records ten times as many events and measures again. If the library is doing
+its job, the two numbers are the same.
+"""
+
+import tracemalloc
+from stream_velocity import VelocityTracker
+
+
+def measure_used_bytes(event_count: int) -> int:
+    """Record `event_count` events and return how many bytes the library holds."""
+    tracker = VelocityTracker(window_seconds=300, bucket_seconds=5)
+    start_time = 1_000_000.0
+
+    tracemalloc.start()
+    for i in range(event_count):
+        # Space events 1 ms apart so they flow through the time window.
+        tracker.record_event(
+            entity_id="account_1",
+            amount=10.0,
+            timestamp=start_time + (i * 0.001),
+        )
+    current_bytes, _ = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+
+    return current_bytes
+
+
+def main() -> None:
+    small = measure_used_bytes(100_000)
+    large = measure_used_bytes(1_000_000)
+
+    print("--- stream-velocity memory benchmark ---")
+    print(f"Memory after   100,000 events: {small / 1024:>8,.1f} KB")
+    print(f"Memory after 1,000,000 events: {large / 1024:>8,.1f} KB")
+
+    # Ten times the events should not mean ten times the memory.
+    slack_bytes = 64 * 1024  # allow 64 KB of measurement noise
+    assert large <= small + slack_bytes, (
+        f"Memory grew with more events: {small / 1024:.1f} KB -> {large / 1024:.1f} KB"
+    )
+
+    # The whole library must stay far below the 100 MB ceiling.
+    assert large < 100 * 1024 * 1024, (
+        f"Memory exceeded 100 MB: {large / 1024 / 1024:.1f} MB"
+    )
+
+    # Even a much larger window (1 hour, 1-second buckets = 3600 buckets)
+    # should still be tiny.
+    big_window = VelocityTracker(window_seconds=3600, bucket_seconds=1)
+    start_time = 1_000_000.0
+    tracemalloc.start()
+    for i in range(10_000):
+        big_window.record_event(
+            entity_id="account_1",
+            amount=10.0,
+            timestamp=start_time + (i * 0.001),
+        )
+    big_window_bytes, _ = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    print(f"Memory for a 1-hour window (3600 buckets): {big_window_bytes / 1024:>8,.1f} KB")
+
+    print("PASS: memory stayed flat and is far below 100 MB")
+
+
+if __name__ == "__main__":
+    main()

stream_velocity-0.1.0/tests/test_velocity.py

@@ -0,0 +1,96 @@
+import unittest
+import time
+from stream_velocity import VelocityTracker
+
+class TestVelocityTracker(unittest.TestCase):
+
+    def test_basic_aggregation(self):
+        tracker = VelocityTracker(window_seconds=60, bucket_seconds=1)
+        now = 1000.0
+
+        tracker.record_event(entity_id="acc_1", amount=50.0, timestamp=now)
+        tracker.record_event(entity_id="acc_1", amount=25.0, timestamp=now + 5)
+
+        metrics = tracker.get_velocity(entity_id="acc_1", timestamp=now + 10)
+
+        self.assertEqual(metrics.count, 2)
+        self.assertEqual(metrics.sum_amount, 75.0)
+
+    def test_window_expiration(self):
+        tracker = VelocityTracker(window_seconds=10, bucket_seconds=1)
+        now = 1000.0
+
+        tracker.record_event(entity_id="acc_2", amount=100.0, timestamp=now)
+
+        # Check inside window
+        metrics_before = tracker.get_velocity(entity_id="acc_2", timestamp=now + 5)
+        self.assertEqual(metrics_before.count, 1)
+
+        # Check outside window (15 seconds later)
+        metrics_after = tracker.get_velocity(entity_id="acc_2", timestamp=now + 15)
+        self.assertEqual(metrics_after.count, 0)
+
+    def test_out_of_order_events(self):
+        tracker = VelocityTracker(window_seconds=60, bucket_seconds=1)
+        now = 1000.0
+
+        tracker.record_event(entity_id="acc_3", amount=10.0, timestamp=now)
+        tracker.record_event(entity_id="acc_3", amount=10.0, timestamp=now + 10)
+
+        # Event arriving late with an older timestamp must not regress the window
+        tracker.record_event(entity_id="acc_3", amount=20.0, timestamp=now - 5)
+
+        metrics = tracker.get_velocity(entity_id="acc_3", timestamp=now + 20)
+        self.assertEqual(metrics.count, 3)
+        self.assertEqual(metrics.sum_amount, 40.0)
+
+    def test_many_bucket_window(self):
+        tracker = VelocityTracker(window_seconds=100000, bucket_seconds=1)
+        now = 1_000_000.0
+
+        tracker.record_event(entity_id="acc_4", amount=1.0, timestamp=now)
+        tracker.record_event(entity_id="acc_4", amount=1.0, timestamp=now + 50_000)
+
+        metrics = tracker.get_velocity(entity_id="acc_4", timestamp=now + 60_000)
+        self.assertEqual(metrics.count, 2)
+        self.assertEqual(metrics.sum_amount, 2.0)
+
+        # Event far outside the 100000s window must be expired
+        expired = tracker.get_velocity(entity_id="acc_4", timestamp=now + 200_000)
+        self.assertEqual(expired.count, 0)
+
+    def test_idle_entity_eviction(self):
+        tracker = VelocityTracker(
+            window_seconds=60,
+            bucket_seconds=1,
+            idle_timeout=10.0,
+            cleanup_interval=0.0,
+        )
+
+        tracker.record_event(entity_id="acc_a", amount=10.0, timestamp=1000.0)
+        self.assertIn("acc_a", tracker.entities)
+
+        # Advance time well beyond the idle timeout by recording another entity.
+        tracker.record_event(entity_id="acc_b", amount=5.0, timestamp=2000.0)
+
+        # acc_a has been idle for 1000s > idle_timeout, so it is evicted.
+        self.assertNotIn("acc_a", tracker.entities)
+        self.assertIn("acc_b", tracker.entities)
+
+        # Querying an evicted entity reports an empty window, not an error.
+        result = tracker.get_velocity(entity_id="acc_a", timestamp=2000.0)
+        self.assertEqual(result.count, 0)
+        self.assertEqual(result.sum_amount, 0.0)
+
+    def test_idle_timeout_disabled_by_default(self):
+        tracker = VelocityTracker(window_seconds=60, bucket_seconds=1)
+
+        tracker.record_event(entity_id="acc_c", amount=10.0, timestamp=1000.0)
+        tracker.record_event(entity_id="acc_d", amount=5.0, timestamp=1_000_000.0)
+
+        # With no idle_timeout, entities are never evicted.
+        self.assertIn("acc_c", tracker.entities)
+        self.assertIn("acc_d", tracker.entities)
+
+if __name__ == "__main__":
+    unittest.main()