refactor(docs, python, cpp): modernize docs with uv, streamline graph factory API, and replace runtime asserts

- Modernize docs directory: migrate to uv + pyproject.toml, remove legacy make/sh/bat scripts, dynamic version from deglib.__version__
- Complete Sphinx API reference across all 7 Python modules (graph, builder, distances, search, analysis, optimization, cpu)
- Expose load_mutable_graph and streamline graph creation/loading as top-level helpers (remove redundant classmethods)
- Eliminate internal to_cpp methods from public Python API and remove unused std.py module
- Replace runtime assertions with proper exceptions (ValueError/std::runtime_error) in builder.py and repository.h

Author: Neiko2002

.readthedocs.yaml

@@ -7,7 +7,8 @@ build:
 
 python:
   install:
-    - requirements: docs/requirements.txt
+    - method: pip
+      path: docs
 
 sphinx:
   configuration: docs/conf.py

cpp/bench/include/repository.h

@@ -1,12 +1,12 @@
 #pragma once
 
-#include <assert.h>
 #include <stdio.h>
 
 #include <cstring>
 #include <filesystem>
 #include <fstream>
 #include <iostream>
+#include <stdexcept>
 #include <unordered_map>
 
 namespace deglib {
@@ -73,10 +73,14 @@ auto fvecs_read(const char* fname, size_t& d_out, size_t& n_out) {
     // read dimension header
     uint32_t dims = 0;
     ifstream.read(reinterpret_cast<char*>(&dims), sizeof(dims));
-    assert((dims > 0 && dims < 1'000'000) && "unreasonable dimension");
+    if (dims == 0 || dims >= 1'000'000) {
+        throw std::runtime_error("unreasonable dimension in fvecs file");
+    }
 
     // compute number of rows
-    assert(file_size % ((dims + 1) * sizeof(float)) == 0 || !"weird file size");
+    if (file_size % ((dims + 1) * sizeof(float)) != 0) {
+        throw std::runtime_error("weird file size in fvecs file");
+    }
     size_t n = (size_t)file_size / ((dims + 1) * sizeof(float));
     d_out = dims;
     n_out = n;
@@ -85,7 +89,9 @@ auto fvecs_read(const char* fname, size_t& d_out, size_t& n_out) {
     auto x = std::make_unique<std::byte[]>(file_size);
     ifstream.seekg(0);
     ifstream.read(reinterpret_cast<char*>(x.get()), file_size);
-    if (!ifstream) assert(ifstream.gcount() == static_cast<int>(file_size) || !"could not read whole file");
+    if (!ifstream && ifstream.gcount() != static_cast<std::streamsize>(file_size)) {
+        throw std::runtime_error("could not read whole file");
+    }
 
     // shift array to remove row headers
     for (size_t i = 0; i < n; i++) std::memmove(&x[i * dims * sizeof(float)], &x[sizeof(dims) + i * (dims + 1) * sizeof(float)], dims * sizeof(float));
@@ -113,10 +119,14 @@ auto u8vecs_read(const char* fname, size_t& d_out, size_t& n_out) {
     // read dimension header
     uint32_t dims = 0;
     ifstream.read(reinterpret_cast<char*>(&dims), sizeof(dims));
-    assert((dims > 0 && dims < 1'000'000) && "unreasonable dimension");
+    if (dims == 0 || dims >= 1'000'000) {
+        throw std::runtime_error("unreasonable dimension in u8vecs file");
+    }
 
     // compute number of rows
-    assert(file_size % (dims + 4) == 0 || !"weird file size");
+    if (file_size % (dims + 4) != 0) {
+        throw std::runtime_error("weird file size in u8vecs file");
+    }
     size_t n = (size_t)file_size / (dims + 4);
     d_out = dims;
     n_out = n;
@@ -125,7 +135,9 @@ auto u8vecs_read(const char* fname, size_t& d_out, size_t& n_out) {
     auto x = std::make_unique<std::byte[]>(file_size);
     ifstream.seekg(0);
     ifstream.read(reinterpret_cast<char*>(x.get()), file_size);
-    if (!ifstream) assert(ifstream.gcount() == static_cast<int>(file_size) || !"could not read whole file");
+    if (!ifstream && ifstream.gcount() != static_cast<std::streamsize>(file_size)) {
+        throw std::runtime_error("could not read whole file");
+    }
 
     // shift array to remove row headers
     for (size_t i = 0; i < n; i++) std::memmove(&x[i * dims], &x[sizeof(dims) + i * (dims + sizeof(dims))], dims);

cpp/deglib/include/deglib/builder.h

@@ -398,9 +398,10 @@ class EvenRegularGraphBuilder {
      * Set the number of threads used to extend the graph during building.
      *
      * When the thread count is greater than 1 and the optimization target is not StreamingData,
-     * the builder will utilize multiple threads to add elements to the graph in parallel.
-     * By default, all available CPU cores/threads are used unless specified.
-     * Note: The order in which elements are added is not guaranteed when using multiple threads.
+     * the builder will utilize multiple threads to search neighbors and connect edges in parallel.
+     * The default thread count is 1.
+     * Note: Elements are always appended to the graph in insertion order. Only the neighbor
+     * search and edge creation of the elements within a batch are processed in parallel.
      *
      * @param thread_count Number of threads which are used to extend the graph.
      */
@@ -417,11 +418,14 @@ class EvenRegularGraphBuilder {
      * (how fast changed are added to the graph), specify the batch size should be considered.
      *
      * e.g.
-     * thread count = 1 and batch size = 1: low throuput, medium latency, order of elements is guaranteed
-     * thread count > 1 and batch size = 1: high throuput, low latency, order of elements is not guaranteed
-     * thread count > 1 and batch size > 1: highest throuput, highest latency, order of elements is not guaranteed
+     * thread count = 1 and batch size = 1: low throughput, medium latency
+     * thread count > 1 and batch size = 1: high throughput, low latency
+     * thread count > 1 and batch size > 1: highest throughput, highest latency
      * * Please note that the optimization target StreamingData only uses a thread count of 1.
      *
+     * The elements of a batch are always appended to the graph in insertion order.
+     * Only the neighbor search and edge creation within a batch are processed in parallel.
+     *
      * The batch size is calculated as:
      *   batch_size = thread_count * tasks_per_batch * task_size
      * where
@@ -432,8 +436,8 @@ class EvenRegularGraphBuilder {
      * A low tasks_per_batch improves the latency but reduces the throughput.
      * Therefore it is recommended to use a higher task_size value.
      *
-     * @param tasks_per_batch Number of tasks for each thread in one batch. (default: 32)
-     * @param task_size Number of elements each thread processes in one task. (default: 10)
+     * @param tasks_per_batch Number of tasks for each thread in one batch. (default: 10)
+     * @param task_size Number of elements each thread processes in one task. (default: 32)
      */
     void setBatchSize(uint32_t tasks_per_batch, uint32_t task_size) {
         extend_thread_task_size = task_size;

cpp/deglib/include/deglib/optimization.h

@@ -109,7 +109,7 @@ inline void prune_worst_edges(deglib::graph::MutableGraph& graph, const uint8_t
 }
 
 /**
- * @brief Remove all edges that do not satisfy the MRNG condition.
+ * @brief Remove all edges that do not satisfy the RNG condition.
  *
  * Parallelized across hardware threads. For each vertex, checks each neighbor
  * using the RNG condition and removes non-conforming edges.
@@ -118,12 +118,12 @@ inline void prune_worst_edges(deglib::graph::MutableGraph& graph, const uint8_t
  * @param numThreads Number of threads to use (0 = use hardware concurrency).
  * @return Number of edges removed.
  */
-inline uint32_t prune_non_mrng_edges(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
-    return deglib::optimization::pruning::prune_non_mrng_edges(graph, numThreads);
+inline uint32_t prune_non_rng_edges(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
+    return deglib::optimization::pruning::prune_non_rng_edges(graph, numThreads);
 }
 
 /**
- * @brief Remove non-MRNG edges using a weight-sorted global strategy.
+ * @brief Remove non-RNG edges using a weight-sorted global strategy.
  *
  * Collects all non-RNG edges, sorts them by weight (ascending), then removes
  * them in that order. Collection is multi-threaded; removal is single-threaded.
@@ -132,12 +132,12 @@ inline uint32_t prune_non_mrng_edges(deglib::graph::MutableGraph& graph, const s
  * @param numThreads Number of threads to use for collection (0 = use hardware concurrency).
  * @return Number of edges removed.
  */
-inline uint32_t prune_non_mrng_edges_weight_sorted(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
-    return deglib::optimization::pruning::prune_non_mrng_edges_weight_sorted(graph, numThreads);
+inline uint32_t prune_non_rng_edges_weight_sorted(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
+    return deglib::optimization::pruning::prune_non_rng_edges_weight_sorted(graph, numThreads);
 }
 
 /**
- * @brief Remove non-MRNG edges using an iterative per-vertex strategy.
+ * @brief Remove non-RNG edges using an iterative per-vertex strategy.
  *
  * For each vertex, iteratively removes non-RNG edges in a do-while loop until
  * no more edges can be removed. This accounts for cascading effects where
@@ -147,8 +147,8 @@ inline uint32_t prune_non_mrng_edges_weight_sorted(deglib::graph::MutableGraph&
  * @param numThreads Number of threads to use (0 = use hardware concurrency).
  * @return Number of edges removed.
  */
-inline uint32_t prune_non_mrng_edges_iterative(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
-    return deglib::optimization::pruning::prune_non_mrng_edges_iterative(graph, numThreads);
+inline uint32_t prune_non_rng_edges_iterative(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
+    return deglib::optimization::pruning::prune_non_rng_edges_iterative(graph, numThreads);
 }
 
 // ========================================================================

cpp/deglib/include/deglib/optimization/pruning.h

@@ -68,7 +68,7 @@ inline void prune_worst_edges(deglib::graph::MutableGraph& graph, const uint8_t
 }
 
 /**
- * @brief Remove all edges that do not satisfy the MRNG condition.
+ * @brief Remove all edges that do not satisfy the RNG condition.
  *
  * Iterates over all vertices and their neighbors, removing any edge that does
  * not satisfy the RNG condition. Each vertex is processed in parallel via
@@ -78,7 +78,7 @@ inline void prune_worst_edges(deglib::graph::MutableGraph& graph, const uint8_t
  * @param numThreads Number of threads to use (0 = use hardware concurrency).
  * @return Number of edges removed.
  */
-inline uint32_t prune_non_mrng_edges(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
+inline uint32_t prune_non_rng_edges(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
     const auto vertex_count = graph.size();
     const auto edge_per_vertex = graph.getEdgesPerVertex();
     const auto thread_count = numThreads == 0 ? std::thread::hardware_concurrency() : numThreads;
@@ -117,7 +117,7 @@ inline uint32_t prune_non_mrng_edges(deglib::graph::MutableGraph& graph, const s
 }
 
 /**
- * @brief Remove non-MRNG edges using a weight-sorted global strategy.
+ * @brief Remove non-RNG edges using a weight-sorted global strategy.
  *
  * Collects all non-RNG edges across the graph, sorts them by weight (ascending),
  * then removes them in that order. This allows lower-weight (more important) edges
@@ -128,7 +128,7 @@ inline uint32_t prune_non_mrng_edges(deglib::graph::MutableGraph& graph, const s
  * @param numThreads Number of threads to use for collection (0 = use hardware concurrency).
  * @return Number of edges removed.
  */
-inline uint32_t prune_non_mrng_edges_weight_sorted(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
+inline uint32_t prune_non_rng_edges_weight_sorted(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
     struct WeightedEdge {
         uint32_t from_vertex;
         uint32_t to_vertex;
@@ -140,7 +140,7 @@ inline uint32_t prune_non_mrng_edges_weight_sorted(deglib::graph::MutableGraph&
     const auto thread_count = numThreads == 0 ? std::thread::hardware_concurrency() : numThreads;
 
     // Collect all non-RNG edges (multi-threaded, per-thread buffers to avoid data races)
-    std::vector<std::vector<WeightedEdge>> nonMRNG_edges_per_thread(thread_count);
+    std::vector<std::vector<WeightedEdge>> non_rng_edges_per_thread(thread_count);
     deglib::concurrent::parallel_for(0, vertex_count, thread_count, [&](size_t vertex_index, size_t thread_id) {
         const auto u = static_cast<uint32_t>(vertex_index);
         const auto neighbor_indices = graph.getNeighborIndices(u);
@@ -150,24 +150,24 @@ inline uint32_t prune_non_mrng_edges_weight_sorted(deglib::graph::MutableGraph&
             const auto neighbor_index = neighbor_indices[n];
             const auto neighbor_weight = neighbor_weights[n];
             if (deglib::analysis::checkRNG(graph, edge_per_vertex, u, neighbor_index, neighbor_weight) == false) {
-                nonMRNG_edges_per_thread[thread_id].push_back({u, neighbor_index, neighbor_weight});
+                non_rng_edges_per_thread[thread_id].push_back({u, neighbor_index, neighbor_weight});
             }
         }
     });
 
     // Merge per-thread results
-    std::vector<WeightedEdge> nonMRNG_edges;
+    std::vector<WeightedEdge> non_rng_edges;
     for (size_t i = 0; i < thread_count; i++) {
-        nonMRNG_edges.insert(nonMRNG_edges.end(), nonMRNG_edges_per_thread[i].begin(), nonMRNG_edges_per_thread[i].end());
+        non_rng_edges.insert(non_rng_edges.end(), non_rng_edges_per_thread[i].begin(), non_rng_edges_per_thread[i].end());
     }
 
     // Sort by weight ascending
-    std::sort(nonMRNG_edges.begin(), nonMRNG_edges.end(), [](const auto& x, const auto& y) { return x.weight < y.weight; });
+    std::sort(non_rng_edges.begin(), non_rng_edges.end(), [](const auto& x, const auto& y) { return x.weight < y.weight; });
 
     // Remove edges that are still non-RNG (single-threaded)
     size_t removed_rng_edges = 0;
-    for (size_t i = 0; i < nonMRNG_edges.size(); i++) {
-        const auto& edge = nonMRNG_edges[i];
+    for (size_t i = 0; i < non_rng_edges.size(); i++) {
+        const auto& edge = non_rng_edges[i];
         if (deglib::analysis::checkRNG(graph, edge_per_vertex, edge.from_vertex, edge.to_vertex, edge.weight) == false) {
             graph.changeEdge(edge.from_vertex, edge.to_vertex, edge.from_vertex, 0);
             removed_rng_edges++;
@@ -178,7 +178,7 @@ inline uint32_t prune_non_mrng_edges_weight_sorted(deglib::graph::MutableGraph&
 }
 
 /**
- * @brief Remove non-MRNG edges using an iterative per-vertex strategy.
+ * @brief Remove non-RNG edges using an iterative per-vertex strategy.
  *
  * For each vertex, iteratively removes non-RNG edges in a do-while loop until
  * no more edges can be removed. This accounts for cascading effects where
@@ -189,7 +189,7 @@ inline uint32_t prune_non_mrng_edges_weight_sorted(deglib::graph::MutableGraph&
  * @param numThreads Number of threads to use (0 = use hardware concurrency).
  * @return Number of edges removed.
  */
-inline uint32_t prune_non_mrng_edges_iterative(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
+inline uint32_t prune_non_rng_edges_iterative(deglib::graph::MutableGraph& graph, const size_t numThreads = 0) {
     const auto vertex_count = graph.size();
     const auto edge_per_vertex = graph.getEdgesPerVertex();
     const auto thread_count = numThreads == 0 ? std::thread::hardware_concurrency() : numThreads;
@@ -211,23 +211,23 @@ inline uint32_t prune_non_mrng_edges_iterative(deglib::graph::MutableGraph& grap
         }
 
         // Find all non-RNG conform neighbors (indices into the sorted neighbors vector)
-        std::vector<uint32_t> nonMRNG_edges;
+        std::vector<uint32_t> non_rng_edges;
         for (uint32_t n = 0; n < neighbors.size(); n++) {
             const auto neighbor_index = neighbors[n].first;
             const auto neighbor_weight = neighbors[n].second;
-            if (deglib::analysis::checkRNG(graph, edge_per_vertex, vertex_index_u32, neighbor_index, neighbor_weight) == false) nonMRNG_edges.emplace_back(n);
+            if (deglib::analysis::checkRNG(graph, edge_per_vertex, vertex_index_u32, neighbor_index, neighbor_weight) == false) non_rng_edges.emplace_back(n);
         }
 
         // Iteratively remove edges until stable
         bool removed_edge = false;
         do {
             removed_edge = false;
-            for (uint32_t n = 0; n < nonMRNG_edges.size(); n++) {
-                const auto neighbor_index = neighbors[nonMRNG_edges[n]].first;
-                const auto neighbor_weight = neighbors[nonMRNG_edges[n]].second;
+            for (uint32_t n = 0; n < non_rng_edges.size(); n++) {
+                const auto neighbor_index = neighbors[non_rng_edges[n]].first;
+                const auto neighbor_weight = neighbors[non_rng_edges[n]].second;
 
                 if (deglib::analysis::checkRNG(graph, edge_per_vertex, vertex_index_u32, neighbor_index, neighbor_weight) == false) {
-                    nonMRNG_edges.erase(nonMRNG_edges.begin() + n);
+                    non_rng_edges.erase(non_rng_edges.begin() + n);
                     graph.changeEdge(vertex_index_u32, neighbor_index, vertex_index_u32, 0);
                     removed_rng_edges++;
                     removed_edge = true;