Contributing¶

Dev environment setup¶

1. Clone the repository:

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

2. Install dependencies with uv:

   uv sync
   

   This installs the project in development mode with all dev dependencies.

Running tests¶

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

Linting and formatting¶

# 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.

Type checking¶

uv run ty check

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

Security scanning¶

uv run bandit -r src/

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

Documentation¶

Serve the docs locally with live reload:

uv run poe docs-serve

Build for deployment:

uv run poe docs-build

Cross-platform support¶

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

Patched usearch fork¶

iscc-usearch depends on a patched usearch fork, published on PyPI as usearch-iscc and installed automatically as a regular dependency. The required version is declared in pyproject.toml.

Each patch is maintained on a separate branch to facilitate upstream merging:

• fix-view-overhead — Fast view() with computed offsets, lazy key reindexing, and GIL release for parallel shard loading
• patch-index-get — Return None for non-existent keys in Index.get()
• fix-search-count-zero — Validate search count parameter to prevent segfault
• fix-serialized-length — Fix serialized_length pybind11 default argument binding
• fix-array-copy-keyword — Accept copy keyword in IndexedKeys.__array__ for NumPy 2.0
• python-128bit-keys — Add 128-bit (UUID) key support to Index and Indexes via key_kind="uuid"
• add-nphd-metric — Native MetricKind.NPHD for Normalized Prefix Hamming Distance

See the Performance explanation for details on the performance patches.