graphrefly 0.1.0__py3-none-any.whl

graphrefly/extra/composite.py

@@ -0,0 +1,303 @@
+"""Composite data patterns (roadmap §3.2b).
+
+These helpers compose existing primitives without introducing new protocol semantics.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterable, Awaitable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, NotRequired, TypedDict, cast
+
+from graphrefly.core.dynamic_node import dynamic_node
+from graphrefly.core.node import Node
+from graphrefly.core.protocol import MessageType, batch
+from graphrefly.core.sugar import derived, state
+from graphrefly.extra.data_structures import ReactiveMapBundle, reactive_map
+from graphrefly.extra.sources import for_each, from_any, of
+from graphrefly.extra.tier1 import merge
+from graphrefly.extra.tier2 import switch_map
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiableBundle:
+    """Result of :func:`verifiable`."""
+
+    node: Node[Any]
+    verified: Node[Any]
+    trigger: Node[Any] | None
+
+
+def verifiable(
+    source: Any,
+    verify_fn: Callable[[Any], Any],
+    *,
+    trigger: Any | None = None,
+    auto_verify: bool = False,
+    initial_verified: Any = None,
+) -> VerifiableBundle:
+    """Compose a value node with a reactive verification companion.
+
+    Args:
+        source: Value source (`Node`, scalar, awaitable, iterable, async iterable).
+        verify_fn: Verification function returning a `NodeInput`.
+        trigger: Optional reactive trigger; each `DATA` triggers verification.
+        auto_verify: When true, source value changes also trigger verification.
+        initial_verified: Initial value for the verification companion.
+    """
+    source_node = from_any(source)
+    has_source_versioning = source_node.v is not None
+    meta_opts: dict[str, Any] = {"source_version": None} if has_source_versioning else {}
+    verified_node = state(initial_verified, **({"meta": meta_opts} if meta_opts else {}))
+
+    trigger_node: Node[Any] | None = None
+    if trigger is not None and auto_verify:
+        trigger_node = merge(from_any(trigger), source_node)
+    elif trigger is not None:
+        trigger_node = from_any(trigger)
+    elif auto_verify:
+        trigger_node = source_node
+
+    if trigger_node is not None:
+        verify_stream = switch_map(
+            lambda _t: _coerce_node_input(verify_fn(source_node.get())),
+        )(trigger_node)
+
+        def _on_verified(value: Any) -> None:
+            with batch():
+                verified_node.down([(MessageType.DATA, value)])
+                # V0 backfill: stamp which source version was verified (§6.0b).
+                if has_source_versioning:
+                    sv = source_node.v
+                    if sv is not None:
+                        verified_node.meta["source_version"].down(
+                            [(MessageType.DATA, {"id": sv.id, "version": sv.version})]
+                        )
+
+        for_each(
+            verify_stream,
+            _on_verified,
+            on_error=lambda _err: None,
+        )
+
+    return VerifiableBundle(node=source_node, verified=verified_node, trigger=trigger_node)
+
+
+class Extraction(TypedDict):
+    """Shape consumed by :func:`distill` extraction stages."""
+
+    upsert: list[dict[str, Any]]
+    remove: NotRequired[list[str]]
+
+
+@dataclass(frozen=True, slots=True)
+class DistillBundle:
+    """Result of :func:`distill`."""
+
+    store: ReactiveMapBundle
+    compact: Node[Any]
+    size: Node[int]
+
+
+def _snapshot_map(store: ReactiveMapBundle) -> Mapping[str, Any]:
+    snap = store.data.get()
+    if snap is None:
+        return {}
+    if hasattr(snap, "value"):
+        return cast("Mapping[str, Any]", snap.value)
+    return cast("Mapping[str, Any]", snap)
+
+
+def _apply_extraction(store: ReactiveMapBundle, extraction: Extraction) -> None:
+    upsert = extraction.get("upsert")
+    if not isinstance(upsert, list):
+        msg = "distill extraction requires upsert: list[{key,value}]"
+        raise TypeError(msg)
+    with batch():
+        for row in upsert:
+            store.set(row["key"], row["value"])
+        for key in extraction.get("remove", []):
+            store.delete(key)
+
+
+def distill(
+    source: Any,
+    extract_fn: Callable[[Any, Mapping[str, Any]], Any],
+    *,
+    score: Callable[[Any, Any], float],
+    cost: Callable[[Any], float],
+    budget: float = 2000,
+    evict: Callable[[str, Any], Any] | None = None,
+    consolidate: Callable[[Mapping[str, Any]], Any] | None = None,
+    consolidate_trigger: Any | None = None,
+    context: Any | None = None,
+    map_options: dict[str, Any] | None = None,
+    map_name: str | None = None,
+    map_default_ttl: float | None = None,
+    map_max_size: int | None = None,
+) -> DistillBundle:
+    """Budget-constrained reactive memory composition.
+
+    Args:
+        source: Source stream to distill.
+        extract_fn: `(raw, existing) -> Extraction` as `NodeInput`.
+        score: Relevance function for compact packing.
+        cost: Cost function for compact packing.
+        budget: Maximum compact budget (default `2000`).
+        evict: Optional reactive eviction predicate per key.
+        consolidate: Optional consolidation function.
+        consolidate_trigger: Optional trigger for consolidation.
+        context: Optional context source affecting compact ranking.
+        map_options: Optional dict-style map config parity with TS (`name`,
+            `default_ttl`, `max_size`).
+        map_name: Optional underlying map node name.
+        map_default_ttl: Optional default TTL seconds for underlying map.
+        map_max_size: Optional underlying map max size.
+    """
+    source_node = from_any(source)
+    context_node = from_any(context) if context is not None else state(None)
+    resolved_default_ttl = (
+        map_options["default_ttl"]
+        if map_options and "default_ttl" in map_options
+        else map_default_ttl
+    )
+    resolved_max_size = (
+        map_options["max_size"] if map_options and "max_size" in map_options else map_max_size
+    )
+    resolved_name = map_options["name"] if map_options and "name" in map_options else map_name
+    store = reactive_map(
+        default_ttl=resolved_default_ttl,
+        max_size=resolved_max_size,
+        name=resolved_name,
+    )
+
+    extraction_stream = switch_map(
+        lambda raw: _coerce_node_input(extract_fn(raw, _snapshot_map(store))),
+    )(source_node)
+    for_each(
+        extraction_stream,
+        lambda ex: _apply_extraction(store, ex),
+        on_error=lambda _err: None,
+    )
+
+    if evict is not None:
+        eviction_keys = dynamic_node(
+            lambda get: _compute_evictions(get, store, evict),
+        )
+
+        def _delete_keys(keys: list[str]) -> None:
+            for key in keys:
+                store.delete(key)
+
+        for_each(
+            cast("Node[Any]", eviction_keys),
+            _delete_keys,
+            on_error=lambda _err: None,
+        )
+
+    if consolidate is not None and consolidate_trigger is not None:
+        consolidation_stream = switch_map(
+            lambda _t: _coerce_node_input(consolidate(_snapshot_map(store))),
+        )(from_any(consolidate_trigger))
+        for_each(
+            consolidation_stream,
+            lambda ex: _apply_extraction(store, ex),
+            on_error=lambda _err: None,
+        )
+
+    compact = derived(
+        [store.data, context_node],
+        lambda deps, _a: _pack_compact(
+            deps[0].value if hasattr(deps[0], "value") else deps[0],
+            deps[1],
+            score,
+            cost,
+            budget,
+        ),
+    )
+    size = derived(
+        [store.data],
+        lambda deps, _a: len(deps[0].value if hasattr(deps[0], "value") else deps[0]),
+        initial=0,
+    )
+    compact.subscribe(lambda _msgs: None)
+    size.subscribe(lambda _msgs: None)
+
+    return DistillBundle(store=store, compact=compact, size=size)
+
+
+def _coerce_node_input(value: Any) -> Node[Any]:
+    if isinstance(value, Node):
+        return value
+    if isinstance(value, AsyncIterable):
+        return from_any(value)
+    if isinstance(value, Awaitable):
+        return from_any(value)
+    if isinstance(value, Mapping):
+        return of(value)
+    if isinstance(value, (str, bytes, bytearray)):
+        return of(value)
+    if isinstance(value, Iterable):
+        return from_any(value)
+    return of(value)
+
+
+def _compute_evictions(
+    get: Callable[[Node[Any]], Any],
+    store: ReactiveMapBundle,
+    evict: Callable[[str, Any], Any],
+) -> list[str]:
+    out: list[str] = []
+    current = get(store.data)
+    snapshot = current.value if hasattr(current, "value") else current
+    for key, mem in snapshot.items():
+        verdict = evict(key, mem)
+        if isinstance(verdict, Node):
+            if get(verdict) is True:
+                out.append(key)
+            continue
+        if isinstance(verdict, bool):
+            if verdict:
+                out.append(key)
+            continue
+        msg = "distill evict() must return bool or Node[bool] for reactive tracking"
+        raise TypeError(msg)
+    return out
+
+
+def _pack_compact(
+    snapshot: Mapping[str, Any],
+    context: Any,
+    score: Callable[[Any, Any], float],
+    cost: Callable[[Any], float],
+    budget: float,
+) -> list[dict[str, Any]]:
+    ranked = [
+        {
+            "key": key,
+            "value": value,
+            "score": float(score(value, context)),
+            "cost": float(cost(value)),
+        }
+        for key, value in snapshot.items()
+    ]
+    ranked.sort(key=lambda row: row["score"], reverse=True)
+    packed: list[dict[str, Any]] = []
+    remaining = float(budget)
+    for row in ranked:
+        if row["cost"] <= remaining:
+            packed.append({"key": row["key"], "value": row["value"], "score": row["score"]})
+            remaining -= row["cost"]
+    return packed
+
+
+__all__ = [
+    "DistillBundle",
+    "Extraction",
+    "VerifiableBundle",
+    "distill",
+    "verifiable",
+]

graphrefly/extra/cron.py

@@ -0,0 +1,133 @@
+"""Minimal 5-field cron parser and matcher (minute hour day-of-month month day-of-week).
+
+Ported from graphrefly-ts extra/cron.ts for from_cron (roadmap 2.3).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+@dataclass
+class CronSchedule:
+    """Parsed representation of a 5-field cron expression.
+
+    Produced by :func:`parse_cron`; consumed by :func:`matches_cron`.
+
+    Attributes:
+        minutes: Set of matching minute values (0–59).
+        hours: Set of matching hour values (0–23).
+        days_of_month: Set of matching day-of-month values (1–31).
+        months: Set of matching month values (1–12).
+        days_of_week: Set of matching day-of-week values (0–6, where 0 = Sunday).
+
+    Example:
+        ```python
+        from graphrefly.extra.cron import parse_cron
+        schedule = parse_cron("0 9 * * 1")
+        assert 0 in schedule.minutes
+        assert 9 in schedule.hours
+        ```
+    """
+
+    minutes: set[int] = field(default_factory=set)
+    hours: set[int] = field(default_factory=set)
+    days_of_month: set[int] = field(default_factory=set)
+    months: set[int] = field(default_factory=set)
+    days_of_week: set[int] = field(default_factory=set)
+
+
+def _parse_field(field_str: str, min_val: int, max_val: int) -> set[int]:
+    result: set[int] = set()
+    for part in field_str.split(","):
+        pieces = part.split("/")
+        range_str = pieces[0]
+        step = int(pieces[1]) if len(pieces) > 1 else 1
+        if step < 1:
+            msg = f"Invalid cron step: {part}"
+            raise ValueError(msg)
+        if range_str == "*":
+            start, end = min_val, max_val
+        elif "-" in range_str:
+            a, b = range_str.split("-")
+            start, end = int(a), int(b)
+        else:
+            start = int(range_str)
+            end = start
+        if start < min_val or end > max_val:
+            msg = f"Cron field out of range: {field_str} ({min_val}-{max_val})"
+            raise ValueError(msg)
+        if start > end:
+            msg = f"Invalid cron range: {start}-{end} in {field_str}"
+            raise ValueError(msg)
+        for i in range(start, end + 1, step):
+            result.add(i)
+    return result
+
+
+def parse_cron(expr: str) -> CronSchedule:
+    """Parse a standard 5-field cron expression into a :class:`CronSchedule`.
+
+    Supports ``*``, ranges (``1-5``), steps (``*/2``), and comma-separated lists.
+    Fields are: minute hour day-of-month month day-of-week.
+
+    Args:
+        expr: A cron expression string with exactly 5 whitespace-separated fields.
+
+    Returns:
+        A :class:`CronSchedule` with the parsed field sets.
+
+    Example:
+        ```python
+        from graphrefly.extra.cron import parse_cron
+        s = parse_cron("0 9 * * 1-5")
+        assert 9 in s.hours
+        assert 0 not in s.days_of_week  # Sunday excluded
+        ```
+    """
+    parts = expr.strip().split()
+    if len(parts) != 5:  # noqa: PLR2004
+        msg = f"Invalid cron: expected 5 fields, got {len(parts)}"
+        raise ValueError(msg)
+    return CronSchedule(
+        minutes=_parse_field(parts[0], 0, 59),
+        hours=_parse_field(parts[1], 0, 23),
+        days_of_month=_parse_field(parts[2], 1, 31),
+        months=_parse_field(parts[3], 1, 12),
+        days_of_week=_parse_field(parts[4], 0, 6),
+    )
+
+
+def matches_cron(schedule: CronSchedule, dt: datetime) -> bool:
+    """Return True when *dt* satisfies every field of *schedule*.
+
+    Args:
+        schedule: A :class:`CronSchedule` produced by :func:`parse_cron`.
+        dt: A :class:`datetime.datetime` to test.
+
+    Returns:
+        ``True`` if minute, hour, day-of-month, month, and day-of-week all match.
+
+    Example:
+        ```python
+        from datetime import datetime
+        from graphrefly.extra.cron import parse_cron, matches_cron
+        s = parse_cron("30 8 * * *")
+        dt = datetime(2025, 1, 1, 8, 30)
+        assert matches_cron(s, dt)
+        ```
+    """
+    return (
+        dt.minute in schedule.minutes
+        and dt.hour in schedule.hours
+        and dt.day in schedule.days_of_month
+        and dt.month in schedule.months
+        and dt.isoweekday() % 7 in schedule.days_of_week
+    )
+
+
+__all__ = ["CronSchedule", "matches_cron", "parse_cron"]