VecturaMLXKit

MLX-based embeddings for VecturaKit — GPU-accelerated on-device vector search using Apple's MLX framework.

Overview

VecturaMLXKit provides MLXEmbedder, an embedding provider that uses Apple's MLX framework for GPU-accelerated inference on Apple Silicon. It conforms to VecturaKit's VecturaEmbedder protocol, so you can use it as a drop-in replacement for SwiftEmbedder or NLContextualEmbedder.

This package also includes vectura-mlx-cli, a command-line tool for managing a VecturaKit database with MLX embeddings.

Installation

Add both VecturaKit and VecturaMLXKit to your Package.swift:

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

Or add them via Xcode's File > Add Package Dependencies UI — no special configuration needed.

Usage

Import

import VecturaKit
import VecturaMLXKit
import MLXEmbedders

Initialize Database with MLX

let config = VecturaConfig(
  name: "my-mlx-vector-db",
  dimension: nil  // Auto-detect dimension from MLX embedder
)

// Create MLX embedder
let embedder = try await MLXEmbedder(configuration: .nomic_text_v1_5)
let vectorDB = try await VecturaKit(config: config, embedder: embedder)

Add Documents

let texts = [
  "First document text",
  "Second document text",
  "Third document text"
]
let documentIds = try await vectorDB.addDocuments(texts: texts)

Search Documents

let results = try await vectorDB.search(
    query: "search query",
    numResults: 5,
    threshold: 0.8
)

for result in results {
    print("Document ID: \(result.id)")
    print("Text: \(result.text)")
    print("Similarity Score: \(result.score)")
}

Document Management

// Update
try await vectorDB.updateDocument(id: documentId, newText: "Updated text")

// Delete
try await vectorDB.deleteDocuments(ids: [documentId1, documentId2])

// Reset
try await vectorDB.reset()

CLI Tool (vectura-mlx-cli)

# Add documents
vectura-mlx add "First document" "Second document" --db-name "my-mlx-db"

# Search documents
vectura-mlx search "search query" --db-name "my-mlx-db" --threshold 0.7 --num-results 5

# Update document
vectura-mlx update <document-uuid> "Updated text" --db-name "my-mlx-db"

# Delete documents
vectura-mlx delete <document-uuid-1> <document-uuid-2> --db-name "my-mlx-db"

# Reset database
vectura-mlx reset --db-name "my-mlx-db"

# Run demo with sample data
vectura-mlx mock --db-name "my-mlx-db"

Options:

• --db-name, -d: Database name (default: "vectura-mlx-cli-db")
• --dimension, -v: Vector dimension (auto-detected by default)
• --threshold, -t: Minimum similarity threshold (default: 0.7)
• --num-results, -n: Number of results to return (default: 10)

Dependencies

• VecturaKit: Core vector database
• mlx-swift-lm: MLX-based embeddings
• swift-argument-parser: CLI framework

License

VecturaMLXKit is released under the MIT License. See the LICENSE file for details.