advalcache 0.1.0__py3-none-any.whl

advalcache/decorators.py

@@ -0,0 +1,211 @@
+"""advalcache/decorators.py — @cache.cached and @cache.memoize descriptors.
+
+These are the primary integration point for most users. They are attached to
+a Cache (or AsyncCache) instance and wrap the caller's function transparently.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import reprlib
+from typing import Any, Callable, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Avoid circular import at runtime
+    from advalcache._engine import AdValEngine, AsyncAdValEngine
+
+# reprlib limits repr length so huge args don't blow out key size
+_repr = reprlib.Repr()
+_repr.maxstring = 128
+_repr.maxother = 64
+
+
+def _build_key(prefix: str, func: Callable, args: tuple, kwargs: dict) -> str:
+    """Build a deterministic cache key from function identity and arguments.
+
+    Format: ``{prefix}{module}.{qualname}:{repr(args)}:{repr(sorted(kwargs.items()))}``
+    """
+    arg_part = _repr.repr(args)
+    kw_part = _repr.repr(sorted(kwargs.items()))
+    return f"{prefix}{func.__module__}.{func.__qualname__}:{arg_part}:{kw_part}"
+
+
+class _CachedDescriptor:
+    """Sync cached descriptor.
+
+    Returned by ``Cache.cached(...)`` and wraps a synchronous function.
+    """
+
+    def __init__(
+        self,
+        engine: "AdValEngine",
+        func: Callable,
+        regen_ms: float,
+        regen_usd: float,
+        change_interval_s: float,
+        cls: str,
+        size_bytes: Optional[int],
+        key_fn: Optional[Callable],
+        key_prefix: str,
+    ) -> None:
+        self._engine = engine
+        self._func = func
+        self._regen_ms = regen_ms
+        self._regen_usd = regen_usd
+        self._change_interval_s = change_interval_s
+        self._cls = cls
+        self._size_bytes = size_bytes
+        self._key_fn = key_fn
+        self._key_prefix = key_prefix
+        functools.update_wrapper(self, func)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        if self._key_fn is not None:
+            key = self._key_prefix + self._key_fn(*args, **kwargs)
+        else:
+            key = _build_key(self._key_prefix, self._func, args, kwargs)
+
+        result = self._engine.get(key)
+        if result is not None:
+            value, _is_fresh, _freshness, _score = result
+            return value
+
+        value = self._func(*args, **kwargs)
+        self._engine.put(
+            key=key, data=value, cls=self._cls,
+            size_bytes=self._size_bytes,
+            regen_ms=self._regen_ms,
+            regen_usd=self._regen_usd,
+            change_interval_s=self._change_interval_s,
+        )
+        return value
+
+    def invalidate(self, *args: Any, **kwargs: Any) -> bool:
+        """Manually invalidate the cache entry for a specific set of arguments."""
+        if self._key_fn is not None:
+            key = self._key_prefix + self._key_fn(*args, **kwargs)
+        else:
+            key = _build_key(self._key_prefix, self._func, args, kwargs)
+        return self._engine.invalidate(key)
+
+    def invalidate_all(self) -> int:
+        """Invalidate all cache entries for this function."""
+        prefix = f"{self._key_prefix}{self._func.__module__}.{self._func.__qualname__}:"
+        return self._engine.invalidate_prefix(prefix)
+
+
+class _AsyncCachedDescriptor:
+    """Async cached descriptor for AsyncCache."""
+
+    def __init__(
+        self,
+        engine: "AsyncAdValEngine",
+        func: Callable,
+        regen_ms: float,
+        regen_usd: float,
+        change_interval_s: float,
+        cls: str,
+        size_bytes: Optional[int],
+        key_fn: Optional[Callable],
+        key_prefix: str,
+    ) -> None:
+        self._engine = engine
+        self._func = func
+        self._regen_ms = regen_ms
+        self._regen_usd = regen_usd
+        self._change_interval_s = change_interval_s
+        self._cls = cls
+        self._size_bytes = size_bytes
+        self._key_fn = key_fn
+        self._key_prefix = key_prefix
+        functools.update_wrapper(self, func)
+
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        if self._key_fn is not None:
+            key = self._key_prefix + self._key_fn(*args, **kwargs)
+        else:
+            key = _build_key(self._key_prefix, self._func, args, kwargs)
+
+        result = await self._engine.get(key)
+        if result is not None:
+            value, _is_fresh, _freshness, _score = result
+            return value
+
+        value = await self._func(*args, **kwargs)
+        await self._engine.put(
+            key=key, data=value, cls=self._cls,
+            size_bytes=self._size_bytes,
+            regen_ms=self._regen_ms,
+            regen_usd=self._regen_usd,
+            change_interval_s=self._change_interval_s,
+        )
+        return value
+
+    async def invalidate(self, *args: Any, **kwargs: Any) -> bool:
+        if self._key_fn is not None:
+            key = self._key_prefix + self._key_fn(*args, **kwargs)
+        else:
+            key = _build_key(self._key_prefix, self._func, args, kwargs)
+        return await self._engine.invalidate(key)
+
+    async def invalidate_all(self) -> int:
+        prefix = f"{self._key_prefix}{self._func.__module__}.{self._func.__qualname__}:"
+        return await self._engine.invalidate_prefix(prefix)
+
+
+def make_cached_decorator(
+    engine: Any,
+    key_prefix: str = "",
+    is_async: bool = False,
+) -> Callable:
+    """Return a ``cached(...)`` decorator factory bound to an engine.
+
+    This is what ``Cache.cached`` and ``AsyncCache.cached`` are.
+    """
+
+    def cached(
+        regen_ms: float = 100.0,
+        regen_usd: float = 0.0,
+        change_interval_s: float = 0.0,
+        cls: str = "generic",
+        size_bytes: Optional[int] = None,
+        key: Optional[Callable] = None,
+    ) -> Callable:
+        """Decorate a function so its return value is cached by AdVal.
+
+        Args:
+            regen_ms: How long it takes to re-generate this value (milliseconds).
+                Used to compute regeneration pain. Higher = more protected from eviction.
+            regen_usd: Dollar cost to re-generate this value.
+                Used alongside regen_ms in the pain term.
+            change_interval_s: How often this object changes upstream (seconds).
+                0 = immutable (always fresh). Small values (< 5 s) may trigger admission
+                control to decline caching — AdVal won't cache objects that will go stale
+                before they are likely to be accessed again.
+            cls: Object class label for telemetry grouping (e.g. "api_response",
+                "ml_result", "static_asset"). Purely informational.
+            size_bytes: Override the estimated size. If None, estimated via sys.getsizeof.
+            key: Optional callable that takes the same arguments as the decorated function
+                and returns a string cache key. Default: auto-built from function
+                name + repr(args).
+        """
+        def decorator(func: Callable) -> Any:
+            if is_async or asyncio.iscoroutinefunction(func):
+                return _AsyncCachedDescriptor(
+                    engine=engine, func=func,
+                    regen_ms=regen_ms, regen_usd=regen_usd,
+                    change_interval_s=change_interval_s, cls=cls,
+                    size_bytes=size_bytes, key_fn=key, key_prefix=key_prefix,
+                )
+            else:
+                return _CachedDescriptor(
+                    engine=engine, func=func,
+                    regen_ms=regen_ms, regen_usd=regen_usd,
+                    change_interval_s=change_interval_s, cls=cls,
+                    size_bytes=size_bytes, key_fn=key, key_prefix=key_prefix,
+                )
+        return decorator
+
+    return cached

advalcache/server.py

@@ -0,0 +1,118 @@
+"""advalcache/server.py — Optional built-in observability server.
+
+Requires the 'fastapi' extra: pip install advalcache[fastapi]
+
+Exposes:
+    GET  /stats       - full telemetry snapshot
+    GET  /keys        - top N resident keys by score
+    GET  /health      - lightweight health check
+    POST /invalidate  - {"key": "..."} or {"prefix": "..."}
+    POST /clear       - flush all entries
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+try:
+    import uvicorn
+    from fastapi import FastAPI
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import JSONResponse
+    from pydantic import BaseModel
+    _HAS_FASTAPI = True
+except ImportError:
+    _HAS_FASTAPI = False
+
+if TYPE_CHECKING:
+    from advalcache._engine import AdValEngine
+
+
+class _InvalidateRequest(BaseModel):
+    key: Optional[str] = None
+    prefix: Optional[str] = None
+
+
+class ObsServer:
+    """Built-in FastAPI observability server for an AdValEngine.
+
+    Started automatically when ``CacheConfig.obs_port`` is set.
+    Runs on a daemon thread — does not block the main process.
+    """
+
+    def __init__(self, engine: "AdValEngine", port: int = 9999) -> None:
+        if not _HAS_FASTAPI:
+            raise ImportError(
+                "advalcache observability server requires 'fastapi' and 'uvicorn'. "
+                "Install with: pip install advalcache[fastapi]"
+            )
+        self._engine = engine
+        self._port = port
+        self._server: Optional[Any] = None
+        self._app = self._build_app()
+
+    def _build_app(self) -> "FastAPI":
+        engine = self._engine
+        app = FastAPI(
+            title="AdVal Cache — Observability",
+            description="Live telemetry and control for an AdVal in-memory cache instance.",
+            version="0.1.0",
+        )
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["*"],
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        @app.get("/health")
+        def health() -> Dict[str, Any]:
+            return {
+                "status": "healthy",
+                "resident_count": engine.count,
+                "resident_mb": engine.resident_mb,
+                "capacity_mb": engine.capacity_mb,
+            }
+
+        @app.get("/stats")
+        def stats() -> JSONResponse:
+            return JSONResponse(engine.snapshot())
+
+        @app.get("/keys")
+        def keys(limit: int = 25) -> JSONResponse:
+            snap = engine.snapshot()
+            top = snap.get("top_resident_keys", [])[:limit]
+            return JSONResponse({"keys": top, "total": snap.get("resident_count", 0)})
+
+        @app.post("/invalidate")
+        def invalidate(req: _InvalidateRequest) -> Dict[str, Any]:
+            if req.key:
+                removed = 1 if engine.invalidate(req.key) else 0
+                return {"removed": removed, "type": "key"}
+            elif req.prefix:
+                removed = engine.invalidate_prefix(req.prefix)
+                return {"removed": removed, "type": "prefix"}
+            return {"error": "provide 'key' or 'prefix'"}
+
+        @app.post("/clear")
+        def clear() -> Dict[str, Any]:
+            engine.clear()
+            return {"status": "cleared"}
+
+        return app
+
+    def run(self) -> None:
+        """Start uvicorn — intended to run on a daemon thread."""
+        config = uvicorn.Config(
+            self._app,
+            host="127.0.0.1",
+            port=self._port,
+            log_level="warning",
+        )
+        self._server = uvicorn.Server(config)
+        self._server.run()
+
+    def shutdown(self) -> None:
+        if self._server is not None:
+            self._server.should_exit = True

advalcache/stats.py

@@ -0,0 +1,84 @@
+"""advalcache/stats.py — CacheStats snapshot dataclass."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List
+
+
+@dataclass(frozen=True)
+class CacheStats:
+    """Frozen snapshot of cache telemetry at a point in time.
+
+    Create via ``cache.get_stats()``. All fields are immutable.
+    """
+
+    # Request counts
+    total_requests: int
+    hits: int
+    misses: int
+    fresh_hits: int
+    stale_hits: int
+    declines: int
+    proactive_refreshes: int
+
+    # Rates (percentages 0–100)
+    hit_rate_pct: float
+    freshness_pct: float
+
+    # Economics
+    usd_saved: float
+
+    # Memory
+    resident_mb: float
+    capacity_mb: float
+    resident_count: int
+
+    # Latency
+    avg_ram_latency_ms: float
+    avg_origin_latency_ms: float
+    speedup_factor: float
+
+    # Eviction breakdown
+    evictions: Dict[str, int]
+
+    # Recent events (list of dicts: time/op/key/details)
+    recent_events: List[Dict[str, Any]]
+
+    # Top resident keys by score
+    top_resident_keys: List[Dict[str, Any]]
+
+    @classmethod
+    def from_snapshot(cls, snap: Dict[str, Any]) -> "CacheStats":
+        """Build a CacheStats from the engine's snapshot dict."""
+        return cls(
+            total_requests=snap.get("total_requests", 0),
+            hits=snap.get("hits", 0),
+            misses=snap.get("misses", 0),
+            fresh_hits=snap.get("fresh_hits", 0),
+            stale_hits=snap.get("stale_hits", 0),
+            declines=snap.get("declines", 0),
+            proactive_refreshes=snap.get("proactive_refreshes", 0),
+            hit_rate_pct=snap.get("hit_rate_pct", 0.0),
+            freshness_pct=snap.get("freshness_pct", 0.0),
+            usd_saved=snap.get("usd_saved", 0.0),
+            resident_mb=snap.get("resident_mb", 0.0),
+            capacity_mb=snap.get("capacity_mb", 0.0),
+            resident_count=snap.get("resident_count", 0),
+            avg_ram_latency_ms=snap.get("avg_ram_latency_ms", 0.0),
+            avg_origin_latency_ms=snap.get("avg_origin_latency_ms", 0.0),
+            speedup_factor=snap.get("speedup_factor", 0.0),
+            evictions=snap.get("evictions", {}),
+            recent_events=snap.get("recent_events", []),
+            top_resident_keys=snap.get("top_resident_keys", []),
+        )
+
+    def summary(self) -> str:
+        """One-liner human-readable summary."""
+        return (
+            f"AdVal | hit={self.hit_rate_pct:.1f}% "
+            f"fresh={self.freshness_pct:.1f}% "
+            f"saved=${self.usd_saved:.4f} "
+            f"ram={self.resident_mb:.1f}/{self.capacity_mb:.1f}MB "
+            f"speedup={self.speedup_factor:.0f}x"
+        )

advalcache-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: advalcache
+Version: 0.1.0
+Summary: AdVal adaptive in-memory cache SDK — value-scored, freshness-aware, zero dependencies.
+Project-URL: Homepage, https://github.com/mdtahseen7/VH26-PRESTORA
+Project-URL: Repository, https://github.com/mdtahseen7/VH26-PRESTORA
+Project-URL: Issues, https://github.com/mdtahseen7/VH26-PRESTORA/issues
+Author-email: Md Tahseen <mdtahseen7378@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: adaptive,cache,caching,django,fastapi,in-memory,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: django>=3.2; extra == 'all'
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: sqlalchemy>=1.4; extra == 'all'
+Requires-Dist: uvicorn>=0.20.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Requires-Dist: uvicorn>=0.20.0; extra == 'fastapi'
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == 'redis'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=1.4; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# AdVal-Cache
+
+**A cache that knows the difference between a $0.31 recommendation vector and a stock
+ticker that is worthless two seconds after you store it.**
+
+LRU asks *when did you last touch this*. LFU asks *how often*. Neither asks the only
+question a bill cares about: **what does losing this actually cost me?** In a real
+service that answer spans four orders of magnitude — a free 4 MB product image against
+a ten-second, fifty-cent ML inference. AdVal-Cache computes a per-object **value
+score** from access pattern, resource footprint, regeneration cost *and* data
+volatility, then decides retain / evict / **refresh** / **decline** — and separately
+decides, in dollars, when buying more cache capacity is worth the rent.
+
+## Quickstart
+
+```powershell
+python -m venv venv; venv\Scripts\activate; pip install -r requirements.txt
+python -m benchmarks.run_all --seed 42          # 80 cells in ~4 min -> results/report.md
+streamlit run dashboard/app.py                  # playback dashboard
+```
+
+Everything is a deterministic simulation: no network, no Redis, no Docker, CPU only.
+Same seed ⇒ byte-identical traces, results and charts.
+
+## Results
+
+60 simulated minutes per scenario, seed 42. The problem statement's baselines are LRU, LFU
+and GDS; exact GDSF ships alongside because it is stronger than the brief requires (D29).
+
+**AdVal is cheaper *and* fresher than the best baseline in 8 of 8 cells.**
+
+| scenario / profile | best baseline | baseline $ | **AdVal $** | saving | baseline fresh | **AdVal fresh** | pre-D31 base $ | pre-D31 AdVal $ |
+|---|---|---|---|---|---|---|---|---|
+| chaos / compute_heavy_rec | gds | 2854.48 | **2816.52** | **1.3%** | 66.2% | **78.5%** | 98.91 | 124.13 |
+| chaos / read_heavy_api | gds | 1086.05 | **986.37** | **9.2%** | 64.2% | **74.2%** | 98.91 | 117.41 |
+| gradual_shift / compute_heavy_rec | gds | 3034.96 | **2989.81** | **1.5%** | 67.1% | **80.2%** | 98.91 | 124.51 |
+| gradual_shift / read_heavy_api | gds | 1046.89 | **923.08** | **11.8%** | 64.7% | **77.7%** | 98.91 | 123.12 |
+| steady / compute_heavy_rec | gds | 4275.14 | **4235.45** | **0.9%** | 59.7% | **73.1%** | 98.91 | 122.15 |
+| steady / read_heavy_api | gdsf_exact | 1282.12 | **1142.86** | **10.9%** | 57.9% | **70.8%** | 100.01 | 120.88 |
+| viral_spike / compute_heavy_rec | gds | 4850.61 | **4802.40** | **1.0%** | 60.2% | **72.6%** | 98.91 | 124.59 |
+| viral_spike / read_heavy_api | gds | 1877.68 | **1755.22** | **6.5%** | 47.1% | **56.0%** | 98.91 | 120.20 |
+
+### Read the last two columns before you believe the first ones
+
+The cost model used to bill compute and memory and **nothing at all for serving a customer
+stale data**. Nobody decided that; it is what you get by leaving wrong answers unpriced,
+and it meant a cache-freshness system was scored on everything except the thing it does —
+`gds` won on cost by serving 75,526 wrong answers an hour for free.
+
+D31 fixes it on a principle rather than a knob: **a stale hit is not a hit, it is a miss
+you failed to notice**, so it is charged the `regen_usd` of the very object it displaced.
+The price is read per object out of the catalog, billed by the simulator so every policy
+pays the same for the same event, and measured at $0.0077–$0.186 per stale serve. That is
+7–170x the ~0.11 cent break-even, which is why the ranking flips.
+
+**On the old model `gds` is still cheaper** — that is the `pre-D31` pair above, kept in
+`summary.csv` as `total_usd_compute_only` in every run, and
+`python -m benchmarks.run_all --stale-mult 0` reproduces it exactly (a test asserts it).
+The honest caveat: at the shipped price the staleness bill is ~10x compute plus memory, so
+the ranking now rests mostly on this one priced assumption. The full flat-price sweep,
+including where AdVal loses, is in `results/dominance.md`.
+
+Savings are 6.5–11.8% on `read_heavy_api` and only 0.9–1.5% on `compute_heavy_rec`, where
+slow-changing `ml_result` objects dominate the staleness bill for every arm alike.
+
+### The four answers that assume nothing
+
+Separately from the cost model, `results/dominance.md`:
+
+1. **Nothing in the study is both cheaper and fresher than AdVal** — 16/16 arm-cells, on
+   either cost model.
+2. **Capacity cannot buy freshness.** `gds` serves 75,526 stale responses at 100 MB and
+   75,526 at 500 MB while its hit rate climbs 81.6% → 93.9%. AdVal at 100 MB is cheaper
+   *and* 12.2 pp fresher than `gds` at 500 MB.
+3. **The flat-price sweep**: above ~0.11 cents per stale response AdVal is cheapest in all
+   8 cells, to 4.6–45 cents where LRU takes over. Both bounds published.
+4. **At 50–60 MB, where memory is actually scarce**, AdVal is cheaper *and* fresher at
+   equal capacity even with staleness free.
+
+Against LRU and LFU, AdVal is 92–99% cheaper on either model. It still loses on tail
+latency — 158 ms p95 against 55 ms — because refreshing on read is not free. Full tables,
+timelines, the ablation ladder and an auto-generated "where this result is weakest"
+section: **`results/report.md`**.
+
+## The score
+
+```
+score(i) = hotness(i) × pain(i) × freshness(i) / size_units(i)
+```
+
+- **hotness** — LRFU decayed counter `c ← 1 + c·e^(−λΔt)`, λ = 0.001 (half-life ≈ 693 s);
+  recency at short lags, frequency at long ones, one number.
+- **pain** — regeneration latency and regeneration dollars, each normalised against the
+  catalog's p99 so neither drowns the other. ~200× spread across object classes.
+- **freshness** — `exp(−(now − last_sync) / change_interval)`, which for a Poisson
+  mutation process is exactly *P(the cached copy is still valid)*. Multiplying a value
+  by a probability gives an expected value, which is the right thing to rank by.
+  Exactly `1.0` for immutable objects and anything slower than 1800 s.
+- **size_units** — `log1p(bytes / 1 KB)`, so 5 MB is penalised ~12× rather than ~5000×.
+  Large objects must justify themselves; they are not banned.
+
+Two runtime loops keep it from being a set of hardcoded constants:
+
+- **The cache A/B tests its own brain.** Every 5000 requests it shadow-replays the
+  window it just served through five candidate weight vectors, seeded from a snapshot
+  of its real state, and adopts whichever delivered the most value. `steady` picks
+  `freq_heavy`; `chaos` picks `fresh_heavy`. Nobody told it which signal matters.
+- **Capacity is a dollar decision that checks itself.** A shadow zone measures the
+  marginal dollars the next slice of memory would have saved; the controller acts,
+  waits five windows, and reverts the change if realised spend per request did not fall
+  by more than the rent it took on. From a badly-sized 30 MB cache it cuts cost 72–84%.
+
+`ARCHITECTURE.md` has the decision-engine diagram and the full justification.
+
+## Repo layout
+
+```
+models.py            THE CONTRACT: Request, CatalogEntry, object classes, ops, constants
+proxy/               FastAPI reverse proxy sidecar · live cache engine · traffic generator
+database/            Neon PostgreSQL client · schema · real-world dataset ingestion pipeline
+cache/               base (interface, sampling, event sink) · lru · lfu · gdsf · adaptive · controller
+generator/           catalog · popularity modes · scenario engine · trace writer · validator
+sim/                 simulator (replay + window aggregation) · metrics (the only cost model)
+benchmarks/          run_all (the 80-cell matrix) · report (tables, charts, honest caveats)
+dashboard/app.py     Streamlit control center: batch replay scrubber & live dynamic proxy mode
+web_adval/           React/Vite standalone web control UI mounted on proxy port 8000
+traces/              trace samples & Postgres query trace generator
+tests/               unit & integration tests: core, live cache, and proxy API
+results/             event logs, window CSVs, summary.csv, report.md, charts/
+```
+
+## Verify it yourself
+
+```powershell
+python -m generator.validate --minutes 60 --seed 42   # 9 workload checks, ~6 s
+python -m pytest -q                                   # 63 tests, ~8 s
+python -m benchmarks.run_all --seed 42                # 80 cells, ~4 min
+```
+
+`generator/validate.py` is the workload referee: it asserts the arrival-rate curve
+matches the scenario spec within 4σ on all four scenarios, that the top-10 popular keys
+genuinely rotate during `gradual_shift` (0 shared keys), that the reuse working set is
+**4.05× cache capacity** (a cache that never fills has no story), that `static_asset` is
+99.4% of bytes but only 30.1% of requests, and that seed 42 reproduces byte-identical
+files. A cache benchmark is only as honest as its workload.
+
+## Reading the docs
+
+| file | what is in it |
+|---|---|
+| `ARCHITECTURE.md` | decision-engine diagram, every term of the score justified, the two adaptive loops |
+| `results/report.md` | generated results: headline tables, charts, ablation, capacity fairness, weaknesses |
+| `DECISIONS.md` | **22 numbered assumptions and corrections**, including two places the problem statement's own numbers disagree, three bugs that only a benchmark could have caught, and one metric that was measuring the wrong thing |
+| `DEMO.md` | the scripted 5-minute walkthrough, with fallbacks |
+| `FORMATS.md` | every on-disk schema: catalog, trace, change stream, event log, window CSV |
+| `PROGRESS.md` | phase-by-phase build log with the ACCEPT evidence for each |

advalcache-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+advalcache/__init__.py,sha256=DENMhpuJRLchnJwYE2nfRj_9yt6E7FfZSrjoedoa0Rk,10515
+advalcache/__main__.py,sha256=kB4xw-ShLl9TlpdY_Khx-hg5c3K8dzX6YmGLZ9d-4lk,1861
+advalcache/_engine.py,sha256=lFKEHjOsByLXsvZ_O1eANWqJvGkePu-ITG9SJbjU6k4,19754
+advalcache/_eviction.py,sha256=DqO6hFyLVhms8p7Z38Eq6t3eEvPyY1PVnzpL0lBlNFc,2914
+advalcache/_refresh.py,sha256=oa4E338jrazZm8Z4Ev1P9_CboQN_BLQbVIflPmXvHic,3139
+advalcache/_scoring.py,sha256=OBP_1p1KQNA760cKUC9F90zE5KbWPdEdifOUhgHHSAU,5274
+advalcache/config.py,sha256=3nNLecT2iknSCoj6Eg4d3k8qpQP7V5J8PFSLmFbzWMw,3941
+advalcache/decorators.py,sha256=duARsgw4HTu-vwAVZ5_TiJNUbIpp8najygbioAPI03M,7884
+advalcache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+advalcache/server.py,sha256=rF0z6156icxDWAziEcjrdO81EW1jd5e9iWSzEBjhcXs,3878
+advalcache/stats.py,sha256=B0Zx3mMH1s3OAaLUYAyy6Xf84RcTj3zepWWzqKfiR4c,2739
+advalcache/adapters/__init__.py,sha256=PEWpmQVWXTIvNj1h6u5bo6l07Lg6SagoN6owQ7uoSrE,77
+advalcache/adapters/django.py,sha256=kcxxenJ7NAyrrKQMfo9OBioh2SbbvuVzqUbOfF8MCJQ,5688
+advalcache/adapters/fastapi.py,sha256=JnCgJezn0-CF51Xn_efu8EgnW5nyJomM_RxEooqQ-0g,2713
+advalcache/adapters/sqlalchemy.py,sha256=hltXd5jFb1pKS5D5kQXMu1UNUTvVMSEdrRk2XJ76tek,2990
+advalcache-0.1.0.dist-info/METADATA,sha256=Ns4Vfn71BUYYBR_L2bdHX8Piz5_a3ghSac0op7h2fJE,11179
+advalcache-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+advalcache-0.1.0.dist-info/entry_points.txt,sha256=szozXPcpLUu7v52lr6XsxZtglUYM_RyZ45e7abQtCbo,56
+advalcache-0.1.0.dist-info/licenses/LICENSE,sha256=_T2oruKd3b683cdBOXvaRA_GgfumOqLua0dxXgEKqkg,1084
+advalcache-0.1.0.dist-info/RECORD,,

advalcache-0.1.0.dist-info/WHEEL

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

advalcache-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+advalcache = advalcache.__main__:main

advalcache-0.1.0.dist-info/licenses/LICENSE

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