microsoft/SPARROW-Engine

microsoft/SPARROW-Engine

Language: Rust

License: MIT

Stars: 1

Forks: 0

Open issues: 1

Created: 2026-07-01T02:12:25Z

Pushed: 2026-07-09T03:58:18Z

Default branch: main

Fork: no

Archived: no

README:

Sparrow Engine

A Rust ML inference engine for camera-trap and bioacoustic data. Drop-in for MegaDetector v6, DeepFaune, HerdNet, OWL-T, SpeciesNet, and MD_AudioBirds_V1; model-agnostic via TOML manifests.

Quickstart

Easiest: Homebrew (macOS arm64 / brew-Linux x86_64)

brew tap microsoft/sparrow-engine
brew install sparrow-engine # CPU; works on macOS arm64 + brew-Linux x86_64
brew install sparrow-engine-gpu # GPU; brew-Linux x86_64 + NVIDIA only

spe device # {"device":"cpu"} or {"device":"cuda:0"}

# One-time: download a model from the Zenodo bundle (brew doesn't ship models)
mkdir -p ~/.sparrow-engine/models && cd ~/.sparrow-engine/models
curl -fLO https://zenodo.org/records/21211015/files/camera_trap__detector__MDV6-yolov10-e.zip
unzip -q camera_trap__detector__MDV6-yolov10-e.zip && rm camera_trap__detector__MDV6-yolov10-e.zip
cd -

spe detect /path/to/photos --model MDV6-yolov10-e --recursive --export-format megadet --export-output detections.json

Both formulas can coexist (separate binaries spe + spe-gpu; shared model cache at ~/.sparrow-engine/models/). The example above pulls MegaDetector v6 (general camera-trap detection); see the [Model zoo](#model-zoo) section below for the other 59 models in the Zenodo bundle (image classifiers, audio detectors, overhead-imagery detectors, image encoders). See docs/user-manual.md §2.4 for the other install paths.

GPU host prerequisites

The sparrow-engine-gpu formula ships ~256 MB of libonnxruntime + ORT CUDA provider sidecars, but it does NOT bundle NVIDIA's runtime libraries (NVIDIA's license forbids redistribution). The host must provide:

| Library | Apt package (Ubuntu/Debian) | pip wheel (no root) | Why | |---|---|---|---| | NVIDIA driver ≥550.x | nvidia-driver-550 (or newer) | — (kernel module; host-only) | GPU access | | CUDA runtime 12.6 | nvidia-cuda-toolkit brings it | nvidia-cuda-runtime-cu12 | libcudart.so.12 | | cuDNN ≥9.10 (9.8 has Conv bug on sm_89) | nvidia-cudnn | nvidia-cudnn-cu12 | libcudnn.so.9 — convolutions | | cuBLAS | bundled with CUDA toolkit | nvidia-cublas-cu12 | matrix multiplications | | cuRAND | bundled with CUDA toolkit | nvidia-curand-cu12 | rand sampling (some models) | | cuFFT | bundled with CUDA toolkit | nvidia-cufft-cu12 | audio FFT (MD_AudioBirds_V1) | | nvJPEG | bundled with CUDA toolkit | nvidia-nvjpeg-cu12 | GPU JPEG decode |

After installing the libraries (system or pip), the brew-installed spe-gpu wrapper auto-discovers them from common host locations — no LD_LIBRARY_PATH setup needed for production users. Search order (first hit wins):

1. SPARROW_ENGINE_CUDA_LIB_DIR (user override; honored as-is) 2. ~/.sparrow-engine/cuda-sidecars/lib/python*/site-packages/nvidia/*/lib (the convention if you used pip sidecars) 3. /usr/lib/python3/dist-packages/torch/lib (Lambda Stack / system PyTorch — cuDNN comes bundled) 4. /usr/local/cuda/lib64 (NVIDIA CUDA toolkit) 5. /usr/lib/x86_64-linux-gnu (Ubuntu apt nvidia-cudnn)

Full table + remediation appears in brew info sparrow-engine-gpu. Quick all-pip install (no root) for a fresh host:

uv venv ~/.sparrow-engine/cuda-sidecars --python 3.11
~/.sparrow-engine/cuda-sidecars/bin/pip install \
nvidia-cudnn-cu12 nvidia-cublas-cu12 nvidia-curand-cu12 \
nvidia-cufft-cu12 nvidia-nvjpeg-cu12 nvidia-cuda-runtime-cu12

Verify with spe-gpu device — {"device":"cuda:0"} means good, any dlopen error in the output names the missing library.

Alternative install paths

If brew isn't right for your environment (server distro without brew-Linux, Windows, etc.), the install wrapper handles probe-and-install for Linux / macOS / Windows:

# Linux / macOS — clone the repo and run from its root
bash installer/sparrow-engine-install.sh

# Windows PowerShell — clone the repo and run from its root
installer\sparrow-engine-install.ps1

The wrapper probes hardware once, picks the right CPU or GPU build, and installs the matching CLI binary plus the Python wheel into ~/.sparrow-engine/. Pass --flavor cpu or --flavor gpu to skip the probe. Pass --docker to install the HTTP-server image instead.

System prerequisites for GPU: NVIDIA driver ≥550.x, CUDA 12.6 runtime, and cuDNN ≥9.10 (cuDNN 9.8 has a Conv-engine bug on sm_89).

Python package only (PyPI)

If you only want the Python wheel — no CLI, no Docker image — install straight from PyPI. Both wheels target CPython ≥ 3.11 (cp311-abi3), so make sure your venv runs Python 3.11 or newer.

With `uv` (recommended):

uv venv --python 3.11
source .venv/bin/activate # Windows: .venv\Scripts\activate

# CPU
uv pip install sparrow-engine

# GPU (Linux x86_64 only; requires CUDA 12.6 runtime on the host)
uv pip install sparrow-engine-gpu

uv venv does not ship pip inside the venv by default, so use uv pip install (uv's pip-compatible wrapper) instead of bare pip install. Calling pip install … after source activate falls back to the system pip, which usually targets the wrong Python version and fails with No matching distribution found.

With stdlib `venv`:

python3.11 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate

# CPU
pip install sparrow-engine

# GPU (Linux x86_64 only; requires CUDA 12.6 runtime on the host)
pip install sparrow-engine-gpu

Both wheels import as sparrow_engine. Never install both into the same environment. Check the installed version with python -c "import sparrow_engine; print(sparrow_engine.__version__)". See [§6 of the user manual](docs/user-manual.md#6-python-package--sparrow-engine) for the full API surface and GPU sidecar options.

Docker image (server deployments)

Sparrow Engine ships as a self-contained HTTP server in two Docker flavors. Both expose /v1/detect, /v1/classify, /v1/detect_audio, /healthz, /openapi.json on port 8080.

| Image | Size | GPU | |---|---|---| | zhongqimiao/sparrow-engine-server:latest | ~170 MB | CPU only | | zhongqimiao/sparrow-engine-server-gpu:latest | ~3.7 GB | CUDA 12 + cuDNN bundled; requires NVIDIA Container Toolkit on the host |

Three install paths. Option A is the simplest; B + C remain for offline operators and...