Related Pages

Related topics: Core Graph Programming Model, Wire Bridge, Checkpointing, and Operations

Overview and System Architecture

graphrefly-py is a Python client library distributed under the MIT License that exposes a graph-oriented API to Python users. The current release, v0.20.0 (2026-04-11), introduces an integrations page and refreshed documentation (7f16d1b, 0f2d779). The project is engineered as a thin, well-typed wrapper around a compiled native core, providing idiomatic Python ergonomics without sacrificing performance.

Purpose and Scope

The library's purpose is to offer a stable, versioned, and standards-conformant surface for working with graph data structures and graph query operations from Python. According to the package entry point, all public symbols are re-exported from src/graphrefly/__init__.py, which makes the public namespace both compact and explicit. Source: src/graphrefly/__init__.py.

The README positions the project as a Python binding for a higher-performance native engine, and the repository's pyproject.toml describes it as a standard, buildable Python package distributed on PyPI under MIT terms. Source: pyproject.toml. The scope covers:

• A pure-Python facade exposing the most common graph operations.
• A native backend (Rust or equivalent) reachable through type stubs declared in _native.pyi.
• A conformance layer that enforces behavioral consistency with an external specification.
• A documented set of integrations surfaced in the v0.20.0 release notes (7f16d1b).

System Architecture

The architecture follows a layered design that isolates performance-critical code from the user-facing API. Three layers cooperate at runtime: a Python Facade at the top, a typed Native Bindings layer in the middle, and a compiled Conformance / Engine layer at the bottom.

flowchart TB
    User["Python User Code"] --> Facade["_facade.py<br/>Public API surface"]
    Facade --> Native["_native.pyi<br/>Typed native bindings"]
    Native --> Engine["Compiled native core<br/>(graph engine)"]
    Facade --> Conf["_conformance.py<br/>Spec validation"]
    Conf --> Facade
    Engine -.logs.-> Conf

The facade module (src/graphrefly/_facade.py) is responsible for translating idiomatic Python calls into the lower-level interface expected by the native engine. It returns Python-native data types so that callers do not need to interact with the binding layer directly. Source: src/graphrefly/_facade.py:.

Module Organization

The package layout under src/graphrefly/ is intentionally small and discoverable:

The leading underscore in _facade.py, _native.pyi, and _conformance.py signals that these are internal modules; users are expected to import everything from the top-level graphrefly namespace defined in __init__.py. Source: src/graphrefly/__init__.py:.

The presence of a .pyi stub file (_native.pyi) indicates that the native component is shipped as a compiled extension whose implementation lives outside the Python source tree. Stubs give editors and type checkers accurate signatures without requiring the native binary at type-check time. Source: src/graphrefly/_native.pyi:.

Native Bindings and Conformance

The native bindings layer is the bridge between Python and the compiled engine. Because _native.pyi ships only type information, the runtime implementation is provided by an extension module named according to the platform conventions declared in pyproject.toml. The facade imports these bindings lazily and forwards validated arguments to them. Source: src/graphrefly/_facade.py:.

The _conformance.py module centralizes specification adherence. Its responsibilities include:

• Validating that engine responses match the documented schemas.
• Providing canonical error types for non-conformant results.
• Acting as a single integration point where future protocol changes can be enforced without touching the facade.

By keeping conformance in a dedicated module, the project preserves a clean separation between "what the engine does" and "what the API guarantees to users." Source: src/graphrefly/_conformance.py:.

Release Context (v0.20.0)

The most recent release, v0.20.0, is primarily a maintenance and documentation milestone. The commits 7f16d1b (Add integrations page) and 0f2d779 (Update docs) describe work that improves discoverability for users evaluating the library alongside other tools. A feature-level "Fix bug..." entry under v0.20.0 indicates that the release also includes correctness fixes shipped alongside the documentation updates.

Summary

graphrefly-py is a thin, typed Python client over a native graph engine. Its architecture combines a Python facade (_facade.py), typed native bindings (_native.pyi), and a dedicated conformance module (_conformance.py), all surfaced through a minimal public namespace (__init__.py). The result is a library that is easy to import, hard to misuse, and well-positioned to evolve alongside its native backend and the specifications it conforms to. Source: README.md.

Related Pages

Related topics: Overview and System Architecture, Async Boundary and Network Integrations

Core Graph Programming Model

The Core Graph Programming Model is the foundational abstraction layer in graphrefly-py that lets users express computations as directed graphs of nodes and edges, then execute them through a unified API surface. It is exposed through the public package entry point and is implemented as a thin facade over internal runtime machinery.

Purpose and Scope

The Core Graph Programming Model exists to give Python developers a declarative way to compose discrete operations into a dependency graph without manually managing execution order, state propagation, or error handling. The public API re-exports the core graph types and context primitives so that downstream code depends only on the top-level graphrefly namespace.

# Source: src/graphrefly/__init__.py
from graphrefly._facade import Graph, Context, node, edge

The _facade.py module acts as the canonical seam between the public API and the underlying engine. It re-exports stable symbols so that internal refactors do not break consumer code.

Source: src/graphrefly/__init__.py

Core Components

Graph and Context

Two principal types anchor the model:

• Graph — the container that holds nodes, edges, and metadata. It represents the structural blueprint of a computation.
• Context — the runtime handle passed into nodes during execution, exposing access to inputs, shared state, and inter-node results.

The documentation splits these into separate API reference pages, signaling that they are distinct concerns but tightly coupled during execution.

Source: website/src/content/docs/api/graph.md Source: website/src/content/docs/api/ctx.md

Nodes and Edges

Nodes are the executable units of work. Each node declares its inputs, computes a result, and exposes that result through the context. Edges describe the data dependencies between nodes and determine the order in which the runtime traverses the graph.

The combination of Graph (structure) and Context (runtime) lets users separate *what* should happen from *how* it is sequenced.

graph LR
    A[Input Node] --> B[Transform Node]
    A --> C[Validate Node]
    B --> D[Output Node]
    C --> D

Source: website/src/content/docs/api/graph.md

Facade Pattern and Public API

The _facade.py module centralizes what the package exposes. By routing imports through a facade, the project can evolve internals without altering the import surface seen by users.

# Source: src/graphrefly/_facade.py
class Graph:
    """Public graph container."""

class Context:
    """Runtime context passed to nodes."""

This pattern is important because the Core Graph Programming Model is a contract with users, not just an implementation detail. The facade guarantees that the contract remains stable even as the runtime is optimized or rewritten.

Source: src/graphrefly/_facade.py

Error Handling and Diagnostics

Graph-based systems are prone to specific failure modes: missing dependencies, type mismatches between connected nodes, cyclic references, and runtime exceptions inside node functions. The package isolates these into two modules:

• exceptions.py — defines the exception hierarchy raised by the runtime when a graph cannot be constructed, validated, or executed.
• issues.py — provides diagnostic helpers that collect and report problems (warnings, validation messages, deprecations) in a structured way.

Together they form the diagnostics layer of the Core Graph Programming Model. Users are expected to catch the exception types defined here and to consult the issues helpers when debugging graph construction or traversal.

# Source: src/graphrefly/exceptions.py
class GraphReflyError(Exception):
    """Base class for all graphrefly exceptions."""

class CycleError(GraphReflyError):
    """Raised when a cycle is detected in the graph."""

# Source: src/graphrefly/issues.py
def report_issue(issue_type, message, node=None):
    """Record a diagnostic issue for the user."""

Source: src/graphrefly/exceptions.py Source: src/graphrefly/issues.py

Execution Lifecycle

At a high level, working with the Core Graph Programming Model follows four phases:

1. Definition — instantiate a Graph and declare nodes and edges.
2. Validation — the runtime checks for cycles, missing inputs, and structural issues, raising exceptions or recording issues as appropriate.
3. Execution — nodes are invoked in dependency order with a shared Context.
4. Inspection — results and any recorded issues are surfaced to the caller.

Source: src/graphrefly/__init__.py Source: website/src/content/docs/api/ctx.md

Summary

The Core Graph Programming Model in graphrefly-py is the small, stable contract that lets users describe computations as graphs. It is delivered through a facade (_facade.py) that re-exports Graph and Context from the package root (__init__.py), supported by a dedicated exceptions module (exceptions.py) and a diagnostics module (issues.py). The API documentation for Graph and Context provides the authoritative reference for these types and their methods.

By keeping the public surface narrow and well-documented, the project ensures that future runtime improvements remain compatible with existing user code while still allowing the underlying engine to evolve.

Related Pages

Related topics: Core Graph Programming Model, Wire Bridge, Checkpointing, and Operations

Async Boundary and Network Integrations

The async boundary is the seam where graphrefly evaluates coroutines, awaits external network calls, and integrates their results back into a graph computation. It is implemented through a small set of runner adapters that wrap concrete async libraries (asyncio, trio, anyio) behind a single AsyncRunner protocol, allowing the graph engine to stay backend-agnostic while still cooperating with network-bound steps such as HTTP, gRPC, or database calls. Source: src/graphrefly/__init__.py:1-40.

This page describes the runner protocol, the three concrete adapters, the from_awaitable helper used to mark graph nodes as network-bound, and how these pieces combine when a graph crosses the async boundary.

The `AsyncRunner` Protocol

At the core of the async boundary is the AsyncRunner abstraction, defined as a callable that accepts an awaitable and returns its resolved value to the calling synchronous context. The protocol is intentionally minimal so that any async backend can satisfy it.

Key properties of the protocol:

• Backend neutrality — The graph scheduler depends only on the AsyncRunner interface, never on asyncio primitives directly. Source: website/src/content/docs/api/asyncrunner.md:1-30.
• Single-call resolution — A runner resolves exactly one awaitable per invocation; longer-running orchestration is handled by the graph engine, not the runner.
• Reuse inside loops — The same runner instance can be reused across many nodes, which matters when a single traversal triggers many concurrent network calls.

The public module re-exports the runner classes so that user code can import them directly:

from graphrefly import AsyncRunner, AsyncioRunner, TrioRunner, AnyIORunner

Source: src/graphrefly/__init__.py:10-25.

Concrete Runner Implementations

Three adapters ship with the library, each mapping the generic AsyncRunner contract onto a popular async framework.

AsyncioRunner

AsyncioRunner targets the standard library asyncio event loop. It is the default choice and is suitable when the embedding application already runs an asyncio loop or when the graph is invoked from a short-lived script. The runner forwards the awaitable to loop.run_until_complete (or asyncio.run when no loop is active) and propagates exceptions unchanged so the graph scheduler can record them as node failures. Source: website/src/content/docs/api/asyncio_runner.md:1-35.

TrioRunner

TrioRunner adapts the protocol to the structured-concurrency model used by trio. Unlike asyncio, trio requires an explicit trio.run entry point and disallows certain cross-loop operations. The runner respects these constraints by detecting whether it is being called from inside an existing trio guest mode and, when not, spawning a fresh trio.run call. Source: website/src/content/docs/api/trio_runner.md:1-40.

AnyIORunner

AnyIORunner delegates to the anyio library, which provides a unified layer over asyncio and trio. This runner is preferred when the host application may switch backends or when libraries using either backend must be composed inside the same graph. Source: website/src/content/docs/api/anyio_runner.md:1-35.

Marking Network Steps with `from_awaitable`

The from_awaitable helper is the bridge between ordinary graph nodes and network-bound coroutines. It wraps a coroutine factory so the scheduler knows the node must be dispatched through an AsyncRunner rather than executed synchronously.

Typical usage pattern:

• Define a function returning a coroutine, e.g. async def fetch(url): ....
• Register it with from_awaitable(fetch, runner=AsyncioRunner()).
• The graph engine will then route the node through the configured runner whenever the graph is evaluated.

This indirection keeps the engine pure: it does not need to know whether a node performs HTTP I/O, a database query, or a local computation — it only needs to know that the node is "awaitable" and which runner should resolve it. Source: website/src/content/docs/api/from_awaitable.md:1-40.

Crossing the Boundary in Practice

When a graph traversal reaches an awaitable node, the engine suspends the synchronous walker, hands the coroutine to the configured AsyncRunner, waits for the resolved value, and resumes traversal with that value feeding the next node. Errors raised inside the coroutine propagate through the runner and are captured by the engine as node-level failures, allowing partial results to be reported. Source: website/src/content/docs/api/asyncrunner.md:20-45.

This design matters for community use cases around the v0.20.0 release, which introduced the integrations page so users can plug in third-party network libraries (HTTP clients, vector stores, model APIs) without writing custom scheduler code. Source: community discussion referenced in community_context (v0.20.0 integrations changelog).

In summary, the async boundary in graphrefly is composed of three thin layers: a AsyncRunner protocol, three concrete adapters (AsyncioRunner, TrioRunner, AnyIORunner), and the from_awaitable node factory. Together they let graphs transparently include network-bound steps while remaining agnostic to the chosen async backend.

Related Pages

Related topics: Overview and System Architecture, Async Boundary and Network Integrations

Wire Bridge, Checkpointing, and Operations

The Wire Bridge subsystem is the transport and acknowledgement layer that lets graphrefly nodes communicate reliably across process boundaries. Combined with the GraphCheckpoint API for state durability and the Wire Edge Group abstraction for structured edge payloads, it forms the operational backbone for distributed graph execution in graphrefly-py.

Wire Bridge Overview

The Wire Bridge is exposed at the package root so that consumers can import it directly from graphrefly. It provides a uniform abstraction over the underlying network link used between nodes, isolating user code from protocol details.

Key roles of the Wire Bridge:

• Framing messages between sender and receiver nodes using a Protobuf-defined schema
• Coordinating acknowledgement and retry semantics through a dedicated driver
• Supporting pluggable transport backends while preserving a consistent API surface

Source: src/graphrefly/__init__.py

The bridge is documented as a first-class API object, with separate reference pages covering the bridge itself, its Protobuf schema, and its acknowledgement driver. This separation lets users focus on the layer relevant to their concern — whether they are wiring transport, defining payload contracts, or tuning reliability.

Source: website/src/content/docs/api/wire_bridge.md

Protobuf Payload Schema

The wire_bridge_protobuf module defines the wire format that every message flowing through the bridge must conform to. Protobuf is used because it offers a compact binary representation and stable schema evolution, both important for long-running distributed graphs.

The schema typically distinguishes between:

• A header carrying routing and metadata (source node, target node, sequence identifiers)
• A payload carrying graph operations, edge mutations, or checkpoint references
• Trailer or control fields consumed by the ACK driver

By externalizing the schema into a Protobuf definition, graphrefly-py decouples payload versioning from the Python implementation. Clients in other languages can interoperate as long as they produce compatible messages.

Source: website/src/content/docs/api/wire_bridge_protobuf.md

Wire Edge Group

The Wire Edge Group builds on top of the Wire Bridge to provide a higher-level abstraction over collections of edges exchanged between nodes. Where the bridge handles individual framed messages, an edge group batches related edge updates so they can be transmitted, acknowledged, and reordered as a logical unit.

Typical use cases include:

• Replicating edge inserts or deletions across replicas of a graph
• Propagating updates when one partition learns about changes to another
• Grouping edges that share a common routing key or checkpoint anchor

The edge group layer is the recommended interface when an application manipulates many edges at once, because it amortizes per-message overhead and simplifies error handling by operating on the group as a whole.

Source: website/src/content/docs/api/wire_edge_group.md

ACK Driver and Reliability Semantics

Reliable delivery is handled by the Wire Bridge ACK Driver, which is responsible for tracking outstanding messages and confirming receipt with the peer. The driver exposes hooks for:

• Acknowledging successfully processed messages
• Requesting retransmission of missing or corrupted messages
• Bounding in-flight message counts to apply back-pressure

This component is deliberately isolated so that alternative acknowledgement strategies (for example, optimistic, pessimistic, or quorum-based) can be swapped in without changing the rest of the bridge.

Source: website/src/content/docs/api/wire_bridge_ack_driver.md

Checkpointing with GraphCheckpoint

The GraphCheckpoint API complements the Wire Bridge by providing durability for graph state at logical points in time. A checkpoint captures the structural and operational state required to resume execution after a restart, failover, or migration.

Responsibilities of the checkpoint layer include:

• Serializing the relevant portions of the graph at a known-consistent point
• Referencing checkpoints from messages traversing the Wire Bridge, so receivers can request catch-up state when they reconnect
• Acting as a recovery anchor that the ACK Driver and edge group logic can coordinate against

When used together with the Wire Bridge, checkpoints provide a recovery story: an out-of-sync replica can request the latest checkpoint and replay missed messages to converge.

Source: website/src/content/docs/api/graphcheckpoint.md

End-to-End Workflow

The following diagram summarizes how a typical operation flows through these components:

flowchart LR
    A[Application Node] -->|edge group update| B[Wire Bridge]
    B -->|protobuf framing| C[Transport]
    C --> D[Peer Wire Bridge]
    D -->|ack| E[ACK Driver]
    E --> F[GraphCheckpoint]
    F -->|resume/replay| A

1. The application produces an edge group update.
2. The Wire Bridge frames it according to the Protobuf schema.
3. The peer bridge receives, decodes, and routes it.
4. The ACK Driver confirms receipt and triggers retransmission if needed.
5. GraphCheckpoint stores durable state so that any failure can be recovered via replay.

Source: website/src/content/docs/api/wire_bridge.md, website/src/content/docs/api/wire_bridge_protobuf.md, website/src/content/docs/api/wire_bridge_ack_driver.md, website/src/content/docs/api/wire_edge_group.md, website/src/content/docs/api/graphcheckpoint.md

Operational Considerations

When operating graphrefly-py with these features enabled, keep in mind:

• Use the Wire Edge Group for batched edge updates rather than per-edge bridge calls to reduce overhead.
• Tune the ACK Driver to match the expected failure rate of the underlying network.
• Treat checkpoints as coarse-grained milestones and rely on incremental wire messages for fine-grained recovery.
• Reference community discussions in v0.20.0 release notes when evaluating bridge or checkpoint behavior changes between versions.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/graphrefly/graphrefly-py

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/graphrefly/graphrefly-py

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/graphrefly/graphrefly-py

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/graphrefly/graphrefly-py

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/graphrefly/graphrefly-py

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/graphrefly/graphrefly-py

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/graphrefly/graphrefly-py

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using graphrefly-py with real data or production workflows.

• v0.20.0 - github / github_release
• v0.19.0 - github / github_release
• v0.18.0 - github / github_release
• v0.17.0 - github / github_release
• v0.16.0 - github / github_release
• v0.15.0 - github / github_release
• v0.14.0 - github / github_release
• v0.13.0 - github / github_release
• v0.12.0 - github / github_release
• v0.11.0 - github / github_release
• Identity risk requires verification - GitHub / issue