query-cascade 0.3.7__tar.gz → 0.3.8__tar.gz

{query_cascade-0.3.7 → query_cascade-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: query-cascade
-Version: 0.3.7
+Version: 0.3.8
 Summary: Minimal demand-driven query framework for incremental computation.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -139,6 +139,16 @@ A few things to know:
 
 ## Advanced Features
 
+### Time-To-Live Cache Invalidation
+Cascade supports expiring cache entries automatically based on wall-clock time. By passing the `ttl` flag to `@engine.query`, you can guarantee that a node will recompute its value if it is accessed after the specified number of seconds has elapsed since its last evaluation. 
+
+```python
+@engine.query(ttl=5.0)
+def fetch_external_data():
+    return request.get("https://api.example.com/data")
+```
+When a TTL expires, Cascade evaluates the function again. If the newly returned value is identical to the previous one, downstream queries are **not** re-evaluated—early bail-out works exactly as it does for regular dependency changes.
+
 ### Asynchronous Execution
 Cascade natively supports asynchronous queries via `async def`. This is extremely useful for I/O-bound workflows (such as making database or network calls). When an asynchronous query evaluates, it runs cooperatively on the active `asyncio` event loop.
 
@@ -264,6 +274,7 @@ pip install query-cascade
 |--------|----------------|
 | `compiler_pipeline.py` | `source → parse → symbols → typecheck`, warnings accumulator, cache-hit narration |
 | `async_execution.py` | Asynchronous query evaluation and asyncio event loop integration for IO-bound work |
+| `ttl_invalidation.py` | Expiring stale query caches automatically based on wall-clock time |
 | `error_caching.py` | Basic exception caching to prevent repeated re-evaluation on failure |
 | `error_caching_persistence.py` | Disk cache hydration of exceptions across process runs |
 | `code_versioning.py` | Automatic cache invalidation when a function's bytecode logic changes |

{query_cascade-0.3.7 → query_cascade-0.3.8}/README.md

@@ -120,6 +120,16 @@ A few things to know:
 
 ## Advanced Features
 
+### Time-To-Live Cache Invalidation
+Cascade supports expiring cache entries automatically based on wall-clock time. By passing the `ttl` flag to `@engine.query`, you can guarantee that a node will recompute its value if it is accessed after the specified number of seconds has elapsed since its last evaluation. 
+
+```python
+@engine.query(ttl=5.0)
+def fetch_external_data():
+    return request.get("https://api.example.com/data")
+```
+When a TTL expires, Cascade evaluates the function again. If the newly returned value is identical to the previous one, downstream queries are **not** re-evaluated—early bail-out works exactly as it does for regular dependency changes.
+
 ### Asynchronous Execution
 Cascade natively supports asynchronous queries via `async def`. This is extremely useful for I/O-bound workflows (such as making database or network calls). When an asynchronous query evaluates, it runs cooperatively on the active `asyncio` event loop.
 
@@ -245,6 +255,7 @@ pip install query-cascade
 |--------|----------------|
 | `compiler_pipeline.py` | `source → parse → symbols → typecheck`, warnings accumulator, cache-hit narration |
 | `async_execution.py` | Asynchronous query evaluation and asyncio event loop integration for IO-bound work |
+| `ttl_invalidation.py` | Expiring stale query caches automatically based on wall-clock time |
 | `error_caching.py` | Basic exception caching to prevent repeated re-evaluation on failure |
 | `error_caching_persistence.py` | Disk cache hydration of exceptions across process runs |
 | `code_versioning.py` | Automatic cache invalidation when a function's bytecode logic changes |

{query_cascade-0.3.7 → query_cascade-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "query-cascade"
-version = "0.3.7"
+version = "0.3.8"
 description = "Minimal demand-driven query framework for incremental computation."
 requires-python = ">=3.12"
 readme = "README.md"

{query_cascade-0.3.7 → query_cascade-0.3.8}/src/cascade/_evaluator.py

@@ -308,7 +308,13 @@ class Evaluator:
             is_memoized = self._store.lookup_query_memoize(key[1])
             if existing is not None:
                 self._store.touch_memo_locked(key)
-                if existing.verified_at == runtime.snapshot.revision:
+                
+                ttl = self._store.lookup_query_ttl(key[1])
+                is_expired = False
+                if ttl is not None and self._store.monotonic_seconds() - existing.computed_at_time > ttl:
+                    is_expired = True
+                    
+                if not is_expired and existing.verified_at == runtime.snapshot.revision:
                     self._store.trace_event("cache_hit", key)
                     if is_memoized or not need_value:
                         return existing, True
@@ -370,7 +376,13 @@ class Evaluator:
             is_memoized = self._store.lookup_query_memoize(key[1])
             if existing is not None:
                 self._store.touch_memo_locked(key)
-                if existing.verified_at == runtime.snapshot.revision:
+                
+                ttl = self._store.lookup_query_ttl(key[1])
+                is_expired = False
+                if ttl is not None and self._store.monotonic_seconds() - existing.computed_at_time > ttl:
+                    is_expired = True
+
+                if not is_expired and existing.verified_at == runtime.snapshot.revision:
                     self._store.trace_event("cache_hit", key)
                     if is_memoized or not need_value:
                         return existing, True
@@ -423,6 +435,11 @@ class Evaluator:
                 self._store.in_flight.pop((key, runtime.snapshot.revision), None)
 
     def try_mark_green(self, key: QueryKey, entry: MemoEntry, snapshot: Snapshot) -> bool:
+        ttl = self._store.lookup_query_ttl(key[1])
+        if ttl is not None and self._store.monotonic_seconds() - entry.computed_at_time > ttl:
+            self._store.trace_event("cache_red_ttl", key)
+            return False
+
         for dep in entry.deps:
             dep_changed_at = self.dependency_changed_at(dep.key, snapshot)
             if dep_changed_at != dep.observed_changed_at:
@@ -431,6 +448,11 @@ class Evaluator:
         return True
 
     async def try_mark_green_async(self, key: QueryKey, entry: MemoEntry, snapshot: Snapshot) -> bool:  # pragma: no cover
+        ttl = self._store.lookup_query_ttl(key[1])
+        if ttl is not None and self._store.monotonic_seconds() - entry.computed_at_time > ttl:
+            self._store.trace_event("cache_red_ttl", key)
+            return False
+
         for dep in entry.deps:
             dep_changed_at = await self.dependency_changed_at_async(dep.key, snapshot)
             if dep_changed_at != dep.observed_changed_at:
@@ -636,6 +658,7 @@ class Evaluator:
                 deps=frame.deps,
                 effects=frozen_effects,
                 last_access=self._store.next_access_id,
+                computed_at_time=start,
                 cycle_nodes=tuple(frame.cycle_nodes),
                 error=error,
             )
@@ -650,6 +673,7 @@ class Evaluator:
                     deps=frame.deps,
                     effects=frozen_effects,
                     last_access=self._store.next_access_id,
+                    computed_at_time=start,
                     cycle_nodes=tuple(frame.cycle_nodes),
                     error=error,
                 )
@@ -768,6 +792,7 @@ class Evaluator:
                     deps=frame.deps,
                     effects=frozen_effects,
                     last_access=self._store.next_access_id,
+                    computed_at_time=start,
                     cycle_nodes=tuple(frame.cycle_nodes),
                     error=error,
                 )
@@ -782,6 +807,7 @@ class Evaluator:
                         deps=frame.deps,
                         effects=frozen_effects,
                         last_access=self._store.next_access_id,
+                        computed_at_time=start,
                         cycle_nodes=tuple(frame.cycle_nodes),
                         error=error,
                     )
@@ -866,6 +892,7 @@ class Evaluator:
                 deps=observed,
                 effects=effects,
                 last_access=self._store.next_access_id,
+                computed_at_time=record.get("computed_at_time", 0.0),
                 error=error,
             )
             self._store.drop_memo_locked(key)
@@ -1197,6 +1224,7 @@ class Evaluator:
                 "deps": deps_records,
                 "effects": effects_node,
                 "is_error": memo.error is not None,
+                "computed_at_time": memo.computed_at_time,
             }
             disk.store_entry(_disk_cache.entry_key(kind, fid, args_blob), record, memo.value_hash, value_blob)
         except PersistentCacheError:

{query_cascade-0.3.7 → query_cascade-0.3.8}/src/cascade/_serde.py

@@ -16,7 +16,7 @@ from typing import Any
 
 from ._state import Dependency, InputVersion, MemoEntry, TraceEvent
 
-PERSISTENCE_FORMAT = 1
+PERSISTENCE_FORMAT = 2
 
 # Used for canonical key ordering; kept separate so tests can monkeypatch `json.dumps`
 # on this module without breaking recursive sorting inside `_to_jsonable`.
@@ -168,6 +168,7 @@ def _to_jsonable(obj: Any) -> Any:
                 "deps": _to_jsonable(list(obj.deps)),
                 "effects": _to_jsonable(obj.effects),
                 "last_access": obj.last_access,
+                "computed_at_time": _to_jsonable(obj.computed_at_time),
             }
         }
 
@@ -290,6 +291,7 @@ def _from_jsonable(obj: Any) -> Any:
                 deps=tuple(deps_raw),
                 effects=_from_jsonable(d["effects"]),
                 last_access=d["last_access"],
+                computed_at_time=_from_jsonable(d.get("computed_at_time", 0.0)),
             )
         if sole_key == "__dataclass__":
             d = sole_val

{query_cascade-0.3.7 → query_cascade-0.3.8}/src/cascade/_state.py

@@ -31,6 +31,7 @@ class MemoEntry:
     deps: tuple[Dependency, ...]
     effects: dict[str, tuple[Any, ...]]
     last_access: int
+    computed_at_time: float = 0.0
     cycle_nodes: tuple[QueryKey, ...] = ()
     error: BaseException | None = None
 

{query_cascade-0.3.7 → query_cascade-0.3.8}/src/cascade/_store.py

@@ -49,6 +49,7 @@ class GraphStore:
         self.query_memoize: dict[str, bool] = {}
         self.query_fixed_points: dict[str, Any] = {}
         self.query_cache_exceptions: dict[str, bool | tuple[type[BaseException], ...]] = {}
+        self.query_ttl: dict[str, float | None] = {}
         self.input_fns: dict[str, Callable[..., Any]] = {}
         self.memos: dict[QueryKey, MemoEntry] = {}
         self.dependents: dict[QueryKey, set[QueryKey]] = defaultdict(set)
@@ -106,7 +107,7 @@ class GraphStore:
             sk = self.key_to_str(key)
             self._stats_by_key[sk] = self._stats_by_key.get(sk, 0.0) + seconds
 
-    def register_query(self, query_id: str, fn: Callable[..., Any], *, memoize: bool = True, fixed_point: Any = None, has_fixed_point: bool = False, cache_exceptions: bool | tuple[type[BaseException], ...] = False) -> None:
+    def register_query(self, query_id: str, fn: Callable[..., Any], *, memoize: bool = True, fixed_point: Any = None, has_fixed_point: bool = False, cache_exceptions: bool | tuple[type[BaseException], ...] = False, ttl: float | None = None) -> None:
         fn_hash = hash_bytecode(fn)
         with self.lock:
             if query_id in self.query_hashes and self.query_hashes[query_id] != fn_hash:
@@ -117,9 +118,14 @@ class GraphStore:
             self.query_hashes[query_id] = fn_hash
             self.query_memoize[query_id] = memoize
             self.query_cache_exceptions[query_id] = cache_exceptions
+            self.query_ttl[query_id] = ttl
             if has_fixed_point:
                 self.query_fixed_points[query_id] = fixed_point
 
+    def lookup_query_ttl(self, query_id: str) -> float | None:
+        with self.lock:
+            return self.query_ttl.get(query_id)
+
     def lookup_query_memoize(self, query_id: str) -> bool:
         with self.lock:
             return self.query_memoize.get(query_id, True)
@@ -495,6 +501,7 @@ class GraphStore:
         deps: dict[QueryKey, int],
         effects: dict[str, tuple[Any, ...]],
         last_access: int,
+        computed_at_time: float,
         cycle_nodes: tuple[QueryKey, ...] = (),
         error: BaseException | None = None,
     ) -> MemoEntry:
@@ -506,6 +513,7 @@ class GraphStore:
             deps=tuple(Dependency(dep_key, observed) for dep_key, observed in deps.items()),
             effects=effects,
             last_access=last_access,
+            computed_at_time=computed_at_time,
             cycle_nodes=cycle_nodes,
             error=error,
         )

{query_cascade-0.3.7 → query_cascade-0.3.8}/src/cascade/engine.py

@@ -284,11 +284,11 @@ class Engine:
         self._store.register_input(handle.id, fn)
         return handle
 
-    def query(self, fn: Callable[..., Any] | None = None, *, memoize: bool = True, fixed_point: Any = _UNSET, cache_exceptions: bool | tuple[type[BaseException], ...] = True) -> Any:
+    def query(self, fn: Callable[..., Any] | None = None, *, memoize: bool = True, fixed_point: Any = _UNSET, cache_exceptions: bool | tuple[type[BaseException], ...] = True, ttl: float | None = None) -> Any:
         def decorator(f: Callable[..., Any]) -> _QueryHandle:
             handle = _QueryHandle(self, f)
             has_fixed_point = fixed_point is not _UNSET
-            self._store.register_query(handle.id, f, memoize=memoize, fixed_point=fixed_point, has_fixed_point=has_fixed_point, cache_exceptions=cache_exceptions)
+            self._store.register_query(handle.id, f, memoize=memoize, fixed_point=fixed_point, has_fixed_point=has_fixed_point, cache_exceptions=cache_exceptions, ttl=ttl)
             return handle
         if fn is not None:
             return decorator(fn)

{query_cascade-0.3.7 → query_cascade-0.3.8}/src/query_cascade.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: query-cascade
-Version: 0.3.7
+Version: 0.3.8
 Summary: Minimal demand-driven query framework for incremental computation.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -139,6 +139,16 @@ A few things to know:
 
 ## Advanced Features
 
+### Time-To-Live Cache Invalidation
+Cascade supports expiring cache entries automatically based on wall-clock time. By passing the `ttl` flag to `@engine.query`, you can guarantee that a node will recompute its value if it is accessed after the specified number of seconds has elapsed since its last evaluation. 
+
+```python
+@engine.query(ttl=5.0)
+def fetch_external_data():
+    return request.get("https://api.example.com/data")
+```
+When a TTL expires, Cascade evaluates the function again. If the newly returned value is identical to the previous one, downstream queries are **not** re-evaluated—early bail-out works exactly as it does for regular dependency changes.
+
 ### Asynchronous Execution
 Cascade natively supports asynchronous queries via `async def`. This is extremely useful for I/O-bound workflows (such as making database or network calls). When an asynchronous query evaluates, it runs cooperatively on the active `asyncio` event loop.
 
@@ -264,6 +274,7 @@ pip install query-cascade
 |--------|----------------|
 | `compiler_pipeline.py` | `source → parse → symbols → typecheck`, warnings accumulator, cache-hit narration |
 | `async_execution.py` | Asynchronous query evaluation and asyncio event loop integration for IO-bound work |
+| `ttl_invalidation.py` | Expiring stale query caches automatically based on wall-clock time |
 | `error_caching.py` | Basic exception caching to prevent repeated re-evaluation on failure |
 | `error_caching_persistence.py` | Disk cache hydration of exceptions across process runs |
 | `code_versioning.py` | Automatic cache invalidation when a function's bytecode logic changes |

{query_cascade-0.3.7 → query_cascade-0.3.8}/src/query_cascade.egg-info/SOURCES.txt

@@ -45,4 +45,5 @@ tests/test_serde.py
 tests/test_stateful_engine_invariants.py
 tests/test_store_coverage.py
 tests/test_subgraph_stats_export.py
-tests/test_sweep_unaccessed.py
+tests/test_sweep_unaccessed.py
+tests/test_ttl.py

query_cascade-0.3.8/tests/test_ttl.py

@@ -0,0 +1,63 @@
+from cascade import Engine
+
+def test_ttl_invalidation_basic():
+    engine = Engine()
+    
+    clock = 0.0
+    engine._store.monotonic_seconds = lambda: clock
+    
+    compute_count = 0
+    
+    @engine.query(ttl=2.0)
+    def my_query():
+        nonlocal compute_count
+        compute_count += 1
+        return "value"
+        
+    assert my_query() == "value"
+    assert compute_count == 1
+    
+    # Still within TTL
+    clock = 1.0
+    assert my_query() == "value"
+    assert compute_count == 1
+    
+    # Exceed TTL
+    clock = 3.0
+    assert my_query() == "value"
+    assert compute_count == 2
+    
+    # Still within new TTL
+    clock = 4.0
+    assert my_query() == "value"
+    assert compute_count == 2
+    
+def test_ttl_invalidation_async():
+    import asyncio
+    engine = Engine()
+    
+    clock = 0.0
+    engine._store.monotonic_seconds = lambda: clock
+    
+    compute_count = 0
+    
+    @engine.query(ttl=1.5)
+    async def my_async_query():
+        nonlocal compute_count
+        compute_count += 1
+        return "async_value"
+        
+    async def run():
+        nonlocal clock
+        assert await my_async_query() == "async_value"
+        assert compute_count == 1
+        
+        clock = 1.0
+        assert await my_async_query() == "async_value"
+        assert compute_count == 1
+        
+        clock = 2.0
+        assert await my_async_query() == "async_value"
+        assert compute_count == 2
+        
+    asyncio.run(run())