VecturaKit

VecturaKit provides several specialized test suites to help developers evaluate performance, scalability, memory usage, and accuracy across different configurations.

Available Suites

1. BenchmarkSuite: Establishes performance baselines for different strategies (e.g., fullMemory, indexed, automatic) and dataset sizes.
2. ScalabilitySuite: Analyzes how performance and memory usage scale as datasets grow from small to large.
3. MemoryProfilerSuite: Provides deep analysis of memory usage throughout the lifecycle (initialization, adding documents, and searching).
4. ParameterTuningSuite: Helps find optimal configurations for indexed mode by sweeping parameters like candidateMultiplier, batchSize, and maxConcurrentBatches.
5. AccuracyTests: Validates search quality (Recall@10) in indexed mode compared to fullMemory mode.
6. RealisticWorkloadSuite (Opt-in): Stress tests the system with production-like characteristics, including cold-starts, multi-client pressure, and mixed read/write traffic.

VecturaKit provides different memory strategies via VecturaConfig to balance performance and memory usage based on your dataset size.

• automatic (Default): Intelligently selects between fullMemory and indexed strategies. Use this for most variable workloads.
• fullMemory: Loads all documents into RAM at initialization. This provides zero I/O during search and extremely low latency (<15ms), but memory usage scales linearly (~187 KB per document). Recommended for datasets up to 10,000 documents.
• indexed: Designed for larger datasets to keep memory usage low. Note that the current FileStorageProvider implementation falls back to fullMemory. For true indexed behavior, a custom IndexedVecturaStorage provider is required.

// Use the automatic strategy (default)
VecturaConfig(name: "my-db")

// For known small datasets (< 10K docs) to ensure maximum speed
VecturaConfig(name: "my-db", memoryStrategy: .fullMemory)

// For large datasets (requires IndexedVecturaStorage implementation)
VecturaConfig(
    name: "large-db",
    memoryStrategy: .indexed(
        candidateMultiplier: 10,
        batchSize: 100,
        maxConcurrentBatches: 4
    )
)

To integrate with external storage systems like SQLite, Core Data, or cloud storage, implement the VecturaStorage protocol. You must provide implementations for creating the storage directory, loading, saving, deleting, and updating documents.

import Foundation
import VecturaKit

final class MyCustomStorageProvider: VecturaStorage {
    private var documents: [UUID: VecturaDocument] = [:]

    func createStorageDirectoryIfNeeded() async throws {
        // Initialize your storage system
    }

    func loadDocuments() async throws -> [VecturaDocument] {
        return Array(documents.values)
    }

    func saveDocument(_ document: VecturaDocument) async throws {
        documents[document.id] = document
    }

    func deleteDocument(withID id: UUID) async throws {
        documents.removeValue(forKey: id)
    }

    func updateDocument(_ document: VecturaDocument) async throws {
        documents[document.id] = document
    }

    func getTotalDocumentCount() async throws -> Int {
        return documents.count
    }
}

// Usage
let config = VecturaConfig(name: "my-db")
let customStorage = MyCustomStorageProvider()
let vectorDB = try await VecturaKit(config: config, storageProvider: customStorage)

VecturaKit provides three memory management strategies via VecturaConfig.memoryStrategy to balance search speed and memory usage:

1. Automatic Mode (Recommended): Automatically switches strategies based on dataset size.
   • < 10,000 documents: Uses fullMemory mode.
   • ≥ 10,000 documents: Uses indexed mode (requires a compatible storage provider).
2. Full Memory Mode: Loads all documents into RAM. Best for small to medium datasets (< 100,000 documents) where sub-10ms latency is required and memory is available.
3. Indexed Mode: Uses on-demand loading and storage-layer indexing. Best for very large datasets (> 100,000 documents) or memory-constrained environments.

// Automatic strategy (default)
let config = VecturaConfig(name: "my-database")
let vectura = try await VecturaKit(config: config)

// Explicit Full Memory Mode
let configFull = VecturaConfig(name: "my-database", memoryStrategy: .fullMemory)
let vecturaFull = try await VecturaKit(config: configFull)

// Explicit Indexed Mode
let configIndexed = VecturaConfig(name: "my-database", memoryStrategy: .indexed(candidateMultiplier: 4))
let vecturaIndexed = try await VecturaKit(config: configIndexed)

If you need specialized search algorithms (e.g., pure vector, pure text, or custom ranking), implement the VecturaSearchEngine protocol. The search method receives the SearchQuery, the VecturaStorage instance, and SearchOptions to perform the lookup.

import Foundation
import VecturaKit

struct MyCustomSearchEngine: VecturaSearchEngine {
    func search(
        query: SearchQuery,
        storage: VecturaStorage,
        options: SearchOptions
    ) async throws -> [VecturaSearchResult] {
        let documents = try await storage.loadDocuments()

        guard case .text(let queryText) = query else {
            return []
        }

        let results = documents.filter { doc in
            doc.text.lowercased().contains(queryText.lowercased())
        }.map { doc in
            VecturaSearchResult(
                id: doc.id,
                text: doc.text,
                score: 1.0,
                createdAt: doc.createdAt
            )
        }

        return Array(results.prefix(options.numResults))
    }

    func indexDocument(_ document: VecturaDocument) async throws {}
    func removeDocument(id: UUID) async throws {}
}

// Usage
let vectorDB = try await VecturaKit(
    config: config, 
    embedder: embedder, 
    searchEngine: MyCustomSearchEngine()
)