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.

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

Releasing¶

The version in pyproject.toml is the single source of truth. Bump it and commit before tagging — the release workflow verifies that the tag name matches the project version and fails the publish if they disagree.

# Bump the version (also updates uv.lock)
uv version 0.8.1

# Commit, then tag and push
git commit -am "chore: release 0.8.1"
git tag 0.8.1
git push origin main --tags

Publishing a GitHub release for that tag triggers the release workflow, which runs the full test matrix, verifies the version, builds, and uploads to PyPI. Tags carry no v prefix.

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
fix-add-skip-duplicates — Skip duplicate keys silently in add() instead of erroring with partial commit (iscc/usearch#6)
feat/save-release-gil — Opt-in GIL release for save() to allow background serialization without blocking async event loops (iscc/usearch#7)

See the Performance explanation for details on the performance patches.