rryam/VecturaKit

VecturaKit – On‑device vector database for Swift apps

What it is – VecturaKit is a Swift library that lets iOS, macOS, watchOS, tvOS and visionOS apps store text documents as vector embeddings locally on the device. It provides the usual vector‑database features (add, update, delete, search) plus a hybrid BM25‑plus‑vector search, and it is built to be completely on‑device so no data leaves the user’s hardware.

Key capabilities

• Pluggable embedder – you can plug in any embedder that conforms to VecturaEmbedder. The package ships with:
  • NLContextualEmbedder – uses Apple’s NaturalLanguage framework (zero external dependencies).
  • OpenAICompatibleEmbedder – talks to any /v1/embeddings API (e.g., OpenAI, Ollama, LM Studio).
  • SwiftEmbedder (via the separate VecturaEmbeddingsKit) – runs swift‑embeddings models such as Model2Vec, BERT, RoBERTa, etc.
  • MLXEmbedder (via VecturaMLXKit) – GPU‑accelerated embeddings on Apple MLX.
• Hybrid search – combines cosine similarity on vectors with BM25 text scoring; the weight between the two is configurable.
• Custom storage & search – you can supply your own storage backend (SQLite, Core Data, cloud, etc.) by conforming to VecturaStorage, and you can replace the search algorithm by conforming to VecturaSearchEngine.
• Memory strategies – automatic, full‑memory, or an indexed mode that loads documents on‑demand, making it usable from a few hundred up to millions of records.
• CLI tools – vectura-cli (NaturalLanguage) and vectura-oai-cli (OpenAI‑compatible) let you experiment from the command line.

Typical usage flow

1. Configure a VecturaConfig (name, optional custom directory, search options, memory strategy).
2. Create an embedder – e.g., let embedder = try await NLContextualEmbedder(language: .english).
3. Instantiate the DB – let db = try await VecturaKit(config: config, embedder: embedder).
4. Add documents – await db.addDocuments(texts: [...]) (batching is parallelized).
5. Search – await db.search(query: "some query", numResults: 5) returns an array of VecturaSearchResult with id, text, similarity score and timestamp.
6. Manage docs – update, delete, fetch by id, or reset the whole database.

Why it matters

• Privacy‑first: All embeddings and indexing happen locally; useful for apps that need semantic search without sending user data to the cloud.
• Swift‑native: No bridging to Python or external services unless you choose an OpenAI‑compatible embedder.
• Extensible: The plug‑in architecture lets you swap in newer embedding models or custom ranking logic without changing the rest of your app.

Getting started Add the package via Swift Package Manager:

.dependencies: [
    .package(url: "https://github.com/rryam/VecturaKit.git", from: "6.3.0"),
]

Then import VecturaKit (and optionally VecturaNLKit or VecturaOAIKit) and follow the quick‑start code shown in the README.

Documentation & community

• Detailed guides live under Docs/ (indexed storage, performance benchmarks).
• Separate packages for embeddings (VecturaEmbeddingsKit) and MLX acceleration (VecturaMLXKit).
• Open‑source license (MIT) and contribution guidelines are provided.

---

Bottom line – VecturaKit is a genuine, production‑ready Swift vector database aimed at on‑device AI/ML workloads, offering flexible embedding back‑ends, hybrid search, and extensibility for custom storage or ranking.