usearch 2.23.0__cp314-cp314t-macosx_11_0_arm64.whl

usearch/__init__.py

@@ -0,0 +1,152 @@
+import os
+import sys
+import ctypes
+import platform
+import warnings
+import urllib.request
+from typing import Optional, Tuple
+from urllib.error import HTTPError
+
+#! Load SimSIMD before the USearch compiled module
+#! We can't just use the `import simsimd` as on Linux and Windows (unlike MacOS),
+#! the symbols are not automatically loaded into the global namespace.
+try:
+    import simsimd
+
+    # Cross-platform check for Windows
+    if sys.platform == "win32":
+        # Add the directory where the `.dll` is located
+        dll_directory = os.path.dirname(simsimd.__file__)
+        os.add_dll_directory(dll_directory)
+
+        # Load SimSIMD library using `ctypes` without `RTLD_GLOBAL`
+        simsimd_lib = ctypes.CDLL(simsimd.__file__)
+
+    else:
+        # Non-Windows: Use `RTLD_GLOBAL` for Unix-based systems (Linux/macOS)
+        simsimd_lib = ctypes.CDLL(simsimd.__file__, mode=ctypes.RTLD_GLOBAL)
+
+except ImportError:
+    pass  # If the user doesn't want SimSIMD, we assume they know what they're doing
+
+
+from usearch.compiled import (
+    VERSION_MAJOR,
+    VERSION_MINOR,
+    VERSION_PATCH,
+    # Default values:
+    DEFAULT_CONNECTIVITY,
+    DEFAULT_EXPANSION_ADD,
+    DEFAULT_EXPANSION_SEARCH,
+    # Dependencies:
+    USES_OPENMP,
+    USES_FP16LIB,
+    USES_SIMSIMD,
+    USES_SIMSIMD_DYNAMIC_DISPATCH,
+)
+
+__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{VERSION_PATCH}"
+
+
+class BinaryManager:
+    def __init__(self, version: Optional[str] = None):
+        if version is None:
+            version = __version__
+        self.version = version or __version__
+
+    @staticmethod
+    def determine_download_dir():
+        # Check if running within a virtual environment
+        virtual_env = os.getenv("VIRTUAL_ENV")
+        if virtual_env:
+            # Use a subdirectory within the virtual environment for binaries
+            return os.path.join(virtual_env, "bin", "usearch_binaries")
+        else:
+            # Fallback to a directory in the user's home folder
+            home_dir = os.path.expanduser("~")
+            return os.path.join(home_dir, ".usearch", "binaries")
+
+    @staticmethod
+    def determine_download_url(version: str, filename: str) -> str:
+        base_url = "https://github.com/unum-cloud/usearch/releases/download"
+        url = f"{base_url}/v{version}/{filename}"
+        return url
+
+    def get_binary_name(self) -> Tuple[str, str]:
+        version = self.version
+        os_map = {"Linux": "linux", "Windows": "windows", "Darwin": "macos"}
+        arch_map = {
+            "x86_64": "amd64" if platform.system() != "Darwin" else "x86_64",
+            "AMD64": "amd64",
+            "arm64": "arm64",
+            "aarch64": "arm64",
+            "x86": "x86",
+        }
+        os_part = os_map.get(platform.system(), "")
+        arch = platform.machine()
+        arch_part = arch_map.get(arch, "")
+        extension = {"Linux": "so", "Windows": "dll", "Darwin": "dylib"}.get(platform.system(), "")
+        source_filename = f"usearch_sqlite_{os_part}_{arch_part}_{version}.{extension}"
+        target_filename = f"usearch_sqlite.{extension}"
+        return source_filename, target_filename
+
+    def sqlite_found_or_downloaded(self) -> Optional[str]:
+        """
+        Attempts to locate the pre-installed `usearch_sqlite` binary.
+        If not found, downloads it from GitHub.
+
+        Returns:
+            The path to the binary if found or downloaded, otherwise None.
+        """
+        # Search local directories
+        local_dirs = ["build", "build_artifacts", "build_release", "build_debug"]
+        source_filename, target_filename = self.get_binary_name()
+
+        # Check local development directories first
+        for local_dir in local_dirs:
+
+            local_path = os.path.join(local_dir, target_filename)
+            if os.path.exists(local_path):
+                path_wout_extension, _, _ = local_path.rpartition(".")
+                return path_wout_extension
+
+            # Most build systems on POSIX would prefix the library name with "lib"
+            local_path = os.path.join(local_dir, "lib" + target_filename)
+            if os.path.exists(local_path):
+                path_wout_extension, _, _ = local_path.rpartition(".")
+                return path_wout_extension
+
+        # Check local installation directories, in case the build is already installed
+        download_dir = self.determine_download_dir()
+        local_path = os.path.join(download_dir, target_filename)
+        if not os.path.exists(local_path):
+
+            # If not found locally, warn the user and download from GitHub
+            warnings.warn("Will download `usearch_sqlite` binary from GitHub.", UserWarning)
+            try:
+                source_url = self.determine_download_url(self.version, source_filename)
+                os.makedirs(download_dir, exist_ok=True)
+                urllib.request.urlretrieve(source_url, local_path)
+            except HTTPError as e:
+                # If the download fails due to HTTPError (e.g., 404 Not Found), like a missing lib version
+                if e.code == 404:
+                    warnings.warn(f"Download failed: {e.url} could not be found.", UserWarning)
+                else:
+                    warnings.warn(f"Download failed with HTTP error: {e.code} {e.reason}", UserWarning)
+                return None
+
+        # Handle the case where binary_path does not exist after supposed successful download
+        if os.path.exists(local_path):
+            path_wout_extension, _, _ = local_path.rpartition(".")
+            return path_wout_extension
+        else:
+            warnings.warn("Failed to download `usearch_sqlite` binary from GitHub.", UserWarning)
+            return None
+
+
+def sqlite_path(version: str = None) -> str:
+    manager = BinaryManager(version=version)
+    result = manager.sqlite_found_or_downloaded()
+    if result is None:
+        raise FileNotFoundError("Failed to find or download `usearch_sqlite` binary.")
+    return result

usearch/client.py

@@ -0,0 +1,120 @@
+from typing import Union, Optional, List
+
+import numpy as np
+from ucall.client import Client
+
+from usearch.index import Matches
+
+
+def _vector_to_ascii(vector: np.ndarray) -> Optional[str]:
+    if vector.dtype != np.int8 and vector.dtype != np.uint8 and vector.dtype != np.byte:
+        return None
+    if not np.all((vector >= 0) | (vector <= 100)):
+        return None
+
+    # Let's map [0, 100] to the range from [23, 123],
+    # poking 60 and replacing with the 124.
+    vector += 23
+    vector[vector == 60] = 124
+    ascii_vector = str(vector)
+    return ascii_vector
+
+
+class IndexClient:
+    def __init__(self, uri: str = "127.0.0.1", port: int = 8545, use_http: bool = True) -> None:
+        self.client = Client(uri=uri, port=port, use_http=use_http)
+
+    def add_one(self, key: int, vector: np.ndarray):
+        assert isinstance(key, int)
+        assert isinstance(vector, np.ndarray)
+        vector = vector.flatten()
+        ascii_vector = _vector_to_ascii(vector)
+        if ascii_vector:
+            self.client.add_ascii(key=key, string=ascii_vector)
+        else:
+            self.client.add_one(key=key, vectors=vector)
+
+    def add_many(self, keys: np.ndarray, vectors: np.ndarray):
+        assert isinstance(keys, int)
+        assert isinstance(vectors, np.ndarray)
+        assert keys.ndim == 1 and vectors.ndim == 2
+        assert keys.shape[0] == vectors.shape[0]
+        self.client.add_many(keys=keys, vectors=vectors)
+
+    def add(self, keys: Union[np.ndarray, int], vectors: np.ndarray):
+        if isinstance(keys, int) or len(keys) == 1:
+            return self.add_one(keys, vectors)
+        else:
+            return self.add_many(keys, vectors)
+
+    def search_one(self, vector: np.ndarray, count: int) -> Matches:
+        matches: List[dict] = []
+        vector = vector.flatten()
+        ascii_vector = _vector_to_ascii(vector)
+        if ascii_vector:
+            matches = self.client.search_ascii(string=ascii_vector, count=count)
+        else:
+            matches = self.client.search_one(vector=vector, count=count)
+
+        print(matches.data)
+        matches = matches.json
+
+        keys = np.array((1, count), dtype=np.uint32)
+        distances = np.array((1, count), dtype=np.float32)
+        counts = np.array((1), dtype=np.uint32)
+        for col, result in enumerate(matches):
+            keys[0, col] = result["key"]
+            distances[0, col] = result["distance"]
+        counts[0] = len(matches)
+
+        return keys, distances, counts
+
+    def search_many(self, vectors: np.ndarray, count: int) -> Matches:
+        batch_size: int = vectors.shape[0]
+        list_of_matches: List[List[dict]] = self.client.search_many(vectors=vectors, count=count)
+
+        keys = np.array((batch_size, count), dtype=np.uint32)
+        distances = np.array((batch_size, count), dtype=np.float32)
+        counts = np.array((batch_size), dtype=np.uint32)
+        for row, matches in enumerate(list_of_matches):
+            for col, result in enumerate(matches):
+                keys[row, col] = result["key"]
+                distances[row, col] = result["distance"]
+            counts[row] = len(results)
+
+        return keys, distances, counts
+
+    def search(self, vectors: np.ndarray, count: int) -> Matches:
+        if vectors.ndim == 1 or (vectors.ndim == 2 and vectors.shape[0] == 1):
+            return self.search_one(vectors, count)
+        else:
+            return self.search_many(vectors, count)
+
+    def __len__(self):
+        return self.client.size().json()
+
+    @property
+    def ndim(self):
+        return self.client.ndim().json()
+
+    def capacity(self):
+        return self.client.capacity().json()
+
+    def connectivity(self):
+        return self.client.connectivity().json()
+
+    def load(self, path: str):
+        raise NotImplementedError()
+
+    def view(self, path: str):
+        raise NotImplementedError()
+
+    def save(self, path: str):
+        raise NotImplementedError()
+
+
+if __name__ == "__main__":
+    index = IndexClient()
+    index.add(42, np.array([0.4] * 256, dtype=np.float32))
+    results = index.search(np.array([0.4] * 256, dtype=np.float32), 10)
+    print(results)