# https://github.com/graphrefly/graphrefly-py Project Manual

Generated at: 2026-07-05 08:08:33 UTC

## Table of Contents

- [Overview and System Architecture](#page-1)
- [Core Graph Programming Model](#page-2)
- [Async Boundary and Network Integrations](#page-3)
- [Wire Bridge, Checkpointing, and Operations](#page-4)

<a id='page-1'></a>

## Overview and System Architecture

### Related Pages

Related topics: [Core Graph Programming Model](#page-2), [Wire Bridge, Checkpointing, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/graphrefly/graphrefly-py/blob/main/README.md)
- [src/graphrefly/__init__.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/__init__.py)
- [src/graphrefly/_facade.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/_facade.py)
- [src/graphrefly/_native.pyi](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/_native.pyi)
- [src/graphrefly/_conformance.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/_conformance.py)
- [pyproject.toml](https://github.com/graphrefly/graphrefly-py/blob/main/pyproject.toml)
</details>

# 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.

```mermaid
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:

| Module | Role |
| --- | --- |
| `__init__.py` | Re-exports the public API and package metadata. |
| `_facade.py` | Implements the user-facing wrapper functions and classes. |
| `_native.pyi` | Declares type signatures for the native extension module. |
| `_conformance.py` | Encapsulates specification checks and behavioral contracts. |

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]()`.

---

<a id='page-2'></a>

## Core Graph Programming Model

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [Async Boundary and Network Integrations](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/graphrefly/__init__.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/__init__.py)
- [src/graphrefly/_facade.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/_facade.py)
- [src/graphrefly/exceptions.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/exceptions.py)
- [src/graphrefly/issues.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/issues.py)
- [website/src/content/docs/api/graph.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/graph.md)
- [website/src/content/docs/api/ctx.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/ctx.md)
</details>

# 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.

```python
# 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.

```mermaid
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.

```python
# 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.

```python
# 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."""
```

```python
# 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.

| Phase | Primary Type | Common Failure Mode |
|-------|--------------|---------------------|
| Definition | `Graph` | Invalid edge reference |
| Validation | `Graph`, `issues` | Cycle detected |
| Execution | `Context` | Node raised exception |
| Inspection | `Context`, `issues` | Missing output |

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.

---

<a id='page-3'></a>

## Async Boundary and Network Integrations

### Related Pages

Related topics: [Core Graph Programming Model](#page-2), [Wire Bridge, Checkpointing, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/graphrefly/__init__.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/__init__.py)
- [website/src/content/docs/api/asyncrunner.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/asyncrunner.md)
- [website/src/content/docs/api/asyncio_runner.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/asyncio_runner.md)
- [website/src/content/docs/api/trio_runner.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/trio_runner.md)
- [website/src/content/docs/api/anyio_runner.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/anyio_runner.md)
- [website/src/content/docs/api/from_awaitable.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/from_awaitable.md)
</details>

# 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]().

| Runner | Backend | Best for | Notable constraint |
|--------|---------|----------|--------------------|
| `AsyncioRunner` | `asyncio` | Default, scripts, FastAPI | Assumes a single loop |
| `TrioRunner` | `trio` | Structured concurrency | Needs `trio.run` boundary |
| `AnyIORunner` | `anyio` | Backend-portable code | Requires `anyio` installed |

## 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.

---

<a id='page-4'></a>

## Wire Bridge, Checkpointing, and Operations

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [Async Boundary and Network Integrations](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/graphrefly/__init__.py](https://github.com/graphrefly/graphrefly-py/blob/main/src/graphrefly/__init__.py)
- [website/src/content/docs/api/wire_bridge.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/wire_bridge.md)
- [website/src/content/docs/api/wire_bridge_protobuf.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/wire_bridge_protobuf.md)
- [website/src/content/docs/api/wire_edge_group.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/wire_edge_group.md)
- [website/src/content/docs/api/wire_bridge_ack_driver.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/wire_bridge_ack_driver.md)
- [website/src/content/docs/api/graphcheckpoint.md](https://github.com/graphrefly/graphrefly-py/blob/main/website/src/content/docs/api/graphcheckpoint.md)
</details>

# 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:

```mermaid
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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: graphrefly/graphrefly-py

Summary: 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
- Evidence strength: runtime_trace
- 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.
- Repro command: `pip install graphrefly`
- Evidence: identity.distribution | https://github.com/graphrefly/graphrefly-py

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/graphrefly/graphrefly-py

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/graphrefly/graphrefly-py

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/graphrefly/graphrefly-py

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/graphrefly/graphrefly-py

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/graphrefly/graphrefly-py

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/graphrefly/graphrefly-py

<!-- canonical_name: graphrefly/graphrefly-py; human_manual_source: deepwiki_human_wiki -->