fix(distance): include <stdexcept> for std::runtime_error and format example Python files

- Add missing <stdexcept> headers in distance kernel files (fp16_ip, fp32_ip, fp32_l2, uint8_l2) to fix Clang/macOS/Linux builds
- Add root ruff.toml configuration
- Reformat Python example scripts with Ruff

Author: Neiko2002

cpp/deglib/include/deglib/distance/fp16_ip.h

@@ -4,6 +4,7 @@
 #include "deglib/distance/residual_mode.h"
 
 #include <cmath>
+#include <stdexcept>
 #include <variant>
 
 namespace deglib::distances::fp16_ip {

cpp/deglib/include/deglib/distance/fp32_ip.h

@@ -3,6 +3,7 @@
 #include "deglib/distance/residual_mode.h"
 
 #include <cmath>
+#include <stdexcept>
 #include <variant>
 
 namespace deglib::distances::fp32_ip {

cpp/deglib/include/deglib/distance/fp32_l2.h

@@ -3,6 +3,7 @@
 #include "deglib/distance/residual_mode.h"
 
 #include <cmath>
+#include <stdexcept>
 #include <variant>
 
 namespace deglib::distances::fp32_l2 {

cpp/deglib/include/deglib/distance/uint8_l2.h

@@ -3,6 +3,7 @@
 #include "deglib/distance/residual_mode.h"
 #include "deglib/distance/uint8.h"
 
+#include <stdexcept>
 #include <variant>
 
 namespace deglib::distances::uint8_l2 {

examples/dynamic_data/dataset_utils.py

@@ -13,9 +13,11 @@ def ivecs_read(filename: str | Path) -> np.ndarray:
     d = a[0]
     return a.reshape(-1, d + 1)[:, 1:].copy()
 
+
 def fvecs_read(filename: str | Path) -> np.ndarray:
     return ivecs_read(filename).view(np.float32)
 
+
 DATASET_METADATA: Dict[str, Dict[str, Any]] = {
     "sift1m": {
         "name": "SIFT1M",
@@ -84,9 +86,11 @@ def fvecs_read(filename: str | Path) -> np.ndarray:
     },
 }
 
+
 def resolve_dataset_key(key: str) -> str:
     return key.lower()
 
+
 def get_default_cache_dir() -> Path:
     """Returns the default dataset cache directory (~/.cache/deg_datasets or DEG_CACHE_DIR)."""
     env_dir = os.environ.get("DEG_CACHE_DIR")
@@ -97,6 +101,7 @@ def get_default_cache_dir() -> Path:
     path.mkdir(parents=True, exist_ok=True)
     return path
 
+
 def download_file(url: str, dest_path: Path):
     """Downloads a file from url to dest_path with progress indication."""
     print(f"Downloading {url} to {dest_path}...")
@@ -127,6 +132,7 @@ def download_file(url: str, dest_path: Path):
     temp_path.rename(dest_path)
     print(f"Download complete: {dest_path}")
 
+
 def ivecs_write(filename: str | Path, data: np.ndarray):
     """Writes a 2D int32 numpy array to ivecs format."""
     filename = Path(filename)
@@ -137,6 +143,7 @@ def ivecs_write(filename: str | Path, data: np.ndarray):
     with_d = np.hstack([d_col, data.astype(np.int32)])
     with_d.tofile(filename)
 
+
 def fvecs_write(filename: str | Path, data: np.ndarray):
     """Writes a 2D float32 numpy array to fvecs format."""
     filename = Path(filename)
@@ -148,6 +155,7 @@ def fvecs_write(filename: str | Path, data: np.ndarray):
     with_d = np.hstack([d_col, data.astype(np.float32)])
     with_d.tofile(filename)
 
+
 def cleanup_legacy_gt(folder: Path):
     """Deletes legacy/broken groundtruth files extracted from old dataset archives."""
     legacy_files = [
@@ -172,15 +180,16 @@ def cleanup_legacy_gt(folder: Path):
             except Exception as e:
                 print(f"Warning: Failed to remove legacy GT file {p}: {e}")
 
+
 def ensure_dataset(dataset_key: str, cache_dir: Path) -> Path:
     """Ensures the dataset is downloaded and extracted in cache_dir, returning folder path."""
     key = resolve_dataset_key(dataset_key)
     if key not in DATASET_METADATA:
         raise ValueError(f"Unknown dataset '{dataset_key}'. Choose from: {list(DATASET_METADATA.keys())}")
-    
+
     meta = DATASET_METADATA[key]
     archive_path = cache_dir / meta["archive"]
-    
+
     # 1. Check if direct folder (e.g., D:\Data\DEG\sift1m or D:\Data\DEG\sift) exists
     extracted_folder = cache_dir / meta["folder"]
     if not extracted_folder.is_dir():
@@ -198,7 +207,7 @@ def ensure_dataset(dataset_key: str, cache_dir: Path) -> Path:
                 archive_path = archive_matches[0]
             else:
                 download_file(meta["url"], archive_path)
-        
+
         print(f"Extracting {archive_path} into {cache_dir}...")
         with tarfile.open(archive_path, "r:gz") as tar:
             tar.extractall(path=cache_dir)
@@ -215,50 +224,63 @@ def ensure_dataset(dataset_key: str, cache_dir: Path) -> Path:
     return extracted_folder
 
 
-
-def compute_and_save_anns_gt(base_vecs: np.ndarray, query_vecs: np.ndarray, float_space: FloatSpace, k: int, out_path: Path):
+def compute_and_save_anns_gt(
+    base_vecs: np.ndarray, query_vecs: np.ndarray, float_space: FloatSpace, k: int, out_path: Path
+):
     """Computes ANNS ground truth against the full base dataset."""
     n_queries = len(query_vecs)
     gt_matrix = np.zeros((n_queries, k), dtype=np.int32)
     print(f"Generating ANNS Ground Truth (Full Dataset, top-{k})...")
     start_t = time.perf_counter()
-    
+
     for q in range(n_queries):
         dists = float_space.compute_distances(query_vecs[q], base_vecs)
         top_k = np.argpartition(dists, k)[:k]
         top_k = top_k[np.argsort(dists[top_k])]
         gt_matrix[q, :] = top_k
         if (q + 1) % 100 == 0 or (q + 1) == n_queries:
             elapsed_ms = int((time.perf_counter() - start_t) * 1000)
-            print(f"\r  Ground truth progress: {q + 1}/{n_queries} ({100.0 * (q + 1) / n_queries:.1f}%) after {elapsed_ms}ms", end="", flush=True)
+            print(
+                f"\r  Ground truth progress: {q + 1}/{n_queries} ({100.0 * (q + 1) / n_queries:.1f}%) after {elapsed_ms}ms",
+                end="",
+                flush=True,
+            )
     print()
     ivecs_write(out_path, gt_matrix)
     print(f"ANNS Ground Truth generated and saved to {out_path}")
 
-def compute_and_save_anns_gt_half(base_vecs: np.ndarray, query_vecs: np.ndarray, float_space: FloatSpace, k: int, out_path: Path):
+
+def compute_and_save_anns_gt_half(
+    base_vecs: np.ndarray, query_vecs: np.ndarray, float_space: FloatSpace, k: int, out_path: Path
+):
     """Computes ANNS ground truth against only the first half of the base dataset.
 
     Mirrors the C++ generate_anns_groundtruth_files() with include_half=true,
     used for dynamic benchmarks where only half the base vectors are active.
     """
-    half_base = base_vecs[:len(base_vecs) // 2]
+    half_base = base_vecs[: len(base_vecs) // 2]
     n_queries = len(query_vecs)
     gt_matrix = np.zeros((n_queries, k), dtype=np.int32)
     print(f"Generating ANNS Ground Truth (Half Dataset = {len(half_base)} vectors, top-{k})...")
     start_t = time.perf_counter()
-    
+
     for q in range(n_queries):
         dists = float_space.compute_distances(query_vecs[q], half_base)
         top_k = np.argpartition(dists, k)[:k]
         top_k = top_k[np.argsort(dists[top_k])]
         gt_matrix[q, :] = top_k
         if (q + 1) % 100 == 0 or (q + 1) == n_queries:
             elapsed_ms = int((time.perf_counter() - start_t) * 1000)
-            print(f"\r  Half GT progress: {q + 1}/{n_queries} ({100.0 * (q + 1) / n_queries:.1f}%) after {elapsed_ms}ms", end="", flush=True)
+            print(
+                f"\r  Half GT progress: {q + 1}/{n_queries} ({100.0 * (q + 1) / n_queries:.1f}%) after {elapsed_ms}ms",
+                end="",
+                flush=True,
+            )
     print()
     ivecs_write(out_path, gt_matrix)
     print(f"ANNS Half Ground Truth generated and saved to {out_path}")
 
+
 def load_dataset_for_dynamic(
     dataset_key: str, cache_dir: Path
 ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, Dict[str, Any]]:

examples/dynamic_data/main.py

@@ -25,6 +25,7 @@ class DataStreamType(Enum):
     - AddHalfRemoveAndAddOneAtATime: Interleaved insertion and deletion operations.
     - AddAllRemoveHalf:              Insert all vectors, then remove the second half.
     """
+
     AddHalf = "AddHalf"
     AddHalfRemoveAndAddOneAtATime = "AddHalfRemoveAndAddOneAtATime"
     AddAllRemoveHalf = "AddAllRemoveHalf"
@@ -48,6 +49,7 @@ class DataStreamType(Enum):
 # Give up opening the plot window if no benchmark data arrived within this many seconds.
 _FIRST_DATA_TIMEOUT = 3600.0
 
+
 def _render_combined_anns_plot(
     queue: multiprocessing.Queue,
     dataset_name: str,
@@ -130,24 +132,27 @@ def draw_msg(stream_idx: int, msg):
         plt.close("all")
 
 
-
-
 # ---------------------------------------------------------------------------
 # Linear search baseline
 # ---------------------------------------------------------------------------
 
-def compute_linear_search_baseline(base_vecs: np.ndarray, float_space: deglib.distances.FloatSpace, sample_size: int = 100) -> float:
+
+def compute_linear_search_baseline(
+    base_vecs: np.ndarray, float_space: deglib.distances.FloatSpace, sample_size: int = 100
+) -> float:
     n_base = len(base_vecs)
     query_count = min(sample_size, n_base)
     rng = np.random.default_rng(7)
     sample_indices = rng.choice(n_base, size=query_count, replace=False)
 
     print(f"\n--- Computing Linear Search Baseline ---")
-    print(f"Computing linear search baseline with {query_count} random queries on {n_base} base vectors "
-          f"using C++ {float_space.metric().name} ({float_space.get_instruction().name})...")
+    print(
+        f"Computing linear search baseline with {query_count} random queries on {n_base} base vectors "
+        f"using C++ {float_space.metric().name} ({float_space.get_instruction().name})..."
+    )
 
     start_time = time.perf_counter()
-    min_dist = float('inf')
+    min_dist = float("inf")
 
     for idx in sample_indices:
         dists = float_space.compute_distances(base_vecs[idx], base_vecs)
@@ -158,8 +163,10 @@ def compute_linear_search_baseline(base_vecs: np.ndarray, float_space: deglib.di
     total_time_us = (time.perf_counter() - start_time) * 1e6
     time_per_query_us = total_time_us / max(query_count, 1)
     linear_baseline_us = time_per_query_us * 2
-    print(f"Linear search baseline: {int(time_per_query_us)}us per query "
-          f"(total: {int(total_time_us / 1000)}ms for {query_count} queries) with min distance {min_dist:.6f}")
+    print(
+        f"Linear search baseline: {int(time_per_query_us)}us per query "
+        f"(total: {int(total_time_us / 1000)}ms for {query_count} queries) with min distance {min_dist:.6f}"
+    )
     return linear_baseline_us
 
 
@@ -168,6 +175,7 @@ def compute_linear_search_baseline(base_vecs: np.ndarray, float_space: deglib.di
 # {dims}D_K{k}_{stream_type_str}.deg  in  <graph_dir>/
 # ---------------------------------------------------------------------------
 
+
 def build_dynamic_graph_filename(graph_dir: Path, dims: int, k: int, stream_type: DataStreamType) -> Path:
     """
     Returns the graph file path matching C++ naming:
@@ -182,6 +190,7 @@ def build_dynamic_graph_filename(graph_dir: Path, dims: int, k: int, stream_type
 # Graph building – simulation of the three DataStreamTypes
 # ---------------------------------------------------------------------------
 
+
 def build_dynamic_graph(
     base_vecs: np.ndarray,
     stream_type: DataStreamType,
@@ -251,7 +260,9 @@ def build_dynamic_graph(
         # 2nd loop: add base_size_quarter pairs from [quarter, half) and remove same number
         for i in range(quarter):
             builder.add_entry(int(all_labels[quarter + i]), base_vecs[quarter + i : quarter + i + 1])
-            builder.add_entry(int(all_labels[half + quarter + i]), base_vecs[half + quarter + i : half + quarter + i + 1])
+            builder.add_entry(
+                int(all_labels[half + quarter + i]), base_vecs[half + quarter + i : half + quarter + i + 1]
+            )
             builder.remove_entry(int(all_labels[half + (i * 2) + 0]))
             builder.remove_entry(int(all_labels[half + (i * 2) + 1]))
 
@@ -266,19 +277,20 @@ def build_dynamic_graph(
     build_time = time.perf_counter() - build_start
     print(f"Graph built in {build_time:.2f} seconds ({graph_mut.size()} vertices).")
 
-        if graph_path:
-            graph_path.parent.mkdir(parents=True, exist_ok=True)
-            graph_mut.save_graph(str(graph_path))
-            print(f"Graph saved to: {graph_path}")
-            return deglib.load_readonly_graph(str(graph_path))
-        else:
-            return graph_mut.to_readonly()
+    if graph_path:
+        graph_path.parent.mkdir(parents=True, exist_ok=True)
+        graph_mut.save_graph(str(graph_path))
+        print(f"Graph saved to: {graph_path}")
+        return deglib.load_readonly_graph(str(graph_path))
+    else:
+        return graph_mut.to_readonly()
 
 
 # ---------------------------------------------------------------------------
 # Main benchmark function
 # ---------------------------------------------------------------------------
 
+
 def run_dynamic_benchmark(
     dataset_key: str,
     cache_dir: Path,
@@ -317,7 +329,9 @@ def run_dynamic_benchmark(
     print(f"Selected Instruction Set: {instruction_set}")
     print(f"Build Threads: {build_threads}")
     print(f"Base vectors: {base_vecs.shape[0]} | Dimension: {dims}")
-    print(f"Query vectors: {query_vecs.shape[0]} | Full-GT shape: {gt_vecs_full.shape} | Half-GT shape: {gt_vecs_half.shape}")
+    print(
+        f"Query vectors: {query_vecs.shape[0]} | Full-GT shape: {gt_vecs_full.shape} | Half-GT shape: {gt_vecs_half.shape}"
+    )
 
     feature_space = deglib.distances.FloatSpace.create(dims, metric, instruction_enum)
     actual_inst = str(feature_space.get_instruction().name)
@@ -418,7 +432,9 @@ def run_dynamic_benchmark(
             anns_recalls.append(recall)
             anns_qps.append(qps)
 
-            print(f"eps {eps:6.3f} \trecall {recall:.5f} \ttime_us_per_query {time_us_per_query:6d}us \t{qps:9.1f} qps \tsearch time: {int(search_time_us / 1000):6d}ms")
+            print(
+                f"eps {eps:6.3f} \trecall {recall:.5f} \ttime_us_per_query {time_us_per_query:6d}us \t{qps:9.1f} qps \tsearch time: {int(search_time_us / 1000):6d}ms"
+            )
 
             if linear_baseline_us > 0 and time_us_per_query > linear_baseline_us:
                 print(f"eps {eps:.3f} \t ABORTED ({time_us_per_query}us/query > {int(linear_baseline_us)}us baseline)")

examples/dynamic_data/presets.py

@@ -57,9 +57,12 @@
     },
 }
 
+
 def get_preset(dataset_key: str) -> Dict[str, Any]:
     """Returns preset graph build and benchmark parameters for dataset_key."""
     key = dataset_key.lower()
     if key not in DYNAMIC_DATASET_PRESETS:
-        raise ValueError(f"No preset for dataset '{dataset_key}'. Standard presets: {list(DYNAMIC_DATASET_PRESETS.keys())}")
+        raise ValueError(
+            f"No preset for dataset '{dataset_key}'. Standard presets: {list(DYNAMIC_DATASET_PRESETS.keys())}"
+        )
     return DYNAMIC_DATASET_PRESETS[key]

examples/knng/dataset_utils.py

@@ -1,6 +1,7 @@
 """
 dataset_utils.py — Helper utilities for downloading and loading SISAP 2026 Task 1 datasets (HDF5 format).
 """
+
 from __future__ import annotations
 
 import os
@@ -25,6 +26,7 @@ def ensure_small_dataset(cache_dir: Path | None = None) -> Path:
     # 1. Try HuggingFace Hub native download/cache
     try:
         from huggingface_hub import hf_hub_download
+
         downloaded = hf_hub_download(
             repo_id=HF_REPO_ID,
             filename=HF_SMALL_FILE,
@@ -49,9 +51,12 @@ def ensure_small_dataset(cache_dir: Path | None = None) -> Path:
 
     # Fallback to direct HTTP download with progress reporter
     print(f"Downloading small dataset from {HF_SMALL_URL} to {target_path}...")
+
     def _progress(count, block_size, total_size):
         percent = int(count * block_size * 100 / max(total_size, 1))
-        sys.stdout.write(f"\rDownloading dataset... {percent}% ({count * block_size / 1024 / 1024:.1f} MB / {total_size / 1024 / 1024:.1f} MB)")
+        sys.stdout.write(
+            f"\rDownloading dataset... {percent}% ({count * block_size / 1024 / 1024:.1f} MB / {total_size / 1024 / 1024:.1f} MB)"
+        )
         sys.stdout.flush()
 
     urllib.request.urlretrieve(HF_SMALL_URL, target_path, _progress)
@@ -71,7 +76,7 @@ def load_hdf5_dataset(file_path: str | Path, max_vecs: int | None = None) -> tup
     with h5py.File(path, "r") as f:
         if "train" not in f:
             raise KeyError(f"Expected dataset key 'train' not found in {path}. Keys found: {list(f.keys())}")
-        
+
         dataset = f["train"]
         if max_vecs is not None and max_vecs < dataset.shape[0]:
             train_data = dataset[:max_vecs]
@@ -116,7 +121,7 @@ def generate_synthetic_dataset(num_vecs: int = 2000, dims: int = 1024, seed: int
 
     # Compute exact inner product matrix for ground truth top 15
     sim_matrix = np.dot(data, data.T)
-    np.fill_diagonal(sim_matrix, -np.inf) # Exclude self
+    np.fill_diagonal(sim_matrix, -np.inf)  # Exclude self
     gt_data = np.argsort(-sim_matrix, axis=1)[:, :15]
 
     return data, gt_data