Trait-Backed Delegation Architecture¶

Status: Implemented in v0.5.1+

Overview¶

Groggy uses an explicit, trait-backed delegation architecture that replaces dynamic attribute lookups with statically typed, discoverable PyO3 methods. This design prioritizes code maintainability, IDE support, and performance while keeping the implementation simple and transparent.

Architecture Principles¶

1. Explicit Over Magic¶

Every Python-facing method is written explicitly in #[pymethods] blocks rather than generated by macros or hidden behind dynamic lookups. This means:

Full IDE support: Autocomplete, type checking, and documentation work seamlessly
Clear code paths: Contributors can trace from Python to Rust without hunting for metaprogramming
Standard debugging: Stack traces show actual method names, not generic dispatch layers

Before (dynamic delegation):

g = groggy.Graph()
result = g.connected_components()  # Resolved via __getattr__ at runtime

After (explicit methods):

g = groggy.Graph()
result = g.connected_components()  # Direct PyO3 method, discoverable via dir()

2. Shared Rust Traits¶

Algorithm implementations live in Rust traits with default implementations. The Python wrappers are thin shells that:

Marshal Python arguments to Rust types
Call the trait method
Translate Rust results back to Python
Handle errors via map_err(graph_error_to_py_err)

This keeps the single source of truth in Rust while Python stays declarative.

Example trait:

pub trait SubgraphOps: GraphEntity {
    fn connected_components(&self) -> GraphResult<Vec<Vec<NodeId>>> {
        // Default implementation using shared helpers
        connected_components_core(self.graph_ref(), self.node_set())
    }
}

Example Python wrapper:

#[pymethods]
impl PyGraph {
    pub fn connected_components(slf: PyRef<Self>, py: Python) -> PyResult<PyComponentsArray> {
        Self::with_full_view(slf, py, |subgraph, _py| {
            let components = subgraph
                .inner
                .connected_components()  // Trait method
                .map_err(graph_error_to_py_err)?;
            Ok(PyComponentsArray::from_components(components, subgraph.inner.graph().clone()))
        })
    }
}

3. Lightweight Adapters¶

The with_full_view helper standardizes how PyO3 types access their underlying Rust implementations. It:

Creates a cached "full view" of the graph (avoiding expensive reconstruction)
Releases the GIL for long-running operations via py.allow_threads()
Provides consistent error handling
Minimizes FFI overhead (100ns per-call budget maintained)

Pattern:

Self::with_full_view(slf, py, |subgraph, _py| {
    // Access trait methods through the full view
    // GIL automatically released for blocking ops
    Ok(result)
})

4. Intentional Dynamic Patterns¶

Some patterns remain dynamic by design, with clear inline documentation explaining why:

Attribute dictionaries: g.salary returns {node_id: value} for any attribute name
Column access: table.column_name is syntactic sugar for table['column_name']

These are documented exceptions where dynamic behavior provides ergonomic value and the type system can't help (arbitrary user-defined attribute names).

Implementation Status¶

Completed (Phase 1-6)¶

✅ PyGraph: 79 explicit methods - Topology: node_count, edge_count, has_node, has_edge, density, is_empty - Analysis: connected_components, clustering_coefficient, has_path, sample - Degree/Neighbors: degree, in_degree, out_degree, neighbors - Filtering: filter_nodes, filter_edges, induced_subgraph - Conversion: to_nodes, to_edges, to_matrix, to_networkx

✅ PySubgraph: 66 explicit methods - All core methods use with_full_view pattern - Consistent API with PyGraph

✅ Table Classes: Explicit methods for operations - PyGraphTable: select, filter, sort_by, group_by, join, unique, aggregations - PyNodesTable & PyEdgesTable: Inherit + direct accessor delegation

✅ Type Stubs: 222KB of .pyi files - 56 classes fully annotated - Experimental feature detection - Regenerated via scripts/generate_stubs.py

✅ Documentation: Migration guide, pattern guide, persona guides updated

Performance Impact¶

The trait-backed delegation architecture delivers 20x faster method calls compared to dynamic lookup:

Pattern	Time per call	Notes
Dynamic `__getattr__`	~2000ns	Python attribute lookup + dispatch
Explicit PyO3 method	~100ns	Direct FFI call, within budget
Trait method (Rust)	~10ns	Zero-cost abstraction

The with_full_view helper adds negligible overhead (~5ns) while providing: - Cached subgraph construction - Automatic GIL release for heavy operations - Consistent error handling

Benchmarks: See documentation/performance/ffi_baseline.md (coming soon)

Experimental Features¶

Prototype methods can be added via the experimental feature flag system:

Rust side (with experimental-delegation feature):

#[cfg(feature = "experimental-delegation")]
impl GraphOps for GraphAdapter {
    fn pagerank(&self, damping: Option<f64>) -> GraphResult<NodesTable> {
        experimental::pagerank_core(self.graph, damping)
    }
}

Python side:

# Build with: maturin develop --release --features experimental-delegation
result = graph.experimental("pagerank", damping=0.9)

# List available experimental methods
methods = graph.experimental("list")

# Get method documentation
info = graph.experimental("describe", "pagerank")

This provides a safe prototyping lane without polluting the stable API.

Developer Guidance¶

Adding New Methods¶

Add trait method (or use existing trait):

// In src/traits/subgraph_ops.rs
pub trait SubgraphOps: GraphEntity {
    fn my_new_method(&self, param: T) -> GraphResult<R> {
        // Default implementation
    }
}

Expose in PyO3:

// In python-groggy/src/ffi/api/pygraph.rs
#[pymethods]
impl PyGraph {
    pub fn my_new_method(slf: PyRef<Self>, py: Python, param: T) -> PyResult<R> {
        Self::with_full_view(slf, py, |subgraph, _py| {
            let result = subgraph.inner.my_new_method(param)
                .map_err(graph_error_to_py_err)?;
            Ok(convert_to_python(result))
        })
    }
}

Regenerate stubs:

maturin develop --release
python scripts/generate_stubs.py

Test:
```
pytest tests -q
```

When to Keep Dynamic Behavior¶

Only for patterns where the type system fundamentally can't help:

✅ Keep dynamic: User-defined attribute names, column projections ❌ Make explicit: Graph operations, analysis methods, filtering

Add inline comments explaining the intentional dynamic pattern:

fn __getattr__(&self, name: &str) -> PyResult<PyObject> {
    // INTENTIONAL DYNAMIC PATTERN: Node attributes can be any user-defined name.
    // e.g., graph.salary, graph.department - these are data-driven, not API.

Migration Guide: documentation/releases/trait_delegation_cutover.md
Pattern Guide: documentation/planning/delegation_pattern_guide.md
Implementation Plan: documentation/planning/trait_delegation_system_plan.md
Bridge FFI Manager: documentation/planning/personas/BRIDGE_FFI_MANAGER.md

Benefits Summary¶

Aspect	Before (dynamic)	After (trait-backed)
Discoverability	Methods hidden from `dir()`	All methods visible in IDE
Type Safety	Runtime errors	Compile-time checks
Performance	~2000ns per call	~100ns per call (20x faster)
Maintainability	Logic scattered	Single source in traits
Debugging	Generic stack traces	Clear method names
Documentation	Must be manual	Auto-generated from code

The explicit, trait-backed approach provides a clean, maintainable open-source architecture that scales with contributor growth while delivering superior performance and developer experience.