// Screenshot batch creation (AnalysisManager.swift:476)
func createScreenshotBatches(from screenshots: [Screenshot]) {
    let maxGap: TimeInterval = config.maxGap         // 5 minutes
    let maxBatchDuration: TimeInterval = config.targetDuration  // 15-30 min
    
    // Break batch if:
    // 1. Gap between screenshots > 5 minutes
    // 2. Batch duration exceeds target duration
    // 3. Minimum batch duration: 5 minutes
}

// Transcribe screenshots using provider
let transcribeResult = try await executeWithProviderBackup(
    operation: "transcribe",
    batchId: batchId,
    primaryContext: primaryContext,
    activeContext: activeContext,
    backupContext: backupContext
) { context in
    try await context.actions.transcribeScreenshots(screenshots, batchStartDate, batchId)
}
observations = transcribeResult.value.observations

struct Observation {
    let id: Int64?
    let batchId: Int64
    let startTs: Int        // Unix timestamp
    let endTs: Int
    let observation: String // Text description of screenshot
    let metadata: String?
    let llmModel: String?
}

// Calculate card-generation lookback window (LLMService.swift:624)
let currentTime = Date(timeIntervalSince1970: TimeInterval(batchEndTs))
let windowStartTime = currentTime.addingTimeInterval(-batchingConfig.cardLookbackDuration)

// Fetch observations from the recent batching window
let recentObservations = StorageManager.shared.fetchObservationsByTimeRange(
    from: windowStartTime,
    to: currentTime
)

// Fetch existing timeline cards for context
let existingTimelineCards = StorageManager.shared.fetchTimelineCardsByTimeRange(
    from: windowStartTime,
    to: currentTime
)

struct ActivityGenerationContext {
    let batchObservations: [Observation]        // Current batch
    let existingCards: [ActivityCardData]       // Previous cards in window
    let currentTime: Date                       // Batch end time
    let categories: [LLMCategoryDescriptor]     // User-defined categories
}

struct ActivityCardData {
    let startTime: String          // "2:30 PM"
    let endTime: String            // "3:45 PM"
    let category: String           // "Development"
    let subcategory: String        // "Coding"
    let title: String              // "Implementing screen recorder"
    let summary: String            // Brief description
    let detailedSummary: String    // Comprehensive summary
    let distractions: [Distraction]?
    let appSites: AppSites?        // Apps and websites used
}

// Replace old cards with new ones in the time range (LLMService.swift:698)
let (insertedCardIds, deletedVideoPaths) = StorageManager.shared.replaceTimelineCardsInRange(
    from: windowStartTime,
    to: currentTime,
    with: cards,
    batchId: batchId
)

// On-demand timelapse creation
func generateTimelapse(for card: TimelineCard) {
    1. Parse time range from card.startTimestamp/endTimestamp
    2. Fetch screenshots in range from database
    3. Create video from screenshots using AVFoundation
    4. Save to file system with card ID
    5. Update card.videoSummaryURL in database
}

// GeminiDirectProvider.swift
func transcribeScreenshots(
    _ screenshots: [Screenshot],
    batchStartTime: Date,
    batchId: Int64?
) async throws -> (observations: [Observation], log: LLMCall) {
    // 1. Create video from screenshots
    let videoURL = try await createVideoFromScreenshots(screenshots)
    
    // 2. Upload video to Gemini Files API
    let fileURI = try await uploadVideo(videoURL)
    
    // 3. Wait for video processing
    try await pollFileStatus(fileURI)
    
    // 4. Generate transcription with native video understanding
    let prompt = buildTranscriptionPrompt()
    let response = try await generateContent(
        model: current.model,
        fileURI: fileURI,
        prompt: prompt
    )
    
    // 5. Parse observations from response
    return parseObservations(response)
}

func generateActivityCards(
    observations: [Observation],
    context: ActivityGenerationContext,
    batchId: Int64?
) async throws -> (cards: [ActivityCardData], log: LLMCall) {
    let prompt = buildCardGenerationPrompt(
        observations: context.batchObservations,
        existingCards: context.existingCards,
        categories: context.categories
    )
    
    let response = try await generateContent(
        model: current.model,
        prompt: prompt
    )
    
    return parseActivityCards(response)
}

// Automatic model fallback on capacity errors
models: [
    .gemini_2_0_flash_exp,     // Try first
    .gemini_1_5_flash          // Fallback on 429/503
]

// Automatic Gemma 2 fallback on persistent errors
if error.isCapacityError && hasGemmaBackup {
    fallbackState.preferGemma = true
    return try await gemmaProvider.transcribeScreenshots(...)
}

// Extract 30 frames evenly distributed across video
let frames = extractFrames(from: videoURL, count: 30)

for (index, frame) in frames.enumerated() {
    let description = try await llm.describeImage(
        image: frame,
        prompt: "Describe what the user is doing in this screenshot."
    )
    observations.append(description)
}

let prompt = """
Merge these 30 observations into coherent activity segments:
\(observations.joined(separator: "\n"))
"""
let mergedSegments = try await llm.generate(prompt: prompt)

for segment in segments {
    let title = try await llm.generate(
        prompt: "Create a concise title for: \(segment)"
    )
}

let shouldMerge = try await llm.generate(
    prompt: "Should these adjacent segments be merged? \(segment1) \(segment2)"
)

// Extract frames at 60-second intervals
let frames = extractFrames(from: videoURL, interval: 60)
// For a 30-minute batch: ~30 frames

// Process 10 frames per call
let batches = frames.chunked(into: 10)

for batch in batches {
    let descriptions = try await chatCLI.analyzeImages(
        images: batch,
        prompt: "Describe each screenshot and what the user is doing."
    )
}

let prompt = """
Merge these observations into coherent activities:
\(allDescriptions.joined(separator: "\n\n"))
"""
let segments = try await chatCLI.generate(prompt: prompt)

let cards = try await chatCLI.generateCards(
    observations: segments,
    existingCards: context.existingCards,
    categories: context.categories
)

// ChatCLIRunner.swift
func runChatCLI(
    tool: ChatCLITool,  // .codex or .claude
    prompt: String,
    images: [Data]
) async throws -> String {
    // 1. Save images to temp files
    let imagePaths = saveTemporaryImages(images)
    
    // 2. Build CLI command
    let command: String
    switch tool {
    case .codex:
        command = "codex \(imagePaths.joined(separator: " ")) --prompt \(prompt)"
    case .claude:
        command = "claude \(imagePaths.joined(separator: " ")) --prompt \(prompt)"
    }
    
    // 3. Execute CLI
    let process = Process()
    process.launchPath = "/usr/bin/env"
    process.arguments = ["bash", "-c", command]
    
    let output = try await process.run()
    
    // 4. Cleanup temp files
    cleanupTemporaryImages(imagePaths)
    
    return output
}

func transcribeScreenshots(...) async throws -> (observations: [Observation], log: LLMCall) {
    // Upload screenshots to Dayflow backend
    let uploadURL = try await uploadScreenshots(screenshots, to: endpoint)
    
    // Poll for processing completion
    let observations = try await pollForObservations(uploadURL)
    
    return observations
}

func executeWithProviderBackup<T>(
    operation: String,
    batchId: Int64?,
    primaryContext: TimelineProviderContext,
    activeContext: TimelineProviderContext,
    backupContext: TimelineProviderContext?,
    work: (TimelineProviderContext) async throws -> T
) async throws -> (value: T, activeContext: TimelineProviderContext, usedProviderBackup: Bool) {
    do {
        // Try primary provider
        let value = try await work(activeContext)
        return (value, activeContext, false)
    } catch {
        guard let backupContext else { throw error }
        
        // Log fallback attempt
        AnalyticsService.shared.capture("llm_timeline_fallback_attempted", ...)
        
        do {
            // Try backup provider
            let value = try await work(backupContext)
            AnalyticsService.shared.capture("llm_timeline_fallback_succeeded", ...)
            return (value, backupContext, true)
        } catch {
            AnalyticsService.shared.capture("llm_timeline_fallback_failed", ...)
            throw error
        }
    }
}

func createErrorCard(
    batchId: Int64,
    batchStartTime: Date,
    batchEndTime: Date,
    error: Error
) -> TimelineCardShell {
    return TimelineCardShell(
        startTimestamp: startTimeStr,
        endTimestamp: endTimeStr,
        category: "System",
        subcategory: "Error",
        title: "Processing failed",
        summary: "Failed to process \(duration) minutes... \(humanError) Your recording is safe and can be reprocessed.",
        detailedSummary: "Error details: \(error.localizedDescription)\n\nThis recording batch can be reprocessed by retrying from Settings."
    )
}

func getHumanReadableError(_ error: Error) -> String {
    // Maps technical errors to user-friendly messages
    // Examples:
    // - "Rate limited. Too many requests to Gemini. Please wait a few minutes."
    // - "Invalid API key. Please check your Gemini API key in Settings."
    // - "Google's AI services may be temporarily down. Check the status page."
}

SELECT 
    created_at,
    batch_id,
    provider,
    operation,
    status,
    latency_ms,
    error_message
FROM llm_calls
ORDER BY created_at DESC
LIMIT 100;

SELECT 
    batch_id,
    start_ts,
    end_ts,
    observation
FROM observations
WHERE batch_id = ?
ORDER BY start_ts;

SELECT 
    id,
    status,
    batch_start_ts,
    batch_end_ts,
    reason
FROM analysis_batches
ORDER BY batch_start_ts DESC;