graphrefly 0.4.0__tar.gz → 0.5.0__tar.gz

{graphrefly-0.4.0 → graphrefly-0.5.0}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 <!-- version list -->
 
+## v0.5.0 (2026-04-05)
+
+### Chores
+
+- Fix mobile nav
+  ([`a372c40`](https://github.com/graphrefly/graphrefly-py/commit/a372c40274d1cd7ec57b69414ada245605177334))
+
+### Features
+
+- Address optimization items
+  ([`8911fd4`](https://github.com/graphrefly/graphrefly-py/commit/8911fd41a177fe9cfaa7e8932f24f2c2af44135a))
+
+
 ## v0.4.0 (2026-04-04)
 
 ### Features

{graphrefly-0.4.0 → graphrefly-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.4.0
+Version: 0.5.0
 Summary: Reactive graph protocol for human + LLM co-operation. Composable nodes, glitch-free diamond resolution, two-phase push, durable streaming. Zero dependencies.
 Project-URL: Homepage, https://py.graphrefly.dev
 Project-URL: Repository, https://github.com/graphrefly/graphrefly-py

{graphrefly-0.4.0 → graphrefly-0.5.0}/docs/optimizations.md

@@ -119,13 +119,20 @@ Union-find over node identity merges components when nodes list dependencies at
 - **`Graph.signal`:** `GuardDenied` aborts the walk on first rejection; nodes visited earlier in the traversal may already have received the message (non-transactional). Prefer guards that allow **system** `signal` when using `destroy()` / lifecycle if you need guaranteed completion.
 - **`Graph.remove` / `_teardown_mounted_graph`:** after the registry drops a name, primary `TEARDOWN` uses `Node.down(..., internal=True)` so a guard cannot reject teardown **after** unregister (would orphan the node instance).
 
+## Open design decisions
+
+- **~~Sink adapter silent error swallowing (Phase 5.2b–5.2d, noted 2026-04-04, resolved 2026-04-04):~~** All per-record sinks now return a `SinkHandle` (or `BufferedSinkHandle`) with a reactive `errors` companion node. The `_create_sink_error_handler()` factory always writes to the errors node; if a user callback is also provided, it fires first. `dispose()` sends `TEARDOWN` to the errors node. Mirrors TS implementation. Re-entrant batch drain protection applied via `contextlib.suppress(Exception)` around `errors_node.down()`.
+- **~~TS buffered sinks missing ERROR flush (Phase 5.3c, noted 2026-04-04, resolved 2026-04-04):~~** Both TS and PY buffered sinks now use `messageTier(msg[0]) >= 3` / `message_tier(msg[0]) >= 3` to flush on any terminal (COMPLETE, ERROR, TEARDOWN). Previously both used hardcoded `COMPLETE || TEARDOWN` checks and silently dropped buffered data on upstream ERROR.
+- **~~Synchronous SQLite blocking in `to_sqlite` sink (Phase 5.2b, noted 2026-04-04, resolved 2026-04-04):~~** Both TS and PY now accept `batch_insert` / `batchInsert` (default `False`) and `max_batch_size` / `maxBatchSize` (default `1000`). DATA values are buffered and flushed inside a `BEGIN`/`COMMIT` transaction on terminal messages (`message_tier >= 3`), at `max_batch_size` threshold, or on `dispose()`. On insert error, the first error triggers `break` + `ROLLBACK`. BEGIN failure preserves pending data for retry via manual `flush()`. Both return `BufferedSinkHandle` when batch mode is enabled.
+
 ---
 
 ## Cross-language implementation notes
 
 **Keep this section in sync with `graphrefly-ts/docs/optimizations.md` § Cross-language implementation notes** so you can open both files side by side.
 
-- **Storage & sink adapter pattern parity (Phase 5.2d, 2026-04-03):** All 5.2d sinks follow the same pattern in both TS and PY: duck-typed client protocols, `on_message` intercepting `DATA`, `SinkTransportError` for serialize/send failures. Buffered sinks (`to_clickhouse`, `to_s3`, `to_file`, `to_csv`) return a `BufferedSinkHandle` with `dispose()` + `flush()`. Per-record sinks (`to_postgres`, `to_mongo`, `to_loki`, `to_tempo`) return an unsubscribe callable. Checkpoint adapters (`checkpoint_to_s3`, `checkpoint_to_redis`) wire `graph.auto_checkpoint()`. PY uses `threading.Timer` for flush timers; TS uses `setTimeout`. PY `to_postgres` calls `client.execute(sql, params)` (psycopg2/3 style); TS calls `client.query(sql, params)` (pg style). PY `json.dumps` includes spaces after separators; TS `JSON.stringify` does not — NDJSON output is semantically equivalent but not byte-identical across languages.
+- **SQLite adapter parity (Phase 5.2b, 2026-04-04):** Both TS and PY use duck-typed `SqliteDbLike` with a `query(sql, params)` method — matching the `PostgresClientLike`/`ClickHouseClientLike` convention. TS `SqliteDbLike.query()` returns `unknown[]`; PY `SqliteDbLike.query()` returns `list[Any]`. Both are fully synchronous (no Promises/async). `from_sqlite`/`fromSqlite` is one-shot (DATA per row, then COMPLETE); compose with `switch_map` + `from_timer` for periodic re-query. `to_sqlite`/`toSqlite` follows per-record sink pattern (same as `to_postgres`/`toPostgres`). Default insert SQL uses JSON column; custom `to_sql` override available. TS uses `node:sqlite` `DatabaseSync` or `better-sqlite3`; PY uses stdlib `sqlite3` — both zero-dep from GraphReFly's perspective (user provides instance).
+- **Storage & sink adapter pattern parity (Phase 5.2d, 2026-04-04):** All 5.2d sinks follow the same pattern in both TS and PY: duck-typed client protocols, `on_message` intercepting `DATA`, `SinkTransportError` for serialize/send failures. All sinks return a `SinkHandle` with `dispose()` + `errors: Node[SinkTransportError | None]`. `dispose()` sends `TEARDOWN` to the errors node. Buffered sinks (`to_clickhouse`, `to_s3`, `to_file`, `to_csv`) return a `BufferedSinkHandle` adding `flush()`. TS `SinkHandle` has optional `flush?: ...`; PY uses separate `BufferedSinkHandle` dataclass (intentional — more Pythonic). Checkpoint adapters (`checkpoint_to_s3`, `checkpoint_to_redis`) wire `graph.auto_checkpoint()`. PY uses `threading.Timer` for flush timers; TS uses `setTimeout`. PY `to_postgres` calls `client.execute(sql, params)` (psycopg2/3 style); TS calls `client.query(sql, params)` (pg style). PY `json.dumps` includes spaces after separators; TS `JSON.stringify` does not — NDJSON output is semantically equivalent but not byte-identical across languages.
 
 ### 1. Message type wire encoding
 
@@ -638,7 +645,7 @@ Both ports now align on the following:
    | `from_http` external cancellation | No external signal (deferred); unsubscribe suppresses late emissions | Supports external `AbortSignal` via options | Language/runtime cancellation primitives |
    | AbortSignal on async sources | Not supported (deferred) | `signal` option on `fromTimer`, `fromPromise`, `fromAsyncIter` | TS has native AbortSignal; Py deferred |
 
-   **Resolved (2026-03-31):** When implemented, async sources (`from_timer`, `from_awaitable`, `from_async_iter`) will accept the same `CancellationToken` protocol from parity follow-up #7 (a small interface with `.is_cancelled` property and `.on_cancel(fn)` callback registration, backed by `threading.Event`). `TEARDOWN`-via-unsubscribe remains the primary cancellation path; the token is for external/cooperative cancellation. Implementation deferred until a concrete user hits the gap, but the cancellation token design is settled.
+   **Resolved (2026-03-31, implemented 2026-04-04):** `CancellationToken` protocol and `cancellation_token()` factory implemented in `core/cancellation.py`. Exported from `graphrefly.core`. Backed by `threading.Event` with lock-protected callback list, `is_cancelled` property, `on_cancel(fn)` returning an unsubscribe callable, and `cancel()` method. Wiring into async sources (`from_timer`, `from_awaitable`, `from_async_iter`) deferred — the protocol is ready. `TEARDOWN`-via-unsubscribe remains the primary cancellation path; the token is for external/cooperative cancellation.
 
 ## Resolved design decisions (cross-language, 2026-04-03)
 

{graphrefly-0.4.0 → graphrefly-0.5.0}/docs/roadmap.md

@@ -302,7 +302,7 @@ Composition layer over 3.2 (`reactive_log`), 4.1 (sagas), 4.2 (event bus), 4.3 (
 - [ ] SQLAlchemy ORM integration
 - [ ] Django ORM integration
 - [ ] Tortoise ORM integration
-- [ ] `from_sqlite(db, query)` / `to_sqlite(db, table)` — SQLite via sqlite3/better-sqlite interface
+- [x] `from_sqlite(db, query)` / `to_sqlite(db, table)` — SQLite via duck-typed `SqliteDbLike` (`query()` method); one-shot source + per-record sink; sync
 
 ### 5.3 — Adapters
 
@@ -330,14 +330,14 @@ Connectors for the universal reduction layer (Phase 8). Each wraps an external p
 
 ### 5.3c — Storage & sink adapters
 
-- [ ] `to_clickhouse(table, opts)` — buffered batch insert sink
-- [ ] `to_s3(bucket, opts)` — object storage sink (Parquet/NDJSON, partitioned; via `boto3`)
-- [ ] `to_postgres(table, opts)` / `to_mongo(collection, opts)` — document/relational sink
-- [ ] `to_loki(opts)` / `to_tempo(opts)` — Grafana stack sinks
-- [ ] `checkpoint_to_s3(bucket, opts)` — graph snapshot persistence to object storage
-- [ ] `checkpoint_to_redis(prefix, opts)` — fast checkpoint for ephemeral infra
-- [ ] `to_file(path, opts)` — file sink
-- [ ] `to_csv(path, opts)` — CSV file sink
+- [x] `to_clickhouse(table, opts)` — buffered batch insert sink
+- [x] `to_s3(bucket, opts)` — object storage sink (Parquet/NDJSON, partitioned; via `boto3`)
+- [x] `to_postgres(table, opts)` / `to_mongo(collection, opts)` — document/relational sink
+- [x] `to_loki(opts)` / `to_tempo(opts)` — Grafana stack sinks
+- [x] `checkpoint_to_s3(bucket, opts)` — graph snapshot persistence to object storage
+- [x] `checkpoint_to_redis(prefix, opts)` — fast checkpoint for ephemeral infra
+- [x] `to_file(path, opts)` — file sink
+- [x] `to_csv(path, opts)` — CSV file sink
 
 ### 5.4 — LLM tool integration
 

{graphrefly-0.4.0 → graphrefly-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.4.0"
+version = "0.5.0"
 description = "Reactive graph protocol for human + LLM co-operation. Composable nodes, glitch-free diamond resolution, two-phase push, durable streaming. Zero dependencies."
 readme = "README.md"
 license = "MIT"
@@ -60,6 +60,8 @@ dev = [
 	"croniter>=2.0",
 	"fastapi>=0.100",
 	"httpx>=0.24",
+	"pillow>=12.2.0",
+	"trio>=0.33.0",
 ]
 
 [tool.semantic_release]

{graphrefly-0.4.0 → graphrefly-0.5.0}/src/graphrefly/core/__init__.py

@@ -1,5 +1,6 @@
 """Core node primitives and protocol types for graphrefly."""
 
+from graphrefly.core.cancellation import CancellationToken, cancellation_token
 from graphrefly.core.clock import monotonic_ns, wall_clock_ns
 from graphrefly.core.dynamic_node import DynamicNodeImpl, dynamic_node
 from graphrefly.core.guard import (
@@ -77,6 +78,8 @@ from graphrefly.core.versioning import (
 
 __all__ = [
     "Actor",
+    "CancellationToken",
+    "cancellation_token",
     "DynamicNodeImpl",
     "DeferWhen",
     "EmitStrategy",

graphrefly-0.5.0/src/graphrefly/core/cancellation.py

@@ -0,0 +1,91 @@
+"""Cooperative cancellation token for async/LLM boundaries.
+
+The ``CancellationToken`` protocol provides a small interface for cooperative
+cancellation that mirrors TypeScript's ``AbortSignal`` pattern.  It is backed
+by ``threading.Event`` and is fully reactive (no polling — callbacks fire
+immediately on cancellation).
+
+Usage::
+
+    token = cancellation_token()
+    token.on_cancel(lambda: print("cancelled"))
+    token.cancel()  # fires callback synchronously
+
+Pass into ``LLMAdapter.invoke()`` via ``LLMInvokeOptions`` so adapters can
+react to cancellation without polling.
+"""
+
+from __future__ import annotations
+
+import threading
+from contextlib import suppress
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+@runtime_checkable
+class CancellationToken(Protocol):
+    """Cooperative cancellation token (cross-language: TS ``AbortSignal``)."""
+
+    @property
+    def is_cancelled(self) -> bool:
+        """Whether cancellation has been requested."""
+        ...
+
+    def on_cancel(self, fn: Callable[[], None]) -> Callable[[], None]:
+        """Register a callback to fire on cancellation.
+
+        Returns an unsubscribe callable that removes the callback.
+        If already cancelled, ``fn`` fires synchronously before returning.
+        """
+        ...
+
+
+class _CancellationTokenImpl:
+    """Concrete cancellation token backed by ``threading.Event``."""
+
+    __slots__ = ("_event", "_callbacks", "_lock")
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+        self._callbacks: list[Callable[[], None]] = []
+        self._lock = threading.Lock()
+
+    @property
+    def is_cancelled(self) -> bool:
+        return self._event.is_set()
+
+    def on_cancel(self, fn: Callable[[], None]) -> Callable[[], None]:
+        with self._lock:
+            if self._event.is_set():
+                fn()
+                return lambda: None
+            self._callbacks.append(fn)
+
+        def _unsub() -> None:
+            with self._lock, suppress(ValueError):
+                self._callbacks.remove(fn)
+
+        return _unsub
+
+    def cancel(self) -> None:
+        """Request cancellation.  Fires all registered callbacks synchronously."""
+        with self._lock:
+            if self._event.is_set():
+                return
+            self._event.set()
+            cbs = list(self._callbacks)
+            self._callbacks.clear()
+        for cb in cbs:
+            cb()
+
+
+def cancellation_token() -> _CancellationTokenImpl:
+    """Create a new cancellation token.
+
+    Returns a concrete token with ``cancel()``, ``is_cancelled``, and
+    ``on_cancel(fn)`` methods.
+    """
+    return _CancellationTokenImpl()

{graphrefly-0.4.0 → graphrefly-0.5.0}/src/graphrefly/extra/__init__.py

@@ -1,8 +1,16 @@
 """Extra operators and sources (roadmap Phase 2+)."""
 
 from graphrefly.extra.adapters import (
+    BufferedSinkHandle,
+    ClickHouseInsertClientLike,
+    FileWriterLike,
     HttpBundle,
     OTelBundle,
+    S3ClientLike,
+    SinkHandle,
+    SqliteDbLike,
+    checkpoint_to_redis,
+    checkpoint_to_s3,
     from_clickhouse_watch,
     from_csv,
     from_event_emitter,
@@ -18,6 +26,7 @@ from graphrefly.extra.adapters import (
     from_pulsar,
     from_rabbitmq,
     from_redis_stream,
+    from_sqlite,
     from_statsd,
     from_syslog,
     from_webhook,
@@ -26,12 +35,21 @@ from graphrefly.extra.adapters import (
     parse_statsd,
     parse_syslog,
     sse_frame,
+    to_clickhouse,
+    to_csv,
+    to_file,
     to_kafka,
+    to_loki,
+    to_mongo,
     to_nats,
+    to_postgres,
     to_pulsar,
     to_rabbitmq,
     to_redis_stream,
+    to_s3,
+    to_sqlite,
     to_sse,
+    to_tempo,
     to_websocket,
 )
 from graphrefly.extra.backoff import (
@@ -226,6 +244,7 @@ __all__ = [
     "from_pulsar",
     "from_rabbitmq",
     "from_redis_stream",
+    "from_sqlite",
     "from_statsd",
     "from_syslog",
     "from_websocket",
@@ -242,11 +261,28 @@ __all__ = [
     "share",
     "throw_error",
     "to_array",
+    "BufferedSinkHandle",
+    "ClickHouseInsertClientLike",
+    "FileWriterLike",
+    "S3ClientLike",
+    "SinkHandle",
+    "checkpoint_to_redis",
+    "checkpoint_to_s3",
+    "to_clickhouse",
+    "to_csv",
+    "to_file",
     "to_kafka",
+    "to_loki",
+    "to_mongo",
     "to_nats",
+    "to_postgres",
     "to_pulsar",
     "to_rabbitmq",
     "to_redis_stream",
+    "to_s3",
+    "to_sqlite",
+    "to_tempo",
+    "SqliteDbLike",
     "sse_frame",
     "to_websocket",
     "to_sse",