Release v0.2.3: Update Python bindings to require ext_edge_ids, refactor FlowPolicy construction to be config-only, and enhance FlowGraph path filtering for noise.

Author: networmix

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.3] - 2025-12-06
+
+### Changed
+
+- **Python bindings**: `StrictMultiDiGraph.from_arrays` now requires `ext_edge_ids` so callers always supply stable external edge identifiers.
+- **FlowPolicy**: construction is now config-only (via `FlowPolicyConfig`), dropping the parameter-heavy constructor.
+
+### Fixed
+
+- **FlowGraph**: `get_flow_path` now filters only below-`kEpsilon` noise so paths are reconstructed even when per-edge allocations are smaller than `kMinFlow`.
+
 ## [0.2.2] - 2025-12-05
 
 ### Fixed

Makefile

@@ -105,7 +105,6 @@ install:
 
 check:
 	@PYTHON=$(PYTHON) bash dev/run-checks.sh
-	@$(MAKE) lint
 
 check-ci:
 	@$(MAKE) lint

bindings/python/module.cpp

@@ -116,27 +116,23 @@ PYBIND11_MODULE(_netgraph_core, m) {
           [](std::int32_t num_nodes,
              py::array src, py::array dst,
              py::array capacity, py::array cost,
-             py::object ext_edge_ids_obj) {
+             py::array ext_edge_ids) {
             // public API: src/dst are int32; pass through as int32 to core
             auto src_s = as_span<std::int32_t>(src, "src");
             auto dst_s = as_span<std::int32_t>(dst, "dst");
             if (src_s.size() != dst_s.size()) throw py::type_error("src and dst must have the same length");
             auto cap_s = as_span<double>(capacity, "capacity");
             // Cost dtype must be int64 to match internal Cost type
             auto cost_s = as_span<std::int64_t>(cost, "cost");
-            // Optional ext_edge_ids
-            std::span<const std::int64_t> ext_s;
-            if (!ext_edge_ids_obj.is_none()) {
-              py::array ext_arr = ext_edge_ids_obj.cast<py::array>();
-              ext_s = as_span<std::int64_t>(ext_arr, "ext_edge_ids");
-            }
+            // ext_edge_ids required: maps internal edge indices to caller's stable IDs
+            auto ext_s = as_span<std::int64_t>(ext_edge_ids, "ext_edge_ids");
             return StrictMultiDiGraph::from_arrays(num_nodes,
                                                   src_s,
                                                   dst_s,
                                                   cap_s, cost_s, ext_s);
           },
           py::arg("num_nodes"), py::arg("src"), py::arg("dst"), py::arg("capacity"), py::arg("cost"),
-          py::kw_only(), py::arg("ext_edge_ids") = py::none())
+          py::arg("ext_edge_ids"))
       .def("num_nodes", &StrictMultiDiGraph::num_nodes)
       .def("num_edges", &StrictMultiDiGraph::num_edges)
       .def("capacity_view", [](const StrictMultiDiGraph& g){ return copy_to_numpy<double>(g.capacity_view()); })
@@ -175,13 +171,9 @@ PYBIND11_MODULE(_netgraph_core, m) {
                                           std::int32_t num_nodes,
                                           py::array src, py::array dst,
                                           py::array capacity, py::array cost,
-                                          py::object ext_edge_ids_obj){
+                                          py::array ext_edge_ids){
         // Build graph and construct shared ownership directly
-        std::span<const std::int64_t> ext_s;
-        if (!ext_edge_ids_obj.is_none()) {
-          py::array ext_arr = ext_edge_ids_obj.cast<py::array>();
-          ext_s = as_span<std::int64_t>(ext_arr, "ext_edge_ids");
-        }
+        auto ext_s = as_span<std::int64_t>(ext_edge_ids, "ext_edge_ids");
         auto sp = std::make_shared<StrictMultiDiGraph>(
             StrictMultiDiGraph::from_arrays(
                 num_nodes,
@@ -193,7 +185,7 @@ PYBIND11_MODULE(_netgraph_core, m) {
         auto gh = algs.build_graph(std::static_pointer_cast<const StrictMultiDiGraph>(sp));
         // GraphHandle holds shared ownership; no additional Python-side owner needed
         return PyGraph{ gh, py::none(), sp->num_nodes(), sp->num_edges() };
-      }, py::arg("num_nodes"), py::arg("src"), py::arg("dst"), py::arg("capacity"), py::arg("cost"), py::kw_only(), py::arg("ext_edge_ids") = py::none())
+      }, py::arg("num_nodes"), py::arg("src"), py::arg("dst"), py::arg("capacity"), py::arg("cost"), py::arg("ext_edge_ids"))
       .def("spf", [](const Algorithms& algs, const PyGraph& pg, std::int32_t src,
                        py::object dst, py::object selection_obj, py::object residual_obj,
                        py::object node_mask, py::object edge_mask, bool multipath, std::string dtype){

dev/run-checks.sh

@@ -81,14 +81,6 @@ if [ "${SKIP_CPP_TESTS:-0}" = "1" ]; then
 else
     echo "🔧 Checking for CMake to run C++ tests..."
     if command -v cmake >/dev/null 2>&1; then
-        # Quick connectivity check to GitHub for googletest download; skip if offline
-        if command -v curl >/dev/null 2>&1; then
-            if ! curl -Is --connect-timeout 5 https://github.com >/dev/null 2>&1; then
-                echo "⚠️  Network appears unavailable (github.com unreachable). Skipping C++ tests."
-                SKIP_CPP_TESTS=1
-            fi
-        fi
-
         if [ "${SKIP_CPP_TESTS:-0}" != "1" ]; then
             echo "🧪 Running C++ tests (ctest)..."
             BUILD_DIR="build/cpp-tests"

include/netgraph/core/flow_policy.hpp

@@ -92,31 +92,6 @@ class FlowPolicy {
     }
   }
 
-  FlowPolicy(const ExecutionContext& ctx,
-             PathAlg path_alg,
-             FlowPlacement flow_placement,
-             EdgeSelection selection,
-             bool require_capacity = true,
-             bool multipath = true,
-             int min_flow_count = 1,
-             std::optional<int> max_flow_count = std::nullopt,
-             std::optional<Cost> max_path_cost = std::nullopt,
-             std::optional<double> max_path_cost_factor = std::nullopt,
-             bool shortest_path = false,
-             bool reoptimize_flows_on_each_placement = false,
-             int max_no_progress_iterations = 100,
-             int max_total_iterations = 10000,
-             bool diminishing_returns_enabled = true,
-             int diminishing_returns_window = 8,
-             double diminishing_returns_epsilon_frac = 1e-3)
-    : ctx_(ctx),
-      path_alg_(path_alg), flow_placement_(flow_placement), selection_(selection),
-      require_capacity_(require_capacity), multipath_(multipath), shortest_path_(shortest_path),
-      min_flow_count_(min_flow_count), max_flow_count_(max_flow_count), max_path_cost_(max_path_cost),
-      max_path_cost_factor_(max_path_cost_factor), reoptimize_flows_on_each_placement_(reoptimize_flows_on_each_placement),
-      max_no_progress_iterations_(max_no_progress_iterations), max_total_iterations_(max_total_iterations),
-      diminishing_returns_enabled_(diminishing_returns_enabled), diminishing_returns_window_(diminishing_returns_window),
-      diminishing_returns_epsilon_frac_(diminishing_returns_epsilon_frac) {}
   ~FlowPolicy() noexcept = default;
 
   [[nodiscard]] int flow_count() const noexcept { return static_cast<int>(flows_.size()); }

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "netgraph-core"
-version = "0.2.2"
+version = "0.2.3"
 description = "C++ implementation of graph algorithms for network flow analysis and traffic engineering with Python bindings"
 readme = "README.md"
 requires-python = ">=3.9"

python/netgraph_core/__init__.py

@@ -41,7 +41,7 @@
             MinCut as MinCut,
             PredDAG as PredDAG,
         )
-except Exception:
+except ImportError:
     # Safe fallback if _docs.py changes; runtime bindings above remain authoritative.
     pass
 

python/netgraph_core/_docs.py

@@ -2,6 +2,9 @@
 
 This module is intentionally light; runtime implementations live in the
 compiled extension. The goal is to provide type hints and help text.
+
+TODO: replace this hand-written stub with generated `.pyi` (e.g. via
+pybind11-stubgen) to prevent drift from the runtime bindings.
 """
 
 from __future__ import annotations
@@ -405,8 +408,7 @@ def build_graph_from_arrays(
         dst: "np.ndarray",
         capacity: "np.ndarray",
         cost: "np.ndarray",
-        *,
-        ext_edge_ids: "Optional[np.ndarray]" = None,
+        ext_edge_ids: "np.ndarray",
     ) -> "Graph":
         """Build graph directly from arrays (graph is owned by the handle)."""
         ...

python/netgraph_core/_version.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

src/cpu_backend.cpp

@@ -24,6 +24,8 @@ class CpuBackend final : public Backend {
       const GraphHandle& gh, NodeId src, const SpfOptions& opts) override {
     const StrictMultiDiGraph& g = *gh.graph;
     // Validate mask lengths strictly; mismatches are user errors.
+    // NOTE: Keep this as the single public boundary check; deeper layers
+    // (shortest_paths) should rely on this to avoid redundant validation.
     if (!opts.node_mask.empty() && opts.node_mask.size() != static_cast<std::size_t>(g.num_nodes())) {
       throw std::invalid_argument("CpuBackend::spf: node_mask length mismatch");
     }