fromscratch-pyvecdb 0.3.0__py3-none-any.whl

fromscratch_pyvecdb-0.3.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: fromscratch-pyvecdb
+Version: 0.3.0
+Summary: An educational vector database library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pyvecdb
+Project-URL: Repository, https://github.com/robcox2910/pyvecdb
+Project-URL: Issues, https://github.com/robcox2910/pyvecdb/issues
+Project-URL: Documentation, https://robcox2910.github.io/pyvecdb/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: database,education,search,similarity,vector
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyvecdb
+
+An educational vector database library built from scratch in Python. Part of the **PyLearn** platform for kids aged 12+.
+
+## What is a Vector Database?
+
+A vector database stores **vectors** (lists of numbers) and finds **similar** ones. Think of it like a music app that turns songs into lists of numbers and finds other songs with similar numbers!
+
+## Features
+
+- **Vector Operations** -- add, subtract, scale, normalize, dot product, magnitude
+- **Vector Store** -- CRUD operations for vector records with dimensionality checks
+- **Distance Metrics** -- cosine similarity, Euclidean, Manhattan, dot product
+- **KNN Search** -- find the K most similar vectors to a query
+- **Metadata Filtering** -- filter results by metadata (eq, ne, gt, gte, lt, lte, in)
+- **Batch Operations** -- insert and search multiple vectors at once
+- **Persistence** -- save/load to JSON files
+- **Pure Python** -- no external dependencies
+
+## Quick Start
+
+```python
+from pyvecdb import VectorStore, knn_search
+
+# Create a store for 3-dimensional vectors
+store = VectorStore(dimensions=3)
+
+# Insert some songs as vectors (energy, happiness, danceability)
+store.insert("thunder", [0.9, 0.6, 0.7], metadata={"genre": "rock", "year": 2017})
+store.insert("lullaby", [0.1, 0.8, 0.2], metadata={"genre": "folk", "year": 2020})
+store.insert("party-rock", [0.95, 0.9, 0.99], metadata={"genre": "pop", "year": 2011})
+store.insert("ballad", [0.3, 0.4, 0.1], metadata={"genre": "rock", "year": 2019})
+
+# Find the 2 most similar songs to a high-energy query
+results = knn_search(store, query=[0.85, 0.7, 0.8], k=2)
+for record, score in results:
+    print(f"{record.record_id}: {score:.3f}")
+# party-rock: 0.998
+# thunder: 0.995
+
+# Filter by metadata -- only rock songs
+results = knn_search(
+    store,
+    query=[0.85, 0.7, 0.8],
+    k=2,
+    metadata_filter={"genre": "rock"},
+)
+```
+
+## Installation
+
+```bash
+git clone https://github.com/robcox2910/pyvecdb.git
+cd pyvecdb
+uv sync --all-extras
+```
+
+## Development
+
+```bash
+uv run ruff check src/ tests/      # Lint
+uv run ruff format src/ tests/      # Format
+uv run pyright src tests            # Type check
+uv run pytest                       # Test (90%+ coverage)
+```
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| **PyVecDB** | **Vector databases** | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pyvecdb/
+<!-- docs:end -->
+
+## License
+
+MIT

fromscratch_pyvecdb-0.3.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pyvecdb/__init__.py,sha256=60yt6pheS_PQEOV63U2Iqqpgtmnd4akAvS-5NQZdrmA,2000
+pyvecdb/_version.py,sha256=RCY04NY0kBCyn6ttH6lnVL6Gz2gceOrt45f0yDOOU8A,520
+pyvecdb/atomic.py,sha256=QLLPGZqpA-TgVV5lDEKCLB7vVr05bxj97_Fwykz_gi4,2345
+pyvecdb/distance.py,sha256=Tq_GGed8SdcZ8RQ4GgEwUGoyXcd10KqUyyBb5EUQQgQ,4341
+pyvecdb/errors.py,sha256=7ajMrizSEMn_e4rd7mYvdtIQL9dWv38oU3p7OrCa5NQ,1711
+pyvecdb/filtering.py,sha256=s1S6_aV82vLBiKHx_11Y-FtrNFyBkLoAkjUijoT6HT8,4041
+pyvecdb/persistence.py,sha256=BCIWp0alRku6ATia-WvhZOkpEOLkV5IjfZJTW0nirVY,5076
+pyvecdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyvecdb/record.py,sha256=sUUgaTG-_7wjp9NaZ5V9Iv0ozcZSTWrTTuEYMp3btwo,3174
+pyvecdb/search.py,sha256=MKtLNSbsvjM2S4Mg2WNQoJd6quHn0h2N4R-tciFf_Cw,5395
+pyvecdb/store.py,sha256=l_rsP5piqlEbo4Je2N-QdsoXu9za4JtCVtDFdo6-LUs,8212
+pyvecdb/vector.py,sha256=uhC4q4aeF9QV1_ste_nV8PHpvzKO8Yp7DE5tnrIwGxs,5208
+fromscratch_pyvecdb-0.3.0.dist-info/METADATA,sha256=nicgBasl2jhM8RwBMAnt6yZyMPOAvM9F8qwJH5oNzSQ,6957
+fromscratch_pyvecdb-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pyvecdb-0.3.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pyvecdb-0.3.0.dist-info/RECORD,,

fromscratch_pyvecdb-0.3.0.dist-info/WHEEL

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

fromscratch_pyvecdb-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyvecdb/__init__.py

@@ -0,0 +1,68 @@
+"""pyvecdb -- an educational vector database built from scratch in Python.
+
+A vector database stores vectors (lists of numbers) and finds similar ones.
+Think of it like a music app that knows your taste -- it turns songs into
+lists of numbers and finds other songs with similar numbers.
+
+This is part of the PyLearn educational platform for kids aged 12+.
+
+Quick Start:
+    >>> from pyvecdb import VectorStore, knn_search
+    >>> store = VectorStore(dimensions=3)
+    >>> store.insert("rock-song", [0.9, 0.1, 0.3], metadata={"genre": "rock"})
+    >>> store.insert("pop-song", [0.2, 0.8, 0.4], metadata={"genre": "pop"})
+    >>> store.insert("rock-ballad", [0.7, 0.3, 0.5], metadata={"genre": "rock"})
+    >>> results = knn_search(store, query=[0.85, 0.15, 0.35], k=2)
+    >>> [r.record_id for r, _ in results]
+    ['rock-song', 'rock-ballad']
+"""
+
+from pyvecdb.distance import (
+    cosine_similarity,
+    dot_product,
+    euclidean_distance,
+    manhattan_distance,
+)
+from pyvecdb.errors import (
+    DimensionMismatchError,
+    DuplicateIDError,
+    EmptyStoreError,
+    EmptyVectorError,
+    PersistenceError,
+    RecordNotFoundError,
+    VecDBError,
+)
+from pyvecdb.filtering import filter_records, matches_filter
+from pyvecdb.persistence import load_store, save_store
+from pyvecdb.record import VectorRecord
+from pyvecdb.search import batch_search, knn_search
+from pyvecdb.store import VectorStore
+from pyvecdb.vector import add, dot, magnitude, normalize, scale, subtract
+
+__all__ = [
+    "DimensionMismatchError",
+    "DuplicateIDError",
+    "EmptyStoreError",
+    "EmptyVectorError",
+    "PersistenceError",
+    "RecordNotFoundError",
+    "VecDBError",
+    "VectorRecord",
+    "VectorStore",
+    "add",
+    "batch_search",
+    "cosine_similarity",
+    "dot",
+    "dot_product",
+    "euclidean_distance",
+    "filter_records",
+    "knn_search",
+    "load_store",
+    "magnitude",
+    "manhattan_distance",
+    "matches_filter",
+    "normalize",
+    "save_store",
+    "scale",
+    "subtract",
+]

pyvecdb/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

pyvecdb/atomic.py

@@ -0,0 +1,66 @@
+"""Safe saving -- never leave a half-written file behind.
+
+The usual way to save a file is: open it, wipe it, write the new
+contents. If the computer crashes after the wipe but before the writing
+finishes, your data is gone -- the old version was wiped and the new one
+never arrived.
+
+So we save like a careful student copying out their homework:
+
+1. Write the new version on a **fresh sheet** (a temporary file sitting
+   right next to the real one).
+2. Make sure the **ink is dry** -- ``fsync`` forces the bytes out of the
+   computer's memory and onto the disk.
+3. **Swap** the fresh sheet in for the old one in a single instant step
+   (``Path.replace``). There is never a moment with no complete file: you
+   see either the old version or the new one, never half of each.
+
+Real databases (SQLite, PostgreSQL, Redis) all use this same trick.
+"""
+
+import contextlib
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+# Permissions for a brand-new file: owner can read/write, others can read.
+_NEW_FILE_MODE = 0o644
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Replace the file at *path* with *text*, so a crash can never leave it half-written.
+
+    Args:
+        path: The file to create or replace (its folder must already exist).
+        text: The new contents, saved as UTF-8.
+
+    """
+    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else _NEW_FILE_MODE
+    fd, temp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as temp_file:
+            temp_file.write(text)
+            temp_file.flush()
+            os.fsync(temp_file.fileno())
+        temp_path.chmod(mode)
+        temp_path.replace(path)
+    except BaseException:
+        temp_path.unlink(missing_ok=True)  # don't leave the scrap sheet lying around
+        raise
+    _sync_folder(path.parent)
+
+
+def _sync_folder(folder: Path) -> None:
+    """Make the swap itself durable by syncing the folder's list of files.
+
+    Some systems (like Windows) can't sync a folder; there the swap is
+    still safe, just not guaranteed to survive a power cut.
+    """
+    with contextlib.suppress(OSError):
+        fd = os.open(folder, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)

pyvecdb/distance.py

@@ -0,0 +1,138 @@
+"""Distance and similarity metrics for comparing vectors.
+
+Imagine you and your friend each rate 5 movies from 1 to 10.
+Your ratings are a vector like [8, 3, 9, 2, 7] and theirs might be [7, 4, 8, 3, 6].
+Distance metrics tell you how similar your taste in movies is!
+
+This module provides four ways to measure how "close" two vectors are:
+
+- **Cosine similarity** -- Are you pointing the same direction? (most popular for AI)
+- **Euclidean distance** -- How far apart are you in a straight line?
+- **Dot product** -- How much do your ratings "agree"?
+- **Manhattan distance** -- How far apart are you walking on a grid?
+
+Example:
+    >>> from pyvecdb.distance import cosine_similarity
+    >>> cosine_similarity([1.0, 0.0], [1.0, 0.0])
+    1.0
+    >>> cosine_similarity([1.0, 0.0], [0.0, 1.0])
+    0.0
+
+"""
+
+import math
+
+from pyvecdb.vector import check_not_empty, check_same_dimensions
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Compute cosine similarity between two vectors.
+
+    Cosine similarity measures the angle between two vectors, ignoring their length.
+    It returns a value between -1 (opposite) and 1 (identical direction).
+    Think of it like comparing which direction two arrows point, not how long they are.
+
+    Args:
+        a: The first vector.
+        b: The second vector.
+
+    Returns:
+        A float between -1.0 and 1.0 (1.0 means identical direction).
+
+    Raises:
+        DimensionMismatchError: If the vectors have different lengths.
+        EmptyVectorError: If either vector is empty.
+        ValueError: If either vector is a zero vector.
+
+    """
+    check_not_empty(a)
+    check_not_empty(b)
+    check_same_dimensions(a, b)
+
+    dot_product = sum(x * y for x, y in zip(a, b, strict=False))
+    mag_a = math.sqrt(sum(x * x for x in a))
+    mag_b = math.sqrt(sum(x * x for x in b))
+
+    if mag_a == 0.0 or mag_b == 0.0:
+        msg = "Cannot compute cosine similarity with a zero vector"
+        raise ValueError(msg)
+
+    return dot_product / (mag_a * mag_b)
+
+
+def euclidean_distance(a: list[float], b: list[float]) -> float:
+    """Compute the Euclidean (straight-line) distance between two vectors.
+
+    This is the "as the crow flies" distance -- the shortest path between
+    two points. Like using a ruler to measure between two dots on paper.
+
+    Args:
+        a: The first vector.
+        b: The second vector.
+
+    Returns:
+        A non-negative float (0.0 means the vectors are identical).
+
+    Raises:
+        DimensionMismatchError: If the vectors have different lengths.
+        EmptyVectorError: If either vector is empty.
+
+    """
+    check_not_empty(a)
+    check_not_empty(b)
+    check_same_dimensions(a, b)
+
+    # ``d * d`` rather than ``d ** 2``: for a number too big to square, ``**``
+    # raises OverflowError, while ``*`` gives infinity, just like magnitude().
+    return math.sqrt(sum((x - y) * (x - y) for x, y in zip(a, b, strict=False)))
+
+
+def dot_product(a: list[float], b: list[float]) -> float:
+    """Compute the dot product of two vectors.
+
+    Multiply each pair of matching numbers and add them all up.
+    A bigger result means the vectors "agree" more.
+
+    Args:
+        a: The first vector.
+        b: The second vector.
+
+    Returns:
+        The sum of component-wise products.
+
+    Raises:
+        DimensionMismatchError: If the vectors have different lengths.
+        EmptyVectorError: If either vector is empty.
+
+    """
+    check_not_empty(a)
+    check_not_empty(b)
+    check_same_dimensions(a, b)
+
+    return sum(x * y for x, y in zip(a, b, strict=False))
+
+
+def manhattan_distance(a: list[float], b: list[float]) -> float:
+    """Compute the Manhattan (taxicab) distance between two vectors.
+
+    Imagine walking through a city grid -- you can only go along streets,
+    not cut diagonally through buildings. Manhattan distance is the total
+    number of blocks you walk (up/down + left/right).
+
+    Args:
+        a: The first vector.
+        b: The second vector.
+
+    Returns:
+        A non-negative float (0.0 means the vectors are identical).
+
+    Raises:
+        DimensionMismatchError: If the vectors have different lengths.
+        EmptyVectorError: If either vector is empty.
+
+    """
+    check_not_empty(a)
+    check_not_empty(b)
+    check_same_dimensions(a, b)
+
+    return sum(abs(x - y) for x, y in zip(a, b, strict=False))

pyvecdb/errors.py

@@ -0,0 +1,61 @@
+"""Custom exceptions for pyvecdb.
+
+Think of these like warning signs at an amusement park -- they tell you
+exactly what went wrong so you can fix it!
+
+Example:
+    If you try to add a 3D vector to a store that expects 5D vectors,
+    you'll get a ``DimensionMismatchError`` telling you the sizes don't match.
+
+"""
+
+
+class VecDBError(Exception):
+    """Base exception for all pyvecdb errors."""
+
+
+class DimensionMismatchError(VecDBError):
+    """Raise when vector dimensions don't match.
+
+    Imagine trying to fit a square peg in a round hole -- if your vector
+    has 3 numbers but the store expects 5, that's a dimension mismatch!
+    """
+
+
+class DuplicateIDError(VecDBError):
+    """Raise when a vector record with the same ID already exists.
+
+    Like how every student has a unique student ID -- you can't have
+    two students with the same number.
+    """
+
+
+class RecordNotFoundError(VecDBError):
+    """Raise when a requested vector record is not found.
+
+    Like looking for a book in the library that doesn't exist -- the
+    ID you asked for isn't in the store.
+    """
+
+
+class EmptyStoreError(VecDBError):
+    """Raise when searching an empty store.
+
+    You can't find the closest pizza shop if there are no pizza shops!
+    """
+
+
+class EmptyVectorError(VecDBError):
+    """Raise when a vector has no components.
+
+    A vector needs at least one number -- an empty list isn't a direction!
+    """
+
+
+class PersistenceError(VecDBError):
+    """Raise when a saved store can't be read back from disk.
+
+    Like opening your saved game and finding the file missing or
+    scrambled -- rather than starting an empty game and pretending all is
+    well, we stop and say which file is the problem.
+    """

pyvecdb/filtering.py

@@ -0,0 +1,128 @@
+"""Metadata filtering for vector search results.
+
+Imagine you're searching for the 5 most similar songs to your favorite,
+but you only want songs released after 2020. That's metadata filtering!
+
+The metadata is the "extra info" attached to each vector record -- things
+like genre, year, artist, rating. Filters let you narrow down results
+based on these fields.
+
+Supported filter operators:
+
+- **$eq** (equals): ``{"genre": "rock"}`` -- exact match (plain values are shorthand for $eq)
+- **ne** (not equals): ``{"genre": {"$ne": "country"}}``
+- **gt / gte / lt / lte**: ``{"year": {"$gt": 2020}}`` -- comparisons
+- **in**: ``{"genre": {"$in": ["rock", "pop"]}}`` -- match any in list
+
+Example:
+    >>> from pyvecdb.filtering import matches_filter
+    >>> metadata = {"genre": "rock", "year": 2023}
+    >>> matches_filter(metadata, {"genre": "rock"})
+    True
+    >>> matches_filter(metadata, {"year": {"$gt": 2020}})
+    True
+
+"""
+
+from collections.abc import Mapping
+
+from pyvecdb.record import VectorRecord
+
+# Type alias for metadata values
+MetadataValue = str | int | float | bool
+
+# Type alias for a single filter condition
+FilterCondition = MetadataValue | dict[str, MetadataValue | list[MetadataValue]]
+
+# Type alias for a complete filter
+MetadataFilter = Mapping[str, FilterCondition]
+
+
+def _compare_values(
+    actual: MetadataValue,
+    operator: str,
+    expected: MetadataValue | list[MetadataValue],
+) -> bool:
+    """Compare a metadata value using the given operator.
+
+    Args:
+        actual: The value from the record's metadata.
+        operator: One of '$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in'.
+        expected: The value (or list) to compare against.
+
+    Returns:
+        True if the comparison passes, False otherwise.
+
+    """
+    match operator:
+        case "$eq":
+            return actual == expected
+        case "$ne":
+            return actual != expected
+        case "$in":
+            return actual in expected if isinstance(expected, list) else False
+        case "$gt" | "$gte" | "$lt" | "$lte":
+            if not isinstance(actual, (int, float)) or not isinstance(expected, (int, float)):
+                return False
+            ops = {
+                "$gt": actual > expected,
+                "$gte": actual >= expected,
+                "$lt": actual < expected,
+                "$lte": actual <= expected,
+            }
+            return ops[operator]
+        case _:
+            return False
+
+
+def matches_filter(
+    metadata: Mapping[str, MetadataValue],
+    filter_dict: MetadataFilter,
+) -> bool:
+    """Check whether a metadata dict matches all conditions in a filter.
+
+    A filter is a dictionary where each key is a metadata field name. The value
+    can be a plain value (shorthand for equals) or a dict of operator-value pairs.
+
+    All conditions must match (AND logic).
+
+    Args:
+        metadata: The record's metadata dictionary.
+        filter_dict: The filter conditions to check.
+
+    Returns:
+        True if all conditions match, False otherwise.
+
+    """
+    for field_name, condition in filter_dict.items():
+        actual = metadata.get(field_name)
+        if actual is None:
+            return False
+
+        if isinstance(condition, dict):
+            for operator, expected in condition.items():
+                if not _compare_values(actual, operator, expected):
+                    return False
+        elif actual != condition:
+            return False
+
+    return True
+
+
+def filter_records(
+    records: list[VectorRecord],
+    filter_dict: MetadataFilter,
+) -> list[VectorRecord]:
+    """Filter a list of vector records by metadata conditions.
+
+    Args:
+        records: The records to filter.
+        filter_dict: The filter conditions to apply.
+
+    Returns:
+        A new list containing only records whose metadata matches all conditions.
+        Note: the records themselves are the live objects from the store, so
+        editing one here also edits it in the store.
+
+    """
+    return [r for r in records if matches_filter(r.metadata, filter_dict)]