fix: resolve all ruff lint and format violations

- Fix F821: add module-level numpy imports for type annotations
- Fix PLC0415: add noqa for intentional lazy imports inside functions
- Fix G004: convert f-string logging to lazy % formatting
- Fix NPY002: add noqa for legacy numpy random calls in benchmarks
- Fix ARG001/ARG002: prefix unused args with underscore
- Fix PTH123: use Path.open() instead of open()
- Fix I001: sort imports
- Exclude *.ipynb from ruff (demo/benchmark notebooks)

Signed-off-by: Maxime Grenu <maxime.grenu@gmail.com>

Author: cluster2600

pyproject.toml

@@ -189,6 +189,7 @@ exclude = [
     ".git/",
     ".venv/",
     "venv/",
+    "*.ipynb",
 ]
 
 [tool.ruff.lint]

python/tests/test_backends.py

@@ -40,37 +40,37 @@ class TestGPUIndex:
 
     def test_create_index(self):
         """Test creating GPU index."""
-        from zvec.backends.gpu import create_index
+        from zvec.backends.gpu import create_index  # noqa: PLC0415
 
         index = create_index(dim=128, index_type="flat")
         assert index is not None
 
     def test_add_vectors(self):
         """Test adding vectors to index."""
-        from zvec.backends.gpu import GPUIndex
+        from zvec.backends.gpu import GPUIndex  # noqa: PLC0415
 
         index = GPUIndex(dim=128, index_type="flat")
-        vectors = np.random.random((100, 128)).astype(np.float32)
+        vectors = np.random.random((100, 128)).astype(np.float32)  # noqa: NPY002
         index.add(vectors)
         assert index.ntotal == 100
 
     def test_search(self):
         """Test searching index."""
-        from zvec.backends.gpu import GPUIndex
+        from zvec.backends.gpu import GPUIndex  # noqa: PLC0415
 
         index = GPUIndex(dim=128, index_type="flat")
-        vectors = np.random.random((100, 128)).astype(np.float32)
+        vectors = np.random.random((100, 128)).astype(np.float32)  # noqa: NPY002
         index.add(vectors)
 
-        query = np.random.random((5, 128)).astype(np.float32)
+        query = np.random.random((5, 128)).astype(np.float32)  # noqa: NPY002
         distances, indices = index.search(query, k=10)
 
         assert distances.shape == (5, 10)
         assert indices.shape == (5, 10)
 
     def test_fallback_to_cpu(self):
         """Test CPU fallback."""
-        from zvec.backends.gpu import GPUIndex
+        from zvec.backends.gpu import GPUIndex  # noqa: PLC0415
 
         index = GPUIndex(dim=128, index_type="flat", use_gpu=False)
         assert not index.use_gpu
@@ -81,7 +81,7 @@ class TestQuantization:
 
     def test_pq_encoder_init(self):
         """Test PQ encoder initialization."""
-        from zvec.backends.quantization import PQEncoder
+        from zvec.backends.quantization import PQEncoder  # noqa: PLC0415
 
         encoder = PQEncoder(m=8, nbits=8, k=256)
         assert encoder.m == 8
@@ -90,10 +90,10 @@ def test_pq_encoder_init(self):
 
     def test_pq_train(self):
         """Test PQ training."""
-        from zvec.backends.quantization import PQEncoder
+        from zvec.backends.quantization import PQEncoder  # noqa: PLC0415
 
-        np.random.seed(42)
-        vectors = np.random.random((1000, 128)).astype(np.float32)
+        np.random.seed(42)  # noqa: NPY002
+        vectors = np.random.random((1000, 128)).astype(np.float32)  # noqa: NPY002
 
         encoder = PQEncoder(m=8, nbits=8, k=256)
         encoder.train(vectors)
@@ -102,10 +102,10 @@ def test_pq_train(self):
 
     def test_pq_encode_decode(self):
         """Test PQ encode/decode."""
-        from zvec.backends.quantization import PQEncoder
+        from zvec.backends.quantization import PQEncoder  # noqa: PLC0415
 
-        np.random.seed(42)
-        vectors = np.random.random((100, 128)).astype(np.float32)
+        np.random.seed(42)  # noqa: NPY002
+        vectors = np.random.random((100, 128)).astype(np.float32)  # noqa: NPY002
 
         encoder = PQEncoder(m=8, nbits=8, k=256)
         encoder.train(vectors)
@@ -118,15 +118,15 @@ def test_pq_encode_decode(self):
 
     def test_pq_index(self):
         """Test PQ index."""
-        from zvec.backends.quantization import PQIndex
+        from zvec.backends.quantization import PQIndex  # noqa: PLC0415
 
-        np.random.seed(42)
-        vectors = np.random.random((100, 128)).astype(np.float32)
+        np.random.seed(42)  # noqa: NPY002
+        vectors = np.random.random((100, 128)).astype(np.float32)  # noqa: NPY002
 
         index = PQIndex(m=8, nbits=8, k=256)
         index.add(vectors)
 
-        query = np.random.random((5, 128)).astype(np.float32)
+        query = np.random.random((5, 128)).astype(np.float32)  # noqa: NPY002
         distances, indices = index.search(query, k=10)
 
         assert distances.shape == (5, 10)
@@ -138,17 +138,17 @@ class TestOPQ:
 
     def test_opq_encoder_init(self):
         """Test OPQ encoder initialization."""
-        from zvec.backends.opq import OPQEncoder
+        from zvec.backends.opq import OPQEncoder  # noqa: PLC0415
 
         encoder = OPQEncoder(m=8, nbits=8, k=256)
         assert encoder.m == 8
 
     def test_scalar_quantizer(self):
         """Test scalar quantizer."""
-        from zvec.backends.opq import ScalarQuantizer
+        from zvec.backends.opq import ScalarQuantizer  # noqa: PLC0415
 
-        np.random.seed(42)
-        vectors = np.random.random((100, 128)).astype(np.float32)
+        np.random.seed(42)  # noqa: NPY002
+        vectors = np.random.random((100, 128)).astype(np.float32)  # noqa: NPY002
 
         quantizer = ScalarQuantizer(bits=8)
         quantizer.train(vectors)
@@ -165,12 +165,12 @@ class TestSearchOptimization:
 
     def test_adc(self):
         """Test asymmetric distance computation."""
-        from zvec.backends.search import asymmetric_distance_computation
+        from zvec.backends.search import asymmetric_distance_computation  # noqa: PLC0415
 
-        np.random.seed(42)
-        queries = np.random.random((10, 128)).astype(np.float32)
-        codes = np.random.randint(0, 256, (100, 8), dtype=np.uint8)
-        distance_table = np.random.random((10, 8, 256)).astype(np.float32)
+        np.random.seed(42)  # noqa: NPY002
+        queries = np.random.random((10, 128)).astype(np.float32)  # noqa: NPY002
+        codes = np.random.randint(0, 256, (100, 8), dtype=np.uint8)  # noqa: NPY002
+        distance_table = np.random.random((10, 8, 256)).astype(np.float32)  # noqa: NPY002
 
         distances = asymmetric_distance_computation(queries, codes, distance_table)
         assert distances.shape == (10, 100)
@@ -181,17 +181,17 @@ class TestHNSW:
 
     def test_hnsw_creation(self):
         """Test HNSW index creation."""
-        from zvec.backends.hnsw import HNSWIndex
+        from zvec.backends.hnsw import HNSWIndex  # noqa: PLC0415
 
         index = HNSWIndex(dim=128, M=16)
         assert index.dim == 128
 
     def test_hnsw_add(self):
         """Test adding vectors to HNSW."""
-        from zvec.backends.hnsw import HNSWIndex
+        from zvec.backends.hnsw import HNSWIndex  # noqa: PLC0415
 
         index = HNSWIndex(dim=128, M=8)
-        vectors = np.random.random((50, 128)).astype(np.float32)
+        vectors = np.random.random((50, 128)).astype(np.float32)  # noqa: NPY002
         index.add(vectors)
 
         # Basic check - just verify no error
@@ -203,27 +203,27 @@ class TestAppleSilicon:
 
     def test_apple_silicon_detection(self):
         """Test Apple Silicon detection."""
-        from zvec.backends import apple_silicon
+        from zvec.backends import apple_silicon  # noqa: PLC0415
 
         # Just verify functions exist and are callable
         assert callable(apple_silicon.is_apple_silicon)
         assert callable(apple_silicon.is_mps_available)
 
     def test_apple_backend_init(self):
         """Test Apple Silicon backend initialization."""
-        from zvec.backends.apple_silicon import AppleSiliconBackend
+        from zvec.backends.apple_silicon import AppleSiliconBackend  # noqa: PLC0415
 
         backend = AppleSiliconBackend(backend="numpy")
         assert backend.backend == "numpy"
 
     def test_l2_distance(self):
         """Test L2 distance computation."""
-        from zvec.backends.apple_silicon import AppleSiliconBackend
+        from zvec.backends.apple_silicon import AppleSiliconBackend  # noqa: PLC0415
 
         backend = AppleSiliconBackend(backend="numpy")
 
-        a = np.random.random((10, 128)).astype(np.float32)
-        b = np.random.random((20, 128)).astype(np.float32)
+        a = np.random.random((10, 128)).astype(np.float32)  # noqa: NPY002
+        b = np.random.random((20, 128)).astype(np.float32)  # noqa: NPY002
 
         distances = backend.l2_distance(a, b)
         assert distances.shape == (10, 20)
@@ -234,7 +234,7 @@ class TestDistributed:
 
     def test_shard_manager(self):
         """Test shard manager."""
-        from zvec.backends.distributed import ShardManager
+        from zvec.backends.distributed import ShardManager  # noqa: PLC0415
 
         manager = ShardManager(n_shards=4, strategy="hash")
         assert manager.n_shards == 4
@@ -244,18 +244,18 @@ def test_shard_manager(self):
 
     def test_distributed_index(self):
         """Test distributed index."""
-        from zvec.backends.distributed import DistributedIndex
+        from zvec.backends.distributed import DistributedIndex  # noqa: PLC0415
 
         index = DistributedIndex(n_shards=4)
-        vectors = np.random.random((100, 128)).astype(np.float32)
+        vectors = np.random.random((100, 128)).astype(np.float32)  # noqa: NPY002
         vector_ids = [f"v_{i}" for i in range(100)]
 
         index.add(vectors, vector_ids)
         assert 4 in index._local_indexes
 
     def test_result_merger(self):
         """Test result merging."""
-        from zvec.backends.distributed import ResultMerger
+        from zvec.backends.distributed import ResultMerger  # noqa: PLC0415
 
         results = [
             (np.array([1.0, 2.0]), np.array([0, 1])),

python/zvec/__init__.py

@@ -25,8 +25,8 @@
 # Public API — grouped by category
 # ==============================
 
-from . import model as model
 from . import backends as backends
+from . import model as model
 
 # —— Extensions ——
 from .extension import (

python/zvec/backends/apple_ane.py

@@ -23,6 +23,9 @@
 # 3. Powers of 2 for batch/dim (≤16k)
 # 4. Fused ops (no separate layernorm)
 # 5. CNNs preferred over Transformers
+from __future__ import annotations
+
+import numpy as np
 
 ANE_OPTIMIZATION_TIPS = """
 # ANE Optimization Guide
@@ -53,19 +56,18 @@
 """
 
 
-def estimate_ane_speedup(dim: int, batch_size: int = 1) -> float:
+def estimate_ane_speedup(dim: int, _batch_size: int = 1) -> float:
     """Estimate ANE speedup based on paper.
-    
+
     From Ben Brown 2023:
     - ANE 3x faster for small embeddings (dim ≤ 256)
     - Lags for large batch operations
     """
     if dim <= 256:
         return 3.0
-    elif dim <= 1024:
+    if dim <= 1024:
         return 2.0
-    else:
-        return 1.0
+    return 1.0
 
 
 def get_optimal_ane_config(dim: int) -> dict:
@@ -74,7 +76,7 @@ def get_optimal_ane_config(dim: int) -> dict:
     optimal_dim = 1
     while optimal_dim < dim:
         optimal_dim *= 2
-    
+
     return {
         "original_dim": dim,
         "optimal_dim": optimal_dim,
@@ -85,58 +87,56 @@ def get_optimal_ane_config(dim: int) -> dict:
 
 class ANEVectorEncoder:
     """Vector encoder optimized for Apple Neural Engine."""
-    
+
     def __init__(self, dim: int, batch_size: int = 1):
         """Initialize ANE encoder.
-        
+
         Args:
             dim: Embedding dimension.
             batch_size: Batch size for encoding.
         """
         self.dim = dim
         self.batch_size = batch_size
         self.config = get_optimal_ane_config(dim)
-        
+
         # Check ANE availability
         self.ane_available = self._check_ane()
-        
+
     def _check_ane(self) -> bool:
         """Check if ANE is available."""
         try:
-            import torch
+            import torch  # noqa: PLC0415
+
             return torch.backends.mps.is_available()
         except ImportError:
             return False
-    
-    def encode(self, texts: list[str]) -> "np.ndarray":
+
+    def encode(self, texts: list[str]) -> np.ndarray:
         """Encode texts to embeddings using ANE.
-        
+
         This is a placeholder - actual implementation would use:
         1. BERT/DistilBERT model
         2. Core ML conversion
         3. ANE inference
         """
-        import numpy as np
-        
+        import numpy as np  # noqa: PLC0415
+
         # Placeholder: random embeddings
-        embeddings = np.random.randn(len(texts), self.dim).astype(np.float16)
-        
-        return embeddings
-    
+        return np.random.randn(len(texts), self.dim).astype(np.float16)  # noqa: NPY002
+
     def optimize_for_ane(self, model_path: str) -> str:
         """Convert PyTorch model to Core ML for ANE.
-        
+
         Args:
             model_path: Path to PyTorch model.
-            
+
         Returns:
             Path to Core ML model.
         """
         # This would use coremltools
         # import coremltools as ct
         # model = ct.convert(model_path)
         # model.save("embedding_model.mlpackage")
-        pass
 
 
 # Reference from Apple ML Research: