KuzcoKuzco.

Quick Start

Build your first AI-powered feature in minutes. This guide covers the basics of text generation with streaming and one-shot responses.

Prerequisites

Make sure you've completed the installation guide and initialized Kuzco with your API key.

Creating a Session

A KuzcoSession manages the conversation state and model interactions:

import Kuzco
// Create a session with a specific model
let session = try await KuzcoSession(model: .qwen3_4b)
// Or with a custom configuration
let config = KuzcoConfiguration(
    temperature: 0.7,
    maxTokens: 1024
)
let session = try await KuzcoSession(model: .qwen3_4b, configuration: config)

Streaming Responses

Streaming provides real-time text generation, ideal for chat interfaces where you want to show text as it's generated:

StreamingExample.swift
import SwiftUI
import Kuzco
struct StreamingView: View {
    @State private var response = ""
    @State private var isLoading = false
    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            ScrollView {
                Text(response)
                    .frame(maxWidth: .infinity, alignment: .leading)
            }
            Button(isLoading ? "Generating..." : "Generate Story") {
                generateStory()
            }
            .disabled(isLoading)
        }
        .padding()
    }
    func generateStory() {
        isLoading = true
        response = ""
        Task {
            do {
                let session = try await KuzcoSession(model: .qwen3_4b)
                for try await partial in session.streamResponse(
                    to: "Write a short story about a robot learning to paint."
                ) {
                    response += partial.text
                }
            } catch {
                response = "Error: \(error.localizedDescription)"
            }
            isLoading = false
        }
    }
}

Understanding the Stream

The streamResponse method returns an AsyncThrowingStream of KuzcoPartialResponse objects:

for try await partial in session.streamResponse(to: prompt) {
    // partial.text - The new text chunk
    // partial.tokenUsage - Current token count (optional)
    // partial.isComplete - Whether generation is finished
    print(partial.text, terminator: "")
}

One-Shot Responses

For simpler use cases where you just need the complete response, use oneShot:

OneShotExample.swift
import SwiftUI
import Kuzco
struct OneShotView: View {
    @State private var response = ""
    @State private var isLoading = false
    var body: some View {
        VStack(spacing: 16) {
            Text(response)
                .frame(maxWidth: .infinity, alignment: .leading)
            Button(isLoading ? "Loading..." : "Get Answer") {
                getAnswer()
            }
            .disabled(isLoading)
        }
        .padding()
    }
    func getAnswer() {
        isLoading = true
        Task {
            do {
                let session = try await KuzcoSession(model: .qwen3_4b)
                let result = try await session.oneShot(
                    "What are the main benefits of on-device AI?"
                )
                response = result.text
            } catch {
                response = "Error: \(error.localizedDescription)"
            }
            isLoading = false
        }
    }
}

Conversation History

Kuzco maintains conversation context automatically. Continue the conversation by sending follow-up messages:

let session = try await KuzcoSession(model: .qwen3_4b)
// First message
let response1 = try await session.oneShot("What is the capital of France?")
print(response1.text) // "The capital of France is Paris."
// Follow-up - the session remembers context
let response2 = try await session.oneShot("What's the population?")
print(response2.text) // "Paris has a population of approximately..."
// Clear history if needed
session.clearHistory()

System Prompts

Set a system prompt to customize the model's behavior:

let session = try await KuzcoSession(model: .qwen3_4b)
// Set a system prompt
session.setSystemPrompt("""
You are a helpful cooking assistant. Provide clear, step-by-step
recipes and cooking tips. Always mention cooking times and temperatures.
""")
let result = try await session.oneShot("How do I make scrambled eggs?")
print(result.text)

Error Handling

Always wrap Kuzco calls in do-catch blocks to handle potential errors:

do {
    let session = try await KuzcoSession(model: .qwen3_4b)
    let response = try await session.oneShot("Hello!")
    print(response.text)
} catch KuzcoError.modelNotDownloaded {
    print("Model needs to be downloaded first")
} catch KuzcoError.invalidAPIKey {
    print("Check your API key configuration")
} catch KuzcoError.insufficientMemory {
    print("Not enough memory for this model")
} catch {
    print("Unexpected error: \(error)")
}

Next Steps

Now that you've learned the basics, explore more features:

Available ModelsConfiguration Options
InstallationAvailable Models