feat: GPU-accelerated indexing with Collection API integration

[cluster2600]

Summary

Implements GPU-accelerated indexing for zvec, addressing #100 and #147.
Incorporates community feedback from #180 (@xXMrNidaXx).

Core architecture

• UnifiedGpuIndex ABC with 6 backend adapters behind a single interface
• GpuIndex bridge connecting GPU search to Collection.fetch() for full Doc results
• C++ first architecture — prefers native _zvec cuVS bindings (zero-copy via GpuBufferLoader), falls back to Python cuVS → FAISS GPU → Apple MPS → FAISS CPU

New in this update (from #180 feedback)

1. PyTorch-style device= API — collection.index("embedding", device="gpu")
   replaces the older gpu_index() method (kept with deprecation warning for backward compat)

2. build_from_collection(batch_size=) — streams vectors directly from
   the collection in batches, no manual extraction needed:

   gpu = collection.index("embedding", device="cuda:0")
   gpu.build_from_collection(batch_size=10_000)

3. ZVEC_GPU_BACKEND_PRIORITY env var — comma-separated backend names
   that override the default auto-selection priority:

   export ZVEC_GPU_BACKEND_PRIORITY=faiss_gpu,cuvs_cagra,faiss_cpu

4. Hybrid CPU/GPU auto-selector — collections below gpu_threshold
   (default 50K, configurable via ZVEC_GPU_AUTO_THRESHOLD env var)
   automatically route to CPU to avoid GPU transfer overhead on small datasets

Backend priority

Priority	Backend	Path
1	C++ cuVS (CAGRA/IVF-PQ/HNSW)	_zvec pybind11 — zero-copy
2	Python cuVS CAGRA	cuvs.neighbors.cagra
3	Python cuVS IVF-PQ	cuvs.neighbors.ivf_pq
4	FAISS GPU	faiss.index_cpu_to_gpu
5	Apple MPS	torch.backends.mps
6	FAISS CPU	fallback

Usage

# PyTorch-style device API (new)
gpu = collection.index("embedding", device="gpu")
gpu.build_from_collection(batch_size=10_000)
docs = gpu.query(query_vec, topk=10, output_fields=["title"])

# Explicit backend + manual build
gpu = collection.index("embedding", backend="cuvs_cagra")
gpu.build(vectors, doc_ids)
results = gpu.search(query_vec, k=10)

# Hybrid auto: small collections → CPU, large → GPU
gpu = collection.index("embedding", gpu_threshold=100_000)
gpu.build(vectors, ids)  # auto-selects CPU if len(vectors) < 100K

Test results

Unit tests (44 tests passing)

• Backend selection (auto, explicit, device strings, env var priority)
• FAISS CPU adapter (train, search, single query)
• Apple MPS adapter (numpy fallback, add)
• GpuIndex bridge (build, search, query, errors, info)
• Device parameter (cpu, gpu override, None fallback)
• GPU threshold (small/large collections, env override, explicit override)
• build_from_collection (fetch_all, explicit IDs, batch_size, errors, chaining)
• Collection.index() + deprecated gpu_index()
• Detection (cuVS, optimal backend, GPU availability)

Apple MPS (M-series Mac)

• 210 QPS on 5,000 vectors (dim=128, brute-force numpy fallback)

NVIDIA RTX 4090 (CUDA 12, sm_89)

Backend	Build (50K vec)	Search (100 queries, k=10)	QPS
cuVS CAGRA	2.3s	2.4ms	43,711
cuVS IVF-PQ	0.2s	2.2ms	45,771
FAISS GPU (flat)	—	0.2ms	529,316

Merge order

This PR shares a common base with #172, #173, #175. Recommended merge order: #172 → #173 → #175 → #176. This PR should merge last.

Test plan

• 44 unit tests passing (adapters, GpuIndex, device=, threshold, build_from_collection, detection)
• Test on NVIDIA GPU with cuVS CAGRA — 43K QPS on RTX 4090
• Test on NVIDIA GPU with cuVS IVF-PQ — 45K QPS on RTX 4090
• FAISS GPU verified — 529K QPS on RTX 4090
• Verify Apple MPS path on Apple Silicon — 210 QPS
• Test C++ cuVS path when _zvec is built with CUDA support (requires custom build)

[cluster2600]

Discussion issue opened: #180 — feedback welcome before review.