API Reference

import NexaSdk

// Load model
let asr = try Asr()
try await asr.load(from: "<path/to/model/dir>")

// Transcribe audio file
let result = try await asr.transcribe(options: .init(audioPath: "<your-audio-path>"))
print(result.asrResult)

import NexaSdk

// Load model
let asr = try Asr()
try await asr.load(from: "<path/to/model/dir>")

do {
    // start record and stream
    let stream = try asr.startRecordingStream()
    for try await content in stream {
        print(content)
    }
    // stop stream
    asr.stopRecordingStream()
} catch {
    asr.stopRecordingStream()
}

/// ASR transcription result
public struct AsrResult: Codable {
    /// Transcribed text
    public let transcript: String
    /// Confidence scores for each unit
    public let confidences: [Float]
    /// Timestamp pairs: [start, end] for each unit
    public let timestamps: [Float]
}

public struct AsrResponse: Codable {
    public let asrResult: AsrResult
    public let profileData: ProfileData?
}

public struct AsrOptions: Codable {
    public let modelPath: String
    public let language: Language
}

public enum Language: String, Codable {
    case en
    case ch
}

public struct ASRStreamConfig {
    // Timestamp mode
    public enum TimestampMode: String {
        case segment
        case word
        case none
    }

    // language
    public var language: Language = .en
    // Duration in seconds for each chunk (default: 4.0)
    public var chunkDuration: Float
    // Overlap between chunks in seconds (default: 3.0)
    public var overlapDuration: Float
    // Audio sample rate (default: 16000)
    public var sampleRate: Int32
    // Maximum chunks in processing queue (default: 10)
    public var maxQueueSize: Int32
    // Audio buffer size for input (default: 512)
    public var bufferSize: Int32
    // Timestamp mode: "none", "segment", "word" (default: none)
    public var timestamps: TimestampMode
    // Beam search size (default: 5)
    public var beamSize: Int32
}

import NexaSdk
import Foundation

// Load embedder for ANE model
let repoDir: URL = URL(string: "path/to/model/dir")!
let embedder = try Embedder(from: repoDir, plugin: .ane)

// Generate embeddings for multiple texts
let texts = ["<your-text1>", "<your-text2>"]
let result = try embedder.embed(texts: texts, config: .init(batchSize: Int32(texts.count)))
for (i, vec) in result.embeddings.enumerated() {
    let head = vec.prefix(10)
    print("[\(i)]", Array(head))
}

public struct EmbeddingConfig {
    /// Processing batch size
    public var batchSize: Int32

    /// Normalization: "l2", "mean"
    /// `nil` means not normalize embeddings
    public var normalizeMethod: NormalizeMethod?
}

public struct EmbedResult {
    public let embeddings: [[Float]]
    public let profileData: ProfileData
}

import NexaSdk

let llm = try LLM()
// load from exact gguf path
try await llm.load(.init(modelPath: "<path/to/model/file>"))

let system = "You are a helpful AI assistant"
let userMsgs = [
    "Tell me a long story, about 100 words",
    "How are you"
]
var messages = [ChatMessage]()
messages.append(.init(role: .system, content: system))
for userMsg in userMsgs {
    messages.append(.init(role: .user, content: userMsg))
    // generation
    let stream = try await llm.generateAsyncStream(messages: messages)
    var response = ""
    for try await token in stream {
        print(token, terminator: "")
        response += token
    }
    messages.append(.init(role: .assistant, content: response))
    print("\n\n")
}

import NexaSdk

let vlm = try VLM()
try await vlm.load(.init(modelPath: "<path/to/model/file>", mmprojPath: "<path/to/mmproj/file>"))

let images = ["<path/to/your/image>"]
var config = GenerationConfig.default
config.imagePaths = images
let message = ChatMessage(role: .user, content: "What do you see in this image", images: images)
let stream = try await vlm.generateAsyncStream(messages: [message], options: .init(config: config))

for try await token in stream {
    print(token, terminator: "")
}
print()

public struct GenerationConfig {
    // Maximum tokens to generate
    public var maxTokens: Int32 
    // Array of stop sequences                
    public var stop: [String]  
    // Number of past tokens to consider                
    public var nPast: Int32           
    // Advanced sampling config          
    public var samplerConfig: SamplerConfig 
    // Array of image paths for VLM, empty for none   
    public var imagePaths: [String] 
    // Array of audio paths for VLM, empty for none          
    public var audioPaths: [String]            
}

public struct SamplerConfig {
    // Sampling temperature (0.0-2.0)
    public var temperature: Float
    // Nucleus sampling parameter (0.0-1.0)
    public var topP: Float
    // Top-k sampling parameter
    public var topK: Int32
    // Minimum probability for nucleus sampling
    public var minP: Float
    // Penalty for repeated tokens
    public var repetitionPenalty: Float
    // Penalty for token presence
    public var presencePenalty: Float
    // Penalty for token frequency
    public var frequencyPenalty: Float
    // Random seed (-1 for random)
    public var seed: Int32
    // Optional grammar file path
    public var grammarPath: String?
 }

public struct ProfileData: CustomStringConvertible, Codable {

    /// Time to first token (us)
    public let ttft: Int64

    /// Prompt processing time (us)
    public let promptTime: Int64

    /// Token generation time (us)
    public let decodeTime: Int64

    /// Number of prompt tokens
    public let promptTokens: Int64

    /// Number of generated tokens
    public let generatedTokens: Int64

    /// Audio duration (us)
    public let audioDuration: Int64

    /// Prefill speed (tokens/sec)
    public let prefillSpeed: Double

    /// Decoding speed (tokens/sec)
    public let decodingSpeed: Double

    /// Real-Time Factor (RTF) (1.0 = real-time, >1.0 = faster, <1.0 = slower)
    public let realTimeFactor: Double

    /// Stop reason: "eos", "length", "user", "stop_sequence"
    public let stopReason: String
}

import NexaSdk
import Foundation

// Load reranker model for CPU/GPU inference
let repoDir = URL(string: "<path/to/model/dir>")!
let reranker = try Reranker(from: repoDir)
let query = "What is machine learning?"
let documents = [
    "Machine learning is a subset of artificial intelligence that enables computers to learn and make decisions ",
    "without being explicitly programmed.",
    "Machine learning algorithms build mathematical models based on sample data to make predictions or decisions.",
    "Deep learning is a subset of machine learning that uses neural networks with multiple layers.",
    "Python is a popular programming language for machine learning and data science.",
    "The weather today is sunny and warm."
]
let result = try await reranker.rerank(query, documents: documents)
print(result.scores)

public struct RerankerResult {
    public let scores: [Float]
    public let profileData: ProfileData
}

public struct RerankConfig {
    /// Processing batch size
    public var batchSize: Int32

    /// `nil` means not normalize scores
    /// Normalization: "softmax", "min-max", "l2"
    public var normalizeMethod: NormalizeMethod?

    public enum NormalizeMethod: String, CaseIterable {
        case softmax
        case minMax = "min-max"
        case l2
    }
}

// CPU/GPU embedder - uses GGUF format models
let embedder = try Embedder(from: "<path/to/model/dir>", plugin: .cpu_gpu)

// ANE embedder - uses CoreML format models
let embedder = try Embedder(from: "<path/to/model/dir>", plugin: .ane)