@sriinnu/runic 1.0.0

package/Sources/RunicCore/UsageLedger/UsageLedgerInsightsAdvisor.swift

@@ -0,0 +1,209 @@
+import Foundation
+
+public struct UsageLedgerReliabilityScore: Sendable, Codable, Hashable {
+    public let score: Int
+    public let grade: String
+    public let summary: String
+    public let primarySignal: String?
+    public let signals: [String]
+
+    public init(
+        score: Int,
+        grade: String,
+        summary: String,
+        primarySignal: String?,
+        signals: [String])
+    {
+        self.score = score
+        self.grade = grade
+        self.summary = summary
+        self.primarySignal = primarySignal
+        self.signals = signals
+    }
+}
+
+public struct UsageLedgerRoutingRecommendation: Sendable, Codable, Hashable {
+    public let fromModel: String
+    public let toModel: String
+    public let shiftPercent: Int
+    public let estimatedSavingsUSD: Double
+    public let baselineCostPer1KUSD: Double
+    public let candidateCostPer1KUSD: Double
+    public let confidence: Double
+    public let rationale: String
+
+    public init(
+        fromModel: String,
+        toModel: String,
+        shiftPercent: Int,
+        estimatedSavingsUSD: Double,
+        baselineCostPer1KUSD: Double,
+        candidateCostPer1KUSD: Double,
+        confidence: Double,
+        rationale: String)
+    {
+        self.fromModel = fromModel
+        self.toModel = toModel
+        self.shiftPercent = shiftPercent
+        self.estimatedSavingsUSD = estimatedSavingsUSD
+        self.baselineCostPer1KUSD = baselineCostPer1KUSD
+        self.candidateCostPer1KUSD = candidateCostPer1KUSD
+        self.confidence = confidence
+        self.rationale = rationale
+    }
+}
+
+public enum UsageLedgerInsightsAdvisor {
+    public static func reliabilityScore(
+        provider _: UsageProvider,
+        daily: UsageLedgerDailySummary?,
+        activeBlock: UsageLedgerBlockSummary?,
+        modelBreakdown: [UsageLedgerModelSummary],
+        projectBreakdown: [UsageLedgerProjectSummary],
+        providerError: String?,
+        ledgerError: String?) -> UsageLedgerReliabilityScore?
+    {
+        let hasAnyData = daily != nil || activeBlock != nil || !modelBreakdown.isEmpty || !projectBreakdown.isEmpty
+        let hasProviderError = !(providerError?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ?? true)
+        let hasLedgerError = !(ledgerError?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ?? true)
+        if !hasAnyData, !hasProviderError, !hasLedgerError {
+            return nil
+        }
+
+        var score = 100
+        var signals: [String] = []
+
+        if hasProviderError {
+            score -= 35
+            signals.append("Provider fetch errors detected.")
+        }
+
+        if hasLedgerError {
+            score -= 25
+            signals.append("Local ledger parsing/loading errors detected.")
+        }
+
+        if daily == nil {
+            score -= 10
+            signals.append("No stable daily usage snapshot yet.")
+        }
+
+        if activeBlock == nil {
+            score -= 5
+            signals.append("No active session block observed.")
+        }
+
+        if projectBreakdown.isEmpty {
+            score -= 10
+            signals.append("No project-level grouping is available.")
+        } else {
+            let unknownProjects = projectBreakdown.filter { $0.displayProjectName == "Unknown project" }.count
+            let unknownRatio = Double(unknownProjects) / Double(max(1, projectBreakdown.count))
+            if unknownRatio > 0.40 {
+                score -= 10
+                signals.append("Many entries cannot be mapped to stable project names.")
+            } else if unknownRatio > 0.15 {
+                score -= 5
+                signals.append("Some entries still have weak project naming confidence.")
+            }
+        }
+
+        if let daily, daily.totals.totalTokens > 0 {
+            let cache = daily.totals.cacheCreationTokens + daily.totals.cacheReadTokens
+            let cacheRatio = Double(cache) / Double(daily.totals.totalTokens)
+            if cacheRatio >= 0.20 {
+                score += 3
+                signals.append("Healthy cache participation in daily traffic.")
+            }
+        }
+
+        if modelBreakdown.count >= 2 {
+            score += 2
+            signals.append("Multiple active models provide routing flexibility.")
+        }
+
+        score = max(0, min(100, score))
+        let grade: String
+        let summary: String
+        switch score {
+        case 90...:
+            grade = "A"
+            summary = "Strong reliability."
+        case 80...89:
+            grade = "B"
+            summary = "Good reliability with minor risk."
+        case 70...79:
+            grade = "C"
+            summary = "Moderate reliability; monitor closely."
+        case 60...69:
+            grade = "D"
+            summary = "Fragile reliability; remediation recommended."
+        default:
+            grade = "F"
+            summary = "Unreliable state; immediate fixes recommended."
+        }
+
+        return UsageLedgerReliabilityScore(
+            score: score,
+            grade: grade,
+            summary: summary,
+            primarySignal: signals.first,
+            signals: signals)
+    }
+
+    public static func routingRecommendation(
+        modelBreakdown: [UsageLedgerModelSummary],
+        shiftPercent: Double = 0.20) -> UsageLedgerRoutingRecommendation?
+    {
+        struct CostPoint {
+            let model: String
+            let tokens: Int
+            let requests: Int
+            let costPer1K: Double
+        }
+
+        let points: [CostPoint] = modelBreakdown.compactMap { summary in
+            guard let cost = summary.totals.costUSD, cost > 0 else { return nil }
+            let tokens = summary.totals.totalTokens
+            guard tokens >= 500 else { return nil }
+            let costPer1K = cost / (Double(tokens) / 1000.0)
+            guard costPer1K.isFinite, costPer1K > 0 else { return nil }
+            return CostPoint(
+                model: summary.model,
+                tokens: tokens,
+                requests: summary.entryCount,
+                costPer1K: costPer1K)
+        }
+
+        guard points.count >= 2 else { return nil }
+        let sorted = points.sorted { $0.costPer1K < $1.costPer1K }
+        guard let cheapest = sorted.first else { return nil }
+        guard let mostExpensive = sorted.last, mostExpensive.model != cheapest.model else { return nil }
+
+        let unitDelta = mostExpensive.costPer1K - cheapest.costPer1K
+        guard unitDelta > 0.05 else { return nil }
+
+        let effectiveShift = max(0.05, min(0.40, shiftPercent))
+        let shiftedTokens = Int(Double(mostExpensive.tokens) * effectiveShift)
+        guard shiftedTokens >= 250 else { return nil }
+
+        let estimatedSavings = unitDelta * (Double(shiftedTokens) / 1000.0)
+        guard estimatedSavings >= 0.01 else { return nil }
+
+        let totalCostedTokens = points.reduce(0) { $0 + $1.tokens }
+        let coverage = min(1.0, Double(totalCostedTokens) / 100_000.0)
+        let confidence = max(0.30, min(0.95, 0.40 + (coverage * 0.55)))
+        let shiftLabel = Int((effectiveShift * 100).rounded())
+
+        let rationale = "Shift \(shiftLabel)% of \(mostExpensive.model) volume to \(cheapest.model) based on observed cost-per-1K."
+        return UsageLedgerRoutingRecommendation(
+            fromModel: mostExpensive.model,
+            toModel: cheapest.model,
+            shiftPercent: shiftLabel,
+            estimatedSavingsUSD: estimatedSavings,
+            baselineCostPer1KUSD: mostExpensive.costPer1K,
+            candidateCostPer1KUSD: cheapest.costPer1K,
+            confidence: confidence,
+            rationale: rationale)
+    }
+}

package/Sources/RunicCore/UsageLedger/UsageLedgerModels.swift

@@ -0,0 +1,417 @@
+import Foundation
+
+public struct UsageLedgerEntry: Sendable, Codable, Hashable {
+    public enum Source: String, Sendable, Codable {
+        case claudeLog
+        case codexLog
+        case api
+        case cli
+        case unknown
+    }
+
+    public let provider: UsageProvider
+    public let timestamp: Date
+    public let sessionID: String?
+    public let projectID: String?
+    public let projectName: String?
+    public let model: String?
+    public let inputTokens: Int
+    public let outputTokens: Int
+    public let cacheCreationTokens: Int
+    public let cacheReadTokens: Int
+    public let costUSD: Double?
+    public let requestID: String?
+    public let messageID: String?
+    public let version: String?
+    public let source: Source
+
+    public init(
+        provider: UsageProvider,
+        timestamp: Date,
+        sessionID: String?,
+        projectID: String?,
+        projectName: String? = nil,
+        model: String?,
+        inputTokens: Int,
+        outputTokens: Int,
+        cacheCreationTokens: Int,
+        cacheReadTokens: Int,
+        costUSD: Double?,
+        requestID: String?,
+        messageID: String?,
+        version: String?,
+        source: Source)
+    {
+        self.provider = provider
+        self.timestamp = timestamp
+        self.sessionID = sessionID
+        self.projectID = projectID
+        self.projectName = projectName
+        self.model = model
+        self.inputTokens = inputTokens
+        self.outputTokens = outputTokens
+        self.cacheCreationTokens = cacheCreationTokens
+        self.cacheReadTokens = cacheReadTokens
+        self.costUSD = costUSD
+        self.requestID = requestID
+        self.messageID = messageID
+        self.version = version
+        self.source = source
+    }
+
+    public var totalTokens: Int {
+        self.inputTokens + self.outputTokens + self.cacheCreationTokens + self.cacheReadTokens
+    }
+
+    public var nonCacheTokens: Int {
+        self.inputTokens + self.outputTokens
+    }
+}
+
+public struct UsageLedgerTotals: Sendable, Codable, Hashable {
+    public let inputTokens: Int
+    public let outputTokens: Int
+    public let cacheCreationTokens: Int
+    public let cacheReadTokens: Int
+    public let costUSD: Double?
+
+    public init(
+        inputTokens: Int,
+        outputTokens: Int,
+        cacheCreationTokens: Int,
+        cacheReadTokens: Int,
+        costUSD: Double?)
+    {
+        self.inputTokens = inputTokens
+        self.outputTokens = outputTokens
+        self.cacheCreationTokens = cacheCreationTokens
+        self.cacheReadTokens = cacheReadTokens
+        self.costUSD = costUSD
+    }
+
+    public var totalTokens: Int {
+        self.inputTokens + self.outputTokens + self.cacheCreationTokens + self.cacheReadTokens
+    }
+
+    public var nonCacheTokens: Int {
+        self.inputTokens + self.outputTokens
+    }
+}
+
+public struct UsageLedgerHourlySummary: Sendable, Codable, Hashable {
+    public let provider: UsageProvider
+    public let projectID: String?
+    public let hourStart: Date
+    public let hourKey: String // "2026-01-31T14:00:00"
+    public let totals: UsageLedgerTotals
+    public let requestCount: Int
+
+    public init(
+        provider: UsageProvider,
+        projectID: String?,
+        hourStart: Date,
+        hourKey: String,
+        totals: UsageLedgerTotals,
+        requestCount: Int)
+    {
+        self.provider = provider
+        self.projectID = projectID
+        self.hourStart = hourStart
+        self.hourKey = hourKey
+        self.totals = totals
+        self.requestCount = requestCount
+    }
+}
+
+public struct UsageLedgerDailySummary: Sendable, Codable, Hashable {
+    public let provider: UsageProvider
+    public let projectID: String?
+    public let dayStart: Date
+    public let dayKey: String
+    public let totals: UsageLedgerTotals
+    public let modelsUsed: [String]
+
+    public init(
+        provider: UsageProvider,
+        projectID: String?,
+        dayStart: Date,
+        dayKey: String,
+        totals: UsageLedgerTotals,
+        modelsUsed: [String])
+    {
+        self.provider = provider
+        self.projectID = projectID
+        self.dayStart = dayStart
+        self.dayKey = dayKey
+        self.totals = totals
+        self.modelsUsed = modelsUsed
+    }
+}
+
+public struct UsageLedgerSessionSummary: Sendable, Codable, Hashable {
+    public let provider: UsageProvider
+    public let sessionID: String
+    public let projectID: String?
+    public let firstActivity: Date
+    public let lastActivity: Date
+    public let totals: UsageLedgerTotals
+    public let modelsUsed: [String]
+    public let versions: [String]
+
+    public init(
+        provider: UsageProvider,
+        sessionID: String,
+        projectID: String?,
+        firstActivity: Date,
+        lastActivity: Date,
+        totals: UsageLedgerTotals,
+        modelsUsed: [String],
+        versions: [String])
+    {
+        self.provider = provider
+        self.sessionID = sessionID
+        self.projectID = projectID
+        self.firstActivity = firstActivity
+        self.lastActivity = lastActivity
+        self.totals = totals
+        self.modelsUsed = modelsUsed
+        self.versions = versions
+    }
+}
+
+public struct UsageLedgerBlockSummary: Sendable, Codable, Hashable {
+    public let provider: UsageProvider
+    public let sessionID: String?
+    public let projectID: String?
+    public let start: Date
+    public let end: Date
+    public let isActive: Bool
+    public let entryCount: Int
+    public let totals: UsageLedgerTotals
+    public let tokensPerMinute: Double?
+    public let projectedTotalTokens: Int?
+
+    public init(
+        provider: UsageProvider,
+        sessionID: String?,
+        projectID: String?,
+        start: Date,
+        end: Date,
+        isActive: Bool,
+        entryCount: Int,
+        totals: UsageLedgerTotals,
+        tokensPerMinute: Double?,
+        projectedTotalTokens: Int?)
+    {
+        self.provider = provider
+        self.sessionID = sessionID
+        self.projectID = projectID
+        self.start = start
+        self.end = end
+        self.isActive = isActive
+        self.entryCount = entryCount
+        self.totals = totals
+        self.tokensPerMinute = tokensPerMinute
+        self.projectedTotalTokens = projectedTotalTokens
+    }
+}
+
+public struct UsageLedgerModelSummary: Sendable, Codable, Hashable {
+    public let provider: UsageProvider
+    public let projectKey: String?
+    public let projectID: String?
+    public let projectName: String?
+    public let projectNameConfidence: UsageLedgerProjectNameConfidence?
+    public let projectNameSource: UsageLedgerProjectNameSource?
+    public let projectNameProvenance: String?
+    public let model: String
+    public let entryCount: Int
+    public let totals: UsageLedgerTotals
+
+    public init(
+        provider: UsageProvider,
+        projectKey: String? = nil,
+        projectID: String?,
+        projectName: String? = nil,
+        projectNameConfidence: UsageLedgerProjectNameConfidence? = nil,
+        projectNameSource: UsageLedgerProjectNameSource? = nil,
+        projectNameProvenance: String? = nil,
+        model: String,
+        entryCount: Int,
+        totals: UsageLedgerTotals)
+    {
+        self.provider = provider
+        self.projectKey = projectKey
+        self.projectID = projectID
+        self.projectName = projectName
+        self.projectNameConfidence = projectNameConfidence
+        self.projectNameSource = projectNameSource
+        self.projectNameProvenance = projectNameProvenance
+        self.model = model
+        self.entryCount = entryCount
+        self.totals = totals
+    }
+
+    public var displayProjectName: String {
+        let trimmedName = self.projectName?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let trimmedName, !trimmedName.isEmpty {
+            return trimmedName
+        }
+        if let fallback = UsageLedgerProjectIdentityResolver.fallbackDisplayName(projectID: self.projectID) {
+            return fallback
+        }
+        return "Unknown project"
+    }
+}
+
+public struct UsageLedgerProjectSummary: Sendable, Codable, Hashable {
+    public let provider: UsageProvider
+    public let projectKey: String?
+    public let projectID: String?
+    public let projectName: String?
+    public let projectNameConfidence: UsageLedgerProjectNameConfidence?
+    public let projectNameSource: UsageLedgerProjectNameSource?
+    public let projectNameProvenance: String?
+    public let entryCount: Int
+    public let totals: UsageLedgerTotals
+    public let modelsUsed: [String]
+
+    public init(
+        provider: UsageProvider,
+        projectKey: String? = nil,
+        projectID: String?,
+        projectName: String? = nil,
+        projectNameConfidence: UsageLedgerProjectNameConfidence? = nil,
+        projectNameSource: UsageLedgerProjectNameSource? = nil,
+        projectNameProvenance: String? = nil,
+        entryCount: Int,
+        totals: UsageLedgerTotals,
+        modelsUsed: [String])
+    {
+        self.provider = provider
+        self.projectKey = projectKey
+        self.projectID = projectID
+        self.projectName = projectName
+        self.projectNameConfidence = projectNameConfidence
+        self.projectNameSource = projectNameSource
+        self.projectNameProvenance = projectNameProvenance
+        self.entryCount = entryCount
+        self.totals = totals
+        self.modelsUsed = modelsUsed
+    }
+
+    public var displayProjectName: String {
+        let trimmedName = self.projectName?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let trimmedName, !trimmedName.isEmpty {
+            return trimmedName
+        }
+        if let fallback = UsageLedgerProjectIdentityResolver.fallbackDisplayName(projectID: self.projectID) {
+            return fallback
+        }
+        return "Unknown project"
+    }
+}
+
+public struct UsageLedgerSpendForecast: Sendable, Codable, Hashable {
+    public let provider: UsageProvider
+    public let projectKey: String?
+    public let projectID: String?
+    public let projectName: String?
+    public let observedDays: Int
+    public let observedCostUSD: Double
+    public let averageDailyCostUSD: Double
+    public let projected30DayCostUSD: Double
+    public let projectedCostP50USD: Double?
+    public let projectedCostP80USD: Double?
+    public let projectedCostP95USD: Double?
+    public let projectionDays: Int
+    public let budgetLimitUSD: Double?
+    public let budgetETAInDays: Double?
+    public let budgetWillBreach: Bool
+
+    public init(
+        provider: UsageProvider,
+        projectKey: String? = nil,
+        projectID: String? = nil,
+        projectName: String? = nil,
+        observedDays: Int,
+        observedCostUSD: Double,
+        averageDailyCostUSD: Double,
+        projected30DayCostUSD: Double,
+        projectedCostP50USD: Double? = nil,
+        projectedCostP80USD: Double? = nil,
+        projectedCostP95USD: Double? = nil,
+        projectionDays: Int = 30,
+        budgetLimitUSD: Double? = nil,
+        budgetETAInDays: Double? = nil,
+        budgetWillBreach: Bool = false)
+    {
+        self.provider = provider
+        self.projectKey = projectKey
+        self.projectID = projectID
+        self.projectName = projectName
+        self.observedDays = observedDays
+        self.observedCostUSD = observedCostUSD
+        self.averageDailyCostUSD = averageDailyCostUSD
+        self.projected30DayCostUSD = projected30DayCostUSD
+        self.projectedCostP50USD = projectedCostP50USD
+        self.projectedCostP80USD = projectedCostP80USD
+        self.projectedCostP95USD = projectedCostP95USD
+        self.projectionDays = projectionDays
+        self.budgetLimitUSD = budgetLimitUSD
+        self.budgetETAInDays = budgetETAInDays
+        self.budgetWillBreach = budgetWillBreach
+    }
+
+    public var projectedAdditionalCostUSD: Double {
+        max(0, self.projected30DayCostUSD - self.observedCostUSD)
+    }
+
+    public func applyingBudget(monthlyLimitUSD: Double?) -> UsageLedgerSpendForecast {
+        guard let monthlyLimitUSD, monthlyLimitUSD > 0 else {
+            return UsageLedgerSpendForecast(
+                provider: self.provider,
+                projectKey: self.projectKey,
+                projectID: self.projectID,
+                projectName: self.projectName,
+                observedDays: self.observedDays,
+                observedCostUSD: self.observedCostUSD,
+                averageDailyCostUSD: self.averageDailyCostUSD,
+                projected30DayCostUSD: self.projected30DayCostUSD,
+                projectedCostP50USD: self.projectedCostP50USD,
+                projectedCostP80USD: self.projectedCostP80USD,
+                projectedCostP95USD: self.projectedCostP95USD,
+                projectionDays: self.projectionDays,
+                budgetLimitUSD: nil,
+                budgetETAInDays: nil,
+                budgetWillBreach: false)
+        }
+
+        let willBreach = self.projected30DayCostUSD > monthlyLimitUSD
+        let etaDays: Double? = {
+            guard willBreach, self.averageDailyCostUSD > 0 else { return nil }
+            if self.observedCostUSD >= monthlyLimitUSD { return 0 }
+            let remainingBudget = monthlyLimitUSD - self.observedCostUSD
+            let value = remainingBudget / self.averageDailyCostUSD
+            guard value.isFinite else { return nil }
+            return max(0, value)
+        }()
+
+        return UsageLedgerSpendForecast(
+            provider: self.provider,
+            projectKey: self.projectKey,
+            projectID: self.projectID,
+            projectName: self.projectName,
+            observedDays: self.observedDays,
+            observedCostUSD: self.observedCostUSD,
+            averageDailyCostUSD: self.averageDailyCostUSD,
+            projected30DayCostUSD: self.projected30DayCostUSD,
+            projectedCostP50USD: self.projectedCostP50USD,
+            projectedCostP80USD: self.projectedCostP80USD,
+            projectedCostP95USD: self.projectedCostP95USD,
+            projectionDays: self.projectionDays,
+            budgetLimitUSD: monthlyLimitUSD,
+            budgetETAInDays: etaDays,
+            budgetWillBreach: willBreach)
+    }
+}