initial commit

IrisCompanion/iris/Models/Candidate.swift

@@ -0,0 +1,61 @@
+//
+//  Candidate.swift
+//  iris
+//
+//  Created by Codex.
+//
+
+import Foundation
+import WeatherKit
+
+struct Candidate: Codable, Equatable {
+    let id: String
+    let type: WinnerType
+    let title: String
+    let subtitle: String
+    let confidence: Double
+    let createdAt: Int
+    let ttlSec: Int
+    let condition: WeatherKit.WeatherCondition?
+    let metadata: [String: String]?
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case type
+        case title
+        case subtitle
+        case confidence
+        case createdAt
+        case ttlSec
+        case condition
+        case metadata
+    }
+
+    init(id: String,
+         type: WinnerType,
+         title: String,
+         subtitle: String,
+         confidence: Double,
+         createdAt: Int,
+         ttlSec: Int,
+         condition: WeatherKit.WeatherCondition? = nil,
+         metadata: [String: String]? = nil) {
+        self.id = id
+        self.type = type
+        self.title = title
+        self.subtitle = subtitle
+        self.confidence = confidence
+        self.createdAt = createdAt
+        self.ttlSec = ttlSec
+        self.condition = condition
+        self.metadata = metadata
+    }
+
+    func isExpired(at now: Int) -> Bool {
+        if ttlSec > 0 {
+            createdAt + ttlSec <= now
+        } else {
+            true
+        }
+    }
+}

IrisCompanion/iris/Models/FeedEnvelope.swift

@@ -0,0 +1,193 @@
+//
+//  FeedEnvelope.swift
+//  iris
+//
+//  Created by Codex.
+//
+
+import Foundation
+import WeatherKit
+
+struct FeedEnvelope: Codable, Equatable {
+    let schema: Int
+    let generatedAt: Int
+    let feed: [FeedCard]
+    let meta: FeedMeta
+
+    enum CodingKeys: String, CodingKey {
+        case schema
+        case generatedAt = "generated_at"
+        case feed
+        case meta
+    }
+}
+
+struct FeedCard: Codable, Equatable {
+    enum Bucket: String, Codable {
+        case rightNow = "RIGHT_NOW"
+        case fyi = "FYI"
+    }
+
+    let id: String
+    let type: WinnerType
+    let title: String
+    let subtitle: String
+    let priority: Double
+    let ttlSec: Int
+    let condition: WeatherKit.WeatherCondition?
+    let bucket: Bucket
+    let actions: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case type
+        case title
+        case subtitle
+        case priority
+        case ttlSec = "ttl_sec"
+        case condition
+        case bucket
+        case actions
+    }
+
+    init(id: String,
+         type: WinnerType,
+         title: String,
+         subtitle: String,
+         priority: Double,
+         ttlSec: Int,
+         condition: WeatherKit.WeatherCondition? = nil,
+         bucket: Bucket,
+         actions: [String]) {
+        self.id = id
+        self.type = type
+        self.title = title
+        self.subtitle = subtitle
+        self.priority = priority
+        self.ttlSec = ttlSec
+        self.condition = condition
+        self.bucket = bucket
+        self.actions = actions
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        id = try container.decode(String.self, forKey: .id)
+        type = try container.decode(WinnerType.self, forKey: .type)
+        title = try container.decode(String.self, forKey: .title)
+        subtitle = try container.decode(String.self, forKey: .subtitle)
+        priority = try container.decode(Double.self, forKey: .priority)
+        ttlSec = try container.decode(Int.self, forKey: .ttlSec)
+        bucket = try container.decode(Bucket.self, forKey: .bucket)
+        actions = try container.decode([String].self, forKey: .actions)
+
+        if let encoded = try container.decodeIfPresent(String.self, forKey: .condition) {
+            condition = WeatherKit.WeatherCondition.irisDecode(encoded)
+        } else {
+            condition = nil
+        }
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(id, forKey: .id)
+        try container.encode(type, forKey: .type)
+        try container.encode(title, forKey: .title)
+        try container.encode(subtitle, forKey: .subtitle)
+        try container.encode(priority, forKey: .priority)
+        try container.encode(ttlSec, forKey: .ttlSec)
+        try container.encode(bucket, forKey: .bucket)
+        try container.encode(actions, forKey: .actions)
+        if let condition {
+            try container.encode(condition.irisScreamingCase(), forKey: .condition)
+        }
+    }
+}
+
+struct FeedMeta: Codable, Equatable {
+    let winnerId: String
+    let unreadCount: Int
+
+    enum CodingKeys: String, CodingKey {
+        case winnerId = "winner_id"
+        case unreadCount = "unread_count"
+    }
+}
+
+extension FeedEnvelope {
+    static func fromWinnerAndWeather(now: Int, winner: WinnerEnvelope, weather: Candidate?) -> FeedEnvelope {
+        var cards: [FeedCard] = []
+
+        let winnerCard = FeedCard(
+            id: winner.winner.id,
+            type: winner.winner.type,
+            title: winner.winner.title.truncated(maxLength: TextConstraints.titleMax),
+            subtitle: winner.winner.subtitle.truncated(maxLength: TextConstraints.subtitleMax),
+            priority: min(max(winner.winner.priority, 0.0), 1.0),
+            ttlSec: max(1, winner.winner.ttlSec),
+            condition: nil,
+            bucket: .rightNow,
+            actions: ["DISMISS"]
+        )
+        cards.append(winnerCard)
+
+        if let weather, weather.id != winner.winner.id {
+            let weatherCard = FeedCard(
+                id: weather.id,
+                type: weather.type,
+                title: weather.title.truncated(maxLength: TextConstraints.titleMax),
+                subtitle: weather.subtitle.truncated(maxLength: TextConstraints.subtitleMax),
+                priority: min(max(weather.confidence, 0.0), 1.0),
+                ttlSec: max(1, weather.ttlSec),
+                condition: weather.condition,
+                bucket: .fyi,
+                actions: ["DISMISS"]
+            )
+            cards.append(weatherCard)
+        }
+
+        return FeedEnvelope(
+            schema: 1,
+            generatedAt: now,
+            feed: cards,
+            meta: FeedMeta(winnerId: winner.winner.id, unreadCount: cards.count)
+        )
+    }
+}
+
+extension FeedEnvelope {
+    static func allQuiet(now: Int, reason: String = "no_candidates", source: String = "engine") -> FeedEnvelope {
+        let card = FeedCard(
+            id: "quiet-000",
+            type: .allQuiet,
+            title: "All Quiet",
+            subtitle: "No urgent updates",
+            priority: 0.05,
+            ttlSec: 300,
+            condition: nil,
+            bucket: .rightNow,
+            actions: ["DISMISS"]
+        )
+        return FeedEnvelope(schema: 1, generatedAt: now, feed: [card], meta: FeedMeta(winnerId: card.id, unreadCount: 1))
+    }
+
+    func winnerCard() -> FeedCard? {
+        feed.first(where: { $0.id == meta.winnerId }) ?? feed.first
+    }
+
+    func asWinnerEnvelope() -> WinnerEnvelope {
+        let now = generatedAt
+        guard let winnerCard = winnerCard() else {
+            return WinnerEnvelope.allQuiet(now: now)
+        }
+        let winner = Winner(
+            id: winnerCard.id,
+            type: winnerCard.type,
+            title: winnerCard.title.truncated(maxLength: TextConstraints.titleMax),
+            subtitle: winnerCard.subtitle.truncated(maxLength: TextConstraints.subtitleMax),
+            priority: min(max(winnerCard.priority, 0.0), 1.0),
+            ttlSec: max(1, winnerCard.ttlSec)
+        )
+        return WinnerEnvelope(schema: 1, generatedAt: now, winner: winner, debug: nil)
+    }
+}

IrisCompanion/iris/Models/FeedStore.swift

@@ -0,0 +1,192 @@
+//
+//  FeedStore.swift
+//  iris
+//
+//  Created by Codex.
+//
+
+import Foundation
+
+final class FeedStore {
+    struct CardKey: Hashable, Codable {
+        let id: String
+        let type: WinnerType
+    }
+
+    struct CardState: Codable, Equatable {
+        var lastShownAt: Int?
+        var dismissedUntil: Int?
+        var snoozedUntil: Int?
+    }
+
+    private struct Persisted: Codable {
+        var feed: FeedEnvelope?
+        var states: [String: CardState]
+    }
+
+    private let queue = DispatchQueue(label: "iris.feedstore.queue")
+    private let fileURL: URL
+    private var cachedFeed: FeedEnvelope?
+    private var states: [String: CardState] = [:]
+
+    init(filename: String = "feed_store_v1.json") {
+        self.fileURL = Self.defaultFileURL(filename: filename)
+        let persisted = Self.load(from: fileURL)
+        self.cachedFeed = persisted?.feed
+        self.states = persisted?.states ?? [:]
+    }
+
+    func getFeed(now: Int = Int(Date().timeIntervalSince1970)) -> FeedEnvelope {
+        queue.sync {
+            guard let feed = cachedFeed else {
+                return FeedEnvelope.allQuiet(now: now, reason: "no_feed", source: "store")
+            }
+            let filtered = normalizedFeed(feed, now: now)
+            if filtered.feed.isEmpty {
+                return FeedEnvelope.allQuiet(now: now, reason: "expired_or_suppressed", source: "store")
+            }
+            return filtered
+        }
+    }
+
+    func setFeed(_ feed: FeedEnvelope, now: Int = Int(Date().timeIntervalSince1970)) {
+        queue.sync {
+            let normalized = normalizedFeed(feed, now: now, applyingSuppression: false)
+            cachedFeed = normalized
+            markShown(feed: normalized, now: now)
+            save()
+        }
+    }
+
+    func lastShownAt(candidateId: String) -> Int? {
+        queue.sync {
+            let matches = states.compactMap { (key, value) -> Int? in
+                guard key.hasSuffix("|" + candidateId) else { return nil }
+                return value.lastShownAt
+            }
+            return matches.max()
+        }
+    }
+
+    func isSuppressed(id: String, type: WinnerType, now: Int) -> Bool {
+        queue.sync {
+            let key = Self.keyString(id: id, type: type)
+            guard let state = states[key] else { return false }
+            if let until = state.dismissedUntil, until > now { return true }
+            if let until = state.snoozedUntil, until > now { return true }
+            return false
+        }
+    }
+
+    func dismiss(id: String, type: WinnerType, until: Int? = nil) {
+        queue.sync {
+            let key = Self.keyString(id: id, type: type)
+            var state = states[key] ?? CardState()
+            state.dismissedUntil = until ?? Int.max
+            states[key] = state
+            save()
+        }
+    }
+
+    func snooze(id: String, type: WinnerType, until: Int) {
+        queue.sync {
+            let key = Self.keyString(id: id, type: type)
+            var state = states[key] ?? CardState()
+            state.snoozedUntil = until
+            states[key] = state
+            save()
+        }
+    }
+
+    func clearSuppression(id: String, type: WinnerType) {
+        queue.sync {
+            let key = Self.keyString(id: id, type: type)
+            var state = states[key] ?? CardState()
+            state.dismissedUntil = nil
+            state.snoozedUntil = nil
+            states[key] = state
+            save()
+        }
+    }
+
+    private func markShown(feed: FeedEnvelope, now: Int) {
+        for card in feed.feed {
+            let key = Self.keyString(id: card.id, type: card.type)
+            var state = states[key] ?? CardState()
+            state.lastShownAt = now
+            states[key] = state
+        }
+    }
+
+    private func normalizedFeed(_ feed: FeedEnvelope, now: Int, applyingSuppression: Bool = true) -> FeedEnvelope {
+        let normalizedCards = feed.feed.compactMap { card -> FeedCard? in
+            let ttl = max(1, card.ttlSec)
+            if feed.generatedAt + ttl <= now { return nil }
+            if applyingSuppression, isSuppressedUnlocked(id: card.id, type: card.type, now: now) { return nil }
+            return FeedCard(
+                id: card.id,
+                type: card.type,
+                title: card.title.truncated(maxLength: TextConstraints.titleMax),
+                subtitle: card.subtitle.truncated(maxLength: TextConstraints.subtitleMax),
+                priority: min(max(card.priority, 0.0), 1.0),
+                ttlSec: ttl,
+                condition: card.condition,
+                bucket: card.bucket,
+                actions: card.actions
+            )
+        }
+
+        let winnerId = normalizedCards.first(where: { $0.id == feed.meta.winnerId })?.id ?? normalizedCards.first?.id ?? "quiet-000"
+        let normalized = FeedEnvelope(
+            schema: 1,
+            generatedAt: max(1, feed.generatedAt),
+            feed: normalizedCards,
+            meta: FeedMeta(winnerId: winnerId, unreadCount: normalizedCards.count)
+        )
+        return normalized
+    }
+
+    private func isSuppressedUnlocked(id: String, type: WinnerType, now: Int) -> Bool {
+        let key = Self.keyString(id: id, type: type)
+        guard let state = states[key] else { return false }
+        if let until = state.dismissedUntil, until > now { return true }
+        if let until = state.snoozedUntil, until > now { return true }
+        return false
+    }
+
+    private func save() {
+        let persisted = Persisted(feed: cachedFeed, states: states)
+        Self.save(persisted, to: fileURL)
+    }
+
+    private static func keyString(id: String, type: WinnerType) -> String {
+        "\(type.rawValue)|\(id)"
+    }
+
+    private static func defaultFileURL(filename: String) -> URL {
+        let fm = FileManager.default
+        let base = fm.urls(for: .applicationSupportDirectory, in: .userDomainMask).first ?? fm.temporaryDirectory
+        let bundle = Bundle.main.bundleIdentifier ?? "iris"
+        return base
+            .appendingPathComponent(bundle, isDirectory: true)
+            .appendingPathComponent(filename, isDirectory: false)
+    }
+
+    private static func load(from url: URL) -> Persisted? {
+        guard let data = try? Data(contentsOf: url) else { return nil }
+        return try? JSONDecoder().decode(Persisted.self, from: data)
+    }
+
+    private static func save(_ persisted: Persisted, to url: URL) {
+        do {
+            let fm = FileManager.default
+            try fm.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.withoutEscapingSlashes]
+            let data = try encoder.encode(persisted)
+            try data.write(to: url, options: [.atomic])
+        } catch {
+            // Best-effort persistence.
+        }
+    }
+}

IrisCompanion/iris/Models/HeuristicRanker.swift

@@ -0,0 +1,81 @@
+//
+//  HeuristicRanker.swift
+//  iris
+//
+//  Created by Codex.
+//
+
+import Foundation
+
+struct UserContext: Equatable {
+    var isMoving: Bool
+    var city: String
+
+    init(isMoving: Bool, city: String = "London") {
+        self.isMoving = isMoving
+        self.city = city
+    }
+}
+
+final class HeuristicRanker {
+    private let nowProvider: () -> Int
+    private let lastShownAtProvider: (String) -> Int?
+
+    init(now: @escaping () -> Int = { Int(Date().timeIntervalSince1970) },
+         lastShownAt: @escaping (String) -> Int? = { _ in nil }) {
+        self.nowProvider = now
+        self.lastShownAtProvider = lastShownAt
+    }
+
+    func pickWinner(from candidates: [Candidate], now: Int? = nil, context: UserContext) -> Winner {
+        let currentTime = now ?? nowProvider()
+
+        let valid = candidates
+            .filter { !$0.isExpired(at: currentTime) }
+            .filter { $0.confidence >= 0.0 }
+
+        guard !valid.isEmpty else {
+            return WinnerEnvelope.allQuiet(now: currentTime).winner
+        }
+
+        var best: (candidate: Candidate, score: Double)?
+        for candidate in valid {
+            let baseWeight = baseWeight(for: candidate.type)
+            var score = baseWeight * min(max(candidate.confidence, 0.0), 1.0)
+            if let shownAt = lastShownAtProvider(candidate.id),
+               currentTime - shownAt <= 2 * 60 * 60 {
+                score -= 0.4
+            }
+            if best == nil || score > best!.score {
+                best = (candidate, score)
+            }
+        }
+
+        guard let best else {
+            return WinnerEnvelope.allQuiet(now: currentTime).winner
+        }
+
+        let priority = min(max(best.score, 0.0), 1.0)
+        return Winner(
+            id: best.candidate.id,
+            type: best.candidate.type,
+            title: best.candidate.title.truncated(maxLength: TextConstraints.titleMax),
+            subtitle: best.candidate.subtitle.truncated(maxLength: TextConstraints.subtitleMax),
+            priority: priority,
+            ttlSec: max(1, best.candidate.ttlSec)
+        )
+    }
+
+    private func baseWeight(for type: WinnerType) -> Double {
+        switch type {
+        case .weatherWarning: return 1.0
+        case .weatherAlert: return 0.9
+        case .transit: return 0.75
+        case .poiNearby: return 0.6
+        case .info: return 0.4
+        case .nowPlaying: return 0.25
+        case .currentWeather: return 0.0
+        case .allQuiet: return 0.0
+        }
+    }
+}

IrisCompanion/iris/Models/WeatherKitConditionCoding.swift

@@ -0,0 +1,50 @@
+//
+//  WeatherKitConditionCoding.swift
+//  iris
+//
+//  Created by Codex.
+//
+
+import Foundation
+import WeatherKit
+
+extension WeatherKit.WeatherCondition {
+    func irisScreamingCase() -> String {
+        Self.upperSnake(from: rawValue)
+    }
+
+    static func irisDecode(_ value: String) -> WeatherKit.WeatherCondition? {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if trimmed.uppercased() == "UNKNOWN" { return nil }
+
+        if let direct = WeatherKit.WeatherCondition(rawValue: trimmed) { return direct }
+
+        let lowerCamel = lowerCamel(fromScreamingOrSnake: trimmed)
+        if let mapped = WeatherKit.WeatherCondition(rawValue: lowerCamel) { return mapped }
+
+        return nil
+    }
+
+    private static func upperSnake(from value: String) -> String {
+        var out = ""
+        out.reserveCapacity(value.count + 8)
+        for scalar in value.unicodeScalars {
+            if CharacterSet.uppercaseLetters.contains(scalar), !out.isEmpty {
+                out.append("_")
+            }
+            out.append(String(scalar).uppercased())
+        }
+        return out
+    }
+
+    private static func lowerCamel(fromScreamingOrSnake value: String) -> String {
+        let parts = value
+            .split(separator: "_")
+            .map { $0.lowercased() }
+        guard let first = parts.first else { return value }
+        let rest = parts.dropFirst().map { $0.prefix(1).uppercased() + $0.dropFirst() }
+        return ([String(first)] + rest).joined()
+    }
+}
+

IrisCompanion/iris/Models/Winner.swift

@@ -0,0 +1,37 @@
+//
+//  Winner.swift
+//  iris
+//
+//  Created by Codex.
+//
+
+import Foundation
+
+enum WinnerType: String, Codable, CaseIterable {
+    case weatherAlert = "WEATHER_ALERT"
+    case weatherWarning = "WEATHER_WARNING"
+    case transit = "TRANSIT"
+    case poiNearby = "POI_NEARBY"
+    case info = "INFO"
+    case nowPlaying = "NOW_PLAYING"
+    case currentWeather = "CURRENT_WEATHER"
+    case allQuiet = "ALL_QUIET"
+}
+
+struct Winner: Codable, Equatable {
+    let id: String
+    let type: WinnerType
+    let title: String
+    let subtitle: String
+    let priority: Double
+    let ttlSec: Int
+
+    enum CodingKeys: String, CodingKey {
+        case id
+        case type
+        case title
+        case subtitle
+        case priority
+        case ttlSec = "ttl_sec"
+    }
+}

IrisCompanion/iris/Models/WinnerEnvelope.swift

@@ -0,0 +1,100 @@
+//
+//  WinnerEnvelope.swift
+//  iris
+//
+//  Created by Codex.
+//
+
+import Foundation
+
+struct WinnerEnvelope: Codable, Equatable {
+    struct DebugInfo: Codable, Equatable {
+        let reason: String
+        let source: String
+    }
+
+    let schema: Int
+    let generatedAt: Int
+    let winner: Winner
+    let debug: DebugInfo?
+
+    enum CodingKeys: String, CodingKey {
+        case schema
+        case generatedAt = "generated_at"
+        case winner
+        case debug
+    }
+
+    static func allQuiet(now: Int, reason: String = "no_candidates", source: String = "engine") -> WinnerEnvelope {
+        let winner = Winner(
+            id: "quiet-000",
+            type: .allQuiet,
+            title: "All Quiet",
+            subtitle: "No urgent updates",
+            priority: 0.05,
+            ttlSec: 300
+        )
+        return WinnerEnvelope(schema: 1, generatedAt: now, winner: winner, debug: .init(reason: reason, source: source))
+    }
+}
+
+enum EnvelopeValidationError: Error, LocalizedError {
+    case invalidSchema(Int)
+    case invalidPriority(Double)
+    case invalidTTL(Int)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidSchema(let schema):
+            return "Invalid schema \(schema). Expected 1."
+        case .invalidPriority(let priority):
+            return "Invalid priority \(priority). Must be between 0 and 1."
+        case .invalidTTL(let ttl):
+            return "Invalid ttl \(ttl). Must be greater than 0."
+        }
+    }
+}
+
+func validateEnvelope(_ envelope: WinnerEnvelope) throws -> WinnerEnvelope {
+    guard envelope.schema == 1 else {
+        throw EnvelopeValidationError.invalidSchema(envelope.schema)
+    }
+    guard envelope.winner.priority >= 0.0, envelope.winner.priority <= 1.0 else {
+        throw EnvelopeValidationError.invalidPriority(envelope.winner.priority)
+    }
+    guard envelope.winner.ttlSec > 0 else {
+        throw EnvelopeValidationError.invalidTTL(envelope.winner.ttlSec)
+    }
+
+    let validatedWinner = Winner(
+        id: envelope.winner.id,
+        type: envelope.winner.type,
+        title: envelope.winner.title.truncated(maxLength: TextConstraints.titleMax),
+        subtitle: envelope.winner.subtitle.truncated(maxLength: TextConstraints.subtitleMax),
+        priority: envelope.winner.priority,
+        ttlSec: envelope.winner.ttlSec
+    )
+
+    return WinnerEnvelope(
+        schema: envelope.schema,
+        generatedAt: envelope.generatedAt,
+        winner: validatedWinner,
+        debug: envelope.debug
+    )
+}
+
+enum TextConstraints {
+    static let titleMax = 26
+    static let subtitleMax = 30
+    static let ellipsis = "..."
+}
+
+extension String {
+    func truncated(maxLength: Int) -> String {
+        guard count > maxLength else { return self }
+        let ellipsisCount = TextConstraints.ellipsis.count
+        guard maxLength > ellipsisCount else { return String(prefix(maxLength)) }
+        return String(prefix(maxLength - ellipsisCount)) + TextConstraints.ellipsis
+    }
+}
+