stream-velocity 0.1.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+stream_velocity/__init__.py,sha256=pNlQAL9nTE_q3gcc_x5uspFsgGqz4--JKkP0vh4XWFw,190
+stream_velocity/ring_buffer.py,sha256=2LOuOSM_YE4EYK2vdX5Cr-7I7oyH5xanEk_vOaT8y7U,3631
+stream_velocity/tracker.py,sha256=vlyAdRL1s1fmdOHWi40a7OLynKaFmiuz33KzbLdyCis,3853
+stream_velocity-0.1.0.dist-info/METADATA,sha256=qEH5xC3yk13uJKPiX5wfnim1VJAHXL8CTRMgyzX-5pY,7908
+stream_velocity-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+stream_velocity-0.1.0.dist-info/licenses/LICENSE,sha256=Rz_5tPzKwMf6dsCSkzX0DyVVkYrnk_EA3vsASoCYflw,1069
+stream_velocity-0.1.0.dist-info/RECORD,,

stream_velocity-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stream_velocity-0.1.0.dist-info/licenses/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.