graphrefly 0.1.0__py3-none-any.whl

graphrefly/__init__.py

@@ -0,0 +1,160 @@
+"""graphrefly — Reactive graph protocol for human and LLM co-operation."""
+
+from graphrefly import compat, integrations, patterns
+from graphrefly.core import (
+    V0,
+    V1,
+    Actor,
+    DeferWhen,
+    DynamicNodeImpl,
+    EmitStrategy,
+    GuardAction,
+    GuardDenied,
+    GuardFn,
+    HashFn,
+    Message,
+    Messages,
+    MessageType,
+    Node,
+    NodeActions,
+    NodeFn,
+    NodeImpl,
+    NodeStatus,
+    NodeVersionInfo,
+    PipeOperator,
+    Runner,
+    SubscribeHints,
+    VersioningLevel,
+    access_hint_for_guard,
+    acquire_subgraph_write_lock,
+    acquire_subgraph_write_lock_with_defer,
+    advance_version,
+    batch,
+    compose_guards,
+    create_versioning,
+    default_hash,
+    defer_down,
+    defer_set,
+    derived,
+    describe_node,
+    dispatch_messages,
+    dynamic_node,
+    effect,
+    emit_with_batch,
+    ensure_registered,
+    get_default_runner,
+    is_batching,
+    is_phase2_message,
+    is_v1,
+    meta_snapshot,
+    monotonic_ns,
+    node,
+    normalize_actor,
+    partition_for_batch,
+    pipe,
+    policy,
+    policy_from_rules,
+    producer,
+    record_mutation,
+    resolve_runner,
+    set_default_runner,
+    state,
+    system_actor,
+    union_nodes,
+    wall_clock_ns,
+)
+from graphrefly.graph import (
+    GRAPH_META_SEGMENT,
+    GRAPH_SNAPSHOT_VERSION,
+    META_PATH_SEG,
+    PATH_SEP,
+    Graph,
+    GraphAutoCheckpointHandle,
+    GraphDiffResult,
+    GraphObserveSource,
+    ObserveResult,
+    SpyHandle,
+    TraceEntry,
+    reachable,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GRAPH_META_SEGMENT",
+    "GRAPH_SNAPSHOT_VERSION",
+    "GraphAutoCheckpointHandle",
+    "Graph",
+    "GraphDiffResult",
+    "GraphObserveSource",
+    "HashFn",
+    "META_PATH_SEG",
+    "NodeVersionInfo",
+    "ObserveResult",
+    "PATH_SEP",
+    "SpyHandle",
+    "TraceEntry",
+    "V0",
+    "V1",
+    "VersioningLevel",
+    "reachable",
+    "compat",
+    "integrations",
+    "patterns",
+    "Runner",
+    "get_default_runner",
+    "resolve_runner",
+    "set_default_runner",
+    "Actor",
+    "DeferWhen",
+    "DynamicNodeImpl",
+    "EmitStrategy",
+    "GuardAction",
+    "GuardDenied",
+    "GuardFn",
+    "Message",
+    "MessageType",
+    "Messages",
+    "Node",
+    "PipeOperator",
+    "NodeActions",
+    "NodeFn",
+    "NodeImpl",
+    "NodeStatus",
+    "SubscribeHints",
+    "__version__",
+    "advance_version",
+    "create_versioning",
+    "default_hash",
+    "is_v1",
+    "monotonic_ns",
+    "wall_clock_ns",
+    "access_hint_for_guard",
+    "acquire_subgraph_write_lock",
+    "acquire_subgraph_write_lock_with_defer",
+    "batch",
+    "compose_guards",
+    "defer_down",
+    "defer_set",
+    "describe_node",
+    "dispatch_messages",
+    "emit_with_batch",
+    "ensure_registered",
+    "is_batching",
+    "is_phase2_message",
+    "meta_snapshot",
+    "node",
+    "normalize_actor",
+    "partition_for_batch",
+    "policy",
+    "policy_from_rules",
+    "record_mutation",
+    "system_actor",
+    "union_nodes",
+    "dynamic_node",
+    "derived",
+    "effect",
+    "pipe",
+    "producer",
+    "state",
+]

graphrefly/compat/__init__.py

@@ -0,0 +1,18 @@
+"""Framework compatibility layer — asyncio/trio runners and async utilities (roadmap §5.1)."""
+
+from graphrefly.compat.async_utils import (
+    first_value_from_async,
+    settled,
+    to_async_iter,
+)
+from graphrefly.compat.asyncio_runner import AsyncioRunner
+
+__all__ = [
+    "AsyncioRunner",
+    "first_value_from_async",
+    "settled",
+    "to_async_iter",
+]
+
+# TrioRunner is available via direct import (optional trio dependency):
+#   from graphrefly.compat.trio_runner import TrioRunner

graphrefly/compat/async_utils.py

@@ -0,0 +1,228 @@
+"""Async utility functions for consuming GraphReFly nodes from async code (roadmap §5.1).
+
+All utilities are **reactive** — they subscribe to nodes via
+:meth:`~graphrefly.core.node.NodeImpl.subscribe` and bridge to the async world
+via :class:`asyncio.Event` / :class:`asyncio.Queue`.  No polling.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import TYPE_CHECKING, Any
+
+from graphrefly.core.protocol import MessageType
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from graphrefly.core.node import Node
+    from graphrefly.core.protocol import Messages
+
+
+async def to_async_iter(source: Node[Any]) -> AsyncIterator[Any]:
+    """Yield values from *source* as an async iterator.
+
+    Subscribes reactively — each ``DATA`` message payload is yielded, and
+    each ``RESOLVED`` message yields the current value via ``source.get()``.
+    ``COMPLETE`` / ``ERROR`` / ``TEARDOWN`` end the iteration.
+    Unsubscribes on ``break`` / ``aclose()``.
+
+    Must be called from a running asyncio event loop.
+
+    Note:
+        ``state()`` nodes do not emit ``DATA`` on subscribe — they only emit
+        when :meth:`~graphrefly.core.node.NodeImpl.set` is called.  For such
+        nodes, the iterator will block until the first update arrives.
+        Derived nodes emit ``DATA`` on subscribe when they recompute.
+
+    Example::
+
+        from graphrefly.extra import of
+        from graphrefly.compat import to_async_iter
+
+        async for value in to_async_iter(of(1, 2, 3)):
+            print(value)
+
+    Yields:
+        Each ``DATA`` payload or current value on ``RESOLVED`` from the source.
+    """
+    loop = asyncio.get_running_loop()
+    queue: asyncio.Queue[tuple[str, Any]] = asyncio.Queue()
+
+    def _enqueue(tag: str, payload: Any) -> None:
+        with contextlib.suppress(RuntimeError):
+            loop.call_soon_threadsafe(queue.put_nowait, (tag, payload))
+
+    def sink(messages: Messages) -> None:
+        for msg in messages:
+            t = msg[0]
+            if t is MessageType.DATA:
+                _enqueue("DATA", msg[1] if len(msg) > 1 else None)
+            elif t is MessageType.RESOLVED:
+                _enqueue("DATA", source.get())
+            elif t is MessageType.ERROR:
+                err = msg[1] if len(msg) > 1 else RuntimeError("node error")
+                _enqueue("ERROR", err)
+            elif t is MessageType.COMPLETE or t is MessageType.TEARDOWN:
+                _enqueue("DONE", None)
+
+    unsub = source.subscribe(sink)
+    try:
+        while True:
+            tag, payload = await queue.get()
+            if tag == "DATA":
+                yield payload
+            elif tag == "ERROR":
+                raise payload
+            else:  # DONE
+                return
+    finally:
+        unsub()
+
+
+async def first_value_from_async(source: Node[Any]) -> Any:
+    """Await the first ``DATA`` value from *source*.
+
+    If the node already has a settled cached value, returns it immediately
+    without subscribing.  Otherwise subscribes reactively and waits.
+
+    Raises:
+        RuntimeError: If the source completes without emitting ``DATA``.
+        Exception: If the source emits ``ERROR``.
+
+    Example::
+
+        from graphrefly import state
+        from graphrefly.compat import first_value_from_async
+
+        s = state(42)
+        value = await first_value_from_async(s)
+        assert value == 42
+    """
+    # Fast path: already settled with a cached value.
+    # ``source.get()`` returns ``None`` when no value is cached, so
+    # ``is not None`` doubles as the "has value" sentinel while still
+    # returning falsy values like ``0``, ``False``, ``""``.
+    status = source.status
+    if status in ("settled", "resolved"):
+        v = source.get()
+        if v is not None:
+            return v
+
+    loop = asyncio.get_running_loop()
+    future: asyncio.Future[Any] = loop.create_future()
+
+    def _set_result(value: Any) -> None:
+        with contextlib.suppress(RuntimeError):
+            loop.call_soon_threadsafe(_resolve, future, value)
+
+    def _set_error(err: BaseException) -> None:
+        with contextlib.suppress(RuntimeError):
+            loop.call_soon_threadsafe(_reject, future, err)
+
+    def sink(messages: Messages) -> None:
+        for msg in messages:
+            t = msg[0]
+            if t is MessageType.DATA:
+                _set_result(msg[1] if len(msg) > 1 else None)
+                return
+            if t is MessageType.ERROR:
+                err = msg[1] if len(msg) > 1 else RuntimeError("node error")
+                _set_error(err)
+                return
+            if t is MessageType.COMPLETE or t is MessageType.TEARDOWN:
+                _set_error(RuntimeError("source completed without DATA"))
+                return
+
+    unsub = source.subscribe(sink)
+    try:
+        return await future
+    finally:
+        unsub()
+
+
+async def settled(source: Node[Any]) -> Any:
+    """Await until *source* has a settled (non-dirty) value.
+
+    If the node already holds a cached value and is in a settled/resolved
+    status, returns it without waiting.  Otherwise subscribes and waits for
+    the first ``DATA`` or ``RESOLVED`` message.
+
+    Raises:
+        RuntimeError: If the source completes or tears down without settling.
+        Exception: If the source emits ``ERROR``.
+
+    Example::
+
+        from graphrefly import derived, state
+        from graphrefly.compat import settled
+
+        a = state(10)
+        b = derived([a], lambda deps, _: deps[0] * 2)
+        value = await settled(b)
+        assert value == 20
+    """
+    # Fast path: already settled (see ``first_value_from_async`` for the
+    # ``is not None`` rationale).
+    status = source.status
+    if status in ("settled", "resolved"):
+        v = source.get()
+        if v is not None:
+            return v
+
+    loop = asyncio.get_running_loop()
+    future: asyncio.Future[Any] = loop.create_future()
+
+    def _set_result(value: Any) -> None:
+        with contextlib.suppress(RuntimeError):
+            loop.call_soon_threadsafe(_resolve, future, value)
+
+    def _set_error(err: BaseException) -> None:
+        with contextlib.suppress(RuntimeError):
+            loop.call_soon_threadsafe(_reject, future, err)
+
+    def sink(messages: Messages) -> None:
+        for msg in messages:
+            t = msg[0]
+            if t is MessageType.DATA:
+                _set_result(msg[1] if len(msg) > 1 else None)
+                return
+            if t is MessageType.RESOLVED:
+                _set_result(source.get())
+                return
+            if t is MessageType.ERROR:
+                err = msg[1] if len(msg) > 1 else RuntimeError("node error")
+                _set_error(err)
+                return
+            if t is MessageType.COMPLETE or t is MessageType.TEARDOWN:
+                _set_error(RuntimeError("source completed without settling"))
+                return
+
+    unsub = source.subscribe(sink)
+    try:
+        return await future
+    finally:
+        unsub()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve(future: asyncio.Future[Any], value: Any) -> None:
+    if not future.done():
+        future.set_result(value)
+
+
+def _reject(future: asyncio.Future[Any], err: BaseException) -> None:
+    if not future.done():
+        future.set_exception(err)
+
+
+__all__ = [
+    "first_value_from_async",
+    "settled",
+    "to_async_iter",
+]

graphrefly/compat/asyncio_runner.py

@@ -0,0 +1,89 @@
+"""AsyncioRunner — schedule coroutines on an asyncio event loop (roadmap §5.1)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine
+
+
+class AsyncioRunner:
+    """Runner backed by a running :mod:`asyncio` event loop.
+
+    Schedule coroutines via ``loop.create_task`` with thread-safe dispatch.
+    Use inside an ``async def`` context (e.g. FastAPI lifespan, async test).
+
+    Example::
+
+        import asyncio
+        from graphrefly.compat import AsyncioRunner
+        from graphrefly.core.runner import set_default_runner
+
+        async def main():
+            runner = AsyncioRunner.from_running()
+            set_default_runner(runner)
+            # ... build graph, use from_awaitable, etc.
+
+        asyncio.run(main())
+    """
+
+    __slots__ = ("_loop",)
+
+    def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._loop = loop
+
+    @classmethod
+    def from_running(cls) -> AsyncioRunner:
+        """Create from the currently running asyncio event loop.
+
+        Raises:
+            RuntimeError: If no event loop is running.
+        """
+        return cls(asyncio.get_running_loop())
+
+    def schedule(
+        self,
+        coro: Coroutine[Any, Any, Any],
+        on_result: Callable[[Any], None],
+        on_error: Callable[[BaseException], None],
+    ) -> Callable[[], None]:
+        task: asyncio.Task[Any] | None = None
+        cancelled = False
+
+        def _create_task() -> None:
+            nonlocal task
+            if cancelled:
+                coro.close()
+                return
+
+            async def _wrapper() -> None:
+                try:
+                    result = await coro
+                except asyncio.CancelledError:
+                    raise
+                except KeyboardInterrupt:
+                    raise
+                except SystemExit:
+                    raise
+                except BaseException as err:
+                    on_error(err)
+                else:
+                    on_result(result)
+
+            task = self._loop.create_task(_wrapper())
+
+        # Thread-safe: schedule task creation on the event loop.
+        self._loop.call_soon_threadsafe(_create_task)
+
+        def cancel() -> None:
+            nonlocal cancelled
+            cancelled = True
+            if task is not None:
+                task.cancel()
+
+        return cancel
+
+
+__all__ = ["AsyncioRunner"]

graphrefly/compat/trio_runner.py

@@ -0,0 +1,81 @@
+"""TrioRunner — schedule coroutines on a trio nursery (roadmap §5.1).
+
+Requires the ``trio`` package (optional dependency).
+
+Usage::
+
+    import trio
+    from graphrefly.compat.trio_runner import TrioRunner
+    from graphrefly.core.runner import set_default_runner
+
+    async def main():
+        async with trio.open_nursery() as nursery:
+            runner = TrioRunner(nursery)
+            set_default_runner(runner)
+            # ... build graph, use from_awaitable, etc.
+
+    trio.run(main)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine
+
+    import trio  # type: ignore[import-not-found]
+
+
+class TrioRunner:
+    """Runner backed by a :mod:`trio` nursery.
+
+    Each scheduled coroutine runs as a trio task in the nursery.
+    Cancel scopes provide best-effort cancellation.
+    """
+
+    __slots__ = ("_nursery",)
+
+    def __init__(self, nursery: trio.Nursery) -> None:
+        self._nursery = nursery
+
+    def schedule(
+        self,
+        coro: Coroutine[Any, Any, Any],
+        on_result: Callable[[Any], None],
+        on_error: Callable[[BaseException], None],
+    ) -> Callable[[], None]:
+        import trio as _trio
+
+        cancel_scope = _trio.CancelScope()
+        cancelled = False
+
+        async def _wrapper() -> None:
+            with cancel_scope:
+                if cancelled:
+                    coro.close()
+                    return
+                try:
+                    result = await coro
+                except _trio.Cancelled:
+                    raise
+                except KeyboardInterrupt:
+                    raise
+                except SystemExit:
+                    raise
+                except BaseException as err:
+                    on_error(err)
+                else:
+                    on_result(result)
+
+        self._nursery.start_soon(_wrapper)
+
+        def cancel() -> None:
+            nonlocal cancelled
+            cancelled = True
+            cancel_scope.cancel()
+
+        return cancel
+
+
+__all__ = ["TrioRunner"]

graphrefly/core/__init__.py

@@ -0,0 +1,142 @@
+"""Core node primitives and protocol types for graphrefly."""
+
+from graphrefly.core.clock import monotonic_ns, wall_clock_ns
+from graphrefly.core.dynamic_node import DynamicNodeImpl, dynamic_node
+from graphrefly.core.guard import (
+    Actor,
+    GuardAction,
+    GuardDenied,
+    GuardFn,
+    access_hint_for_guard,
+    compose_guards,
+    normalize_actor,
+    policy,
+    policy_from_rules,
+    record_mutation,
+    system_actor,
+)
+from graphrefly.core.meta import describe_node, meta_snapshot
+from graphrefly.core.node import (
+    Node,
+    NodeActions,
+    NodeFn,
+    NodeImpl,
+    NodeStatus,
+    SubscribeHints,
+    node,
+)
+from graphrefly.core.protocol import (
+    DeferWhen,
+    EmitStrategy,
+    Message,
+    Messages,
+    MessageType,
+    batch,
+    dispatch_messages,
+    emit_with_batch,
+    is_batching,
+    is_phase2_message,
+    is_terminal_message,
+    message_tier,
+    partition_for_batch,
+    propagates_to_meta,
+)
+from graphrefly.core.runner import (
+    Runner,
+    get_default_runner,
+    resolve_runner,
+    set_default_runner,
+)
+from graphrefly.core.subgraph_locks import (
+    acquire_subgraph_write_lock,
+    acquire_subgraph_write_lock_with_defer,
+    defer_down,
+    defer_set,
+    ensure_registered,
+    union_nodes,
+)
+from graphrefly.core.sugar import (
+    PipeOperator,
+    derived,
+    effect,
+    pipe,
+    producer,
+    state,
+)
+from graphrefly.core.versioning import (
+    V0,
+    V1,
+    HashFn,
+    NodeVersionInfo,
+    VersioningLevel,
+    advance_version,
+    create_versioning,
+    default_hash,
+    is_v1,
+)
+
+__all__ = [
+    "Actor",
+    "DynamicNodeImpl",
+    "DeferWhen",
+    "EmitStrategy",
+    "GuardAction",
+    "GuardDenied",
+    "GuardFn",
+    "Message",
+    "MessageType",
+    "Messages",
+    "Node",
+    "PipeOperator",
+    "NodeActions",
+    "NodeFn",
+    "NodeImpl",
+    "NodeStatus",
+    "SubscribeHints",
+    "monotonic_ns",
+    "wall_clock_ns",
+    "access_hint_for_guard",
+    "acquire_subgraph_write_lock",
+    "acquire_subgraph_write_lock_with_defer",
+    "batch",
+    "compose_guards",
+    "defer_down",
+    "defer_set",
+    "describe_node",
+    "dispatch_messages",
+    "emit_with_batch",
+    "ensure_registered",
+    "is_batching",
+    "is_phase2_message",
+    "is_terminal_message",
+    "message_tier",
+    "propagates_to_meta",
+    "meta_snapshot",
+    "node",
+    "normalize_actor",
+    "partition_for_batch",
+    "policy",
+    "policy_from_rules",
+    "record_mutation",
+    "system_actor",
+    "union_nodes",
+    "dynamic_node",
+    "Runner",
+    "get_default_runner",
+    "resolve_runner",
+    "set_default_runner",
+    "derived",
+    "effect",
+    "pipe",
+    "producer",
+    "state",
+    "V0",
+    "V1",
+    "NodeVersionInfo",
+    "VersioningLevel",
+    "HashFn",
+    "advance_version",
+    "create_versioning",
+    "default_hash",
+    "is_v1",
+]