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: "6.0.0"),
    .package(url: "https://github.com/rryam/VecturaMLXKit.git", from: "3.0.0"),
],

VecturaMLXKit 3.x tracks the VecturaKit 6.x release line and shares the same minimum deployment targets: macOS 15, iOS 18, tvOS 18, visionOS 2, and watchOS 11.

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)

Local Validation

For fast compile checks, swift build and swift test are fine. For MLX runtime verification on macOS, use Xcode or xcodebuild instead of swift run.

swift run vectura-mlx-cli ... can compile successfully and still fail at runtime if the MLX Metal bundle is not packaged into the SwiftPM CLI build. The reliable path is an Xcode-style build that emits mlx-swift_Cmlx.bundle/Contents/Resources/default.metallib.

Recommended local smoke test:

xcrun --find metal
xcrun --find metallib

xcodebuild \
  -scheme vectura-mlx-cli \
  -destination 'platform=macOS' \
  -derivedDataPath /tmp/VecturaMLXKit-xc \
  build

find /tmp/VecturaMLXKit-xc/Build/Products/Debug -name default.metallib

/tmp/VecturaMLXKit-xc/Build/Products/Debug/vectura-mlx-cli mock --db-name qa-db

Expected behavior:

• default.metallib is present under mlx-swift_Cmlx.bundle
• the CLI gets past Setting up database...
• the mock flow resets the database, adds sample documents, searches, updates, deletes, and exits successfully

Adaptive batching is enabled by default. To compare behavior with the legacy single-batch path, set:

VECTURA_MLX_ADAPTIVE_BATCHING=0 /tmp/VecturaMLXKit-xc/Build/Products/Debug/vectura-mlx-cli mock --db-name qa-db-off
VECTURA_MLX_ADAPTIVE_BATCHING=1 /tmp/VecturaMLXKit-xc/Build/Products/Debug/vectura-mlx-cli mock --db-name qa-db-on

To benchmark the real embedding pipeline, build the TestMLXExamples scheme and run it in benchmark mode:

xcodebuild \
  -scheme TestMLXExamples \
  -destination 'platform=macOS' \
  -derivedDataPath /tmp/VecturaMLXKit-xc \
  build

MLX_RUNTIME_BENCH=1 VECTURA_MLX_ADAPTIVE_BATCHING=0 /tmp/VecturaMLXKit-xc/Build/Products/Debug/TestMLXExamples
MLX_RUNTIME_BENCH=1 VECTURA_MLX_ADAPTIVE_BATCHING=1 /tmp/VecturaMLXKit-xc/Build/Products/Debug/TestMLXExamples

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.