rxgraph 0.6.0__tar.gz → 0.7.0__tar.gz

{rxgraph-0.6.0 → rxgraph-0.7.0}/Cargo.lock

@@ -1302,7 +1302,7 @@ checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
 [[package]]
 name = "rxgraph"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "anyhow",
  "arrow",
@@ -1310,6 +1310,8 @@ dependencies = [
  "criterion",
  "inventory",
  "pretty_assertions",
+ "pyo3",
+ "pyo3-arrow",
  "rand",
  "rayon",
  "serde",
@@ -1319,25 +1321,12 @@ dependencies = [
  "stats_alloc",
 ]
 
-[[package]]
-name = "rxgraph-py"
-version = "0.5.0"
-dependencies = [
- "anyhow",
- "arrow",
- "pyo3",
- "pyo3-arrow",
- "rayon",
- "rxgraph",
- "serde_json",
-]
-
 [[package]]
 name = "rxgraph-python"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "pyo3",
- "rxgraph-py",
+ "rxgraph",
 ]
 
 [[package]]

{rxgraph-0.6.0 → rxgraph-0.7.0}/Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/rxgraph", "crates/rxgraph-py", "crates/rxgraph-python"]
+members = ["crates/rxgraph", "crates/rxgraph-python"]
 exclude = ["examples/rust-kernel-plugin"]
 resolver = "3"
 

{rxgraph-0.6.0 → rxgraph-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rxgraph
-Version: 0.6.0
+Version: 0.7.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -185,10 +185,20 @@ result = graph.search(
 )
 ```
 
+The consumer's crate depends on `rxgraph` with the `python` feature (their own
+crate is the `cdylib` that needs pyo3's `extension-module`; rxgraph's `python`
+feature deliberately does not enable it):
+
+```toml
+[dependencies]
+rxgraph = { version = "0.6", features = ["python"] }
+pyo3 = { version = "0.28", features = ["extension-module"] }
+```
+
 The Rust side implements `rxgraph::Kernel` and ends with a small macro call:
 
 ```rust
-rxgraph_py::plugin! {
+rxgraph::plugin! {
     module = _native;
     "hop_budget" => HopBudget::from_params,
 }

{rxgraph-0.6.0 → rxgraph-0.7.0}/README.md

@@ -171,10 +171,20 @@ result = graph.search(
 )
 ```
 
+The consumer's crate depends on `rxgraph` with the `python` feature (their own
+crate is the `cdylib` that needs pyo3's `extension-module`; rxgraph's `python`
+feature deliberately does not enable it):
+
+```toml
+[dependencies]
+rxgraph = { version = "0.6", features = ["python"] }
+pyo3 = { version = "0.28", features = ["extension-module"] }
+```
+
 The Rust side implements `rxgraph::Kernel` and ends with a small macro call:
 
 ```rust
-rxgraph_py::plugin! {
+rxgraph::plugin! {
     module = _native;
     "hop_budget" => HopBudget::from_params,
 }

{rxgraph-0.6.0 → rxgraph-0.7.0}/crates/rxgraph/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rxgraph"
-version = "0.6.0"
+version = "0.7.0"
 edition.workspace = true
 rust-version.workspace = true
 description = "High-performance graph traversal engine"
@@ -22,6 +22,11 @@ anyhow.workspace = true
 arrow.workspace = true
 arrow-schema.workspace = true
 inventory.workspace = true
+# Optional: only pulled in by the `python` feature for the PyO3 binding layer.
+# `extension-module` is intentionally NOT enabled here; the final extension
+# crate (cdylib) enables it, so this stays linkable/testable as an rlib.
+pyo3 = { workspace = true, optional = true }
+pyo3-arrow = { workspace = true, optional = true }
 rand.workspace = true
 rayon.workspace = true
 serde.workspace = true
@@ -30,6 +35,12 @@ smallvec.workspace = true
 sprs.workspace = true
 stats_alloc.workspace = true
 
+[features]
+# Exposes the PyO3 binding layer (`register`, the `plugin!` macro, and pyclasses)
+# so downstream consumers can build native kernel plugins against the published
+# crate without an unpublished path-dependency.
+python = ["dep:pyo3", "dep:pyo3-arrow"]
+
 [dev-dependencies]
 criterion.workspace = true
 pretty_assertions.workspace = true

{rxgraph-0.6.0 → rxgraph-0.7.0}/crates/rxgraph/README.md

@@ -21,7 +21,7 @@ evaluates stateful traversal kernels without copying user columns out of Arrow.
 
 ```toml
 [dependencies]
-rxgraph = "0.0.5"
+rxgraph = "0.6"
 ```
 
 ## Data Model
@@ -121,8 +121,8 @@ parallelism and optional per-node intermediate state materialization.
 
 ## Python Bindings
 
-Python bindings are published separately as the `rxgraph` package on PyPI from
-the same repository. The reusable PyO3 binding layer is also available as the
-`rxgraph-py` crate. Downstream native-kernel plugins use
-`rxgraph_py::plugin!` to register kernels and build a custom extension; see
+Python bindings are published as the `rxgraph` package on PyPI. The same PyO3
+binding layer is available from this crate via the `python` feature; downstream
+native-kernel plugins enable `features = ["python"]` and use the
+`rxgraph::plugin!` macro to register kernels and build a custom extension; see
 [`examples/rust-kernel-plugin/`](../../examples/rust-kernel-plugin/README.md).

rxgraph-0.7.0/crates/rxgraph/examples/native_row_lazy.rs

@@ -0,0 +1,378 @@
+use std::{
+    cell::RefCell,
+    collections::{BTreeMap, BTreeSet},
+    sync::OnceLock,
+};
+
+use anyhow::{Context, Result};
+use rxgraph::{
+    GraphId, NodeId, RunOptions, TraversalStrategy, search_native,
+    traversal::native::{self, GraphStore, OutgoingEdge},
+};
+
+fn main() -> Result<()> {
+    let store = FraudStore::sample();
+    let result = run_search(&store, false)?;
+
+    println!(
+        "paths={} evaluated_edges={} loaded_nodes={:?} loaded_edges={:?} loaded_outgoing={:?}",
+        result.paths.len(),
+        result.stats.evaluated_edges,
+        store.loaded_nodes(),
+        store.loaded_edges(),
+        store.loaded_outgoing(),
+    );
+    for path in result.paths {
+        let labels = path
+            .nodes
+            .iter()
+            .map(|node| node.payload.label)
+            .collect::<Vec<_>>();
+        println!(
+            "path labels={labels:?} risk={} checkpoints={:?}",
+            path.state.total_risk, path.state.checkpoints
+        );
+    }
+
+    Ok(())
+}
+
+fn run_search(
+    store: &FraudStore,
+    intermediate_states: bool,
+) -> Result<native::SearchResult<'_, Account, Transfer, RiskState>> {
+    search_native(
+        store,
+        RiskKernel {
+            max_risk: 7,
+            require_checkpoint: true,
+        },
+        RunOptions {
+            start_nodes: vec![0_u64.into()],
+            strategy: TraversalStrategy::BreadthFirst,
+            intermediate_states,
+            ..RunOptions::default()
+        },
+    )
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct Account {
+    label: &'static str,
+    target: bool,
+    blocked: bool,
+    checkpoint: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct Transfer {
+    risk: u64,
+    allowed: bool,
+}
+
+#[derive(Clone, Debug)]
+struct TransferRow {
+    src: NodeId,
+    dest: NodeId,
+    transfer: Transfer,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct RiskState {
+    total_risk: u64,
+    visited: BTreeSet<NodeId>,
+    checkpoints: BTreeMap<NodeId, &'static str>,
+}
+
+#[derive(Clone, Debug)]
+struct RiskKernel {
+    max_risk: u64,
+    require_checkpoint: bool,
+}
+
+impl native::Kernel for RiskKernel {
+    type Node = Account;
+    type Edge = Transfer;
+    type State = RiskState;
+
+    fn initial_state(
+        &self,
+        cx: &native::StartCtx<'_, Self::Node, Self::Edge>,
+    ) -> Result<Self::State> {
+        let account = cx.node()?;
+        let mut visited = BTreeSet::new();
+        visited.insert(cx.id());
+        let mut checkpoints = BTreeMap::new();
+        if account.checkpoint {
+            checkpoints.insert(cx.id(), account.label);
+        }
+        Ok(RiskState {
+            total_risk: 0,
+            visited,
+            checkpoints,
+        })
+    }
+
+    fn visit(&self, cx: &native::EdgeCtx<'_, Self::Node, Self::Edge, Self::State>) -> Result<bool> {
+        let transfer = cx.edge()?;
+        let dest = cx.dest()?;
+        Ok(transfer.allowed
+            && !dest.blocked
+            && cx.state().total_risk.saturating_add(transfer.risk) <= self.max_risk)
+    }
+
+    fn next_state(
+        &self,
+        cx: &native::EdgeCtx<'_, Self::Node, Self::Edge, Self::State>,
+    ) -> Result<Self::State> {
+        let transfer = cx.edge()?;
+        let dest = cx.dest()?;
+        let mut next = cx.state().clone();
+        next.total_risk += transfer.risk;
+        next.visited.insert(cx.dest_id());
+        if dest.checkpoint {
+            next.checkpoints.insert(cx.dest_id(), dest.label);
+        }
+        Ok(next)
+    }
+
+    fn stop(&self, cx: &native::EdgeCtx<'_, Self::Node, Self::Edge, Self::State>) -> Result<bool> {
+        Ok(cx.dest()?.target && (!self.require_checkpoint || !cx.state().checkpoints.is_empty()))
+    }
+}
+
+struct FraudStore {
+    accounts: Vec<Account>,
+    transfers: Vec<TransferRow>,
+    outgoing_index: Vec<Vec<usize>>,
+    account_cache: Vec<OnceLock<Account>>,
+    transfer_cache: Vec<OnceLock<Transfer>>,
+    outgoing_cache: Vec<OnceLock<Vec<OutgoingEdge>>>,
+    account_loads: RefCell<BTreeSet<NodeId>>,
+    transfer_loads: RefCell<BTreeSet<u32>>,
+    outgoing_loads: RefCell<BTreeSet<NodeId>>,
+}
+
+impl FraudStore {
+    fn sample() -> Self {
+        let accounts = vec![
+            Account {
+                label: "origin",
+                target: false,
+                blocked: false,
+                checkpoint: false,
+            },
+            Account {
+                label: "merchant",
+                target: false,
+                blocked: false,
+                checkpoint: true,
+            },
+            Account {
+                label: "sink",
+                target: true,
+                blocked: false,
+                checkpoint: false,
+            },
+            Account {
+                label: "cold-wallet",
+                target: false,
+                blocked: false,
+                checkpoint: false,
+            },
+            Account {
+                label: "blocked",
+                target: true,
+                blocked: true,
+                checkpoint: false,
+            },
+        ];
+        let transfers = vec![
+            TransferRow {
+                src: 0,
+                dest: 1,
+                transfer: Transfer {
+                    risk: 2,
+                    allowed: true,
+                },
+            },
+            TransferRow {
+                src: 1,
+                dest: 2,
+                transfer: Transfer {
+                    risk: 4,
+                    allowed: true,
+                },
+            },
+            TransferRow {
+                src: 1,
+                dest: 4,
+                transfer: Transfer {
+                    risk: 1,
+                    allowed: true,
+                },
+            },
+            TransferRow {
+                src: 3,
+                dest: 2,
+                transfer: Transfer {
+                    risk: 1,
+                    allowed: true,
+                },
+            },
+        ];
+        Self::new(accounts, transfers)
+    }
+
+    fn new(accounts: Vec<Account>, transfers: Vec<TransferRow>) -> Self {
+        let mut outgoing_index = vec![Vec::new(); accounts.len()];
+        for (edge, transfer) in transfers.iter().enumerate() {
+            outgoing_index[transfer.src as usize].push(edge);
+        }
+        let account_cache = (0..accounts.len()).map(|_| OnceLock::new()).collect();
+        let transfer_cache = (0..transfers.len()).map(|_| OnceLock::new()).collect();
+        let outgoing_cache = (0..accounts.len()).map(|_| OnceLock::new()).collect();
+        Self {
+            accounts,
+            transfers,
+            outgoing_index,
+            account_cache,
+            transfer_cache,
+            outgoing_cache,
+            account_loads: RefCell::new(BTreeSet::new()),
+            transfer_loads: RefCell::new(BTreeSet::new()),
+            outgoing_loads: RefCell::new(BTreeSet::new()),
+        }
+    }
+
+    fn loaded_nodes(&self) -> BTreeSet<NodeId> {
+        self.account_loads.borrow().clone()
+    }
+
+    fn loaded_edges(&self) -> BTreeSet<u32> {
+        self.transfer_loads.borrow().clone()
+    }
+
+    fn loaded_outgoing(&self) -> BTreeSet<NodeId> {
+        self.outgoing_loads.borrow().clone()
+    }
+}
+
+impl GraphStore for FraudStore {
+    type Node = Account;
+    type Edge = Transfer;
+
+    fn resolve_node(&self, external: GraphId<'_>) -> Result<Option<NodeId>> {
+        Ok(match external {
+            GraphId::U64(value) if (value as usize) < self.accounts.len() => Some(value as NodeId),
+            _ => None,
+        })
+    }
+
+    fn external_node(&self, internal: NodeId) -> Result<Option<GraphId<'_>>> {
+        Ok(((internal as usize) < self.accounts.len()).then_some(GraphId::U64(internal as u64)))
+    }
+
+    fn external_edge(&self, internal: rxgraph::EdgeId) -> Result<Option<GraphId<'_>>> {
+        Ok(((internal as usize) < self.transfers.len()).then_some(GraphId::U64(internal as u64)))
+    }
+
+    fn outgoing(&self, src: NodeId) -> Result<&[OutgoingEdge]> {
+        let src_index = src as usize;
+        let edge_ids = self
+            .outgoing_index
+            .get(src_index)
+            .with_context(|| format!("node row {src} is out of range"))?;
+        let outgoing = self
+            .outgoing_cache
+            .get(src_index)
+            .context("outgoing cache row is missing")?
+            .get_or_init(|| {
+                self.outgoing_loads.borrow_mut().insert(src);
+                edge_ids
+                    .iter()
+                    .map(|&edge| OutgoingEdge {
+                        edge: edge as rxgraph::EdgeId,
+                        dest: self.transfers[edge].dest,
+                    })
+                    .collect()
+            });
+        Ok(outgoing)
+    }
+
+    fn node(&self, id: NodeId) -> Result<&Self::Node> {
+        let index = id as usize;
+        let account = self
+            .accounts
+            .get(index)
+            .with_context(|| format!("node row {id} is out of range"))?;
+        Ok(self
+            .account_cache
+            .get(index)
+            .context("account cache row is missing")?
+            .get_or_init(|| {
+                self.account_loads.borrow_mut().insert(id);
+                account.clone()
+            }))
+    }
+
+    fn edge(&self, id: rxgraph::EdgeId) -> Result<&Self::Edge> {
+        let index = id as usize;
+        let transfer = self
+            .transfers
+            .get(index)
+            .with_context(|| format!("edge row {id} is out of range"))?;
+        Ok(self
+            .transfer_cache
+            .get(index)
+            .context("transfer cache row is missing")?
+            .get_or_init(|| {
+                self.transfer_loads.borrow_mut().insert(id);
+                transfer.transfer.clone()
+            }))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn native_example_returns_native_state_and_payloads() {
+        let store = FraudStore::sample();
+        let result = run_search(&store, true).unwrap();
+
+        assert_eq!(result.paths.len(), 1);
+        let path = &result.paths[0];
+        assert_eq!(
+            path.nodes
+                .iter()
+                .map(|node| node.payload.label)
+                .collect::<Vec<_>>(),
+            vec!["origin", "merchant", "sink"]
+        );
+        assert_eq!(path.state.total_risk, 6);
+        assert_eq!(path.state.visited, BTreeSet::from([0, 1, 2]));
+        assert_eq!(path.state.checkpoints, BTreeMap::from([(1, "merchant")]));
+        assert_eq!(
+            path.nodes
+                .iter()
+                .map(|node| node.state.as_ref().unwrap().total_risk)
+                .collect::<Vec<_>>(),
+            vec![0, 2, 6]
+        );
+    }
+
+    #[test]
+    fn native_example_loads_only_reached_rows() {
+        let store = FraudStore::sample();
+        let result = run_search(&store, false).unwrap();
+
+        assert_eq!(result.stats.evaluated_edges, 3);
+        assert_eq!(store.loaded_outgoing(), BTreeSet::from([0, 1]));
+        assert_eq!(store.loaded_nodes(), BTreeSet::from([0, 1, 2, 4]));
+        assert_eq!(store.loaded_edges(), BTreeSet::from([0, 1, 2]));
+    }
+}

{rxgraph-0.6.0 → rxgraph-0.7.0}/crates/rxgraph/src/lib.rs

@@ -28,14 +28,19 @@ mod arrow;
 pub mod dsl;
 pub mod examples;
 pub mod graph;
+#[cfg(feature = "python")]
+mod python;
 pub mod traversal;
 
+#[cfg(feature = "python")]
+pub use python::register;
+
 pub use dsl::{DslExpr, DslKernel, Scalar, StateRow, Value};
 pub use graph::{EdgeId, Graph, GraphId, GraphRepo, NodeId, OwnedGraphId};
 pub use traversal::{
     BoxedRun, EdgeCtx, GraphPath, Kernel, KernelEntry, RunKernel, RunOptions, SearchResult,
     SearchStats, TraversalConfig, TraversalConfigBuilder, TraversalStrategy, boxed_run,
-    build_kernel, register_kernel,
+    build_kernel, register_kernel, search_native,
 };
 
 // Re-exported so plugin crates can register kernels without their own dependency.

rxgraph-0.6.0/crates/rxgraph-py/src/lib.rs → rxgraph-0.7.0/crates/rxgraph/src/python.rs

@@ -1,3 +1,7 @@
+use crate::{
+    DslKernel, Graph, GraphId, OwnedGraphId, RunOptions, SearchResult, SearchStats, StateRow,
+    TraversalConfigBuilder, TraversalStrategy, Value, build_kernel,
+};
 use pyo3::{
     Borrowed,
     conversion::IntoPyObjectExt,
@@ -7,10 +11,6 @@ use pyo3::{
 };
 use pyo3_arrow::PyTable;
 use rayon::ThreadPoolBuilder;
-use rxgraph::{
-    DslKernel, Graph, GraphId, OwnedGraphId, RunOptions, SearchResult, SearchStats, StateRow,
-    TraversalConfigBuilder, TraversalStrategy, Value, build_kernel,
-};
 use std::thread;
 
 /// Registers all rxgraph native classes and functions into a Python module.
@@ -37,7 +37,7 @@ pub fn register(m: &Bound<'_, PyModule>) -> PyResult<()> {
 /// `rxgraph::Kernel`.
 ///
 /// ```ignore
-/// rxgraph_py::plugin! {
+/// rxgraph::plugin! {
 ///     module = _native;
 ///     "hop_budget" => HopBudget::from_params,
 /// }
@@ -49,10 +49,10 @@ macro_rules! plugin {
         $($name:literal => $factory:expr),+ $(,)?
     ) => {
         $(
-            ::rxgraph::inventory::submit! {
-                ::rxgraph::KernelEntry {
+            $crate::inventory::submit! {
+                $crate::KernelEntry {
                     name: $name,
-                    make: |params| Ok(::rxgraph::boxed_run(($factory)(params)?)),
+                    make: |params| Ok($crate::boxed_run(($factory)(params)?)),
                 }
             }
         )+
@@ -466,7 +466,7 @@ struct PySearchPath {
 }
 
 impl PySearchPath {
-    fn from_path(_py: Python<'_>, path: rxgraph::GraphPath<'_>) -> PyResult<Self> {
+    fn from_path(_py: Python<'_>, path: crate::GraphPath<'_>) -> PyResult<Self> {
         Ok(Self {
             nodes: path.nodes.into_iter().map(GraphId::into_owned).collect(),
             edges: path.edges.into_iter().map(GraphId::into_owned).collect(),

{rxgraph-0.6.0 → rxgraph-0.7.0}/crates/rxgraph/src/traversal/mod.rs

@@ -21,6 +21,7 @@
 mod algo;
 mod config;
 mod kernel;
+pub mod native;
 mod progress;
 mod registry;
 
@@ -29,6 +30,7 @@ use crate::{dsl::StateRow, graph::GraphId};
 pub use algo::RunOptions;
 pub use config::{TraversalConfig, TraversalConfigBuilder, TraversalStrategy};
 pub use kernel::{EdgeCtx, Kernel};
+pub use native::search_native;
 pub use registry::{
     BoxedRun, KernelEntry, RunKernel, boxed_run, build_kernel, inventory, register_kernel,
 };