predcache 0.1.0__py3-none-any.whl

predcache/__init__.py

@@ -0,0 +1,14 @@
+"""predcache: persistent prediction caching and batched inference for ML models."""
+
+__version__ = "0.1.0"
+
+from .cache import PredictionCache, CacheEntry
+from .batched import BatchedInferenceRunner, InferenceFn
+from .windowing import FeatureWindowAssembler
+
+__all__ = [
+    "PredictionCache",
+    "CacheEntry",
+    "BatchedInferenceRunner",
+    "FeatureWindowAssembler",
+]

predcache/batched.py

@@ -0,0 +1,114 @@
+"""Batched inference runner.
+
+Wraps any model callable in batching + progress reporting, decoupling the
+*scoring* of a feature matrix from the *loop* that feeds it.  In the source
+production system this exact pattern (batch_size=500 across three Keras
+classifiers) turned hours-long full-range backtests into minutes by making
+the cost of inference independent of how many bars were requested.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence
+
+import numpy as np
+
+__all__ = ["BatchedInferenceRunner", "InferenceFn"]
+
+# A scorer takes (start, stop) and returns an array-like of predictions
+# for that slice.  Returning (n_samples, n_outputs) is typical.
+InferenceFn = Callable[[int, int], Any]
+
+DEFAULT_BATCH_SIZE = 500
+
+
+class BatchedInferenceRunner:
+    """Run a scorer over *n_samples* rows in fixed batches.
+
+    Parameters
+    ----------
+    n_samples
+        Total number of feature rows to score.
+    inference_fn
+        Callable ``(start, stop) -> array-like`` that scores rows
+        ``[start, stop)`` of the pre-built feature matrix.
+    batch_size
+        Rows per scoring call.  500 was tuned on the source system
+        (Keras predict overhead vs memory footprint); any positive int works.
+    progress_every
+        Emit a progress dict every *progress_every* batches via the
+        ``progress`` callback (or collect them in ``self.progress_log``).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> features = np.random.rand(1000, 35).astype(np.float32)
+    >>> runner = BatchedInferenceRunner(
+    ...     n_samples=len(features),
+    ...     inference_fn=lambda s, e: model.predict(features[s:e], verbose=0),
+    ...     batch_size=500,
+    ... )
+    >>> preds = runner.run()
+    """
+
+    def __init__(
+        self,
+        n_samples: int,
+        inference_fn: InferenceFn,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        progress_every: int = 20,
+    ):
+        if batch_size <= 0:
+            raise ValueError("batch_size must be positive")
+        self.n_samples = int(n_samples)
+        self.inference_fn = inference_fn
+        self.batch_size = int(batch_size)
+        self.progress_every = max(1, int(progress_every))
+        self.progress_log: List[Dict[str, Any]] = []
+
+    def batches(self) -> Iterator[tuple]:
+        start = 0
+        while start < self.n_samples:
+            stop = min(start + self.batch_size, self.n_samples)
+            yield start, stop
+            start = stop
+
+    def run(self, progress_cb: Optional[Callable[[Dict[str, Any]], None]] = None) -> List[Any]:
+        """Score all rows; returns a list of per-row predictions."""
+        out: List[Any] = []
+        t0 = time.perf_counter()
+        n_batches = 0
+        for start, stop in self.batches():
+            chunk = self.inference_fn(start, stop)
+            out.extend(_row_iter(chunk))
+            n_batches += 1
+            if progress_cb and n_batches % self.progress_every == 0:
+                cb = {
+                    "rows_done": stop,
+                    "rows_total": self.n_samples,
+                    "batches": n_batches,
+                    "elapsed_s": round(time.perf_counter() - t0, 3),
+                }
+                self.progress_log.append(cb)
+                progress_cb(cb)
+        return out
+
+
+def _row_iter(chunk: Any) -> Iterator[Any]:
+    arr = np.asarray(chunk)
+    if arr.ndim == 1:
+        for v in arr:
+            yield v.item() if hasattr(v, "item") else v
+    else:
+        for row in arr:
+            yield row
+
+
+def stack_features(matrices: Sequence[Any]) -> np.ndarray:
+    """Concatenate per-bar feature rows into one matrix (float32).
+
+    Utility used before calling a runner; keeps dtype consistent so
+    framework predict() calls do not re-copy the array.
+    """
+    return np.concatenate([np.asarray(m, dtype=np.float32) for m in matrices], axis=0)

predcache/cache.py

@@ -0,0 +1,220 @@
+"""Persistent, timestamp-keyed prediction cache.
+
+Extracted and generalized from a production trading system (Neuromomentum /
+ExtremePrediction) where full-range backtests over 100k+ bars were dominated
+by redundant neural-network inference.  Storing predictions keyed by bar
+timestamp (not row index) lets any sub-range be replayed without offset
+alignment and lets incremental backtests reuse everything previously computed.
+
+Design goals
+------------
+* **Correctness first** — atomic writes (temp file + os.replace), so a crash
+  mid-save never corrupts the cache.
+* **Backend-agnostic** — pickle (default) and parquet backends ship in the
+  box; register your own with :func:`register_backend`.
+* **Framework-agnostic** — works with any callable batch scorer (Keras,
+  PyTorch, ONNX, sklearn, plain numpy).
+"""
+
+from __future__ import annotations
+
+import os
+import pickle
+import tempfile
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Hashable, Iterable, List, Optional, Protocol
+
+__all__ = ["PredictionCache", "CacheEntry", "register_backend"]
+
+
+class _Backend(Protocol):
+    """A cache backend persists a mapping of keys to payloads."""
+
+    def dump(self, entries: Dict[Hashable, Any], path: str) -> None: ...
+
+    def load(self, path: str) -> Dict[Hashable, Any]: ...
+
+
+# ---------------------------------------------------------------------------
+# Built-in backends
+# ---------------------------------------------------------------------------
+
+def _pickle_dump(entries: Dict[Hashable, Any], path: str) -> None:
+    with open(path, "wb") as f:
+        pickle.dump(entries, f, protocol=pickle.HIGHEST_PROTOCOL)
+
+
+def _pickle_load(path: str) -> Dict[Hashable, Any]:
+    with open(path, "rb") as f:
+        data = pickle.load(f)
+    return data if isinstance(data, dict) else {}
+
+
+def _parquet_dump(entries: Dict[Hashable, Any], path: str) -> None:
+    import pandas as pd  # optional dependency
+
+    keys = list(entries.keys())
+    df = pd.DataFrame({"key": keys, "value": [entries[k] for k in keys]})
+    df.to_parquet(path)
+
+
+def _parquet_load(path: str) -> Dict[Hashable, Any]:
+    import pandas as pd  # optional dependency
+
+    df = pd.read_parquet(path)
+    return dict(zip(df["key"], df["value"]))
+
+
+_BACKENDS: Dict[str, _Backend] = {
+    "pickle": (_pickle_dump, _pickle_load),
+    "parquet": (_parquet_dump, _parquet_load),
+}
+
+
+def register_backend(name: str, dump: Callable, load: Callable) -> None:
+    """Register a custom cache backend (dump/load callables)."""
+    _BACKENDS[name] = (dump, load)
+
+
+@dataclass(frozen=True)
+class CacheEntry:
+    """One cached prediction, keyed by a timestamp or other hashable."""
+
+    key: Hashable
+    value: Any
+    meta: Dict[str, Any] = None  # type: ignore[assignment]
+
+    def __post_init__(self):
+        if self.meta is None:
+            object.__setattr__(self, "meta", {})
+
+
+class PredictionCache:
+    """Persistent cache for model predictions keyed by bar timestamp.
+
+    Parameters
+    ----------
+    path
+        File path of the cache file.  Created on first save.
+    backend
+        ``"pickle"`` (default, zero-dependency) or ``"parquet"``
+        (requires ``pyarrow``; compact for numeric payloads).
+    safe_save
+        Write via a temp file + :func:`os.replace` so a crash never
+        corrupts an existing cache.  Default ``True``.
+
+    Notes
+    -----
+    Keys should be timestamps or any other stable hashable identity —
+    *not* row indices.  Index keys silently break when a frame is sliced
+    or resampled; timestamp keys survive any sub-range extraction.
+
+    Examples
+    --------
+    >>> from predcache import PredictionCache
+    >>> cache = PredictionCache("preds.pkl")
+    >>> cache.get_or_compute(
+    ...     keys=["2026-01-02 10:00", "2026-01-02 10:01"],
+    ...     compute_fn=lambda missing: {k: float(k[-4:]) for k in missing},
+    ... )
+    {'2026-01-02 10:01': 10.01, '2026-01-02 10:01': 10.01}
+    """
+
+    def __init__(self, path: str, backend: str = "pickle"):
+        self.path = path
+        if backend not in _BACKENDS:
+            raise ValueError(
+                f"Unknown backend {backend!r}. Registered: {sorted(_BACKENDS)}"
+            )
+        self._dump, self._load = _BACKENDS[backend]
+        self._entries: Dict[Hashable, Any] = {}
+        self._dirty = False
+
+    # -- I/O -----------------------------------------------------------------
+
+    def load(self) -> "PredictionCache":
+        if os.path.exists(self.path):
+            self._entries = self._load(self.path)
+        return self
+
+    def save(self) -> None:
+        if not self._dirty:
+            return
+        directory = os.path.dirname(self.path)
+        if directory:
+            os.makedirs(directory, exist_ok=True)
+        if self.path.endswith(".tmp"):
+            self._dump(self._entries, self.path)
+        else:
+            fd, tmp = tempfile.mkstemp(
+                dir=directory or ".", prefix=os.path.basename(self.path), suffix=".tmp"
+            )
+            os.close(fd)
+            try:
+                self._dump(self._entries, tmp)
+                os.replace(tmp, self.path)
+            finally:
+                if os.path.exists(tmp):
+                    os.remove(tmp)
+        self._dirty = False
+
+    # -- lookup / mutation -----------------------------------------------------
+
+    def __contains__(self, key: Hashable) -> bool:
+        return key in self._entries
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def get(self, key: Hashable, default: Any = None) -> Any:
+        return self._entries.get(key, default)
+
+    def put(self, key: Hashable, value: Any) -> None:
+        self._entries[key] = value
+        self._dirty = True
+
+    def keys(self) -> Iterable[Hashable]:
+        return self._entries.keys()
+
+    def items(self) -> Iterable[tuple]:
+        return self._entries.items()
+
+    def info(self) -> Dict[str, Any]:
+        return {
+            "path": self.path,
+            "entries": len(self._entries),
+            "backend": "pickle" if self.path.endswith(".pkl") else "auto",
+        }
+
+    # -- the core convenience ---------------------------------------------------
+
+    def get_or_compute(
+        self,
+        keys: List[Hashable],
+        compute_fn: Callable[[List[Hashable]], Dict[Hashable, Any]],
+        save: bool = True,
+    ) -> Dict[Hashable, Any]:
+        """Return predictions for *keys*, computing only the missing ones.
+
+        ``compute_fn`` receives the list of missing keys and must return a
+        dict ``{key: value}``.  Computed values are merged into the cache.
+        """
+        missing = [k for k in keys if k not in self._entries]
+        if missing:
+            computed = compute_fn(missing) or {}
+            for k, v in computed.items():
+                self._entries[k] = v
+            self._dirty = True
+            if save:
+                self.save()
+        return {k: self._entries[k] for k in keys if k in self._entries}
+
+    def drop(self, keys: List[Hashable]) -> int:
+        removed = 0
+        for k in keys:
+            if k in self._entries:
+                del self._entries[k]
+                removed += 1
+        if removed:
+            self._dirty = True
+        return removed

predcache/windowing.py

@@ -0,0 +1,90 @@
+"""Feature-window assembly helpers.
+
+Generalizes the windowing pattern from the source trading system: for each
+bar at index *i*, build a feature vector from a look-back window ending at
+*i*, optionally reversed (most-recent-first, the convention used when the
+models were trained on MT5 series ordering), then normalize.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, List, Optional, Sequence
+
+import numpy as np
+
+__all__ = ["normalize_absolute", "FeatureWindowAssembler"]
+
+
+def normalize_absolute(vec: np.ndarray) -> np.ndarray:
+    """Scale a vector so every element lies in [-1, 1] (L-inf normalization).
+
+    Matches the source system's ``normalize_vector_absolute``: divide by the
+    max absolute value, preserving sign and zeros.  Returns the input
+    unchanged when its max abs value is 0.
+    """
+    vec = np.asarray(vec, dtype=np.float32)
+    scale = np.max(np.abs(vec))
+    if scale == 0:
+        return vec
+    return vec / scale
+
+
+class FeatureWindowAssembler:
+    """Build look-back feature windows from an OHLC frame.
+
+    Parameters
+    ----------
+    window
+        Look-back length in bars (``bars_to_fetch`` in the source system).
+    warmup
+        Number of initial bars to skip before emitting windows.
+    row_fn
+        Callable ``(window_df) -> 1-D array`` producing the feature vector
+        for one window.  Receives the reversed (most-recent-first) window
+        slice.  This keeps domain feature logic (fractal detection, price
+        deltas, external regressors) in *your* code — the assembler only
+        handles looping, warmup and stacking.
+
+    Examples
+    --------
+    >>> assembler = FeatureWindowAssembler(window=50, warmup=10, row_fn=my_features)
+    >>> X = assembler.build(df)          # (n_bars - warmup, n_features)
+    >>> keys = assembler.keys(df)        # matching timestamp keys
+    """
+
+    def __init__(
+        self,
+        window: int,
+        warmup: int = 0,
+        row_fn: Optional[Callable] = None,
+    ):
+        if window <= 0:
+            raise ValueError("window must be positive")
+        if warmup < 0:
+            raise ValueError("warmup must be >= 0")
+        self.window = int(window)
+        self.warmup = int(warmup)
+        self.row_fn = row_fn
+
+    def windows(self, df) -> List:
+        """Yield reversed (most-recent-first) window slices starting at warmup."""
+        n = len(df)
+        for i in range(self.warmup, n):
+            lo = max(0, i - (self.window - 1))
+            yield df.iloc[lo : i + 1].iloc[::-1].reset_index(drop=True)
+
+    def keys(self, df, key_col: str = "time") -> List:
+        """Timestamp keys for each window (stable identity for caching)."""
+        return [df.iloc[i][key_col] for i in range(self.warmup, len(df))]
+
+    def build(self, df, key_col: Optional[str] = None):
+        """Stack feature rows for every window; returns (X, keys)."""
+        if self.row_fn is None:
+            raise ValueError("row_fn is required to build features")
+        rows: List[np.ndarray] = []
+        for win in self.windows(df):
+            rows.append(np.asarray(self.row_fn(win), dtype=np.float32))
+        if not rows:
+            return np.zeros((0, 0), dtype=np.float32), []
+        keys = self.keys(df, key_col) if key_col else self.keys(df)
+        return np.stack(rows, axis=0), keys

predcache-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: predcache
+Version: 0.1.0
+Summary: Persistent timestamp-keyed prediction cache and batched inference runner for ML models
+Author-email: Anton Uralskii <uralskyanton@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Geomanti/predcache
+Project-URL: Repository, https://github.com/Geomanti/predcache
+Project-URL: Issues, https://github.com/Geomanti/predcache/issues
+Project-URL: Changelog, https://github.com/Geomanti/predcache/blob/main/CHANGELOG.md
+Keywords: cache,inference,batching,machine-learning,backtesting,time-series,mlops
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Provides-Extra: parquet
+Requires-Dist: pandas>=1.5; extra == "parquet"
+Requires-Dist: pyarrow>=10; extra == "parquet"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pandas>=1.5; extra == "test"
+Dynamic: license-file
+
+# predcache
+
+**Persistent timestamp-keyed prediction cache and batched inference runner for ML models.**
+
+Extracted and generalized from a production neural-network trading system where
+full-range backtests over 100,000+ bars were dominated by redundant model
+inference. Storing predictions keyed by **bar timestamp** (not row index) makes
+any sub-range replayable without offset alignment — and makes incremental
+backtests reuse everything previously computed. The result: full-range runs
+went from **hours to minutes**.
+
+## Why
+
+Typical ML backtesting pipelines recompute model inference for the same bars on
+every run — every parameter sweep, every range extension, every "what if".
+`predcache` decouples the two expensive parts:
+
+1. **Feature-window assembly** — building look-back feature rows from an OHLC
+   frame (most-recent-first, warmup-aware), with your domain logic plugged in
+   via `row_fn`.
+2. **Batched inference** — scoring rows through *any* model callable
+   (Keras, PyTorch, ONNX, sklearn) in fixed batches with progress reporting.
+3. **Persistent caching** — predictions keyed by timestamp, saved atomically,
+   so the next run computes only what's missing.
+
+## Install
+
+```bash
+pip install predcache              # core (numpy only)
+pip install predcache[parquet]     # + parquet backend
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from predcache import PredictionCache, BatchedInferenceRunner, FeatureWindowAssembler
+
+# 1. Assemble feature windows (your domain logic stays in row_fn)
+assembler = FeatureWindowAssembler(
+    window=50, warmup=500,
+    row_fn=lambda win: my_feature_logic(win),   # 1-D feature vector per window
+)
+X, keys = assembler.build(df, key_col="time")   # X: (n_bars - warmup, n_features)
+
+# 2. Batched inference through any model
+runner = BatchedInferenceRunner(
+    n_samples=len(X),
+    inference_fn=lambda s, e: model.predict(X[s:e], verbose=0),
+    batch_size=500,
+)
+preds = runner.run()
+
+# 3. Cache by timestamp — next run computes only missing bars
+cache = PredictionCache("predictions.pkl")
+out = cache.get_or_compute(
+    keys=keys,
+    compute_fn=lambda missing: predict_bars(X, keys, missing),
+)
+```
+
+## Features
+
+- **Timestamp-keyed cache** — sub-range extraction without offset alignment;
+  row-index caches silently break on slicing/resampling, timestamp keys don't.
+- **Atomic saves** — temp file + `os.replace`; a crash mid-save never corrupts
+  an existing cache.
+- **Pluggable backends** — pickle (zero-dependency) and parquet ship in the
+  box; register custom backends with `register_backend(name, dump, load)`.
+- **Batched inference runner** — framework-agnostic `(start, stop) -> scores`
+  contract, progress callbacks, tuned default batch size (500).
+- **L-inf normalization** helper matching the source system's
+  `normalize_vector_absolute`.
+
+## Origin
+
+This package is the generalized core of the prediction-serving layer of
+[Neuromomentum](https://github.com/Geomanti)'s production trading system
+(three Keras classifiers, MT5 live execution, 2012–2026 backtest range). The
+original cache manager was 542 lines of domain-specific code; what ships here
+is the reusable pattern: timestamp-keyed persistence, compute-only-missing,
+batched scoring, windowed feature assembly.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

predcache-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+predcache/__init__.py,sha256=6ygXlSDqtYnwfE9FjwR2RHJ1FtDW1mG_l7LPxJT6MCI,373
+predcache/batched.py,sha256=9KX2oMEzjsN-WPPLydEGiV2IzR7SKKPkGn1iX4IFwww,3907
+predcache/cache.py,sha256=RHsHZM8h7fpbxsFPXrzxKNgXjv61MlfMpmuW1und224,7223
+predcache/windowing.py,sha256=f6VNt8EIOeXY4teukUQlXyZUwzBXZtCtirs8H4UUFfA,3314
+predcache-0.1.0.dist-info/licenses/LICENSE,sha256=IImUGSfeYtg7nXjxl9JJUnofX8XsYfeOWThilV4cHn8,1070
+predcache-0.1.0.dist-info/METADATA,sha256=omrs49Tw7afub0EdOcvLDe9mBKRwyLDW01vuntPDcls,4883
+predcache-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+predcache-0.1.0.dist-info/top_level.txt,sha256=zu1kFhCpeR0jg0dWN4SsytadJ0ZCkiPsB8bJiQOBe8Q,10
+predcache-0.1.0.dist-info/RECORD,,

predcache-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

predcache-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Uralskii
+
+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.

predcache-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+predcache