Prepare AI models for your app.

Once you’ve added the Primordial SDK to your project and created an evaluation key, you’re ready to set up your AI models.

Create a Primordial Client

PrimordialClient is the main entry point for configuring, activating, and accessing Primordial SDK features.

import Primordial

let primordial = PrimordialClient()

Primordial takes care of choosing AI models and gives you ready-to-use defaults. See AI Capabilities to learn which model each AI capability uses by default.

Use Apple’s Foundation Model

To use the system model provided by Apple Intelligence, use .appleFoundationModel() when creating the client.

let primordial = PrimordialClient(
  aiConfiguration: .init(
    generation: .appleFoundationModel()
  )
)

Apple’s Foundation Model is managed by the operating system, so your app does not need to download or remove it. Before using it, check whether it is available on the device. If Apple Intelligence is turned off, direct the user to Apple’s setup guide.

let capabilities = await primordial.ai.generation.capabilities()
          
switch capabilities.availability {
  case .available:
    print("Apple Foundation Model is ready")

  case .systemUnavailable(let reason):
    print("Apple Foundation Model is unavailable: \(reason)")

  case .unavailable(let message):
    print(message)
}

Apple selection on pre-26 systems reports .systemUnavailable(.operatingSystemNotSupported).

Configuration and fallback model option

AI Capabilities

When the PrimordialClient uses Apple’s Foundation Model, .generation uses Apple’s system model instead of downloading Qwen3. The .answering capability still downloads the embedding model for collection search.

Check What Your App Needs

Before downloading, check which AI capabilities your app or workflow needs. Primordial tells you the download size, required storage, and whether they are ready to use.

let requirement = await primordial.ai.status(
    for: [.answering, .voiceInput]
)

print(requirement.downloadBytes)
print(requirement.requiredAvailableBytes)
print(requirement.isInstalled)
print(requirement.isAvailable)

Activate Primordial

Activate Primordial before installing models or running an AI task.

try await primordial.activate(
  .evaluationKey("pk_eval_your_key_here")
)

You can check primordial.isActivated when your UI needs to reflect activation state. Keep the evaluation key out of logs and user-visible error messages.

Download the Required Models

Use makeAvailable to download the models your app needs. If you use Apple’s Foundation Model, it checks whether the system model is ready instead.

for try await progress in primordial.ai.makeAvailable(
    [.answering, .voiceInput]
) {
    print(progress.fractionCompleted)
    print(progress.downloadedBytes)
    print(progress.totalBytes)
    print(progress.phase)
}

Primordial checks storage, downloads the missing resources, verifies them, and resumes valid partial downloads. Calling makeAvailable again does not download an already installed model again.

Keep iOS downloads running

SwiftUI apps add one modifier to their main scene. UIKit apps use the app delegate fallback.

import Primordial
import SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .primordialBackgroundDownloads()
    }
}

func application(
    _ application: UIApplication,
    handleEventsForBackgroundURLSession identifier: String,
    completionHandler: @escaping () -> Void
) {
    PrimordialClient.handleEventsForBackgroundURLSession(
        identifier: identifier,
        completionHandler: completionHandler
    )
}

Use Custom Models

If you want to use different AI models or configure default models, see Advanced API: Model Configuration.