API Reference

class KuzcoClient {
    static let shared: KuzcoClient
    /// Initialize the SDK with your API key
    static func initialize(apiKey: String)
    /// Check if the client is initialized
    var isInitialized: Bool { get }
    /// Current API key (read-only)
    var apiKey: String? { get }
}

class KuzcoSession {
    /// Create a new session with the specified model
    init(model: KuzcoModel, configuration: KuzcoConfiguration = .default) async throws
    /// Stream responses token by token
    func streamResponse(to prompt: String) -> AsyncThrowingStream<KuzcoPartialResponse, Error>
    /// Get a complete response
    func oneShot(_ prompt: String) async throws -> KuzcoResponse
    /// Analyze an image with a prompt (vision models only)
    func analyzeImage(_ image: UIImage, prompt: String) async throws -> KuzcoResponse
    /// Stream image analysis
    func streamImageAnalysis(_ image: UIImage, prompt: String) -> AsyncThrowingStream<KuzcoPartialResponse, Error>
    /// Set system prompt
    func setSystemPrompt(_ prompt: String)
    /// Add a message to conversation history
    func addMessage(role: MessageRole, content: String)
    /// Clear conversation history
    func clearHistory()
    /// Get conversation history
    var conversationHistory: [Message] { get }
    /// Update configuration
    func updateConfiguration(_ configuration: KuzcoConfiguration)
}

class KuzcoImageGenerator {
    /// Create an image generator
    init(model: KuzcoModel) async throws
    /// Generate an image from a prompt
    func generate(
        prompt: String,
        negativePrompt: String? = nil,
        width: Int = 512,
        height: Int = 512,
        steps: Int = 30,
        guidanceScale: Float = 7.5,
        seed: UInt32? = nil
    ) async throws -> UIImage
    /// Generate with progress tracking
    func generateWithProgress(
        prompt: String,
        negativePrompt: String? = nil,
        width: Int = 512,
        height: Int = 512,
        steps: Int = 30,
        guidanceScale: Float = 7.5,
        seed: UInt32? = nil
    ) -> AsyncThrowingStream<ImageGenerationProgress, Error>
}

class KuzcoModelManager {
    static let shared: KuzcoModelManager
    /// Check if a model is downloaded
    func isModelAvailable(_ model: KuzcoModel) async -> Bool
    /// Download a model with progress
    func downloadModel(_ model: KuzcoModel) -> AsyncThrowingStream<DownloadProgress, Error>
    /// Delete a downloaded model
    func deleteModel(_ model: KuzcoModel) async throws
    /// Delete all downloaded models
    func deleteAllModels() async throws
    /// Get list of downloaded models
    func downloadedModels() async -> [KuzcoModel]
    /// Get total storage used
    func totalStorageUsed() async -> Int64
    /// Get storage used by a specific model
    func storageUsed(for model: KuzcoModel) async -> Int64?
    /// Get model file path
    func modelPath(for model: KuzcoModel) async -> URL?
    /// Fetch available models from API
    func fetchAvailableModels() async throws -> [LLMModel]
    /// Models directory
    var modelsDirectory: URL { get }
    /// Enable background downloads
    var enableBackgroundDownloads: Bool { get set }
}

struct KuzcoPartialResponse {
    /// The new text chunk
    let text: String
    /// Token usage statistics (may be nil during streaming)
    let tokenUsage: TokenUsage?
    /// Whether generation is complete
    let isComplete: Bool
    /// Model that generated this response
    let model: KuzcoModel
}

struct KuzcoResponse {
    /// The complete generated text
    let text: String
    /// Token usage statistics
    let tokenUsage: TokenUsage
    /// Model that generated this response
    let model: KuzcoModel
    /// Generation time in seconds
    let generationTime: TimeInterval
}

struct TokenUsage {
    /// Tokens in the prompt
    let promptTokens: Int
    /// Tokens in the completion
    let completionTokens: Int
    /// Total tokens used
    var totalTokens: Int {
        promptTokens + completionTokens
    }
}

struct DownloadProgress {
    /// Progress from 0.0 to 1.0
    let progress: Double
    /// Bytes downloaded so far
    let bytesDownloaded: Int64
    /// Total bytes to download
    let totalBytes: Int64
    /// Download speed in bytes per second
    let bytesPerSecond: Int64?
    /// Estimated time remaining in seconds
    let estimatedTimeRemaining: TimeInterval?
    /// Whether download is complete
    let isComplete: Bool
}

struct ImageGenerationProgress {
    /// Progress from 0.0 to 1.0
    let progress: Double
    /// Current step number
    let currentStep: Int
    /// Total steps
    let totalSteps: Int
    /// Preview image (available at intervals)
    let previewImage: UIImage?
    /// Final image (available when complete)
    let image: UIImage?
    /// Whether generation is complete
    var isComplete: Bool {
        currentStep >= totalSteps
    }
}

struct KuzcoConfiguration {
    var temperature: Float       // 0.0 - 2.0, default: 0.7
    var maxTokens: Int           // default: 2048
    var topK: Int                // default: 40
    var topP: Float              // 0.0 - 1.0, default: 0.9
    var repeatPenalty: Float     // default: 1.1
    var contextLength: Int?      // nil uses model default
    var stopSequences: [String]  // default: []
    // Presets
    static let `default`: KuzcoConfiguration
    static let creative: KuzcoConfiguration
    static let precise: KuzcoConfiguration
    static let coding: KuzcoConfiguration
    static let lowMemory: KuzcoConfiguration
    static let performance: KuzcoConfiguration
}

class KuzcoAPIConfiguration {
    static let shared: KuzcoAPIConfiguration
    func configure(
        baseURL: String?,
        modelsEndpoint: String = "/models",
        downloadEndpoint: String = "/downloads",
        headers: [String: String] = [:],
        timeout: TimeInterval = 60
    )
    func updateHeaders(_ headers: [String: String])
    func reset()
    var baseURL: String { get }
    var modelsEndpoint: String { get }
}

enum KuzcoModel: String, CaseIterable {
    // Text models
    case qwen3_4b
    case qwen3_8b
    case llama3_3b
    case phi4_mini
    case gemma3_4b
    case deepseekR1_1_5b
    // Vision models
    case qwen3VL
    case smolVLM
    // Image generation
    case stableDiffusion21
    var type: ModelType { get }
    var displayName: String { get }
    var defaultContextLength: Int { get }
}

enum MessageRole: String {
    case system
    case user
    case assistant
}

enum KuzcoError: Error {
    /// API key is missing or invalid
    case invalidAPIKey
    /// Client not initialized
    case notInitialized
    /// Model is not downloaded
    case modelNotDownloaded(KuzcoModel)
    /// Insufficient memory to load model
    case insufficientMemory
    /// Model loading failed
    case modelLoadFailed(String)
    /// Generation failed
    case generationFailed(String)
    /// Invalid model type for operation
    case invalidModelType(expected: ModelType, got: ModelType)
    /// Network error
    case networkError(Error)
    /// Download failed
    case downloadFailed(String)
    /// Invalid response from API
    case invalidResponse
    /// Operation cancelled
    case cancelled
}

do {
    let session = try await KuzcoSession(model: .qwen3_4b)
    let response = try await session.oneShot("Hello!")
    print(response.text)
} catch KuzcoError.notInitialized {
    print("Call KuzcoClient.initialize() first")
} catch KuzcoError.invalidAPIKey {
    print("Check your API key")
} catch KuzcoError.modelNotDownloaded(let model) {
    print("Download \(model) first")
} catch KuzcoError.insufficientMemory {
    print("Not enough memory - try a smaller model")
} catch KuzcoError.modelLoadFailed(let reason) {
    print("Failed to load model: \(reason)")
} catch KuzcoError.generationFailed(let reason) {
    print("Generation failed: \(reason)")
} catch KuzcoError.networkError(let underlying) {
    print("Network error: \(underlying.localizedDescription)")
} catch {
    print("Unexpected error: \(error)")
}

struct Message {
    let role: MessageRole
    let content: String
    let timestamp: Date
    init(role: MessageRole, content: String)
}

struct LLMModel: Codable {
    let id: String
    let name: String
    let description: String
    let size: Int64
    let contextLength: Int
    let type: String
    let downloadURL: String
}