Capture inputs and prompt templates

Use one optional recording: argument for application input, prompt template, and output references. Input and template accept normal Encodable & Sendable values.

struct SummaryInput: Codable, Sendable { let text: String }
let input = SummaryInput(text: text)
let response = try await session.respond(
    to: "Summarize: \(input.text)",
    recording: .init(
        input: input,
        promptTemplate: [
            "instructions": "Summarize the text in one sentence.",
            "prompt": "Summarize: {{text}}"
        ]
    )
)

Pass the actual instructions to client.session or trace.session. Your code renders the prompt; LedgeKit saves the template as supplied and does not interpret placeholders.

Application input and template are saved when the span starts, including when the model later fails or is interrupted. Values are scoped to that call; subsequent calls do not inherit them. Encoding failures emit a diagnostic and preserve an explicit capture-error marker without preventing model execution.

Workflow input

try await client.withTrace("summarize_and_review", version: 1, input: input) { trace in
    // Each model call supplies its own recording.input when needed.
}

Trace input belongs to the whole workflow. Span input belongs to one agent call. Either can be saved to a dataset. Include the arguments needed to execute current application code again, rather than inferring them from a prompt.

Use LedgeJSONValue.null for explicit JSON null; omitted optional input means nothing was captured. Captured values count toward the 4 MiB trace limit.

modelInput has one shape for String and native Prompt calls: id, transcript, tools, responseFormat, options, contextOptions, and metadata. Apple serializes the transcript and settings; structured prompt parts and full schemas are retained. Completion never changes input. Each generation after a tool result has its own request snapshot.

Framework or tool failures outside an executor attempt retain application context and providerCapture.failurePhase (before_generation or after_generation). These session-failure spans omit modelInput because no model request is captured at that failure boundary.