LumoKit

Requirements

• Swift 6.2+
• iOS 18.0+, macOS 15.0+

Installation

Add LumoKit to your Package.swift using Swift Package Manager:

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

Then attach the dependency to your target:

.target(
    name: "AppModule",
    dependencies: [
        .product(name: "LumoKit", package: "LumoKit")
    ]
)

Getting Started

import LumoKit
import VecturaKit

// Configure vector database
let vecturaConfig = VecturaConfig(
    name: "knowledge-base",
    searchOptions: .init(
        defaultNumResults: 10,
        minThreshold: 0.7
    )
)

// Configure chunking strategy
let chunkingConfig = ChunkingConfig(
    chunkSize: 500,
    overlapPercentage: 0.15,  // 15% overlap between chunks
    strategy: .semantic,  // Content-aware chunking
    contentType: .prose  // For prose text
)

// Initialize LumoKit
let lumoKit = try await LumoKit(
    config: vecturaConfig,
    chunkingConfig: chunkingConfig
)

// Optionally choose a specific embedding model.
// Use a separate store when switching models so stored vector dimensions stay consistent.
let customModelConfig = VecturaConfig(
    name: "knowledge-base-retrieval",
    searchOptions: .init(
        defaultNumResults: 10,
        minThreshold: 0.7
    )
)

let customModelLumoKit = try await LumoKit(
    config: customModelConfig,
    chunkingConfig: chunkingConfig,
    modelSource: .id("minishlab/potion-retrieval-32M")
)

// Or provide any Vectura embedder directly
let customEmbedderConfig = VecturaConfig(
    name: "knowledge-base-multilingual",
    searchOptions: .init(
        defaultNumResults: 10,
        minThreshold: 0.7
    )
)

let customEmbedderLumoKit = try await LumoKit(
    config: customEmbedderConfig,
    chunkingConfig: chunkingConfig,
    embedder: SwiftEmbedder(modelSource: .id("intfloat/multilingual-e5-small"))
)

// Parse and index a document
let url = URL(fileURLWithPath: "/path/to/document.pdf")
try await lumoKit.parseAndIndex(url: url)

// Search
let results = try await lumoKit.semanticSearch(
    query: "Explain vector databases",
    numResults: 5,
    threshold: 0.65
)

for result in results {
    print(result.text)
}

Custom Embedder Examples

LumoKit can also accept any embedder that conforms to VecturaEmbedder.

Use NLContextualEmbedder

import LumoKit
import VecturaKit
import VecturaNLKit

let embedder = try await NLContextualEmbedder(language: .english)
let lumoKit = try await LumoKit(
    config: vecturaConfig,
    chunkingConfig: chunkingConfig,
    embedder: embedder
)

Use OpenAICompatibleEmbedder

import LumoKit
import VecturaKit
import VecturaOAIKit

let embedder = OpenAICompatibleEmbedder(
    baseURL: "https://api.openai.com/v1",
    model: "text-embedding-3-small",
    apiKey: "<api-key>"
)

let lumoKit = try await LumoKit(
    config: vecturaConfig,
    chunkingConfig: chunkingConfig,
    embedder: embedder
)

Use MLXEmbedder

import LumoKit
import VecturaKit
import VecturaMLXKit
import MLXEmbedders

let embedder = try await MLXEmbedder(configuration: .multilingual_e5_small)
let lumoKit = try await LumoKit(
    config: vecturaConfig,
    chunkingConfig: chunkingConfig,
    embedder: embedder
)

Examples

API Overview

public final class LumoKit {
    public init(
        config: VecturaConfig,
        chunkingConfig: ChunkingConfig? = nil,
        modelSource: VecturaModelSource = .default
    ) async throws

    public init(
        config: VecturaConfig,
        chunkingConfig: ChunkingConfig? = nil,
        embedder: VecturaEmbedder
    ) async throws

    public func parseAndIndex(url: URL, chunkingConfig: ChunkingConfig? = nil) async throws -> [UUID]
    public func parseDocument(from url: URL, chunkingConfig: ChunkingConfig? = nil) async throws -> [Chunk]

    public func chunkText(_ text: String, config: ChunkingConfig) throws -> [Chunk]

    public func semanticSearch(
        query: String,
        numResults: Int = 5,
        threshold: Float = 0.7
    ) async throws -> [VecturaSearchResult]

    public func addDocuments(texts: [String]) async throws -> [UUID]
    public func deleteChunks(ids: [UUID]) async throws
    public func documentCount() async throws -> Int
    public func resetDB() async throws
}

public struct ChunkingConfig {
    public let chunkSize: Int
    public let overlapPercentage: Double
    public let strategy: ChunkingStrategyType // .sentence, .paragraph, .semantic
    public let contentType: ContentType // .prose, .code, .markdown, .mixed
}

public enum LumoKitError: Error {
    case emptyDocument
    case invalidChunkSize
    case invalidURL
    case fileNotFound
    case unsupportedFileType
    case invalidSearchParameters
    case chunkingFailed(strategy: String, underlyingError: Error)
}