Evaluation reporting APIs
Persist native evaluation reports and upload their original bytes.
Import LedgeKitTesting for these APIs.
Captured executions
LedgeEvaluationCapture is a transport for evaluation execution. Inject it into
LedgeClient, execute the actual agent or workflow, and flush the client.
Its read-only envelopes contain LedgeCapturedTrace values and their
LedgeCapturedSpan calls, preserving all captured wire fields.
Each captured span or trace exposes .response: LedgeEvaluationResponse for
Apple's ModelSubject. The response encodes exactly { span } or { trace }.
There is no initializer accepting application output. A span's modelOutput
comes from its recorded session; requests, errors and durations stay separate.
Reports with arbitrary Response values or output that differs from the recorded transcript range are rejected. Missing responses stay missing.
LedgeEvaluationReporter
An actor with durable local storage and a write key.
public init(writeKey: String, localDirectory: URL? = nil, session: URLSession = .shared)
public func submit(_ reportURL: URL) async throws
public func retryPending() async throws -> [Delivery]submit reads a local report file, validates its native structure and 4 MiB limit,
and saves the original bytes before upload. It moves the saved copy from Pending
to Uploaded only after a valid receipt with a matching report ID. Different bytes
with the same pending result ID cause a conflict. Temporary failures receive up
to three total attempts per delivery; failed files remain pending.
The default Application Support directory is isolated by a hash of the write key.
localDirectory overrides the exact directory; dedicate it to the intended app
and environment. See local storage.
retryPending attempts previously saved files without running inference. It can throw for directory access; individual file results are returned as Delivery values with file: URL and error: String?. A nil error indicates successful delivery.
LedgeEvaluationError
Cases: invalidReport(String), conflictingLocalReport, uploadRejected(Int), invalidResponse. The enum conforms to Error, LocalizedError, and Sendable.
See uploading reports for complete persistence and retry examples.