---

name: api-and-indexing description: "Build, update, search, filter, and safely manage LEANN indexes through the Python API, including precomputed embeddings and hybrid or grep retrieval." disable-model-invocation: true metadata: disco-role: operating license: MIT

LEANN API and Indexing

Use this sub-skill for the Python lifecycle around LeannBuilder, LeannSearcher, passage metadata, precomputed vectors, low-level updates, metadata filters, BM25/vector fusion, grep retrieval, and resource cleanup.

Route by task

• Verify constructors, method signatures, defaults, result fields, and artifact names in API reference.
• Implement a new build, precomputed-vector build, update, staged replacement, or cleanup flow with indexing and search workflows.
• Configure post-search metadata filters, pure BM25, hybrid retrieval, or grep with metadata, hybrid, and grep.
• Diagnose bad base paths, missing artifacts, dimension or ID mismatches, update duplication, BM25/grep failures, and daemon cleanup with troubleshooting.
• Prove a local installation and HNSW backend without a model download by running the bundled precomputed-index smoke.

Operating rules

1. Treat index_path as a base path, not as the .meta.json, .index, or passage file. Keep every sibling artifact together.
2. Use a new staging directory for builds and critical updates. Validate it, then publish the whole directory; never overwrite unrelated files or delete a parent directory in response to an error message.
3. Give every passage a unique string ID. For precomputed arrays, make the passage IDs and supplied vector IDs identical and order-aligned.
4. Set build and query embedding configuration consistently. A precomputed build avoids document embedding, but semantic search still needs a query embedding; pure BM25 and grep do not.
5. Configure recomputation on LeannSearcher; the per-call search override is deprecated. Disable warmup and daemon use for offline BM25-only checks.
6. Always call cleanup() or use with LeannSearcher(...) as searcher:.
7. Treat filters as post-retrieval filters. Missing or unsupported fields do not raise by default; they remove the affected result.
8. Choose update behavior from stored backend/index metadata. IVF supports remove-then-add; HNSW only supports low-level append on non-compact indexes.

Boundaries

• For CLI build/search, daemon commands, filesystem watching, or idempotent document builds, use CLI operations.
• For HNSW, IVF, DiskANN algorithms, storage modes, and backend tuning, use backends and storage.
• For embedding modes, model/provider credentials, prompt templates, and chat providers, use embeddings and chat.
• For document, email, browser, chat-history, or code ingestion applications, use RAG applications.