graphrefly 0.18.0__tar.gz → 0.19.0__tar.gz

{graphrefly-0.18.0 → graphrefly-0.19.0}/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 <!-- version list -->
 
+## v0.19.0 (2026-04-10)
+
+### Chores
+
+- 9.0 initial test (needs revisit)
+  ([`f47a8b4`](https://github.com/graphrefly/graphrefly-py/commit/f47a8b4d32e999d4f867465f678d576184fc111d))
+
+### Features
+
+- Add start
+  ([`4a008dc`](https://github.com/graphrefly/graphrefly-py/commit/4a008dcda7704e14be12a7111b1d0b9188c736b3))
+
+- Address optimization items
+  ([`371f9e2`](https://github.com/graphrefly/graphrefly-py/commit/371f9e25e590ded4150fd6aed7e0de3933b8f0f3))
+
+- Consolidate inspection tools
+  ([`94aa9af`](https://github.com/graphrefly/graphrefly-py/commit/94aa9af3e3d793103496bfcc71a0a4bbb38f5ea3))
+
+- Fix
+  ([`222e66f`](https://github.com/graphrefly/graphrefly-py/commit/222e66f4d8954aa772534c9fc796eea3ba30a304))
+
+- Fix async pytest
+  ([`f25ae08`](https://github.com/graphrefly/graphrefly-py/commit/f25ae0885fd824320b498fd2d923f6e4f6ebb0f5))
+
+- Fix inspection tool
+  ([`09c90f2`](https://github.com/graphrefly/graphrefly-py/commit/09c90f273613fbae1fd7987397d85d4b6fabec8d))
+
+- Fix retries and reingestions
+  ([`55d1a3d`](https://github.com/graphrefly/graphrefly-py/commit/55d1a3d0beff848a6ecefb054e42d194050d5c37))
+
+- Reusable harness patterns
+  ([`84bafbb`](https://github.com/graphrefly/graphrefly-py/commit/84bafbb8476c1d00ae373bbc757d4bf813ce16c8))
+
+
 ## v0.18.0 (2026-04-08)
 
 ### Features

graphrefly-0.19.0/CLAUDE.md

@@ -0,0 +1,48 @@
+# graphrefly-py
+
+Python implementation of the GraphReFly reactive graph protocol.
+
+**All operational docs (roadmap, optimizations, test guidance, docs guidance, skills, archive) live in `~/src/graphrefly-ts`.** See that repo's `CLAUDE.md` for the full agent context.
+
+## Commands
+
+uv workspace managed by mise. `mise trust && mise install` to set up uv. `uv sync` to install dependencies.
+
+- Test: `uv run pytest`
+- Lint: `uv run ruff check src/ tests/`
+- Lint fix: `uv run ruff check --fix src/ tests/`
+- Format: `uv run ruff format src/ tests/`
+- Type check: `uv run mypy src/`
+
+## Package naming
+
+- Distribution name: `graphrefly-py`
+- Import path: `graphrefly`
+
+## Layout
+
+- `src/graphrefly/core/` — message protocol, `node` primitive, batch, sugar constructors (Phase 0)
+- `src/graphrefly/graph/` — `Graph` container, describe/observe, snapshot (Phase 1+)
+- `src/graphrefly/extra/` — operators, sources, data structures, resilience (Phase 2–3)
+- `src/graphrefly/patterns/` — domain-layer APIs: orchestration, messaging, memory, AI, CQRS, reactive layout (Phase 4+)
+- `src/graphrefly/compat/` — async runners: asyncio, trio (Phase 5+)
+- `src/graphrefly/integrations/` — framework integrations: FastAPI (Phase 5+)
+
+## Key references
+
+| Doc | Location |
+|-----|----------|
+| Behavior spec | `~/src/graphrefly/GRAPHREFLY-SPEC.md` |
+| Composition guide | `~/src/graphrefly/COMPOSITION-GUIDE.md` |
+| Roadmap, optimizations, test/docs guidance, skills, archive | `~/src/graphrefly-ts/` (single source of truth) |
+| Predecessor (patterns, concurrency) | `~/src/callbag-recharge-py` (reference only, not spec) |
+
+## Design invariants (spec §5.8–5.12)
+
+1. **No polling.** Use reactive timer sources (`from_timer`, `from_cron`).
+2. **No imperative triggers.** Use reactive `NodeInput` signals.
+3. **No raw async primitives.** Async boundaries belong in sources and runners, not node fns.
+4. **Central timer and `message_tier`.** Use `core/clock.py`; never hardcode type checks.
+5. **Phase 4+ APIs must be developer-friendly.** No protocol internals in primary surface.
+6. **Thread safety.** Per-subgraph `RLock`, per-node `_cache_lock`. Design for GIL and free-threaded Python.
+7. **No `async def` in public APIs.** Return `Node[T]`, `Graph`, `None`, or plain synchronous values.

{graphrefly-0.18.0 → graphrefly-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.18.0
+Version: 0.19.0
 Summary: Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies.
 Project-URL: Homepage, https://py.graphrefly.dev
 Project-URL: Repository, https://github.com/graphrefly/graphrefly-py

{graphrefly-0.18.0 → graphrefly-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.18.0"
+version = "0.19.0"
 description = "Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies."
 readme = "README.md"
 license = "MIT"
@@ -90,6 +90,7 @@ quote-style = "double"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["tests"]
 asyncio_mode = "auto"
 addopts = "-m 'not benchmark'"
 markers = [

{graphrefly-0.18.0 → graphrefly-0.19.0}/src/graphrefly/__init__.py

@@ -37,7 +37,6 @@ from graphrefly.core import (
     defer_down,
     defer_set,
     derived,
-    describe_node,
     dispatch_messages,
     down_with_batch,
     dynamic_node,
@@ -47,7 +46,6 @@ from graphrefly.core import (
     is_batching,
     is_phase2_message,
     is_v1,
-    meta_snapshot,
     monotonic_ns,
     node,
     normalize_actor,
@@ -74,7 +72,6 @@ from graphrefly.graph import (
     GraphDiffResult,
     GraphObserveSource,
     ObserveResult,
-    SpyHandle,
     TraceEntry,
     reachable,
 )
@@ -93,7 +90,6 @@ __all__ = [
     "NodeVersionInfo",
     "ObserveResult",
     "PATH_SEP",
-    "SpyHandle",
     "TraceEntry",
     "V0",
     "V1",
@@ -138,13 +134,11 @@ __all__ = [
     "compose_guards",
     "defer_down",
     "defer_set",
-    "describe_node",
     "dispatch_messages",
     "down_with_batch",
     "ensure_registered",
     "is_batching",
     "is_phase2_message",
-    "meta_snapshot",
     "node",
     "normalize_actor",
     "partition_for_batch",

{graphrefly-0.18.0 → graphrefly-0.19.0}/src/graphrefly/compat/async_utils.py

@@ -11,6 +11,7 @@ import asyncio
 import contextlib
 from typing import TYPE_CHECKING, Any
 
+from graphrefly.core.node import NO_VALUE
 from graphrefly.core.protocol import MessageType
 
 if TYPE_CHECKING:
@@ -101,13 +102,11 @@ async def first_value_from_async(source: Node[Any]) -> Any:
         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``, ``""``.
+    # Uses NO_VALUE sentinel so ``None`` as a real domain value is not skipped.
     status = source.status
     if status in ("settled", "resolved"):
-        v = source.get()
-        if v is not None:
+        v = getattr(source, "_cached", NO_VALUE)
+        if v is not NO_VALUE:
             return v
 
     loop = asyncio.get_running_loop()
@@ -163,12 +162,11 @@ async def settled(source: Node[Any]) -> Any:
         value = await settled(b)
         assert value == 20
     """
-    # Fast path: already settled (see ``first_value_from_async`` for the
-    # ``is not None`` rationale).
+    # Fast path: already settled — uses NO_VALUE sentinel so ``None`` is not skipped.
     status = source.status
     if status in ("settled", "resolved"):
-        v = source.get()
-        if v is not None:
+        v = getattr(source, "_cached", NO_VALUE)
+        if v is not NO_VALUE:
             return v
 
     loop = asyncio.get_running_loop()

{graphrefly-0.18.0 → graphrefly-0.19.0}/src/graphrefly/compat/asyncio_runner.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import threading
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -29,10 +30,12 @@ class AsyncioRunner:
         asyncio.run(main())
     """
 
-    __slots__ = ("_loop",)
+    __slots__ = ("_loop", "_scheduled", "_completed")
 
     def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
         self._loop = loop
+        self._scheduled = 0
+        self._completed = 0
 
     @classmethod
     def from_running(cls) -> AsyncioRunner:
@@ -50,11 +53,12 @@ class AsyncioRunner:
         on_error: Callable[[BaseException], None],
     ) -> Callable[[], None]:
         task: asyncio.Task[Any] | None = None
-        cancelled = False
+        cancelled = threading.Event()
 
         def _create_task() -> None:
             nonlocal task
-            if cancelled:
+            if cancelled.is_set():
+                self._completed += 1
                 coro.close()
                 return
 
@@ -71,19 +75,42 @@ class AsyncioRunner:
                     on_error(err)
                 else:
                     on_result(result)
+                finally:
+                    self._completed += 1
 
             task = self._loop.create_task(_wrapper())
 
-        # Thread-safe: schedule task creation on the event loop.
-        self._loop.call_soon_threadsafe(_create_task)
+        # Increment eagerly on the calling thread so __repr__ is always consistent.
+        self._scheduled += 1
+        try:
+            self._loop.call_soon_threadsafe(_create_task)
+        except RuntimeError:
+            # Loop closed — cannot schedule; close the coroutine and balance the counter.
+            self._completed += 1
+            coro.close()
 
         def cancel() -> None:
-            nonlocal cancelled
-            cancelled = True
+            cancelled.set()
             if task is not None:
                 task.cancel()
 
         return cancel
 
+    def would_block_deadlock(self) -> bool:
+        """True if blocking the current thread would starve this runner's loop."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return False
+        return loop is self._loop
+
+    def __repr__(self) -> str:
+        pending = self._scheduled - self._completed
+        running = self._loop.is_running()
+        return (
+            f"AsyncioRunner(scheduled={self._scheduled}, completed={self._completed}, "
+            f"pending={pending}, loop_running={running})"
+        )
+
 
 __all__ = ["AsyncioRunner"]

{graphrefly-0.18.0 → graphrefly-0.19.0}/src/graphrefly/compat/trio_runner.py

@@ -8,6 +8,7 @@ Usage::
     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)
@@ -19,6 +20,7 @@ Usage::
 
 from __future__ import annotations
 
+import threading
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -34,10 +36,12 @@ class TrioRunner:
     Cancel scopes provide best-effort cancellation.
     """
 
-    __slots__ = ("_nursery",)
+    __slots__ = ("_nursery", "_scheduled", "_completed")
 
     def __init__(self, nursery: trio.Nursery) -> None:
         self._nursery = nursery
+        self._scheduled = 0
+        self._completed = 0
 
     def schedule(
         self,
@@ -48,11 +52,12 @@ class TrioRunner:
         import trio as _trio
 
         cancel_scope = _trio.CancelScope()
-        cancelled = False
+        cancelled = threading.Event()
 
         async def _wrapper() -> None:
             with cancel_scope:
-                if cancelled:
+                if cancelled.is_set():
+                    self._completed += 1
                     coro.close()
                     return
                 try:
@@ -67,15 +72,34 @@ class TrioRunner:
                     on_error(err)
                 else:
                     on_result(result)
+                finally:
+                    self._completed += 1
 
+        self._scheduled += 1
         self._nursery.start_soon(_wrapper)
 
         def cancel() -> None:
-            nonlocal cancelled
-            cancelled = True
+            cancelled.set()
             cancel_scope.cancel()
 
         return cancel
 
+    def would_block_deadlock(self) -> bool:
+        """True if blocking the current thread would starve the trio nursery."""
+        try:
+            import trio as _trio
+
+            _trio.lowlevel.current_trio_token()
+            return True
+        except RuntimeError:
+            return False
+
+    def __repr__(self) -> str:
+        pending = self._scheduled - self._completed
+        return (
+            f"TrioRunner(scheduled={self._scheduled}, completed={self._completed}, "
+            f"pending={pending})"
+        )
+
 
 __all__ = ["TrioRunner"]

{graphrefly-0.18.0 → graphrefly-0.19.0}/src/graphrefly/core/__init__.py

@@ -17,7 +17,6 @@ from graphrefly.core.guard import (
     record_mutation,
     system_actor,
 )
-from graphrefly.core.meta import describe_node, meta_snapshot
 from graphrefly.core.node import (
     NO_VALUE,
     Node,
@@ -112,7 +111,6 @@ __all__ = [
     "compose_guards",
     "defer_down",
     "defer_set",
-    "describe_node",
     "dispatch_messages",
     "down_with_batch",
     "ensure_registered",
@@ -121,7 +119,6 @@ __all__ = [
     "is_terminal_message",
     "message_tier",
     "propagates_to_meta",
-    "meta_snapshot",
     "node",
     "normalize_actor",
     "partition_for_batch",