microvec 0.1.0__py3-none-any.whl

microvec-0.1.0.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: microvec
+Version: 0.1.0
+Summary: A lightweight, production-grade in-memory vector database
+Project-URL: Homepage, https://github.com/huolter/microVector
+Project-URL: Repository, https://github.com/huolter/microVector
+Project-URL: Bug Tracker, https://github.com/huolter/microVector/issues
+Project-URL: Changelog, https://github.com/huolter/microVector/blob/main/CHANGELOG.md
+Author: huolter
+License: MIT
+Keywords: database,embeddings,rag,search,similarity,vector
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MicroVector
+
+A lightweight, production-grade in-memory vector database for Python.
+
+```
+pip install microvector
+```
+
+No external services. No complex setup. Just numpy and your embeddings.
+
+---
+
+## Features
+
+- **Fast similarity search** — cosine, euclidean, and dot product metrics
+- **Rich results** — every search result includes the document text and metadata, not just an index
+- **Batch operations** — insert thousands of vectors in one call
+- **Metadata filtering** — filter candidates before scoring with any Python predicate
+- **Safe persistence** — JSON + numpy format (no pickle, no security risk)
+- **Full type hints** — works great with mypy and IDEs
+- **Zero required dependencies** beyond numpy
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+from microvector import MicroVectorDB
+
+# Create a database for 768-dimensional embeddings (e.g. OpenAI ada-002)
+db = MicroVectorDB(dimension=768)
+
+# Add documents with their embeddings
+db.add_node(embed("Paris is the capital of France"), "Paris is the capital of France")
+db.add_node(embed("The Eiffel Tower is in Paris"),   "The Eiffel Tower is in Paris")
+db.add_node(embed("Python is a programming language"), "Python is a programming language")
+
+# Search — results include document text, not just indexes
+results = db.search_top_k(embed("What city is the Eiffel Tower in?"), k=2)
+for r in results:
+    print(f"{r.score:.3f}  {r.document}")
+# 0.921  The Eiffel Tower is in Paris
+# 0.887  Paris is the capital of France
+
+# Save and reload
+db.save("my_knowledge_base")
+db = MicroVectorDB.load("my_knowledge_base")
+```
+
+---
+
+## Installation
+
+**Requires Python 3.9+ and numpy >= 1.21.**
+
+```bash
+pip install microvector
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/huolter/microVector
+cd microVector
+pip install -e ".[dev]"
+```
+
+---
+
+## API Reference
+
+### `MicroVectorDB(dimension)`
+
+Create a new database. All vectors must have this exact dimension.
+
+```python
+db = MicroVectorDB(dimension=512)
+```
+
+---
+
+### `add_node(vector, document, metadata=None, num_bits=None) → int`
+
+Add a single vector. Returns the assigned index.
+
+```python
+idx = db.add_node(
+    vector=np.array([...]),
+    document="The text this vector represents",
+    metadata={"source": "wikipedia", "date": "2024-01"},
+    num_bits=8,   # optional: apply 8-bit scalar quantization
+)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `vector` | `np.ndarray` | 1-D array matching the database dimension |
+| `document` | `str` | Text or identifier associated with this vector |
+| `metadata` | `dict` | Optional key-value pairs stored alongside the vector |
+| `num_bits` | `int` | Optional quantization (1–16 bits). Reduces memory at the cost of precision. |
+
+---
+
+### `add_nodes(vectors, documents, metadata=None) → list[int]`
+
+Batch insert. All inputs are validated before any insertion occurs.
+
+```python
+import numpy as np
+
+vectors = np.random.rand(1000, 512)
+docs = [f"Document {i}" for i in range(1000)]
+indices = db.add_nodes(vectors, docs)
+```
+
+---
+
+### `search_top_k(query_vector, k, metric='cosine', filter_fn=None) → list[SearchResult]`
+
+Find the top-k most similar vectors. Returns results sorted by score descending.
+
+```python
+results = db.search_top_k(query, k=5)
+results = db.search_top_k(query, k=5, metric="euclidean")
+
+# Filter before scoring — only consider documents tagged "news"
+results = db.search_top_k(
+    query, k=5,
+    filter_fn=lambda node: node.metadata.get("type") == "news"
+)
+```
+
+**Metrics:**
+
+| Metric | Range | Notes |
+|--------|-------|-------|
+| `cosine` | [-1, 1] | Best for text embeddings. Direction-based, scale-invariant. |
+| `euclidean` | (0, 1] | `1 / (1 + dist)`. Identical vectors = 1.0. |
+| `dot` | (-∞, +∞) | Fastest. Best for pre-normalized unit vectors. |
+
+**`SearchResult` fields:**
+
+```python
+result.index     # int   — node's assigned index
+result.document  # str   — the document text
+result.score     # float — similarity score (higher = more similar)
+result.metadata  # dict  — metadata stored with this node
+```
+
+---
+
+### `search_by_threshold(query_vector, min_score, metric='cosine') → list[SearchResult]`
+
+Return all nodes with score >= `min_score`, sorted descending.
+
+```python
+results = db.search_by_threshold(query, min_score=0.8)
+```
+
+---
+
+### `get_node(index) → Node`
+
+Retrieve a node by index.
+
+```python
+node = db.get_node(42)
+print(node.document, node.metadata)
+```
+
+---
+
+### `update_node(index, vector=None, document=None, metadata=None)`
+
+Update fields of an existing node. Omit fields to leave them unchanged.
+
+```python
+db.update_node(42, document="Updated text")
+db.update_node(42, metadata={"status": "reviewed"})
+```
+
+---
+
+### `remove_node(index)`
+
+Remove a node. Its index is permanently retired (never reused).
+
+```python
+db.remove_node(42)
+```
+
+---
+
+### `save(path)` / `MicroVectorDB.load(path)`
+
+Persist to and restore from a `.mvdb/` directory. Safe format: JSON + numpy binary.
+
+```python
+db.save("my_db")              # creates my_db.mvdb/
+db = MicroVectorDB.load("my_db")
+```
+
+The `.mvdb/` directory contains:
+- `index.json` — node metadata and documents (human-readable)
+- `vectors.npy` — all vectors as a 2-D numpy array
+
+---
+
+### Utility methods
+
+```python
+len(db)           # number of nodes
+42 in db          # check if index exists
+repr(db)          # MicroVectorDB(dimension=512, nodes=1000, next_index=1000)
+db.stats()        # {'count': 1000, 'dimension': 512, 'next_index': 1000, ...}
+```
+
+---
+
+## Exceptions
+
+All exceptions inherit from `MicroVectorError`.
+
+```python
+from microvector import (
+    MicroVectorError,
+    DimensionMismatchError,  # wrong vector dimension
+    EmptyDatabaseError,      # search on empty database
+    NodeNotFoundError,       # get/update/remove non-existent index
+)
+```
+
+---
+
+## Design Notes
+
+**Why in-memory?** MicroVector is designed for small-to-medium datasets (up to ~100k vectors) where the simplicity of pure-Python outweighs the need for a dedicated service. It starts instantly, needs no configuration, and is trivially embeddable in any Python application.
+
+**Why not pickle?** Pickle can execute arbitrary code when loading untrusted files. MicroVector uses JSON + numpy binary format which is safe, portable, and inspectable with any text editor.
+
+**Index monotonicity.** Deleted indexes are never reused. This prevents stale external references from silently pointing to new data.
+
+---
+
+## Roadmap
+
+- [ ] Approximate nearest neighbor (HNSW)
+- [ ] Voronoi cell indexing
+- [ ] FAISS optional backend for large datasets
+- [ ] Async search support
+- [ ] Benchmarks
+
+---
+
+## License
+
+MIT

microvec-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+microvector/__init__.py,sha256=aOlY0tDisQbs5JMtW0QLoLSUHnvyWQOrnYpyDAz5_P4,804
+microvector/core.py,sha256=g1W3Ou2Tim6W8TmcHLiBpE_8djaewnIIONUZKNuloA4,14946
+microvector/exceptions.py,sha256=NWHhUDeLuJGHRfEMHlbTdtWUwa1R6pBR5opcO_jwb-Y,916
+microvector/models.py,sha256=-YfPkQ_0YP4pgXBDNnEpIle4n73u-chsk_20n4mQhus,894
+microvector/quantization.py,sha256=DRemEHwhhkcoCUobpU-XAbbkzWI5Tct2WyJdJV5EAZE,1149
+microvector/similarity.py,sha256=9SABrDuMYBin5gSBql_hjnukBO5FHkbUlKtNwJ8tv6I,2136
+microvec-0.1.0.dist-info/METADATA,sha256=h4l8q3qMCdKliPbDQXWz33PywG_pNAWBq2-UADtP9Ns,7972
+microvec-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+microvec-0.1.0.dist-info/RECORD,,

microvec-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

microvector/__init__.py

@@ -0,0 +1,36 @@
+"""
+microvector — A lightweight, production-grade in-memory vector database.
+
+Quick start::
+
+    import numpy as np
+    from microvector import MicroVectorDB
+
+    db = MicroVectorDB(dimension=3)
+    db.add_node(np.array([1.0, 0.0, 0.0]), "hello world")
+
+    results = db.search_top_k(np.array([1.0, 0.0, 0.0]), k=1)
+    print(results[0].document)   # "hello world"
+    print(results[0].score)      # ~1.0
+"""
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MicroVectorDB",
+    "SearchResult",
+    "Node",
+    "MicroVectorError",
+    "DimensionMismatchError",
+    "EmptyDatabaseError",
+    "NodeNotFoundError",
+]
+
+from .core import MicroVectorDB
+from .exceptions import (
+    DimensionMismatchError,
+    EmptyDatabaseError,
+    MicroVectorError,
+    NodeNotFoundError,
+)
+from .models import Node, SearchResult

microvector/core.py

@@ -0,0 +1,436 @@
+"""Core MicroVectorDB class."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+import numpy as np
+
+from .exceptions import DimensionMismatchError, EmptyDatabaseError, NodeNotFoundError
+from .models import Node, SearchResult
+from .quantization import binary_quantization
+from .similarity import get_metric
+
+
+class MicroVectorDB:
+    """
+    A lightweight, in-memory vector database.
+
+    Indexes are assigned monotonically and are never reused after deletion.
+    All similarity scores follow the convention: higher = more similar.
+
+    Example:
+        >>> import numpy as np
+        >>> from microvector import MicroVectorDB
+        >>> db = MicroVectorDB(dimension=3)
+        >>> db.add_node(np.array([1.0, 0.0, 0.0]), "hello")
+        0
+        >>> results = db.search_top_k(np.array([1.0, 0.0, 0.0]), k=1)
+        >>> results[0].document
+        'hello'
+    """
+
+    def __init__(self, dimension: int) -> None:
+        """
+        Initialize a new MicroVectorDB.
+
+        Args:
+            dimension: The fixed dimension of all vectors in this database.
+
+        Raises:
+            ValueError: If dimension < 1.
+        """
+        if dimension < 1:
+            raise ValueError(f"dimension must be >= 1, got {dimension}")
+        self._dimension = dimension
+        self._nodes: dict[int, Node] = {}
+        self._next_index: int = 0
+
+    # ------------------------------------------------------------------ #
+    # Internal helpers                                                      #
+    # ------------------------------------------------------------------ #
+
+    def _validate_vector(self, vector: np.ndarray) -> None:
+        """Validate that a vector is a 1-D numpy array of the correct dimension."""
+        if not isinstance(vector, np.ndarray):
+            raise TypeError(f"vector must be np.ndarray, got {type(vector).__name__}")
+        if vector.ndim != 1:
+            raise ValueError(f"vector must be 1-D, got shape {vector.shape}")
+        if vector.shape[0] != self._dimension:
+            raise DimensionMismatchError(self._dimension, vector.shape[0])
+
+    # ------------------------------------------------------------------ #
+    # Mutation                                                              #
+    # ------------------------------------------------------------------ #
+
+    def add_node(
+        self,
+        vector: np.ndarray,
+        document: str,
+        metadata: dict[str, Any] | None = None,
+        num_bits: int | None = None,
+    ) -> int:
+        """
+        Add a single node to the database.
+
+        Args:
+            vector: The embedding vector. Must match the database dimension.
+            document: The text or identifier associated with this vector.
+            metadata: Optional dict of arbitrary key-value pairs.
+            num_bits: If set, apply n-bit scalar quantization before storing.
+
+        Returns:
+            The index assigned to the new node.
+
+        Raises:
+            TypeError: If vector is not a numpy array.
+            DimensionMismatchError: If vector dimension doesn't match the database.
+        """
+        self._validate_vector(vector)
+        v = (
+            binary_quantization(vector, num_bits)
+            if num_bits is not None
+            else vector.copy()
+        )
+        node = Node(
+            index=self._next_index,
+            vector=v,
+            document=document,
+            metadata=metadata or {},
+        )
+        self._nodes[self._next_index] = node
+        self._next_index += 1
+        return node.index
+
+    def add_nodes(
+        self,
+        vectors: np.ndarray | list[np.ndarray],
+        documents: list[str],
+        metadata: list[dict[str, Any] | None] | None = None,
+    ) -> list[int]:
+        """
+        Add multiple nodes in a single call.
+
+        All inputs are validated before any insertion occurs, so either all
+        nodes are added or none are (fail-fast, not partial).
+
+        Args:
+            vectors: A 2-D numpy array (n, dim) or list of 1-D arrays.
+            documents: List of document strings, one per vector.
+            metadata: Optional list of metadata dicts, one per vector.
+
+        Returns:
+            List of assigned indexes, in the same order as the inputs.
+
+        Raises:
+            ValueError: If vectors and documents have different lengths.
+            DimensionMismatchError: If any vector has wrong dimension.
+        """
+        if isinstance(vectors, np.ndarray):
+            if vectors.ndim != 2:
+                raise ValueError(
+                    "Batch vectors array must be 2-D (n_vectors, dimension)"
+                )
+            vector_list: list[np.ndarray] = [
+                vectors[i] for i in range(vectors.shape[0])
+            ]
+        else:
+            vector_list = list(vectors)
+
+        if len(vector_list) != len(documents):
+            raise ValueError(
+                f"vectors and documents must have the same length: "
+                f"{len(vector_list)} != {len(documents)}"
+            )
+        if metadata is not None and len(metadata) != len(vector_list):
+            raise ValueError(
+                f"metadata list must match vectors length: "
+                f"{len(metadata)} != {len(vector_list)}"
+            )
+
+        # Validate all before inserting any
+        for v in vector_list:
+            self._validate_vector(v)
+
+        metas: list[dict[str, Any] | None] = (
+            metadata if metadata is not None else [None] * len(vector_list)
+        )
+        return [
+            self.add_node(v, doc, meta)
+            for v, doc, meta in zip(vector_list, documents, metas)
+        ]
+
+    def get_node(self, index: int) -> Node:
+        """
+        Retrieve a node by its index.
+
+        Raises:
+            NodeNotFoundError: If no node with that index exists.
+        """
+        if index not in self._nodes:
+            raise NodeNotFoundError(index)
+        return self._nodes[index]
+
+    def update_node(
+        self,
+        index: int,
+        vector: np.ndarray | None = None,
+        document: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Update one or more fields of an existing node.
+
+        Only provided fields are changed; omitted fields are left as-is.
+
+        Raises:
+            NodeNotFoundError: If no node with that index exists.
+            DimensionMismatchError: If the new vector has wrong dimension.
+        """
+        node = self.get_node(index)
+        if vector is not None:
+            self._validate_vector(vector)
+            node.vector = vector.copy()
+        if document is not None:
+            node.document = document
+        if metadata is not None:
+            node.metadata = metadata
+
+    def remove_node(self, index: int) -> None:
+        """
+        Remove a node by its index.
+
+        The index is permanently retired — it will not be reused for future nodes.
+
+        Raises:
+            NodeNotFoundError: If no node with that index exists.
+        """
+        if index not in self._nodes:
+            raise NodeNotFoundError(index)
+        del self._nodes[index]
+
+    # ------------------------------------------------------------------ #
+    # Search                                                                #
+    # ------------------------------------------------------------------ #
+
+    def search_top_k(
+        self,
+        query_vector: np.ndarray,
+        k: int,
+        metric: str = "cosine",
+        filter_fn: Callable[[Node], bool] | None = None,
+    ) -> list[SearchResult]:
+        """
+        Find the top-k most similar nodes to a query vector.
+
+        Args:
+            query_vector: The query embedding. Must match the database dimension.
+            k: Number of results to return. If k > number of nodes, all nodes
+               are returned (no error).
+            metric: Distance metric — 'cosine', 'euclidean', or 'dot'.
+            filter_fn: Optional predicate to pre-filter nodes before scoring.
+                       Only nodes where filter_fn(node) is True are considered.
+
+        Returns:
+            List of SearchResult objects sorted by score descending.
+            Each result includes: index, document, score, metadata.
+
+        Raises:
+            EmptyDatabaseError: If the database has no nodes.
+            DimensionMismatchError: If query_vector dimension doesn't match.
+            ValueError: If k < 1 or metric is unknown.
+        """
+        if not self._nodes:
+            raise EmptyDatabaseError()
+        self._validate_vector(query_vector)
+        if k < 1:
+            raise ValueError(f"k must be >= 1, got {k}")
+
+        sim_fn = get_metric(metric)
+        candidates = (
+            (n for n in self._nodes.values() if filter_fn(n))
+            if filter_fn is not None
+            else self._nodes.values()
+        )
+
+        results: list[SearchResult] = []
+        for node in candidates:
+            score = sim_fn(query_vector, node.vector)
+            results.append(
+                SearchResult(
+                    index=node.index,
+                    document=node.document,
+                    score=score,
+                    metadata=node.metadata,
+                )
+            )
+
+        results.sort(reverse=True)
+        return results[:k]
+
+    def search_by_threshold(
+        self,
+        query_vector: np.ndarray,
+        min_score: float,
+        metric: str = "cosine",
+    ) -> list[SearchResult]:
+        """
+        Return all nodes with similarity score >= min_score, sorted descending.
+
+        Args:
+            query_vector: The query embedding.
+            min_score: Minimum score threshold (inclusive).
+            metric: Distance metric — 'cosine', 'euclidean', or 'dot'.
+
+        Returns:
+            List of SearchResult objects with score >= min_score, sorted descending.
+
+        Raises:
+            EmptyDatabaseError: If the database has no nodes.
+            DimensionMismatchError: If query_vector dimension doesn't match.
+        """
+        if not self._nodes:
+            raise EmptyDatabaseError()
+        self._validate_vector(query_vector)
+
+        sim_fn = get_metric(metric)
+        results: list[SearchResult] = []
+        for node in self._nodes.values():
+            score = sim_fn(query_vector, node.vector)
+            if score >= min_score:
+                results.append(
+                    SearchResult(
+                        index=node.index,
+                        document=node.document,
+                        score=score,
+                        metadata=node.metadata,
+                    )
+                )
+        results.sort(reverse=True)
+        return results
+
+    # ------------------------------------------------------------------ #
+    # Persistence                                                           #
+    # ------------------------------------------------------------------ #
+
+    def save(self, path: str | Path) -> None:
+        """
+        Save the database to a ``.mvdb/`` directory.
+
+        The directory contains:
+        - ``index.json``: Node metadata, documents, and manifest.
+        - ``vectors.npy``: All vectors as a 2-D numpy array.
+
+        This format is safe (no arbitrary code execution unlike pickle),
+        portable, and human-inspectable.
+
+        Args:
+            path: Destination path. The ``.mvdb`` extension is added automatically
+                  if not already present.
+        """
+        path = Path(path)
+        if not path.name.endswith(".mvdb"):
+            path = path.with_suffix(".mvdb")
+        path.mkdir(parents=True, exist_ok=True)
+
+        indices = sorted(self._nodes.keys())
+        manifest = {
+            "version": "1.0",
+            "dimension": self._dimension,
+            "next_index": self._next_index,
+            "count": len(indices),
+            "nodes": [
+                {
+                    "index": i,
+                    "document": self._nodes[i].document,
+                    "metadata": self._nodes[i].metadata,
+                    "vector_row": row,
+                }
+                for row, i in enumerate(indices)
+            ],
+        }
+
+        if indices:
+            vector_matrix = np.stack([self._nodes[i].vector for i in indices])
+        else:
+            vector_matrix = np.empty((0, self._dimension), dtype=np.float32)
+
+        with open(path / "index.json", "w", encoding="utf-8") as f:
+            json.dump(manifest, f, indent=2)
+        np.save(str(path / "vectors.npy"), vector_matrix)
+
+    @classmethod
+    def load(cls, path: str | Path) -> MicroVectorDB:
+        """
+        Load a database from a ``.mvdb/`` directory.
+
+        Args:
+            path: Path to the ``.mvdb`` directory (extension added if omitted).
+
+        Returns:
+            A fully restored MicroVectorDB instance.
+
+        Raises:
+            FileNotFoundError: If the path does not exist.
+        """
+        path = Path(path)
+        if not path.name.endswith(".mvdb"):
+            path = path.with_suffix(".mvdb")
+
+        if not path.exists():
+            raise FileNotFoundError(f"No database found at {path}")
+
+        with open(path / "index.json", encoding="utf-8") as f:
+            manifest = json.load(f)
+
+        vectors = np.load(str(path / "vectors.npy"))
+        db = cls(dimension=manifest["dimension"])
+        db._next_index = manifest["next_index"]
+
+        for node_meta in manifest["nodes"]:
+            row = node_meta["vector_row"]
+            node = Node(
+                index=node_meta["index"],
+                vector=vectors[row],
+                document=node_meta["document"],
+                metadata=node_meta["metadata"],
+            )
+            db._nodes[node.index] = node
+
+        return db
+
+    # ------------------------------------------------------------------ #
+    # Dunder methods                                                        #
+    # ------------------------------------------------------------------ #
+
+    def __len__(self) -> int:
+        """Return the number of nodes currently in the database."""
+        return len(self._nodes)
+
+    def __contains__(self, index: object) -> bool:
+        """Check whether an index exists in the database."""
+        return index in self._nodes
+
+    def __repr__(self) -> str:
+        return (
+            f"MicroVectorDB(dimension={self._dimension}, "
+            f"nodes={len(self._nodes)}, "
+            f"next_index={self._next_index})"
+        )
+
+    def stats(self) -> dict[str, Any]:
+        """
+        Return a summary of the database state.
+
+        Returns:
+            Dict with keys: count, dimension, next_index, index_gaps, indices.
+        """
+        return {
+            "count": len(self._nodes),
+            "dimension": self._dimension,
+            "next_index": self._next_index,
+            "index_gaps": self._next_index - len(self._nodes),
+            "indices": sorted(self._nodes.keys()),
+        }

microvector/exceptions.py

@@ -0,0 +1,29 @@
+"""Custom exceptions for microvector."""
+
+
+class MicroVectorError(Exception):
+    """Base exception for all microvector errors."""
+
+
+class DimensionMismatchError(MicroVectorError):
+    """Raised when a vector's dimension does not match the database dimension."""
+
+    def __init__(self, expected: int, got: int) -> None:
+        super().__init__(f"Vector dimension mismatch: expected {expected}, got {got}")
+        self.expected = expected
+        self.got = got
+
+
+class EmptyDatabaseError(MicroVectorError):
+    """Raised when a search is attempted on an empty database."""
+
+    def __init__(self) -> None:
+        super().__init__("Cannot search an empty database.")
+
+
+class NodeNotFoundError(MicroVectorError):
+    """Raised when a node with the given index does not exist."""
+
+    def __init__(self, index: int) -> None:
+        super().__init__(f"No node found with index {index}.")
+        self.index = index

microvector/models.py

@@ -0,0 +1,36 @@
+"""Data models for microvector."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+
+@dataclass
+class Node:
+    """A stored vector with its associated document and optional metadata."""
+
+    index: int
+    vector: np.ndarray
+    document: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Node):
+            return NotImplemented
+        return self.index == other.index and np.array_equal(self.vector, other.vector)
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    """An immutable search result returned by query methods."""
+
+    index: int
+    document: str
+    score: float
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __lt__(self, other: SearchResult) -> bool:
+        return self.score < other.score

microvector/quantization.py

@@ -0,0 +1,36 @@
+"""Vector quantization utilities."""
+
+from typing import cast
+
+import numpy as np
+
+
+def binary_quantization(vector: np.ndarray, num_bits: int) -> np.ndarray:
+    """
+    Scalar quantization: maps float values into 2^num_bits integer buckets.
+
+    Args:
+        vector: 1-D float array.
+        num_bits: Number of bits (1–16). Common values: 4, 8.
+
+    Returns:
+        Quantized vector as float32.
+
+    Note:
+        When min == max (constant vector), all values map to bucket 0.
+    """
+    if num_bits < 1 or num_bits > 16:
+        raise ValueError(f"num_bits must be between 1 and 16, got {num_bits}")
+    if vector.ndim != 1:
+        raise ValueError(f"vector must be 1-D, got shape {vector.shape}")
+
+    num_buckets = 2**num_bits
+    v_min, v_max = float(np.min(vector)), float(np.max(vector))
+
+    if v_min == v_max:
+        return cast(np.ndarray, np.zeros(vector.shape, dtype=np.float32))
+
+    ranges = np.linspace(v_min, v_max, num=num_buckets + 1, endpoint=True)
+    quantized = np.digitize(vector, ranges, right=True) - 1
+    quantized = np.clip(quantized, 0, num_buckets - 1)
+    return cast(np.ndarray, quantized.astype(np.float32))

microvector/similarity.py

@@ -0,0 +1,71 @@
+"""Similarity and distance functions for vector search."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+
+
+def _validate_shapes(a: np.ndarray, b: np.ndarray) -> None:
+    if a.shape != b.shape:
+        raise ValueError(f"Shape mismatch: {a.shape} vs {b.shape}")
+
+
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """
+    Cosine similarity between two vectors.
+
+    Returns a value in [-1.0, 1.0] where 1.0 means identical direction.
+    Returns 0.0 if either vector has zero norm (no direction to compare).
+
+    Fixes original bug: crashed with ZeroDivisionError on zero-norm vectors.
+    """
+    _validate_shapes(a, b)
+    norm_a = float(np.linalg.norm(a))
+    norm_b = float(np.linalg.norm(b))
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    raw = np.dot(a, b) / (norm_a * norm_b)
+    return float(np.clip(raw, -1.0, 1.0))
+
+
+def euclidean_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """
+    Euclidean similarity between two vectors: 1 / (1 + distance).
+
+    Maps distance [0, ∞) → similarity (0, 1]. Identical vectors score 1.0.
+
+    Fixes original bug: returned raw negative distance, making far vectors
+    rank as more similar than near ones.
+    """
+    _validate_shapes(a, b)
+    dist = float(np.linalg.norm(a - b))
+    return 1.0 / (1.0 + dist)
+
+
+def dot_product_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """
+    Raw dot product similarity.
+
+    Not normalized to [0, 1]. Best used with pre-normalized embeddings
+    (e.g., unit-norm vectors from OpenAI or HuggingFace models).
+    """
+    _validate_shapes(a, b)
+    return float(np.dot(a, b))
+
+
+METRICS: dict[str, Callable[[np.ndarray, np.ndarray], float]] = {
+    "cosine": cosine_similarity,
+    "euclidean": euclidean_similarity,
+    "dot": dot_product_similarity,
+}
+
+
+def get_metric(name: str) -> Callable[[np.ndarray, np.ndarray], float]:
+    """Return the similarity function for the given metric name."""
+    if name not in METRICS:
+        raise ValueError(
+            f"Unknown metric '{name}'. Choose from: {sorted(METRICS.keys())}"
+        )
+    return METRICS[name]