pymc-cache 0.1.0__tar.gz

pymc_cache-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.extraction-source/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.pytest_cache/
+dist/
+build/
+_site/
+.quarto/
+/reference/
+/objects.json
+.pymc-cache/
+*.nc
+.pi/
+
+/.quarto/
+**/*.quarto_ipynb

pymc_cache-0.1.0/AGENTS.md

@@ -0,0 +1,3 @@
+# Repository guidance
+
+This repository owns cache identity, storage, and policy only. It must not depend on cloudposterior, pymc-monitor or Modal. Keep `.extraction-source/` temporary, ignored and out of all artifacts. Follow `CONTRIBUTING.md`; preserve old external cache data. Never silently reuse an entry when a model or sampler cannot be identified safely.

pymc_cache-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Extract independent PyMC model-aware sampling cache from cloudposterior.
+- Add versioned, fail-closed graph and call identity; bounded memory and atomic NetCDF disk backends.
+- Add a preflight session API, safe disk-management CLI, and PyMC 5/6 and ArviZ 0/1 support.
+- Encode nutpie divergence messages losslessly; support nullable diagnostic warning text and floating NaN without dropping data.
+- Pre-release identity and disk schema 3 invalidate schema-1/2 entries; old files are misses, left untouched and never overwritten. Existing caches must be sampled again.
+
+Old cloudposterior keys are deliberately not trusted or imported; old files are not deleted.

pymc_cache-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Install [uv](https://docs.astral.sh/uv/) and Quarto. Run `bash scripts/lock.sh`, `uv run --frozen pytest -q --cov=pymc_cache --cov-fail-under=85`, `uv run --frozen ruff check src tests scripts examples`, `bash scripts/build-docs.sh`, `uv build --no-sources`, and `uv run --frozen python scripts/check_artifact.py`. `scripts/lock.sh` checks the lock without user configuration before a frozen run; update the lock intentionally with `uv lock --no-config` when dependencies change. Test both supported PyMC/ArviZ majors before proposing a release. Make one conventional commit per logical change; discuss new cache formats and identity semantics before changing them. Do not check in posterior data.

pymc_cache-0.1.0/LICENSE

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

pymc_cache-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: pymc-cache
+Version: 0.1.0
+Summary: Safe, model-aware caching of PyMC sampling results
+Project-URL: Homepage, https://github.com/justmytwospence/pymc-cache
+Project-URL: Documentation, https://justmytwospence.github.io/pymc-cache/
+Project-URL: Repository, https://github.com/justmytwospence/pymc-cache
+Project-URL: Issues, https://github.com/justmytwospence/pymc-cache/issues
+Author: Spencer Boucher
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bayesian,cache,inferencedata,mcmc,pymc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: arviz<2,>=0.17
+Requires-Dist: h5netcdf>=1.3
+Requires-Dist: h5py>=3.10
+Requires-Dist: numpy>=1.25
+Requires-Dist: pymc<7,>=5.28
+Requires-Dist: pytensor>=2.38
+Requires-Dist: xarray>=2023.1
+Description-Content-Type: text/markdown
+
+# pymc-cache
+
+Safe, model-aware caching of native PyMC sampling results. Python 3.11+, PyMC 5.28–6 and ArviZ 0.x–1.x. No cloud account, monitoring service or Modal dependency.
+
+```bash
+pip install 'pymc-cache @ git+https://github.com/justmytwospence/pymc-cache.git@<commit-sha>'
+```
+
+```python
+import pymc as pm
+import pymc_cache as pc
+
+with pm.Model() as model:
+    mu = pm.Normal("mu", 0, 1)
+    options = dict(draws=10, tune=10, chains=1, cores=1, random_seed=42,
+                   progressbar=False, model=model, cache="disk")
+    trace = pc.sample(**options)
+    # The next call loads the result from .pymc-cache/ without sampling:
+    again = pc.sample(**options)
+```
+
+`pc.sample_smc(model=model, draws=100, cache="disk")` uses the native SMC sampler with an independent key. `cache=True` (default) uses an 8-entry in-memory LRU. `cache=False` runs the native sampler without hashing the model. Pass a directory/Path for a custom disk location; `overwrite=True` skips reads and atomically replaces an existing entry. Both backends copy results on read; memory copies on write too. Disk files are one NetCDF file per full SHA-256 key, with the key embedded in its metadata. Corruption is treated as a miss. `pc.cleanup_cache()` removes only entries owned by this package; `pymc-cache list|prune|clear --dir PATH` inspects/manages the same entries without following symlinks.
+
+## Preflight and integrations
+
+```python
+session = pc.CacheSession(cache="disk", model=model)
+lookup = session.lookup({"draws": 10, "tune": 10, "chains": 1,
+                         "cores": 1, "random_seed": 42, "progressbar": False})
+if lookup.hit:
+    trace = lookup.result
+else:
+    trace = pm.sample(model=model, **lookup.normalized_kwargs)
+    session.store(lookup, trace, status="complete")
+```
+
+A runner used with `pc.sample(..., sample_fn=runner)` must implement `runner.__pymc_cache_normalize__(model, call_kwargs)` and return **exactly** `call_kwargs`, `key_kwargs`, `sampler_identity`, and `versions`. The call arguments passed to the runner and the canonical key arguments must be explicit. The runner returns an inference result; only complete results, or adaptive results with an attested `met` convergence report, are stored. Stopped, futile, capped and incomplete results are returned but never stored. Cache identity includes the complete model graph, constants, mutable shared data, deterministics, coordinates, sampling kwargs, RNG states, operation, sampler and software versions. Unknown/custom Ops fail closed rather than risk a wrong hit. Unsafe steps/callbacks/callables require an explicit `sampler_key` identifying their implementation and configuration; the caller is responsible for changing this key when the callable changes. No code is executed from cache metadata.
+
+Caching may hold sensitive posterior data. Treat `.pymc-cache/` as private, and use `cache=False` for confidential models when persistent data is not allowed. Cache files are not authenticated against a malicious writer; do not use a shared untrusted directory.
+
+See [getting started](getting-started.qmd), [caching walkthrough](guides/walkthrough.qmd), [identity guide](guides/identity.qmd), [storage guide](guides/storage.qmd), [monitor composition](guides/monitor.qmd), [legacy migration](guides/migration.qmd), [troubleshooting](guides/troubleshooting.qmd), [runnable examples](examples/basic.py), and [API reference](reference.qmd). This package does not patch `pm.sample`, intercept model contexts, cache posterior predictive calls or provide cloud execution.

pymc_cache-0.1.0/README.md

@@ -0,0 +1,41 @@
+# pymc-cache
+
+Safe, model-aware caching of native PyMC sampling results. Python 3.11+, PyMC 5.28–6 and ArviZ 0.x–1.x. No cloud account, monitoring service or Modal dependency.
+
+```bash
+pip install 'pymc-cache @ git+https://github.com/justmytwospence/pymc-cache.git@<commit-sha>'
+```
+
+```python
+import pymc as pm
+import pymc_cache as pc
+
+with pm.Model() as model:
+    mu = pm.Normal("mu", 0, 1)
+    options = dict(draws=10, tune=10, chains=1, cores=1, random_seed=42,
+                   progressbar=False, model=model, cache="disk")
+    trace = pc.sample(**options)
+    # The next call loads the result from .pymc-cache/ without sampling:
+    again = pc.sample(**options)
+```
+
+`pc.sample_smc(model=model, draws=100, cache="disk")` uses the native SMC sampler with an independent key. `cache=True` (default) uses an 8-entry in-memory LRU. `cache=False` runs the native sampler without hashing the model. Pass a directory/Path for a custom disk location; `overwrite=True` skips reads and atomically replaces an existing entry. Both backends copy results on read; memory copies on write too. Disk files are one NetCDF file per full SHA-256 key, with the key embedded in its metadata. Corruption is treated as a miss. `pc.cleanup_cache()` removes only entries owned by this package; `pymc-cache list|prune|clear --dir PATH` inspects/manages the same entries without following symlinks.
+
+## Preflight and integrations
+
+```python
+session = pc.CacheSession(cache="disk", model=model)
+lookup = session.lookup({"draws": 10, "tune": 10, "chains": 1,
+                         "cores": 1, "random_seed": 42, "progressbar": False})
+if lookup.hit:
+    trace = lookup.result
+else:
+    trace = pm.sample(model=model, **lookup.normalized_kwargs)
+    session.store(lookup, trace, status="complete")
+```
+
+A runner used with `pc.sample(..., sample_fn=runner)` must implement `runner.__pymc_cache_normalize__(model, call_kwargs)` and return **exactly** `call_kwargs`, `key_kwargs`, `sampler_identity`, and `versions`. The call arguments passed to the runner and the canonical key arguments must be explicit. The runner returns an inference result; only complete results, or adaptive results with an attested `met` convergence report, are stored. Stopped, futile, capped and incomplete results are returned but never stored. Cache identity includes the complete model graph, constants, mutable shared data, deterministics, coordinates, sampling kwargs, RNG states, operation, sampler and software versions. Unknown/custom Ops fail closed rather than risk a wrong hit. Unsafe steps/callbacks/callables require an explicit `sampler_key` identifying their implementation and configuration; the caller is responsible for changing this key when the callable changes. No code is executed from cache metadata.
+
+Caching may hold sensitive posterior data. Treat `.pymc-cache/` as private, and use `cache=False` for confidential models when persistent data is not allowed. Cache files are not authenticated against a malicious writer; do not use a shared untrusted directory.
+
+See [getting started](getting-started.qmd), [caching walkthrough](guides/walkthrough.qmd), [identity guide](guides/identity.qmd), [storage guide](guides/storage.qmd), [monitor composition](guides/monitor.qmd), [legacy migration](guides/migration.qmd), [troubleshooting](guides/troubleshooting.qmd), [runnable examples](examples/basic.py), and [API reference](reference.qmd). This package does not patch `pm.sample`, intercept model contexts, cache posterior predictive calls or provide cloud execution.

pymc_cache-0.1.0/SECURITY.md

@@ -0,0 +1,3 @@
+# Security
+
+Cache files contain model outputs and potentially sensitive observed data. Store them in private directories, restrict filesystem permissions, and do not point this package at an untrusted shared cache. A full SHA-256 key is an accidental-collision/identity guard, **not** a cryptographic authenticity check against a malicious writer. Unsupported custom PyTensor Ops require a caller-maintained `model_key`; unsupported sampler steps and callables require a caller-maintained `sampler_key`. Changing their behavior without changing those keys is unsafe. Report vulnerabilities privately through GitHub's private vulnerability reporting. Do not attach real model data or credentials.

pymc_cache-0.1.0/_quarto.yml

@@ -0,0 +1,51 @@
+project:
+  type: website
+  output-dir: _site
+  render:
+    - index.qmd
+    - getting-started.qmd
+    - guides/*.qmd
+    - reference.qmd
+    - api/*.qmd
+    - contributing.qmd
+    - releasing.qmd
+website:
+  title: pymc-cache
+  site-url: https://justmytwospence.github.io/pymc-cache/
+  repo-url: https://github.com/justmytwospence/pymc-cache
+  navbar:
+    left:
+      - href: getting-started.qmd
+        text: Get started
+      - href: guides/identity.qmd
+        text: Identity and safety
+      - href: guides/storage.qmd
+        text: Storage
+      - href: reference.qmd
+        text: API
+quartodoc:
+  package: pymc_cache
+  dir: api
+  sections:
+    - title: Public API
+      contents:
+        - sample
+        - sample_smc
+        - CacheBackend
+        - MemoryCache
+        - DiskCache
+        - CacheSession
+        - CachePolicy
+        - CacheEntry
+        - CacheLookup
+        - UncacheableError
+        - CacheWarning
+        - cleanup_cache
+        - model_digest
+        - cache_key
+format:
+  html:
+    theme: cosmo
+    toc: true
+execute:
+  enabled: false

pymc_cache-0.1.0/api/CacheBackend.qmd

@@ -0,0 +1,7 @@
+# CacheBackend { #pymc_cache.CacheBackend }
+
+```python
+CacheBackend()
+```
+
+Minimal backend interface; extra management operations are optional.

pymc_cache-0.1.0/api/CacheEntry.qmd

@@ -0,0 +1,16 @@
+# CacheEntry { #pymc_cache.CacheEntry }
+
+```python
+CacheEntry(
+    key,
+    model_slug,
+    operation,
+    created_at,
+    size_bytes,
+    status,
+    path,
+    software_versions,
+)
+```
+
+Metadata for an owned, valid disk entry (without loading posterior arrays).

pymc_cache-0.1.0/api/CacheLookup.qmd

@@ -0,0 +1,21 @@
+# CacheLookup { #pymc_cache.CacheLookup }
+
+```python
+CacheLookup(
+    backend,
+    key,
+    hit,
+    result,
+    normalized_kwargs,
+    disable_reason,
+    operation,
+    versions,
+    sampler_identity,
+    pre_run_model_digest,
+)
+```
+
+Immutable record of a pre-sampling cache lookup.
+
+``result`` is non-None only for a hit; ``key`` is usable by a later store.
+``normalized_kwargs`` is a snapshot, including pre-sampling RNG state.

pymc_cache-0.1.0/api/CachePolicy.qmd

@@ -0,0 +1,7 @@
+# CachePolicy { #pymc_cache.CachePolicy }
+
+```python
+CachePolicy(reuse_unseeded=True)
+```
+
+Select whether unseeded sampling may reuse a previous run.

pymc_cache-0.1.0/api/CacheSession.qmd

@@ -0,0 +1,51 @@
+# CacheSession { #pymc_cache.CacheSession }
+
+```python
+CacheSession(
+    cache=True,
+    *,
+    model=None,
+    policy=None,
+    namespace='',
+    model_key=None,
+    sampler_key=None,
+)
+```
+
+Compute identity and check a cache before beginning costly sampling.
+
+Reuse the returned CacheLookup with :meth:`store` after sampling completes.
+This API lets a remote caller avoid provisioning a container on a hit.
+
+## Methods
+
+| Name | Description |
+| --- | --- |
+| [lookup](#pymc_cache.CacheSession.lookup) | Return a hit, a storable miss, or a safe uncacheable miss. |
+| [store](#pymc_cache.CacheSession.store) | Publish only if graph and result still match the preflight identity. |
+
+### lookup { #pymc_cache.CacheSession.lookup }
+
+```python
+CacheSession.lookup(
+    sample_kwargs,
+    *,
+    operation='sample',
+    overwrite=False,
+    versions=None,
+    sampler_identity=None,
+)
+```
+
+Return a hit, a storable miss, or a safe uncacheable miss.
+
+### store { #pymc_cache.CacheSession.store }
+
+```python
+CacheSession.store(lookup, idata, *, status='complete', effective_sampler=None)
+```
+
+Publish only if graph and result still match the preflight identity.
+
+A reported sampler fallback is not stored under the preflight key; callers
+must preflight a new identity if they want to cache that result.

pymc_cache-0.1.0/api/CacheWarning.qmd

@@ -0,0 +1,7 @@
+# CacheWarning { #pymc_cache.CacheWarning }
+
+```python
+CacheWarning()
+```
+
+A cache was bypassed or an entry could not be persisted.

pymc_cache-0.1.0/api/DiskCache.qmd

@@ -0,0 +1,52 @@
+# DiskCache { #pymc_cache.DiskCache }
+
+```python
+DiskCache(base_dir=None, model=None, *, max_entries_per_model=20)
+```
+
+One-file, full-key-verified atomic NetCDF result cache.
+
+Entries live at ``<root>/<model>/<parameters>-<full-sha256>.nc``. Contents
+have an independently checked full key and schema; legacy files are never
+reused. The directory is a trusted local cache, not an untrusted file reader.
+
+## Methods
+
+| Name | Description |
+| --- | --- |
+| [clear](#pymc_cache.DiskCache.clear) | Delete only format-owned entries, preserving other files. |
+| [delete](#pymc_cache.DiskCache.delete) | Remove matching owned entries, never arbitrary files or symlinks. |
+| [entries](#pymc_cache.DiskCache.entries) | List this format's entries without materializing posterior data. |
+| [prune](#pymc_cache.DiskCache.prune) | Keep the N newest entries per model; return count removed. |
+
+### clear { #pymc_cache.DiskCache.clear }
+
+```python
+DiskCache.clear()
+```
+
+Delete only format-owned entries, preserving other files.
+
+### delete { #pymc_cache.DiskCache.delete }
+
+```python
+DiskCache.delete(key)
+```
+
+Remove matching owned entries, never arbitrary files or symlinks.
+
+### entries { #pymc_cache.DiskCache.entries }
+
+```python
+DiskCache.entries()
+```
+
+List this format's entries without materializing posterior data.
+
+### prune { #pymc_cache.DiskCache.prune }
+
+```python
+DiskCache.prune(keep=None)
+```
+
+Keep the N newest entries per model; return count removed.

pymc_cache-0.1.0/api/MemoryCache.qmd

@@ -0,0 +1,21 @@
+# MemoryCache { #pymc_cache.MemoryCache }
+
+```python
+MemoryCache(max_entries=8)
+```
+
+Thread-safe, copy-isolated LRU of posterior results.
+
+## Methods
+
+| Name | Description |
+| --- | --- |
+| [clear](#pymc_cache.MemoryCache.clear) | Discard stored entries and return the number removed. |
+
+### clear { #pymc_cache.MemoryCache.clear }
+
+```python
+MemoryCache.clear()
+```
+
+Discard stored entries and return the number removed.

pymc_cache-0.1.0/api/UncacheableError.qmd

@@ -0,0 +1,7 @@
+# UncacheableError { #pymc_cache.UncacheableError }
+
+```python
+UncacheableError()
+```
+
+Raised when the identity of a model or sampling option cannot be established.

pymc_cache-0.1.0/api/cache_key.qmd

@@ -0,0 +1,15 @@
+# cache_key { #pymc_cache.cache_key }
+
+```python
+cache_key(
+    model_identity,
+    sample_kwargs,
+    *,
+    operation='sample',
+    versions=None,
+    namespace='',
+    sampler_key=None,
+)
+```
+
+Full SHA-256 identity of a model, sampler settings and environment.

pymc_cache-0.1.0/api/cleanup_cache.qmd

@@ -0,0 +1,7 @@
+# cleanup_cache { #pymc_cache.cleanup_cache }
+
+```python
+cleanup_cache(base_dir=None)
+```
+
+Remove only new-format entries in a directory; do not delete the root.

pymc_cache-0.1.0/api/index.qmd

@@ -0,0 +1,20 @@
+# Function reference {.doc .doc-index}
+
+## Public API
+
+| | |
+| --- | --- |
+| [sample](sample.qmd#pymc_cache.sample) | Run ``pm.sample`` (or a trusted runner), reusing a matching result. |
+| [sample_smc](sample_smc.qmd#pymc_cache.sample_smc) | Run and cache ``pm.sample_smc`` without conflating it with NUTS. |
+| [CacheBackend](CacheBackend.qmd#pymc_cache.CacheBackend) | Minimal backend interface; extra management operations are optional. |
+| [MemoryCache](MemoryCache.qmd#pymc_cache.MemoryCache) | Thread-safe, copy-isolated LRU of posterior results. |
+| [DiskCache](DiskCache.qmd#pymc_cache.DiskCache) | One-file, full-key-verified atomic NetCDF result cache. |
+| [CacheSession](CacheSession.qmd#pymc_cache.CacheSession) | Compute identity and check a cache before beginning costly sampling. |
+| [CachePolicy](CachePolicy.qmd#pymc_cache.CachePolicy) | Select whether unseeded sampling may reuse a previous run. |
+| [CacheEntry](CacheEntry.qmd#pymc_cache.CacheEntry) | Metadata for an owned, valid disk entry (without loading posterior arrays). |
+| [CacheLookup](CacheLookup.qmd#pymc_cache.CacheLookup) | Immutable record of a pre-sampling cache lookup. |
+| [UncacheableError](UncacheableError.qmd#pymc_cache.UncacheableError) | Raised when the identity of a model or sampling option cannot be established. |
+| [CacheWarning](CacheWarning.qmd#pymc_cache.CacheWarning) | A cache was bypassed or an entry could not be persisted. |
+| [cleanup_cache](cleanup_cache.qmd#pymc_cache.cleanup_cache) | Remove only new-format entries in a directory; do not delete the root. |
+| [model_digest](model_digest.qmd#pymc_cache.model_digest) | Content hash of model graph, data, outputs and coordinates. |
+| [cache_key](cache_key.qmd#pymc_cache.cache_key) | Full SHA-256 identity of a model, sampler settings and environment. |

pymc_cache-0.1.0/api/model_digest.qmd

@@ -0,0 +1,10 @@
+# model_digest { #pymc_cache.model_digest }
+
+```python
+model_digest(model, *, model_key=None)
+```
+
+Content hash of model graph, data, outputs and coordinates.
+
+Custom Python operations require a user-maintained ``model_key``. Their
+implementation cannot be inferred reliably from an Op's class name.

pymc_cache-0.1.0/api/sample.qmd

@@ -0,0 +1,21 @@
+# sample { #pymc_cache.sample }
+
+```python
+sample(
+    model=None,
+    cache=True,
+    overwrite=False,
+    policy=None,
+    namespace='',
+    model_key=None,
+    sampler_key=None,
+    sample_fn=None,
+    **sample_kwargs,
+)
+```
+
+Run ``pm.sample`` (or a trusted runner), reusing a matching result.
+
+No global PyMC function is replaced. ``cache='disk'`` persists under
+``.pymc-cache``; ``cache=False`` always samples anew. A user-supplied
+sample_fn must opt into safe identity or supply a trusted sampler_key.

pymc_cache-0.1.0/api/sample_smc.qmd

@@ -0,0 +1,16 @@
+# sample_smc { #pymc_cache.sample_smc }
+
+```python
+sample_smc(
+    model=None,
+    cache=True,
+    overwrite=False,
+    policy=None,
+    namespace='',
+    model_key=None,
+    sampler_key=None,
+    **sample_kwargs,
+)
+```
+
+Run and cache ``pm.sample_smc`` without conflating it with NUTS.

pymc_cache-0.1.0/contributing.qmd

@@ -0,0 +1,5 @@
+---
+title: Contributing
+---
+
+Follow the [repository contributing guide](https://github.com/justmytwospence/pymc-cache/blob/main/CONTRIBUTING.md) for installation and checks. Cache identity and persistence changes need explicit tests for false hits, incomplete results, older ArviZ and legacy data preservation. Do not commit posterior files, `.extraction-source/`, or generated site output.

pymc_cache-0.1.0/custom.scss

@@ -0,0 +1,2 @@
+/* Small readable adjustments to the default Quarto theme. */
+main.content { max-width: 68rem; }

pymc_cache-0.1.0/examples/basic.py

@@ -0,0 +1,26 @@
+"""Run a tiny repeatable PyMC sample twice with a private disk cache."""
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import pymc as pm
+
+import pymc_cache as pc
+
+
+def main() -> None:
+    with pm.Model() as model:
+        pm.Normal("mu", 0, 1)
+    with tempfile.TemporaryDirectory(prefix="pymc-cache-example-") as directory:
+        options = dict(model=model, draws=10, tune=10, chains=1, cores=1,
+                       random_seed=42, progressbar=False, cache=Path(directory))
+        first = pc.sample(**options)
+        second = pc.sample(**options)
+        assert first is not second
+        assert len(pc.DiskCache(directory).entries()) == 1
+        print("Reused", len(second.posterior.draw), "draws from disk")
+
+
+if __name__ == "__main__":
+    main()

pymc_cache-0.1.0/examples/custom_backend.py

@@ -0,0 +1,36 @@
+"""Implement a minimal copy-isolated backend without a storage dependency."""
+from __future__ import annotations
+
+import copy
+
+import pymc as pm
+
+import pymc_cache as pc
+
+
+class PrivateBackend:
+    def __init__(self):
+        self.entries = {}
+
+    def load(self, key, **kwargs):
+        value = self.entries.get(key)
+        return copy.deepcopy(value) if value is not None else None
+
+    def save(self, key, idata, **kwargs):
+        self.entries[key] = copy.deepcopy(idata)
+
+
+def main():
+    with pm.Model() as model:
+        pm.Normal("x")
+    backend = PrivateBackend()
+    options = dict(model=model, cache=backend, draws=2, tune=2, chains=1,
+                   cores=1, random_seed=42, progressbar=False)
+    first = pc.sample(**options)
+    second = pc.sample(**options)
+    assert first is not second and len(backend.entries) == 1
+    print("Custom backend reused", len(second.posterior.draw), "draws")
+
+
+if __name__ == "__main__":
+    main()

pymc_cache-0.1.0/examples/monitor_composition.py

@@ -0,0 +1,48 @@
+"""Preflight an optional monitor runner before starting its work.
+
+The callable is injected: pymc-cache does not import or install pymc-monitor.
+Only pass a stable sampler_identity/versions for a runner whose semantics you own.
+"""
+from __future__ import annotations
+
+import pymc as pm
+
+import pymc_cache as pc
+from pymc_cache.policy import report_from_idata
+
+
+def run_with_monitor(model, monitor_run, *, cache, sampler_identity, versions, **options):
+    """Reuse a result or call an external monitor; never store unverified adaptive runs."""
+    session = pc.CacheSession(cache=cache, model=model)
+    lookup = session.lookup(options, sampler_identity=sampler_identity, versions=versions)
+    if lookup.hit:
+        return lookup.result, True
+    result = monitor_run(model=model, **lookup.normalized_kwargs)
+    report = report_from_idata(result)
+    status = report.get("status", "unverified") if report else (
+        "unverified" if options.get("until") else "complete"
+    )
+    session.store(lookup, result, status=status, effective_sampler=sampler_identity)
+    return result, False
+
+
+def main():
+    # Replace pm.sample with your pymc-monitor runner after verifying its call
+    # signature, version and convergence-report contract in your installation.
+    with pm.Model() as model:
+        pm.Normal("x")
+    cache = pc.MemoryCache()
+    opts = dict(draws=2, tune=2, chains=1, cores=1, random_seed=42, progressbar=False)
+    first, hit = run_with_monitor(model, pm.sample, cache=cache,
+                                  sampler_identity="native-pymc-example", versions={
+                                      "runner": pm.__version__}, **opts)
+    assert not hit
+    second, hit = run_with_monitor(model, pm.sample, cache=cache,
+                                   sampler_identity="native-pymc-example", versions={
+                                       "runner": pm.__version__}, **opts)
+    assert hit and first is not second
+    print("Preflight skipped the runner:", hit)
+
+
+if __name__ == "__main__":
+    main()