🧠 Smart Features

Article Recommendations

The ArticleRecommendationEngine analyzes your reading history to suggest unread articles you're likely to enjoy. It scores articles using two signals:

How Scoring Works

Each unread article receives a composite score (0.0–1.0):

feedScore = readCount(feed) / maxReadCount        // 0.0 – 1.0
keywordScore = matchingKeywords / totalKeywords     // 0.0 – 1.0
finalScore = (0.6 × feedScore) + (0.4 × keywordScore)

Articles are returned sorted by score, with a recommendation reason explaining why each was suggested:

• .preferredFeed — "You've read 42 articles from TechCrunch"
• .keywordMatch — "Matches your interests: Swift, iOS, Xcode"
• .frequentlyRevisited — Similar to articles you've re-read
• .combined — Multiple signals contributed

Usage

let engine = ArticleRecommendationEngine()
engine.readingHistory = ReadingHistoryManager.shared

// Get top 10 recommendations
let scored = engine.recommend(
    from: allUnreadStories,
    limit: 10,
    minScore: 0.1  // filter out low-confidence picks
)

for article in scored {
    print("\(article.story.title) — \(article.score)")
    print("  → \(article.reason)")
}

Smart Feeds

SmartFeedManager lets users create saved keyword-based searches that automatically filter stories across all enabled feeds—like creating a custom "virtual feed" from keywords you care about.

Capabilities

Creating a Smart Feed

let mgr = SmartFeedManager.shared

// Create a "Swift Development" smart feed
let feed = SmartFeed(
    name: "Swift Development",
    keywords: ["swift", "swiftui", "xcode", "ios"],
    matchMode: .any,
    searchScope: .titleAndBody
)

mgr.addSmartFeed(feed)  // persisted automatically

// Get matching stories
let matches = mgr.matchingStories(
    for: feed,
    from: allStories
)
print("Found \(matches.count) matching articles")

How Matching Works

Keyword matching is case-insensitive and uses localizedCaseInsensitiveContains for locale-aware comparison. With .any mode, a story matches if any keyword appears. With .all mode, every keyword must be present.

Digest Generator

The DigestGenerator creates formatted reading summaries—like a personal newsletter of what you've read. Supports multiple time windows and output formats.

Time Periods

Output Formats

Generating a Digest

let generator = DigestGenerator()
generator.readingHistory = ReadingHistoryManager.shared
generator.readingStats = ReadingStatsManager.shared

// Generate this week's digest as Markdown
let digest = generator.generate(
    period: .thisWeek,
    format: .markdown,
    includeStats: true  // append reading stats summary
)

print(digest.content)     // formatted string
print(digest.storyCount)  // number of articles included
print(digest.feedCount)   // number of feeds represented

Digest Structure

Each digest includes:

• Header — period name and date range
• Stories by Feed — grouped by source feed, with titles, publication dates, and links
• Reading Stats (optional) — total articles read, average per day, top feeds, most active days
• Footer — generation timestamp

Keyword Alerts

KeywordAlertManager monitors incoming stories for specific terms and marks matching articles for attention. Unlike Smart Feeds (which are browsing filters), alerts are notifications—they surface articles you might miss.

Alert vs Smart Feed

Usage

let mgr = KeywordAlertManager.shared

// Create alert for "security vulnerability"
let alert = KeywordAlert(keyword: "security vulnerability")
mgr.addAlert(alert)

// Check new stories against all alerts
let triggered = mgr.checkStories(newStories)
for match in triggered {
    print("⚠️ Alert '\(match.alert.keyword)' triggered by: \(match.story.title)")
}

Reading Statistics

ReadingStatsManager tracks aggregate reading metrics over time. All data computed from ReadingHistoryManager entries.

Available Metrics

The ReadingStatsViewController displays these metrics with simple charts. Stats are updated each time ReadingHistoryManager records a read event.