graphrefly 0.19.0__tar.gz → 0.20.0__tar.gz

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

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v0.20.0 (2026-04-11)
+
+### Chores
+
+- Add integrations page
+  ([`7f16d1b`](https://github.com/graphrefly/graphrefly-py/commit/7f16d1b9d9b5aadb5875e4bcb08e6decae469d1f))
+
+- Update docs
+  ([`0f2d779`](https://github.com/graphrefly/graphrefly-py/commit/0f2d779eeddcf9eec9ed339bcae4dbf6899363d3))
+
+### Features
+
+- Fix bug
+  ([`e5f9cc4`](https://github.com/graphrefly/graphrefly-py/commit/e5f9cc440a854cde0aac1060f02121b85ce06831))
+
+
 ## v0.19.0 (2026-04-10)
 
 ### Chores

{graphrefly-0.19.0 → graphrefly-0.20.0}/CLAUDE.md

@@ -14,6 +14,16 @@ uv workspace managed by mise. `mise trust && mise install` to set up uv. `uv syn
 - Format: `uv run ruff format src/ tests/`
 - Type check: `uv run mypy src/`
 
+## Documentation workflow (critical)
+
+- Follow cross-language standard in `~/src/graphrefly-ts/docs/docs-guidance.md`.
+- `website/src/content/docs/api/*.md` pages are generated; do not hand-edit.
+- For docs updates in this repo:
+  1. Update source docstrings.
+  2. Run `pnpm --dir website docs:gen`.
+  3. Validate with `pnpm --dir website docs:gen:check` and `pnpm --dir website sync-docs:check`.
+- Keep `llms.txt` concise and source-oriented; avoid long static API inventories that drift.
+
 ## Package naming
 
 - Distribution name: `graphrefly-py`
@@ -35,6 +45,9 @@ uv workspace managed by mise. `mise trust && mise install` to set up uv. `uv syn
 | 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) |
+| Reactive collaboration harness (§9.0) — 7-stage loop, gate, `promptNode`, strategy model | `~/src/graphrefly-ts/archive/docs/SESSION-reactive-collaboration-harness.md` |
+| Harness engineering strategy — 8 requirements, wave plan, MCP priority | `~/src/graphrefly-ts/archive/docs/SESSION-harness-engineering-strategy.md` |
+| Marketing & positioning — pillars, wave plan, reply playbooks, blog plan | `~/src/graphrefly-ts/archive/docs/SESSION-marketing-promotion-strategy.md` |
 | Predecessor (patterns, concurrency) | `~/src/callbag-recharge-py` (reference only, not spec) |
 
 ## Design invariants (spec §5.8–5.12)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphrefly
-Version: 0.19.0
+Version: 0.20.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
@@ -25,15 +25,15 @@ Description-Content-Type: text/markdown
 
 # GraphReFly
 
-**Describe what matters. It watches, filters, and explains — persistently.**
+**The reactive harness layer for agent workflows.** Describe in plain language, review visually, run persistently, trace every decision.
 
-You're buried under emails, alerts, feeds, and messages. You can't process it all. GraphReFly lets you describe automations in plain language, review them visually, run them persistently, and trace every decision back to its source.
+GraphReFly makes long-running human + LLM co-operation reactive, resumable, and causally explainable. State pushes downstream on change (no re-reading), nodes have lifecycles (not infinite append), and every decision has a traceable causal chain — the substrate underneath tools, agents, and personal automations.
 
 [![PyPI](https://img.shields.io/pypi/v/graphrefly?color=blue)](https://pypi.org/project/graphrefly/)
 [![license](https://img.shields.io/github/license/graphrefly/graphrefly-py)](./LICENSE)
 [![Python](https://img.shields.io/pypi/pyversions/graphrefly)](https://pypi.org/project/graphrefly/)
 
-[Docs](https://py.graphrefly.dev) | [Spec](https://py.graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [API Reference](https://py.graphrefly.dev/api/)
+[Docs](https://graphrefly.dev/py/) | [Spec](https://graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [Python API](https://graphrefly.dev/py/api/)
 
 ---
 
@@ -72,6 +72,23 @@ count.push(3)
 
 You describe what you need — an LLM composes a reactive graph (like SQL for data flows). The graph runs persistently, checkpoints its state, and traces every decision through a causal chain. Ask "why?" at any point and get a human-readable explanation from source to conclusion.
 
+## Harness engineering coverage
+
+The eight requirements of a production agent harness cluster into a handful of composed blocks that sit on top of the reactive graph primitives:
+
+| Need | GraphReFly |
+|---|---|
+| Context & state | `persistent_state()` — `auto_checkpoint` + `snapshot` / `restore` + incremental diff |
+| Agent memory | `agent_memory()` — `distill` + vectors + knowledge graph + tiers, OpenViking decay |
+| Control flow & resilience | `resilient_pipeline()` — `rate_limiter → breaker → retry → timeout → fallback`, correct ordering built in |
+| Execution & policy | `guarded_execution()` — Actor / Guard ABAC + `policy()` + `budget_gate` + scoped describe |
+| Observability & causality | `graph_lens()` — reactive topology, health, flow, and `why(node)` causal chains as structured data |
+| Human governance | `gate` — reactive `pending` / `is_open` with `approve` / `reject` / `modify(fn, n)` |
+| Verification | Multi-model eval harness with regression gates |
+| Continuous improvement | Strategy model: `root_cause × intervention → success_rate` |
+
+The library computes structured facts reactively; LLMs and UIs render them. Natural language is never the library's job — which keeps the whole stack model-agnostic and testable.
+
 ## Why GraphReFly?
 
 |  | Redux / Zustand | RxPY | Pydantic AI | LangGraph | TC39 Signals | **GraphReFly** |

{graphrefly-0.19.0 → graphrefly-0.20.0}/README.md

@@ -1,14 +1,14 @@
 # GraphReFly
 
-**Describe what matters. It watches, filters, and explains — persistently.**
+**The reactive harness layer for agent workflows.** Describe in plain language, review visually, run persistently, trace every decision.
 
-You're buried under emails, alerts, feeds, and messages. You can't process it all. GraphReFly lets you describe automations in plain language, review them visually, run them persistently, and trace every decision back to its source.
+GraphReFly makes long-running human + LLM co-operation reactive, resumable, and causally explainable. State pushes downstream on change (no re-reading), nodes have lifecycles (not infinite append), and every decision has a traceable causal chain — the substrate underneath tools, agents, and personal automations.
 
 [![PyPI](https://img.shields.io/pypi/v/graphrefly?color=blue)](https://pypi.org/project/graphrefly/)
 [![license](https://img.shields.io/github/license/graphrefly/graphrefly-py)](./LICENSE)
 [![Python](https://img.shields.io/pypi/pyversions/graphrefly)](https://pypi.org/project/graphrefly/)
 
-[Docs](https://py.graphrefly.dev) | [Spec](https://py.graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [API Reference](https://py.graphrefly.dev/api/)
+[Docs](https://graphrefly.dev/py/) | [Spec](https://graphrefly.dev/spec/) | [TypeScript](https://graphrefly.dev) | [Python API](https://graphrefly.dev/py/api/)
 
 ---
 
@@ -47,6 +47,23 @@ count.push(3)
 
 You describe what you need — an LLM composes a reactive graph (like SQL for data flows). The graph runs persistently, checkpoints its state, and traces every decision through a causal chain. Ask "why?" at any point and get a human-readable explanation from source to conclusion.
 
+## Harness engineering coverage
+
+The eight requirements of a production agent harness cluster into a handful of composed blocks that sit on top of the reactive graph primitives:
+
+| Need | GraphReFly |
+|---|---|
+| Context & state | `persistent_state()` — `auto_checkpoint` + `snapshot` / `restore` + incremental diff |
+| Agent memory | `agent_memory()` — `distill` + vectors + knowledge graph + tiers, OpenViking decay |
+| Control flow & resilience | `resilient_pipeline()` — `rate_limiter → breaker → retry → timeout → fallback`, correct ordering built in |
+| Execution & policy | `guarded_execution()` — Actor / Guard ABAC + `policy()` + `budget_gate` + scoped describe |
+| Observability & causality | `graph_lens()` — reactive topology, health, flow, and `why(node)` causal chains as structured data |
+| Human governance | `gate` — reactive `pending` / `is_open` with `approve` / `reject` / `modify(fn, n)` |
+| Verification | Multi-model eval harness with regression gates |
+| Continuous improvement | Strategy model: `root_cause × intervention → success_rate` |
+
+The library computes structured facts reactively; LLMs and UIs render them. Natural language is never the library's job — which keeps the whole stack model-agnostic and testable.
+
 ## Why GraphReFly?
 
 |  | Redux / Zustand | RxPY | Pydantic AI | LangGraph | TC39 Signals | **GraphReFly** |

graphrefly-0.20.0/llms.txt

@@ -0,0 +1,114 @@
+# GraphReFly — Python package (`graphrefly`)
+
+The reactive harness layer for agent workflows. Reactive graph runtime for human + LLM co-operation — causal tracing, persistent checkpoints, policy enforcement, zero runtime dependencies.
+
+Keywords: harness engineering, agent harness, reactive graph, causal trace, explain_path, agent orchestration, LLM co-operation, human-in-the-loop, reactive middleware, universal reduction layer.
+
+This file is an AI-oriented index for the Python repo. It points to source-of-truth docs and generated API references instead of maintaining a long, drift-prone inline API catalog.
+
+## Canonical behavior and docs authority
+
+- Behavior spec: `~/src/graphrefly/GRAPHREFLY-SPEC.md`
+- Composition guidance: `~/src/graphrefly/COMPOSITION-GUIDE.md`
+- Docs conventions (cross-language): `~/src/graphrefly-ts/docs/docs-guidance.md`
+- Roadmap/state (cross-language): `~/src/graphrefly-ts/docs/roadmap.md`
+- Testing standard (cross-language): `~/src/graphrefly-ts/docs/test-guidance.md`
+
+## Active strategy docs (cross-language, live in graphrefly-ts)
+
+- `~/src/graphrefly-ts/archive/docs/SESSION-reactive-collaboration-harness.md` — 7-stage reactive collaboration loop, gate port, `prompt_node`, `valve` rename, strategy model, `harness_loop()` factory
+- `~/src/graphrefly-ts/archive/docs/SESSION-harness-engineering-strategy.md` — 8-requirement coverage, three-wave announcement plan, MCP Server priority, eval system design
+- `~/src/graphrefly-ts/archive/docs/SESSION-marketing-promotion-strategy.md` — positioning pillars, wave plan, reply-marketing playbooks, competitive intel, prompt optimization algorithms, blog content plan
+
+## Primary links
+
+- Python docs: https://graphrefly.dev/py/
+- Python API reference: https://graphrefly.dev/py/api/
+- TypeScript docs: https://graphrefly.dev
+
+## Package entry points
+
+- Root: `from graphrefly import ...`
+- Subpackages: `graphrefly.core`, `graphrefly.graph`, `graphrefly.extra`, `graphrefly.patterns`, `graphrefly.compat`, `graphrefly.integrations`
+
+## Public API by subpackage
+
+Full export lists live in the generated API pages under `website/src/content/docs/api/`. The descriptions below explain *what lives in each subpackage and why*, so an LLM reading this cold can navigate without consuming the drift-prone catalog. Python uses snake_case (`from_timer`, `switch_map`, `agent_loop`) — the behavior parity with TypeScript holds, the naming does not.
+
+### `graphrefly.core` — `src/graphrefly/core/`
+
+The minimal reactive substrate. One primitive (`node`) plus sugar constructors (`state`, `derived`, `producer`, `effect`, `pipe`, `dynamic_node`). Protocol internals: `MessageType` enum (`DATA`, `DIRTY`, `RESOLVED`, `COMPLETE`, `ERROR`, `TEARDOWN`, `INVALIDATE`, `PAUSE`, `RESUME`), dispatch (`dispatch_messages`, `is_phase2_message`), two-phase batch semantics (`batch`, `is_batching`, `partition_for_batch`, `down_with_batch`), guard / policy (`policy`, `policy_from_rules`, `compose_guards`, `GuardDenied`, `access_hint_for_guard`), actor identity (`Actor`, `system_actor`, `normalize_actor`), meta snapshots (`meta_snapshot`, `describe_node`), versioning (`create_versioning`, `advance_version`, `default_hash`, `is_v1`), and the central clock (`monotonic_ns`, `wall_clock_ns`). **Anything outside this package must not call `time.time_ns()` / `time.monotonic_ns()` directly — use `src/graphrefly/core/clock.py`.** Also holds the `Runner` protocol and default-runner resolution (`get_default_runner`, `set_default_runner`, `resolve_runner`) for asyncio/trio backends. Thread-safety invariants (per-subgraph `RLock`, per-node `_cache_lock`) are enforced here.
+
+### `graphrefly.graph` — `src/graphrefly/graph/`
+
+The `Graph` container: reactive node registry with `register` / `resolve` / `describe` / `observe` / `snapshot` / `diff` / `diagram` / `spy` / `mount` / `unmount` / `teardown`. `reachable(graph, start_path, options=None)` computes the dependency closure from a node path — foundation for `explain_path` (causal walkback) and persistence scope.
+
+### `graphrefly.extra` — `src/graphrefly/extra/`
+
+Everything reactive that isn't the primitive. Organized into focused modules:
+
+- **Tier 1 operators** (`tier1.py`) — transform (`map`, `filter`, `scan`, `reduce`), limiting (`take`, `skip`, `take_while`, `take_until`), selection (`first`, `last`, `find`, `element_at`), utility (`start_with`, `tap`, `distinct_until_changed`, `pairwise`), combination (`combine`, `with_latest_from`), merging (`merge`, `zip`, `concat`, `race`).
+- **Tier 2 operators** (`tier2.py`) — higher-order (`switch_map`, `concat_map`, `flat_map`, `exhaust_map`), timing (`debounce`, `throttle`, `delay`), sampling (`sample`, `audit`, `timeout`), buffering (`buffer`, `buffer_count`, `buffer_time`), windowing (`window`, `window_count`, `window_time`), `interval`, `repeat`, `pausable`, `rescue`. **Note:** the existing `gate(control)` here is a boolean control gate and is being renamed to `valve` per §9.0; the new human-approval `gate` lives under `patterns.orchestration`.
+- **Sources** (`sources.py`) — synchronous (`of`, `empty`, `never`, `throw_error`, `from_iter`, `from_timer`, `from_cron`), async bridges (`from_awaitable`, `from_async_iter`), network / IO (`from_http`, `from_event_emitter`, `from_fs_watch`, `from_webhook`, `from_websocket`, `from_mcp`, `from_git_hook`), multicast / caching (`share`, `cached`, `replay`), collectors (`for_each`, `to_list`, `to_array`, `first_value_from`), sinks (`to_sse`, `to_websocket`). **All async boundaries must enter through sources** — node fns and operators never contain `async def` or raw awaitables.
+- **Data structures** (`data_structures.py` + dedicated files) — `reactive_map`, `reactive_log` + `log_slice`, `reactive_index`, `reactive_list`, `pubsub`.
+- **Resilience** (`resilience.py` + `backoff.py`) — `retry`, `circuit_breaker` + `CircuitOpenError`, `token_bucket`, `token_tracker`, `rate_limiter`, `with_breaker`, `with_status`; backoff strategies (`constant`, `linear`, `exponential`, `fibonacci`, `decorrelated_jitter`, `with_max_attempts`, `resolve_backoff_preset`).
+- **Cron** (`cron.py`) — `parse_cron`, `matches_cron`.
+- **Checkpoint** (`checkpoint.py`) — `Memory` / `Dict` / `File` / `Sqlite` adapters, `save_graph_checkpoint` / `restore_graph_checkpoint`, `checkpoint_node_value`. Auto-checkpoint is gated by `message_tier >= 3`. See `docs/ADAPTER-CONTRACT.md` for the adapter contract.
+- **Composite** (`composite.py`) — `verifiable(source, opts)` wraps a node with verification tracking; `distill(raw, extract, opts)` compacts raw data into a budget-bounded summary (the reactive memory primitive that `agent_memory` plugs into).
+- **Backpressure** (`backpressure.py`) — watermark controller for PAUSE/RESUME flow control.
+
+### `graphrefly.patterns` — `src/graphrefly/patterns/` (Phase 4+ domain APIs)
+
+Developer-facing factories that compose primitives into recognizable patterns. **Protocol internals never surface here** — sensible defaults, minimal boilerplate, clear errors. Python uses `with batch():` context managers instead of TypeScript's callback form, and `Node.__or__` maps to the TS `pipe()`.
+
+- **Orchestration** (`orchestration.py`) — `pipeline`, `task`, `branch`, the boolean control `gate` *(being renamed to `valve`)*, `approval`, `for_each`, `join`, `loop`, `sub_pipeline`, `sensor`, `wait`, `on_failure`. The §9.0 port of the human-approval gate (`pending` / `count` / `is_open` reactive nodes and `approve` / `reject` / `modify(fn, n=1)` / `open` / `close` methods) also lands here.
+- **Messaging** (`messaging.py`) — `topic` (TopicGraph), `subscription` (SubscriptionGraph with cursor / `pull` / `ack`), `job_queue`, `job_flow`, `topic_bridge`. These are the primitives the §9.0 harness loop uses for static-topology sinks and cursor-driven readers.
+- **Memory** (`memory.py`) — `collection`, `light_collection`, `vector_index`, `knowledge_graph`, `decay(source, opts)` (OpenViking exponential decay, 7-day default half-life). `decay` is the priority-scoring primitive for the §9.0 QUEUE stage.
+- **AI** (`ai.py`) — `from_llm`, `streaming_prompt_node`, `stream_extractor`, `chat_stream`, `tool_registry`, `system_prompt_builder`, `llm_extractor`, `llm_consolidator`, `agent_memory` (default: distill + vectors + KG + tiers), `agent_loop` (ReAct inner loop), `knobs_as_tools`, `gauges_as_context`, `validate_graph_def`. The §9.0 `prompt_node` factory (wraps any LLM call in a derived node with retry / cache / structured output) also lives here and is what plugs into `distill` as `extract_fn` / `consolidate_fn`.
+- **CQRS** (`cqrs.py`) — `cqrs(name, opts=None)` creates a commands / events / projections / sagas Graph.
+- **Reactive layout** (`reactive_layout/`) — `reactive_layout`, `reactive_block_layout`, `analyze_and_measure`, `compute_line_breaks`, `compute_char_positions`. DOM-free Knuth-Plass line breaking as a `state → derived` graph.
+
+### `graphrefly.compat` — `src/graphrefly/compat/`
+
+Async runner bindings. `AsyncioRunner` wraps a Graph in an asyncio event loop; `TrioRunner` does the same for trio. These are the only places allowed to orchestrate coroutines — node fns and operators stay synchronous. Runners resolve via `graphrefly.core.resolve_runner` so downstream code can inject a specific backend.
+
+### `graphrefly.integrations` — `src/graphrefly/integrations/`
+
+Framework integrations. `fastapi.GraphReflyRouter(graph)` exposes `GET /describe`, `GET /snapshot`, `WS /observe` over a registered `Graph`. Keep these thin — all logic belongs in `core` / `extra` / `patterns`.
+
+### Design docs that back the above
+
+- Phase 4+ factory authors must read `~/src/graphrefly/COMPOSITION-GUIDE.md` before composing primitives — covers lazy activation, subscription ordering, null guards, feedback cycles, `prompt_node` SENTINEL, wiring order.
+- Backlog / anti-patterns / deferred follow-ups: `~/src/graphrefly-ts/docs/optimizations.md` (cross-language).
+- Historical design decisions and parity notes: `~/src/graphrefly-ts/archive/optimizations/` (cross-language).
+
+## Generated docs workflow
+
+Python API pages are generated from docstrings:
+
+- Generator: `website/scripts/gen_api_docs.py`
+- Output: `website/src/content/docs/api/*.md`
+- Commands:
+  - `pnpm --dir website docs:gen`
+  - `pnpm --dir website docs:gen:check`
+  - `pnpm --dir website sync-docs`
+  - `pnpm --dir website sync-docs:check`
+
+Do not hand-edit generated API pages.
+
+## Core design invariants
+
+- No polling; propagation is reactive.
+- No imperative triggers outside graph/message flow.
+- No raw async primitives inside reactive layer logic.
+- Use `src/graphrefly/core/clock.py` and `message_tier` helpers for timing/tier semantics.
+- Keep Phase 4+ surfaces developer-oriented (hide protocol internals from primary API docs).
+- Thread safety: per-subgraph `RLock`, per-node `_cache_lock`; no `async def` / `Awaitable` in public APIs.
+
+## Harness engineering coverage
+
+GraphReFly covers the 8 requirements of a production agent harness — context/state control, execution boundary, control flow, verification, observability, policy/safety, human governance, continuous improvement. Mapping lives in `README.md` and `~/src/graphrefly-ts/archive/docs/SESSION-harness-engineering-strategy.md`.
+
+## Reactive collaboration loop (§9.0)
+
+`harness_loop()` wires a static topology: INTAKE → TRIAGE → QUEUE → GATE → EXECUTE → VERIFY → REFLECT. Static topology + flowing data (the Kafka insight). Humans steer via `gate.modify(fn, n)`. Strategy model (`root_cause × intervention → success_rate`) feeds TRIAGE routing. Design source: `~/src/graphrefly-ts/archive/docs/SESSION-reactive-collaboration-harness.md`.

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

@@ -1,6 +1,6 @@
 [project]
 name = "graphrefly"
-version = "0.19.0"
+version = "0.20.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"

{graphrefly-0.19.0 → graphrefly-0.20.0}/src/graphrefly/extra/tier1.py

@@ -158,13 +158,19 @@ def reduce(  # noqa: A001 — roadmap API name
     def _op(src: Node[Any]) -> Node[Any]:
         acc = [seed]
         saw_data = [False]
+        dep_has_data = [False]
 
         def compute(deps: list[Any], _actions: NodeActions) -> Any:
+            if not dep_has_data[0]:
+                return None
             saw_data[0] = True
             acc[0] = reducer(acc[0], deps[0])
             return None
 
         def on_message(msg: Any, _index: int, actions: NodeActions) -> bool:
+            if msg[0] is MessageType.DATA:
+                dep_has_data[0] = True
+                return False
             if msg[0] is MessageType.COMPLETE:
                 if not saw_data[0]:
                     acc[0] = seed
@@ -329,10 +335,13 @@ def take_while(predicate: Callable[[Any], bool]) -> PipeOperator:
 
     def _op(src: Node[Any]) -> Node[Any]:
         done = [False]
+        dep_has_data = [False]
 
         def compute(deps: list[Any], actions: NodeActions) -> Any:
             if done[0]:
                 return None
+            if not dep_has_data[0]:
+                return None
             v = deps[0]
             if not predicate(v):
                 done[0] = True
@@ -340,9 +349,15 @@ def take_while(predicate: Callable[[Any], bool]) -> PipeOperator:
                 return None
             return v
 
+        def on_message(msg: Any, _index: int, _actions: NodeActions) -> bool:
+            if msg[0] is MessageType.DATA:
+                dep_has_data[0] = True
+            return False
+
         return node(
             [src],
             compute,
+            on_message=on_message,
             describe_kind="take_while",
             complete_when_deps_complete=False,
         )
@@ -494,15 +509,14 @@ def last(*, default: Any = _LAST_NO_DEFAULT) -> PipeOperator:
                 return True
             return False
 
-        init = default if use_default else None
-        return node(
-            [src],
-            compute,
-            on_message=on_message,
-            describe_kind="last",
-            initial=init,
-            complete_when_deps_complete=False,
-        )
+        opts: dict[str, Any] = {
+            "on_message": on_message,
+            "describe_kind": "last",
+            "complete_when_deps_complete": False,
+        }
+        if use_default:
+            opts["initial"] = default
+        return node([src], compute, **opts)
 
     return _op
 

{graphrefly-0.19.0 → graphrefly-0.20.0}/src/graphrefly/extra/tier2.py

@@ -145,7 +145,6 @@ def switch_map(
     def _op(outer: Node[Any]) -> Node[Any]:
         inner_unsub: Callable[[], None] | None = None
         source_done = False
-        attached = False
 
         def clear_inner() -> None:
             nonlocal inner_unsub
@@ -154,8 +153,7 @@ def switch_map(
                 inner_unsub = None
 
         def attach(v: Any, a: NodeActions) -> None:
-            nonlocal attached, inner_unsub
-            attached = True
+            nonlocal inner_unsub
             clear_inner()
 
             def _on_inner_complete() -> None:
@@ -165,9 +163,7 @@ def switch_map(
 
             inner_unsub = _forward_inner(_as_node(fn(v)), a, _on_inner_complete)
 
-        def compute(deps: list[Any], a: NodeActions) -> Any:
-            if not attached:
-                attach(deps[0], a)
+        def compute(_deps: list[Any], _a: NodeActions) -> Any:
             return clear_inner
 
         def on_message(msg: Any, _index: int, a: NodeActions) -> bool:
@@ -240,7 +236,6 @@ def concat_map(
         queue: deque[Any] = deque()
         inner_unsub: Callable[[], None] | None = None
         source_done = False
-        attached = False
 
         def clear_inner() -> None:
             nonlocal inner_unsub
@@ -265,16 +260,12 @@ def concat_map(
             inner_unsub = _forward_inner(_as_node(fn(v)), a, _on_inner_complete)
 
         def enqueue(v: Any, a: NodeActions) -> None:
-            nonlocal attached
-            attached = True
             if max_buffer > 0 and len(queue) >= max_buffer:
                 queue.popleft()
             queue.append(v)
             try_pump(a)
 
-        def compute(deps: list[Any], a: NodeActions) -> Any:
-            if not attached:
-                enqueue(deps[0], a)
+        def compute(_deps: list[Any], _a: NodeActions) -> Any:
             return clear_inner
 
         def on_message(msg: Any, _index: int, a: NodeActions) -> bool:
@@ -355,7 +346,6 @@ def flat_map(
         source_done = False
         inner_stops: list[Callable[[], None]] = []
         buffer: deque[Any] = deque()
-        attached = False
 
         def try_complete(a: NodeActions) -> None:
             if source_done and active == 0 and len(buffer) == 0:
@@ -397,11 +387,7 @@ def flat_map(
             active = 0
             buffer.clear()
 
-        def compute(deps: list[Any], a: NodeActions) -> Any:
-            nonlocal attached
-            if not attached:
-                attached = True
-                enqueue(deps[0], a)
+        def compute(_deps: list[Any], _a: NodeActions) -> Any:
             return clear_all
 
         def on_message(msg: Any, _index: int, a: NodeActions) -> bool:
@@ -463,7 +449,6 @@ def exhaust_map(fn: Callable[[Any], Any], *, initial: Any = _UNSET) -> PipeOpera
     def _op(outer: Node[Any]) -> Node[Any]:
         inner_unsub: Callable[[], None] | None = None
         source_done = False
-        attached = False
 
         def clear_inner() -> None:
             nonlocal inner_unsub
@@ -472,8 +457,7 @@ def exhaust_map(fn: Callable[[Any], Any], *, initial: Any = _UNSET) -> PipeOpera
                 inner_unsub = None
 
         def attach(v: Any, a: NodeActions) -> None:
-            nonlocal attached, inner_unsub
-            attached = True
+            nonlocal inner_unsub
 
             def _on_inner_complete() -> None:
                 clear_inner()
@@ -482,9 +466,7 @@ def exhaust_map(fn: Callable[[Any], Any], *, initial: Any = _UNSET) -> PipeOpera
 
             inner_unsub = _forward_inner(_as_node(fn(v)), a, _on_inner_complete)
 
-        def compute(deps: list[Any], a: NodeActions) -> Any:
-            if not attached and inner_unsub is None:
-                attach(deps[0], a)
+        def compute(_deps: list[Any], _a: NodeActions) -> Any:
             return clear_inner
 
         def on_message(msg: Any, _index: int, a: NodeActions) -> bool:

{graphrefly-0.19.0 → graphrefly-0.20.0}/src/graphrefly/patterns/ai.py

@@ -11,10 +11,10 @@ import json
 import math
 import re as _re
 import threading
-from collections.abc import AsyncIterable, Iterable
+from collections.abc import AsyncIterable, Callable, Iterable
 from dataclasses import dataclass, field
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any, Protocol, cast, runtime_checkable
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast, runtime_checkable
 
 from graphrefly.core.cancellation import cancellation_token
 from graphrefly.core.clock import monotonic_ns
@@ -40,7 +40,7 @@ from graphrefly.patterns.messaging import TopicGraph, topic
 from graphrefly.patterns.orchestration import GateController, gate
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Mapping, Sequence
+    from collections.abc import Mapping, Sequence
 
     from graphrefly.core.node import NodeImpl
 
@@ -831,6 +831,121 @@ def cost_meter_extractor(
     )
 
 
+# ---------------------------------------------------------------------------
+# Composition B: Content safety pipeline
+# ---------------------------------------------------------------------------
+
+
+def redactor(
+    stream_topic: TopicGraph,
+    patterns: list[Any],
+    replace_fn: Callable[[str], str] | None = None,
+    *,
+    name: str | None = None,
+) -> Node[StreamChunk]:
+    """Stream extractor that replaces matched patterns in the accumulated text.
+
+    Returns a derived node emitting a sanitized :class:`StreamChunk` on every
+    chunk: ``accumulated`` and ``token`` have matched substrings replaced by
+    ``replace_fn``. The default ``replace_fn`` replaces with ``"[REDACTED]"``.
+
+    Compose with :func:`content_gate` for in-flight safety pipelines.
+
+    Args:
+        stream_topic: Streaming topic to monitor.
+        patterns:     List of compiled ``re.Pattern`` objects.
+        replace_fn:   ``(match: str) -> str`` replacement function.
+                      Defaults to ``lambda m: "[REDACTED]"``.
+        name:         Optional node name.
+
+    Returns:
+        Derived node emitting sanitized :class:`StreamChunk` values.
+    """
+    _replace = replace_fn if replace_fn is not None else (lambda _m: "[REDACTED]")
+
+    def _sanitize(text: str) -> str:
+        result = text
+        for pat in patterns:
+            result = pat.sub(_replace, result)
+        return result
+
+    def _compute(dep_values: list[Any], _actions: Any) -> StreamChunk:
+        chunk = dep_values[0]
+        if chunk is None:
+            return StreamChunk(source="", token="", accumulated="", index=-1)
+        c: StreamChunk = chunk
+        return StreamChunk(
+            source=c.source,
+            token=_sanitize(c.token),
+            accumulated=_sanitize(c.accumulated),
+            index=c.index,
+        )
+
+    return derived([stream_topic.latest], _compute, name=name or "redactor")
+
+
+# ---------------------------------------------------------------------------
+
+ContentDecision = Literal["allow", "review", "block"]
+
+
+def content_gate(
+    stream_topic: TopicGraph,
+    classifier: Callable[[str], float] | Node[float],
+    threshold: float,
+    *,
+    hard_multiplier: float = 1.5,
+    name: str | None = None,
+) -> Node[ContentDecision]:
+    """Derived node that classifies accumulated stream text.
+
+    Emits a three-way decision on every new chunk:
+
+    - ``"allow"`` — score below ``threshold``
+    - ``"review"`` — score in ``[threshold, threshold × hard_multiplier)``
+    - ``"block"`` — score at or above ``threshold × hard_multiplier``
+
+    Wire the output into a valve (automatic) or gate (human approval).
+    This node does not itself control flow — it classifies.
+
+    Args:
+        stream_topic:    Streaming topic to classify.
+        classifier:      ``(accumulated: str) -> float`` scoring function, or
+                         a ``Node[float]`` for live scores.
+        threshold:       Score at which output becomes ``"review"`` or
+                         ``"block"``.
+        hard_multiplier: Multiplier on ``threshold`` for ``"block"`` boundary.
+        name:            Optional node name.
+
+    Returns:
+        Derived node emitting :data:`ContentDecision`.
+    """
+    hard_threshold = threshold * hard_multiplier
+    classifier_fn: Callable[[str], float] | None = classifier if callable(classifier) else None
+    classifier_node: Node[float] | None = None if callable(classifier) else classifier
+
+    deps: list[Node[Any]] = [stream_topic.latest]
+    if classifier_node is not None:
+        deps.append(classifier_node)
+
+    def _compute(dep_values: list[Any], _actions: Any) -> ContentDecision:
+        chunk = dep_values[0]
+        if chunk is None:
+            return "allow"
+        score: float = (
+            dep_values[1] if (classifier_node is not None and len(dep_values) > 1) else 0.0
+        )
+        if classifier_fn is not None:
+            score = classifier_fn(chunk.accumulated)
+        if score >= hard_threshold:
+            return "block"
+        if score >= threshold:
+            return "review"
+        return "allow"
+
+    return derived(deps, _compute, name=name or "content-gate", initial="allow")
+
+
 # ---------------------------------------------------------------------------
 # gated_stream
 # ---------------------------------------------------------------------------