refactor(python): wrap BuilderStatus in a facade and replace "progress" callback string with show_progress

Author: Neiko2002

docs/tutorials/building_graphs.rst

@@ -155,7 +155,7 @@ To build an index from a 2D NumPy array in a single call:
        k=30,                     # Number of edges per vertex
        eps=0.1,                  # Exploration margin during build
        threads=0,                # 0 = use all available CPU cores
-       callback="progress",      # Print progress bar to stdout
+       show_progress=True,        # Print progress bar to stdout
    )
 
 ---

examples/dynamic_data/main.py

@@ -273,7 +273,7 @@ def build_dynamic_graph(
             builder.add_entry(int(all_labels[rem_idx]), base_vecs[rem_idx : rem_idx + 1])
 
     build_start = time.perf_counter()
-    builder.build(callback="progress")
+    builder.build(show_progress=True)
     build_time = time.perf_counter() - build_start
     print(f"Graph built in {build_time:.2f} seconds ({graph_mut.size()} vertices).")
 

examples/sliding_window/main.py

@@ -133,7 +133,7 @@ def run_sliding_window_benchmark(
     initial_labels = np.arange(0, window_size, dtype=np.uint32)
     initial_features = base_vectors[:window_size]
     builder.add_entry(initial_labels, initial_features)
-    builder.build(callback="progress")
+    builder.build(show_progress=True)
 
     build_time = time.perf_counter() - t0
     print(f"Initial graph built in {build_time:.2f}s (Throughput: {window_size / build_time:,.0f} vec/s)\n")

examples/static_data/main.py

@@ -194,7 +194,7 @@ def run_static_benchmark(
 
         labels = np.arange(base_vecs.shape[0], dtype=np.uint32)
         builder.add_entry(labels, base_vecs)
-        builder.build(callback="progress")
+        builder.build(show_progress=True)
 
         build_time = time.perf_counter() - build_start
         print(f"Graph built in {build_time:.2f} seconds ({graph_mut.size()} vertices).")

examples/vibe/module.py

@@ -133,7 +133,7 @@ def fit(self, X: np.ndarray, cache_dir: Path | None = None):
                 X,
                 metric=self.metric_enum,
                 threads=self.threads,
-                callback="progress",
+                show_progress=True,
             )
 
             # 2. Build graph in FP32
@@ -146,7 +146,7 @@ def fit(self, X: np.ndarray, cache_dir: Path | None = None):
                 seed=7,
                 optimization_target=self.opt_enum,
                 thread_count=self.threads,
-                callback="progress",
+                show_progress=True,
             )
 
             print(f"Saving graph to cache {cache_file}...", flush=True)
@@ -251,7 +251,7 @@ def fit(self, X: np.ndarray, cache_dir: Path | None = None):
                 X,
                 metric=self.base_metric,
                 threads=self.threads,
-                callback="progress",
+                show_progress=True,
             )
 
             # 2. Build graph in FP32
@@ -264,7 +264,7 @@ def fit(self, X: np.ndarray, cache_dir: Path | None = None):
                 seed=7,
                 optimization_target=self.opt_enum,
                 thread_count=self.threads,
-                callback="progress",
+                show_progress=True,
             )
 
             print(f"Saving graph to cache {cache_file}...", flush=True)

python/src/deglib/__init__.py

@@ -7,7 +7,7 @@
 from . import search
 from .search import Searcher, create_searcher
 
-from .builder import GraphBuilder, build_from_data
+from .builder import GraphBuilder, BuilderStatus, build_from_data
 from .graph import (
     DynamicExplorationGraph,
     create_empty,
@@ -30,6 +30,7 @@
     "load_dynamic_graph",
     "load_mutable_graph",
     "GraphBuilder",
+    "BuilderStatus",
     "build_from_data",
     "FloatSpace",
     "Metric",

python/src/deglib/builder.py

@@ -26,6 +26,74 @@ class OptimizationTarget(enum.IntEnum):
     LowLID = deglib_cpp.OptimizationTarget.LowLID
 
 
+class BuilderStatus:
+    """
+    Snapshot of the graph build progress.
+
+    Instances are created internally and passed to the ``callback`` of
+    :meth:`GraphBuilder.build`, and returned by :meth:`GraphBuilder.build`.
+    This facade wraps the native status object so that end users never have to
+    interact with the ``deglib_cpp`` bindings directly.
+
+    The instance handed to a progress ``callback`` is only valid for the
+    duration of that callback invocation.
+    """
+
+    def __init__(self, status_cpp: deglib_cpp.BuilderStatus):
+        self._status_cpp = status_cpp
+
+    @property
+    def step(self) -> int:
+        """Number of graph manipulation steps completed."""
+        return self._status_cpp.step
+
+    @property
+    def added(self) -> int:
+        """Total number of vertices added so far."""
+        return self._status_cpp.added
+
+    @property
+    def deleted(self) -> int:
+        """Total number of vertices deleted so far."""
+        return self._status_cpp.deleted
+
+    @property
+    def improved(self) -> int:
+        """Total number of successful edge improvements so far."""
+        return self._status_cpp.improved
+
+    @property
+    def tries(self) -> int:
+        """Total number of improvement attempts so far."""
+        return self._status_cpp.tries
+
+    @property
+    def step_added_ids(self):
+        """External labels added during the current build step."""
+        return self._status_cpp.step_added_ids
+
+    @property
+    def step_deleted_ids(self):
+        """External labels deleted during the current build step."""
+        return self._status_cpp.step_deleted_ids
+
+    @property
+    def total_added_ids(self):
+        """All external labels added across the entire build."""
+        return self._status_cpp.total_added_ids
+
+    @property
+    def total_deleted_ids(self):
+        """All external labels deleted across the entire build."""
+        return self._status_cpp.total_deleted_ids
+
+    def __repr__(self) -> str:
+        return (
+            f"BuilderStatus(step={self.step}, added={self.added}, deleted={self.deleted}, "
+            f"improved={self.improved}, tries={self.tries})"
+        )
+
+
 class GraphBuilder:
     """
     Constructs a GraphBuilder for building and optimizing a regular graph.
@@ -186,26 +254,33 @@ def get_batch_size(self) -> int:
         return self.builder_cpp.get_batch_size()
 
     def build(
-        self, callback: Callable[[deglib_cpp.BuilderStatus], None] | str | None = None, infinite: bool = False
-    ) -> deglib_cpp.BuilderStatus:
+        self,
+        callback: Callable[[BuilderStatus], None] | None = None,
+        show_progress: bool = False,
+        infinite: bool = False,
+    ) -> BuilderStatus:
         """
         Build the graph. This could be run on a separate thread in an infinite loop. Call stop() to end this process.
 
         :param callback: The callback that is called after each step of the build process. A BuilderStatus
-                                     is the only argument to the function.
-                                     If None nothing is printed.
-                                     If callback is the string "progress", a simple progress bar is printed to stdout.
+                                     is the only argument to the function. If None nothing is printed.
+        :param show_progress: If True and no callback is given, a simple progress bar is printed to stdout.
+                              Ignored when running in infinite mode (total workload is unknown).
         :param infinite: If set to True, blocks indefinitely, until the stop() function is called. Can be used, if
                          build() is run in a separate thread.
         :return: BuilderStatus containing build metrics and ID vectors for added/deleted vertices.
-        :rtype: deglib_cpp.BuilderStatus
+        :rtype: BuilderStatus
         """
+        if callback is None and show_progress and not infinite:
+            callback = ProgressCallback(self.get_num_new_entries(), self.get_num_remove_entries())
+
         if callback is None:
-            return self.builder_cpp.build_silent(infinite)
-        else:
-            if not infinite and callback == "progress":
-                callback = ProgressCallback(self.get_num_new_entries(), self.get_num_remove_entries())
-            return self.builder_cpp.build(callback, infinite)
+            return BuilderStatus(self.builder_cpp.build_silent(infinite))
+
+        def _callback(status_cpp) -> None:
+            callback(BuilderStatus(status_cpp))
+
+        return BuilderStatus(self.builder_cpp.build(_callback, infinite))
 
     def stop(self):
         """
@@ -241,7 +316,8 @@ def build_from_data(
     max_path_length: int = 5,
     improve_tries: int = 0,
     thread_count: int = 0,
-    callback: Callable[[deglib_cpp.BuilderStatus], None] | str | None = None,
+    callback: Callable[[BuilderStatus], None] | None = None,
+    show_progress: bool = False,
 ) -> DynamicExplorationGraph:
     """
     Create a new graph built from the given data using a GraphBuilder.
@@ -282,8 +358,10 @@ def build_from_data(
     :type improve_tries: int
     :param thread_count: Number of threads to use for parallel building. If 0, uses hardware concurrency.
     :type thread_count: int
-    :param callback: Callback function for build progress reporting. If "progress", shows progress bar
-    :type callback: Callable[[deglib_cpp.BuilderStatus], None] | str | None
+    :param callback: Callback function for build progress reporting, receiving a BuilderStatus. If None, nothing is reported.
+    :type callback: Callable[[BuilderStatus], None] | None
+    :param show_progress: If True and no callback is given, a simple progress bar is printed to stdout.
+    :type show_progress: bool
     :return: The constructed and optimized graph
     :rtype: DynamicExplorationGraph
     """
@@ -311,7 +389,7 @@ def build_from_data(
     if thread_count > 0:
         builder.set_thread_count(thread_count)
 
-    builder.build(callback=callback)
+    builder.build(callback=callback, show_progress=show_progress)
 
     return graph
 
@@ -347,15 +425,15 @@ def __init__(
         self.last_print_time = 0
         self.min_print_interval = min_print_interval
 
-    def __call__(self, builder_status: deglib_cpp.BuilderStatus):
+    def __call__(self, builder_status: BuilderStatus):
         """
         Display the current build progress as a formatted progress bar.
 
         Called by the builder during the build process to report status. Updates are throttled
         by min_print_interval to avoid excessive output, except for the final step.
 
         :param builder_status: Current status of the build process containing step counts
-        :type builder_status: deglib_cpp.BuilderStatus
+        :type builder_status: BuilderStatus
         """
         current_time = time.time()
         num_steps = builder_status.added + builder_status.deleted

python/src/deglib/optimization.py

@@ -39,10 +39,11 @@ def presort(
     space_or_metric: FloatSpace | Metric | None = None,
     radius_decay: float = 0.9,
     threads: int = 0,
-    callback: typing.Callable[[float], typing.Union[bool, None]] | str | None = None,
+    callback: typing.Callable[[float], typing.Union[bool, None]] | None = None,
     *,
     metric: Metric | None = None,
     space: FloatSpace | None = None,
+    show_progress: bool = False,
 ) -> np.ndarray:
     """
     Perform 1D pre-sorting of dataset feature vectors using Fast Linear Alignment Scheme (FLAS).
@@ -54,11 +55,11 @@ def presort(
     :param space_or_metric: FloatSpace instance or Metric type used for distance computation during sorting.
     :param radius_decay: Decay factor per iteration for neighborhood radius (default 0.9).
     :param threads: Number of worker threads (0 uses all available CPU cores).
-    :param callback: Optional callback for reporting sorting progress.
-                     If ``'progress'``, prints progress to stdout.
-                     If a function, receives progress float in range [0.0, 1.0]. Returning True cancels sorting.
+    :param callback: Optional callback for reporting sorting progress. Receives a progress float in range
+                     [0.0, 1.0]. Returning True cancels sorting.
     :param metric: Explicit Metric enum (cannot be combined with space or space_or_metric).
     :param space: Explicit FloatSpace instance (cannot be combined with metric or space_or_metric).
+    :param show_progress: If True and no callback is given, prints progress to stdout.
     :return: 1D uint32 NumPy array containing the sorted permutation of original vector indices.
     """
     # Count how many of the three ways to specify distance/space were provided
@@ -87,7 +88,9 @@ def presort(
         raise TypeError(f"Expected Metric or FloatSpace, got {type(target).__name__}")
 
     cb_fn = None
-    if callback == "progress":
+    if callback is not None:
+        cb_fn = callback
+    elif show_progress:
         last_pct = [-1]
 
         def progress_cb(prog: float) -> bool:
@@ -102,8 +105,6 @@ def progress_cb(prog: float) -> bool:
             return False
 
         cb_fn = progress_cb
-    elif callable(callback):
-        cb_fn = callback
 
     return deglib_cpp.presort(vectors_f32, cpp_space, radius_decay, threads, cb_fn)
 

python/tests/experiments.py

@@ -20,7 +20,7 @@ def main():
         vec: np.ndarray
         builder.add_entry(i, vec)
 
-    builder.build(callback="progress")
+    builder.build(show_progress=True)
 
     valid_labels = np.random.choice(graph.size(), size=5, replace=False)
 
@@ -41,7 +41,7 @@ def main2():
 
     # build index
     data = np.random.random((samples, dims)).astype(np.float32)
-    index = deglib.builder.build_from_data(data, extend_eps=0.1, callback="progress")
+    index = deglib.builder.build_from_data(data, extend_eps=0.1, show_progress=True)
 
     # search
     query = np.random.random(dims).astype(np.float32)
@@ -89,7 +89,7 @@ def do_build_with_remove(seed, edges_per_vertex):
     for label in range(0, data.shape[0], 2):
         builder.remove_entry(label)
 
-    builder.build(callback="progress")
+    builder.build(show_progress=True)
 
 
 KNOWN_CRASHES = {(1, 10)}