predcache 0.1.0__tar.gz

predcache-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,86 @@
+# 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/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "predcache"
+version = "0.1.0"
+description = "Persistent timestamp-keyed prediction cache and batched inference runner for ML models"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Anton Uralskii", email = "uralskyanton@gmail.com" }]
+keywords = [
+    "cache",
+    "inference",
+    "batching",
+    "machine-learning",
+    "backtesting",
+    "time-series",
+    "mlops",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["numpy>=1.21"]
+
+[project.optional-dependencies]
+parquet = ["pandas>=1.5", "pyarrow>=10"]
+test = ["pytest>=7", "pandas>=1.5"]
+
+[project.urls]
+Homepage = "https://github.com/Geomanti/predcache"
+Repository = "https://github.com/Geomanti/predcache"
+Issues = "https://github.com/Geomanti/predcache/issues"
+Changelog = "https://github.com/Geomanti/predcache/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

predcache-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

predcache-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/predcache.egg-info/PKG-INFO

@@ -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/src/predcache.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/predcache/__init__.py
+src/predcache/batched.py
+src/predcache/cache.py
+src/predcache/windowing.py
+src/predcache.egg-info/PKG-INFO
+src/predcache.egg-info/SOURCES.txt
+src/predcache.egg-info/dependency_links.txt
+src/predcache.egg-info/requires.txt
+src/predcache.egg-info/top_level.txt
+tests/test_predcache.py

predcache-0.1.0/src/predcache.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

predcache-0.1.0/src/predcache.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy>=1.21
+
+[parquet]
+pandas>=1.5
+pyarrow>=10
+
+[test]
+pytest>=7
+pandas>=1.5

predcache-0.1.0/src/predcache.egg-info/top_level.txt

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

predcache-0.1.0/tests/test_predcache.py

@@ -0,0 +1,139 @@
+import numpy as np
+import pandas as pd
+import pytest
+
+from predcache import BatchedInferenceRunner, FeatureWindowAssembler, PredictionCache
+from predcache.batched import stack_features
+from predcache.windowing import normalize_absolute
+
+
+# ---------------------------------------------------------------------------
+# PredictionCache
+# ---------------------------------------------------------------------------
+
+def _fake_compute(keys):
+    return {k: f"pred:{k}" for k in keys}
+
+
+def test_cache_roundtrip(tmp_path):
+    p = str(tmp_path / "cache.pkl")
+    c = PredictionCache(p)
+    out = c.get_or_compute(["a", "b", "c"], _fake_compute)
+    assert out == {"a": "pred:a", "b": "pred:b", "c": "pred:c"}
+
+    # fresh instance reads persisted state
+    c2 = PredictionCache(p).load()
+    assert "a" in c2 and len(c2) == 3
+    assert c2.get("b") == "pred:b"
+
+
+def test_cache_computes_only_missing(tmp_path):
+    p = str(tmp_path / "cache.pkl")
+    c = PredictionCache(p)
+    calls = []
+
+    def tracking_compute(keys):
+        calls.append(list(keys))
+        return _fake_compute(keys)
+
+    c.get_or_compute(["a", "b"], tracking_compute)
+    c.get_or_compute(["a", "b", "c"], tracking_compute)
+    # second call must only ask for "c"
+    assert calls == [["a", "b"], ["c"]]
+
+
+def test_cache_atomic_save(tmp_path):
+    p = str(tmp_path / "cache.pkl")
+    c = PredictionCache(p)
+    c.get_or_compute(["k1"], _fake_compute)
+    # simulate leftover temp file — must not break loads
+    (tmp_path / "cache.pkl.abc123.tmp").write_bytes(b"garbage")
+    c2 = PredictionCache(p).load()
+    assert c2.get("k1") == "pred:k1"
+
+
+def test_cache_drop(tmp_path):
+    p = str(tmp_path / "cache.pkl")
+    c = PredictionCache(p)
+    c.get_or_compute(["x", "y"], _fake_compute)
+    assert c.drop(["x", "missing"]) == 1
+    assert "x" not in c
+
+
+def test_parquet_backend(tmp_path):
+    pytest.importorskip("pyarrow")
+    p = str(tmp_path / "cache.parquet")
+    c = PredictionCache(p, backend="parquet")
+    c.get_or_compute(["t1", "t2"], lambda ks: {k: [0.5, 1] for k in ks})
+    c2 = PredictionCache(p, backend="parquet").load()
+    assert c2.get("t1") == [0.5, 1]
+
+
+# ---------------------------------------------------------------------------
+# BatchedInferenceRunner
+# ---------------------------------------------------------------------------
+
+def test_runner_batches_and_scores():
+    features = np.arange(1200 * 3, dtype=np.float32).reshape(1200, 3)
+    seen = []
+
+    def scorer(s, e):
+        seen.append((s, e))
+        return features[s:e].sum(axis=1)
+
+    runner = BatchedInferenceRunner(len(features), scorer, batch_size=500)
+    preds = runner.run()
+    assert seen == [(0, 500), (500, 1000), (1000, 1200)]
+    assert len(preds) == 1200
+    # row 0 = 0+1+2 = 3; row 1199 sums the last 3 values of arange(3600)
+    assert np.isclose(float(preds[0]), 3.0)
+    assert np.isclose(float(preds[-1]), 3597.0 + 3598.0 + 3599.0)
+
+
+def test_runner_progress():
+    n = 1500
+    runner = BatchedInferenceRunner(n, lambda s, e: np.ones(e - s), batch_size=500, progress_every=1)
+    events = []
+    runner.run(progress_cb=events.append)
+    assert len(events) == 3
+    assert events[-1]["rows_done"] == n
+    assert runner.progress_log == events
+
+
+def test_stack_features():
+    m = stack_features([np.ones((2, 4)), np.zeros((3, 4))])
+    assert m.shape == (5, 4) and m.dtype == np.float32
+
+
+# ---------------------------------------------------------------------------
+# Windowing
+# ---------------------------------------------------------------------------
+
+def _ohlc(n=30):
+    return pd.DataFrame(
+        {
+            "time": pd.date_range("2026-01-01", periods=n, freq="min"),
+            "close": np.linspace(1.0, 2.0, n),
+            "high": np.linspace(1.1, 2.1, n),
+            "low": np.linspace(0.9, 1.9, n),
+        }
+    )
+
+
+def test_normalize_absolute():
+    v = np.array([2.0, -1.0, 0.0], dtype=np.float32)
+    out = normalize_absolute(v)
+    assert np.isclose(out[0], 1.0) and np.isclose(out[1], -0.5)
+    z = normalize_absolute(np.zeros(3))
+    assert (z == 0).all()
+
+
+def test_assembler_windows_and_keys():
+    df = _ohlc(30)
+    asm = FeatureWindowAssembler(window=5, warmup=10, row_fn=lambda w: [w["close"].iloc[0]])
+    X, keys = asm.build(df, key_col="time")
+    assert X.shape == (20, 1)
+    assert len(keys) == 20
+    assert keys[0] == df.iloc[10]["time"]
+    # most-recent-first: window's first row is the bar at index 10
+    assert np.isclose(X[0, 0], df.iloc[10]["close"])