doeff-core-effects 0.1.0__py3-none-any.whl

doeff_core_effects/__init__.py

@@ -0,0 +1,42 @@
+"""
+doeff-core-effects — reference implementation of effects and handlers.
+
+This package provides:
+- Core effects: Ask, Get, Put, Tell
+- Core handlers: reader, state, writer
+- Scheduler: Spawn, Wait, Gather, Race, Cancel, Promise, ExternalPromise, Semaphore
+"""
+
+from doeff_core_effects.effects import (
+    Ask, Get, Put, Tell, Try, Slog, WriterTellEffect,
+    Local, Listen, Await, slog,
+)
+from doeff_core_effects.handlers import (
+    reader, state, writer, try_handler, slog_handler,
+    local_handler, listen_handler, await_handler,
+    lazy_ask, env_var_ask,
+)
+from doeff_core_effects.scheduler import (
+    Cancel,
+    CreateExternalPromise,
+    CreatePromise,
+    CreateSemaphore,
+    AcquireSemaphore,
+    ReleaseSemaphore,
+    CompletePromise,
+    ExternalPromise,
+    FailPromise,
+    Future,
+    Gather,
+    PRIORITY_HIGH,
+    PRIORITY_IDLE,
+    PRIORITY_NORMAL,
+    Promise,
+    Race,
+    Semaphore,
+    Spawn,
+    Task,
+    TaskCancelledError,
+    Wait,
+    scheduled,
+)

doeff_core_effects/cache.py

@@ -0,0 +1,172 @@
+"""Cache decorator for doeff programs using cache effects.
+
+The @cache decorator memoizes @do function results via CacheGet/CachePut effects.
+Requires a cache handler (cache_handler, in_memory_cache_handler, or sqlite_cache_handler)
+to be installed via WithHandler.
+
+NOTE: The full @cache decorator with execution context-based call site attribution
+is not yet ported. This module provides the core cache helpers and a simplified
+@cache decorator.
+"""
+
+import os
+import tempfile
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any, TypeVar
+
+from frozendict import frozendict as FrozenDict
+
+from doeff import UnhandledEffect, do
+from doeff_core_effects.memo_effects import MemoExists, MemoGet, MemoPut
+from doeff_core_effects.memo_policy import Lifecycle, MemoPolicy, ensure_memo_policy
+
+T = TypeVar("T")
+
+CACHE_PATH_ENV_KEY = "DOEFF_CACHE_PATH"
+
+
+def persistent_cache_path() -> Path:
+    """Return the persistent cache path from env or default."""
+    env_path = os.environ.get(CACHE_PATH_ENV_KEY)
+    if env_path:
+        return Path(env_path)
+    return Path(tempfile.gettempdir()) / "doeff_cache"
+
+
+def clear_persistent_cache() -> None:
+    """Clear the persistent cache directory."""
+    path = persistent_cache_path()
+    if path.exists():
+        import shutil
+        shutil.rmtree(path)
+
+
+def _function_identifier(target: Any) -> str:
+    """Return a descriptive identifier for a callable (module.qualname)."""
+    module = getattr(target, "__module__", None)
+    qualname = getattr(target, "__qualname__", None)
+    name = getattr(target, "__name__", None)
+
+    parts: list[str] = []
+    if module:
+        parts.append(module)
+    if qualname:
+        parts.append(qualname)
+    elif name:
+        parts.append(name)
+
+    if parts:
+        return ".".join(parts)
+
+    func_attr = getattr(target, "func", None)
+    if func_attr is not None and func_attr is not target:
+        inner = _function_identifier(func_attr)
+        cls = target.__class__
+        return f"{cls.__module__}.{cls.__qualname__}({inner})"
+
+    cls = target.__class__
+    return f"{cls.__module__}.{cls.__qualname__}"
+
+
+def default_cache_key(func_name: str, args: tuple, kwargs: FrozenDict) -> tuple:
+    """Default cache key: (func_name, args, FrozenDict(kwargs))."""
+    return (func_name, args, kwargs)
+
+
+def cache(
+    ttl: float | None = None,
+    key_func: Callable | None = None,
+    *,
+    lifecycle: Lifecycle | str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    policy: MemoPolicy | Mapping[str, Any] | None = None,
+) -> Callable:
+    """Cache decorator that uses MemoGet/MemoPut effects for memoization.
+
+    The cache key defaults to ``(func_name, args, FrozenDict(kwargs))`` where
+    ``func_name`` is the fully qualified module path of the wrapped callable.
+
+    Args:
+        ttl: Expiry in seconds. None means no expiry.
+        key_func: Optional key builder. Receives (func_name, args, FrozenDict(kwargs)).
+        lifecycle: Lifecycle hint for custom handlers.
+        metadata: Extra metadata for custom handlers.
+        policy: Full MemoPolicy (overrides ttl/lifecycle/metadata).
+    """
+    memo_policy = ensure_memo_policy(
+        ttl=ttl,
+        lifecycle=lifecycle,
+        metadata=metadata,
+        policy=policy,
+    )
+
+    def decorator(func: Callable) -> Callable:
+        func_name = _function_identifier(func)
+
+        @do
+        def cached_fn(*args, **kwargs):
+            frozen_kwargs = FrozenDict(kwargs) if kwargs else FrozenDict()
+            cache_key_obj = (
+                key_func(func_name, args, frozen_kwargs)
+                if key_func
+                else (func_name, args, frozen_kwargs)
+            )
+
+            # Memo handler is optional. If absent (UnhandledEffect on MemoExists/Get)
+            # or storage misses (KeyError), fall through to compute. The
+            # yield func(...) below is NOT wrapped: its failures must propagate.
+            try:
+                if (yield MemoExists(cache_key_obj)):
+                    try:
+                        cached_value = yield MemoGet(cache_key_obj)
+                        return cached_value
+                    except KeyError:
+                        pass
+            except UnhandledEffect:
+                pass
+
+            # Memo miss — run the function
+            result = yield func(*args, **kwargs)
+
+            # Best-effort store: if no memo handler is installed, swallow. The
+            # compute result returned above is authoritative.
+            try:
+                yield MemoPut(cache_key_obj, result, policy=memo_policy)
+            except UnhandledEffect:
+                pass
+            return result
+
+        # Preserve metadata
+        for attr in ("__name__", "__qualname__", "__doc__", "__module__"):
+            val = getattr(func, attr, None)
+            if val is not None:
+                try:
+                    setattr(cached_fn, attr, val)
+                except (AttributeError, TypeError):
+                    pass
+
+        return cached_fn
+
+    return decorator
+
+
+# Convenience presets
+cache_1min = cache(ttl=60)
+cache_5min = cache(ttl=300)
+cache_1hour = cache(ttl=3600)
+cache_forever = cache(ttl=None)
+
+
+__all__ = [
+    "CACHE_PATH_ENV_KEY",
+    "FrozenDict",
+    "cache",
+    "cache_1hour",
+    "cache_1min",
+    "cache_5min",
+    "cache_forever",
+    "clear_persistent_cache",
+    "default_cache_key",
+    "persistent_cache_path",
+]

doeff_core_effects/cache_effects.py

@@ -0,0 +1,116 @@
+"""Cache effects for memoization."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from doeff_core_effects.cache_policy import (
+    CacheLifecycle,
+    CachePolicy,
+    CacheStorage,
+    ensure_cache_policy,
+)
+from doeff_vm import EffectBase
+
+
+class CacheGetEffect(EffectBase):
+    """Requests the cached value for the key."""
+    def __init__(self, key):
+        super().__init__()
+        self.key = key
+
+    def __repr__(self):
+        return f"CacheGet({self.key!r})"
+
+
+class CachePutEffect(EffectBase):
+    """Persists the value under the key."""
+    def __init__(self, key, value, policy):
+        super().__init__()
+        if not isinstance(policy, CachePolicy):
+            raise TypeError(f"policy must be CachePolicy, got {type(policy).__name__}")
+        self.key = key
+        self.value = value
+        self.policy = policy
+
+    def __repr__(self):
+        return f"CachePut({self.key!r}, ...)"
+
+
+class CacheDeleteEffect(EffectBase):
+    """Deletes the value under the key."""
+    def __init__(self, key):
+        super().__init__()
+        self.key = key
+
+    def __repr__(self):
+        return f"CacheDelete({self.key!r})"
+
+
+class CacheExistsEffect(EffectBase):
+    """Checks if a key exists in the cache."""
+    def __init__(self, key):
+        super().__init__()
+        self.key = key
+
+    def __repr__(self):
+        return f"CacheExists({self.key!r})"
+
+
+# Convenience constructors (lowercase)
+
+def cache_get(key: Any) -> CacheGetEffect:
+    return CacheGetEffect(key=key)
+
+
+def cache_put(
+    key: Any,
+    value: Any,
+    ttl: float | None = None,
+    *,
+    lifecycle: CacheLifecycle | str | None = None,
+    storage: CacheStorage | str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    policy: CachePolicy | Mapping[str, Any] | None = None,
+) -> CachePutEffect:
+    cache_policy = ensure_cache_policy(
+        ttl=ttl,
+        lifecycle=lifecycle,
+        storage=storage,
+        metadata=metadata,
+        policy=policy,
+    )
+    return CachePutEffect(key=key, value=value, policy=cache_policy)
+
+
+def cache_delete(key: Any) -> CacheDeleteEffect:
+    return CacheDeleteEffect(key=key)
+
+
+def cache_exists(key: Any) -> CacheExistsEffect:
+    return CacheExistsEffect(key=key)
+
+
+# Capitalized aliases
+CacheGet = cache_get
+CachePut = cache_put
+CacheDelete = cache_delete
+CacheExists = cache_exists
+
+
+__all__ = [
+    "CacheDelete",
+    "CacheDeleteEffect",
+    "CacheExists",
+    "CacheExistsEffect",
+    "CacheGet",
+    "CacheGetEffect",
+    "CacheLifecycle",
+    "CachePolicy",
+    "CachePut",
+    "CachePutEffect",
+    "CacheStorage",
+    "cache_delete",
+    "cache_exists",
+    "cache_get",
+    "cache_put",
+]

doeff_core_effects/cache_handlers.py

@@ -0,0 +1,222 @@
+"""Cache effect handlers and memoization helpers."""
+
+import dataclasses
+import hashlib
+import json
+from collections.abc import Callable, Mapping, Set
+from pathlib import Path
+from typing import Any, TypeAlias
+
+from doeff import do
+from doeff.program import Resume, Pass
+
+from doeff_core_effects.cache_effects import (
+    CacheExistsEffect,
+    CacheGetEffect,
+    CachePutEffect,
+    CacheGet,
+    CachePut,
+    CacheExists,
+)
+from doeff_core_effects.effects import Try
+from doeff_core_effects.storage import DurableStorage, InMemoryStorage, SQLiteStorage
+
+MemoKeyFn: TypeAlias = Callable[[object], str]
+
+
+def _dumps(value: object) -> bytes:
+    try:
+        import cloudpickle as serializer
+    except ModuleNotFoundError:
+        import pickle as serializer
+
+    return serializer.dumps(value)
+
+
+def _normalize_for_hash(value: object) -> object:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {
+            "__type__": f"{type(value).__module__}.{type(value).__qualname__}",
+            **{
+                field.name: _normalize_for_hash(getattr(value, field.name))
+                for field in dataclasses.fields(value)
+            },
+        }
+    elif isinstance(value, Mapping):
+        return {
+            str(key): _normalize_for_hash(item)
+            for key, item in sorted(value.items(), key=lambda item: str(item[0]))
+        }
+    elif isinstance(value, tuple):
+        return {"__tuple__": [_normalize_for_hash(item) for item in value]}
+    elif isinstance(value, list):
+        return [_normalize_for_hash(item) for item in value]
+    elif isinstance(value, Set) and not isinstance(value, (str, bytes, bytearray)):
+        normalized = [_normalize_for_hash(item) for item in value]
+        return {
+            "__set__": sorted(normalized, key=lambda item: json.dumps(item, sort_keys=True))
+        }
+    elif isinstance(value, Path):
+        return {"__path__": str(value)}
+    elif isinstance(value, bytes):
+        return {"__bytes__": value.hex()}
+    elif isinstance(value, type):
+        return f"{value.__module__}.{value.__qualname__}"
+    elif hasattr(value, "__dict__") and not isinstance(value, type):
+        # Generic object with __dict__ (e.g. EffectBase subclasses)
+        return {
+            "__type__": f"{type(value).__module__}.{type(value).__qualname__}",
+            **{
+                k: _normalize_for_hash(v)
+                for k, v in sorted(value.__dict__.items())
+            },
+        }
+    return value
+
+
+def _storage_key(key: object) -> str:
+    if isinstance(key, str):
+        return key
+    return f"sha256:{content_address(key)}"
+
+
+def _persist_value(
+    storage: DurableStorage,
+    storage_key: str,
+    *,
+    original_key: object,
+    value: object,
+) -> None:
+    try:
+        storage.put(storage_key, value)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Cache handler could not persist value for key {original_key!r}: {exc}"
+        ) from exc
+
+
+def content_address(effect: object) -> str:
+    """Return a SHA-256 content address for an effect payload."""
+    try:
+        payload = _dumps(effect)
+    except Exception:
+        payload = json.dumps(_normalize_for_hash(effect), sort_keys=True, default=repr).encode(
+            "utf-8"
+        )
+    return hashlib.sha256(payload).hexdigest()
+
+
+def cache_handler(storage: DurableStorage):
+    """Interpret CacheGet/CachePut/CacheExists against a pluggable storage backend.
+
+    Storage methods return Programs (DoExpr). The handler yields them to get values.
+    This makes the handler transparent to sync (Pure) and async (Await) storage alike.
+    """
+
+    @do
+    def handler(effect, k):
+        if not isinstance(effect, (CacheGetEffect, CacheExistsEffect, CachePutEffect)):
+            yield Pass(effect, k)
+            return
+
+        key = _storage_key(effect.key)
+
+        if isinstance(effect, CacheExistsEffect):
+            exists = yield storage.exists(key)
+            result = yield Resume(k, exists)
+            return result
+
+        if isinstance(effect, CacheGetEffect):
+            value = yield storage.get(key)
+            if value is None:
+                exists = yield storage.exists(key)
+                if not exists:
+                    from doeff.program import ResumeThrow
+                    return (yield ResumeThrow(k, KeyError(effect.key)))
+            result = yield Resume(k, value)
+            return result
+
+        # CachePutEffect
+        yield storage.put(key, effect.value)
+        result = yield Resume(k, None)
+        return result
+
+    return handler
+
+
+def in_memory_cache_handler():
+    """Return a cache handler backed by in-memory storage."""
+    return cache_handler(InMemoryStorage())
+
+
+def sqlite_cache_handler(db_path: str | Path):
+    """Return a cache handler backed by SQLite storage."""
+    return cache_handler(SQLiteStorage(db_path))
+
+
+def make_memo_rewriter(
+    effect_type: type,
+    key_fn: MemoKeyFn = content_address,
+):
+    """Create a handler that memoizes effects of the given type through cache.
+
+    On cache hit: Resume with cached value (outer handler not called).
+    On cache miss: re-perform effect → outer handler handles it → store result in cache.
+    """
+    from doeff_core_effects.effects import WriterTellEffect as Slog
+
+    @do
+    def handler(effect, k):
+        if not isinstance(effect, effect_type):
+            yield Pass(effect, k)
+            return
+
+        key = key_fn(effect)
+        yield Slog(f"[memo] checking {effect_type.__name__} key={key[:16]}…")
+
+        # Check cache — narrow try/except to CacheGet only.
+        # Resume(k) must NOT be inside try/except: if the resumed body raises
+        # KeyError, it must propagate, not fall through to the MISS path.
+        _MISS = object()  # sentinel
+        if (yield CacheExists(key)):
+            try:
+                cached = yield CacheGet(key)
+            except KeyError:
+                cached = _MISS  # race: evicted between Exists and Get
+
+            if cached is not _MISS:
+                yield Slog(f"[memo] HIT {effect_type.__name__} key={key[:16]}…")
+                result = yield Resume(k, cached)
+                return result
+
+        # Cache miss — "delegate" by re-performing the effect.
+        yield Slog(f"[memo] MISS {effect_type.__name__} key={key[:16]}… → delegating")
+        delegated = yield effect
+
+        # Store in cache
+        yield CachePut(key, delegated)
+        yield Slog(f"[memo] STORED {effect_type.__name__} key={key[:16]}…")
+
+        # Resume body with result
+        result = yield Resume(k, delegated)
+        return result
+
+    return handler
+
+
+def memo_rewriters(
+    *effect_types: type,
+    key_fn: MemoKeyFn = content_address,
+) -> list:
+    """Create memo rewriter handlers for each provided effect type."""
+    return [make_memo_rewriter(et, key_fn=key_fn) for et in effect_types]
+
+
+__all__ = [
+    "cache_handler",
+    "content_address",
+    "in_memory_cache_handler",
+    "make_memo_rewriter",
+    "memo_rewriters",
+    "sqlite_cache_handler",
+]

doeff_core_effects/cache_policy.py

@@ -0,0 +1,102 @@
+"""Cache policy types shared between cache effects and handlers."""
+
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class CacheLifecycle(str, Enum):
+    """Lifecycle hint describing how long cached data should live."""
+
+    TRANSIENT = "transient"
+    SESSION = "session"
+    PERSISTENT = "persistent"
+
+
+class CacheStorage(str, Enum):
+    """Preferred storage target for cached entries."""
+
+    MEMORY = "memory"
+    DISK = "disk"
+
+
+@dataclass(frozen=True)
+class CachePolicy:
+    """Policy metadata attached to cache entries."""
+
+    ttl: float | None = None
+    lifecycle: CacheLifecycle = CacheLifecycle.TRANSIENT
+    storage: CacheStorage | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def resolved_storage(self) -> CacheStorage:
+        """Determine the effective storage based on hints."""
+        if self.storage is not None:
+            return self.storage
+        if self.lifecycle is CacheLifecycle.PERSISTENT:
+            return CacheStorage.DISK
+        return CacheStorage.MEMORY
+
+
+def ensure_cache_policy(
+    *,
+    ttl: float | None = None,
+    lifecycle: CacheLifecycle | str | None = None,
+    storage: CacheStorage | str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    policy: CachePolicy | Mapping[str, Any] | None = None,
+) -> CachePolicy:
+    """Normalize parameters into a CachePolicy instance."""
+
+    if policy is not None:
+        if any(param is not None for param in (ttl, lifecycle, storage, metadata)):
+            raise ValueError("When policy is provided, other cache policy parameters must be omitted")
+        if isinstance(policy, CachePolicy):
+            return policy
+        if isinstance(policy, Mapping):
+            return ensure_cache_policy(**policy)  # type: ignore[misc]
+        raise TypeError("policy must be CachePolicy or mapping")
+
+    lifecycle_value = _normalize_lifecycle(lifecycle)
+    storage_value = _normalize_storage(storage)
+    metadata_dict: Mapping[str, Any]
+    if metadata is None:
+        metadata_dict = {}
+    elif isinstance(metadata, Mapping):
+        metadata_dict = dict(metadata)
+    else:
+        raise TypeError("metadata must be mapping if provided")
+
+    return CachePolicy(
+        ttl=ttl,
+        lifecycle=lifecycle_value,
+        storage=storage_value,
+        metadata=metadata_dict,
+    )
+
+
+def _normalize_lifecycle(value: CacheLifecycle | str | None) -> CacheLifecycle:
+    if value is None:
+        return CacheLifecycle.TRANSIENT
+    if isinstance(value, CacheLifecycle):
+        return value
+    return CacheLifecycle(value)
+
+
+def _normalize_storage(value: CacheStorage | str | None) -> CacheStorage | None:
+    if value is None:
+        return None
+    if isinstance(value, CacheStorage):
+        return value
+    return CacheStorage(value)
+
+
+
+__all__ = [
+    "CacheLifecycle",
+    "CachePolicy",
+    "CacheStorage",
+    "ensure_cache_policy",
+]