Configure LedgeKit

Create one client at your application's composition root and pass it to features that call models.

import LedgeKit

func makeClient(
    loadWriteKey: @escaping @Sendable () async throws -> String,
    recordingEnabled: Bool
) throws -> LedgeClient {
    try LedgeClient(
        serviceName: "my-app",
        credentials: .tokenProvider(loadWriteKey),
        isEnabled: recordingEnabled,
        onDiagnostic: { event in
            print("LedgeKit \(event.code.rawValue): \(event.message)")
        }
    )
}

Use .apiKey(key) for a fixed credential or .tokenProvider(loadWriteKey) to resolve one on each delivery attempt. Your application owns key retrieval and rotation. A credential-provider failure leaves telemetry pending and does not replace the model's response or error.

Startup and storage

The first trace or flush() automatically recovers interrupted work and schedules pending delivery. Concurrent first calls share that initialization. To attempt recovery at application launch, call await client.flush().

Default storage is in Application Support under LedgeKit/v1, using a stable hash of the service name. Set localDirectory: to use another writable directory. Give independent clients separate directories so they do not recover each other's active work.

Disable recording

Set isEnabled: false when constructing the client. The same record and respond calls continue to execute native model operations, without capture, local file writes, or uploads.

Configuration errors

Client and agent construction throw for invalid names or versions. Names must contain non-whitespace text and fit within 256 characters; versions must be positive 32-bit integers. Empty static credentials throw during client setup.

Telemetry capture and delivery failures are reported through onDiagnostic and delivery summaries. Advanced callers can inject a custom transport.