Contributing¶

Dev environment setup¶

Clone the repository:

git clone https://github.com/iscc/iscc-usearch.git
cd iscc-usearch

Install dependencies with uv:
```
uv sync
```
This installs the project in development mode with all dev dependencies.

Tests require 100% code coverage. To run the full suite:

uv run pytest

To run a single test file or function:

uv run pytest tests/test_nphd.py
uv run pytest tests/test_nphd.py::test_nphd_index_add_and_search

To generate a coverage report with missing lines:

uv run pytest --cov=iscc_usearch --cov-report=term-missing

# Check for lint issues
uv run ruff check .

# Auto-format code
uv run ruff format .

The max line length is 119 characters and line endings are LF, both configured in pyproject.toml.

uv run ty check

Some usearch-related type errors are downgraded to warnings in pyproject.toml because usearch has incomplete type annotations.

uv run bandit -r src/

assert statements are allowed (B101 is skipped) because the project uses them for parameter validation.

Serve the docs locally with live reload:

uv run poe docs-serve

Build for deployment:

uv run poe docs-build

All code, scripts, and dev tools must work on Linux, macOS, and Windows. Please test on multiple platforms when possible.

iscc-usearch depends on a patched usearch fork (v2.23.3), published on PyPI as usearch-iscc and installed automatically as a regular dependency.

The fork includes:

Fast view() for memory-mapped indexes (computed offsets instead of pointer tables)
Lazy key reindexing with double-checked locking
GIL release in Python bindings for parallel shard loading
Fixes for get() on missing keys, search(count=0), and NumPy 2.0 compatibility