🧭 Reader Intelligence & Productivity

📊 Overview & Architecture

These 12 engines form the Reader Intelligence tier of FeedReader's autonomous system. While the Feed Intelligence layer focuses on feed-level hygiene (diversity auditing, anomaly detection, credibility), Reader Intelligence operates at the reader level — understanding how you read, what you're missing, and how to optimize your information diet.

Total: 9,089 lines of autonomous reader intelligence code.

🎯 Attention Allocator

FeedAttentionAllocator — 658 lines

Tracks how your reading attention is distributed across topics and sources, detects "attention sinks" (patterns that waste your time), manages per-topic budgets, and proactively reallocates attention to maximize information diversity and value.

Attention Sink Types

Severity Levels

Each detected sink is classified by severity: .mild, .moderate, .significant, or .severe — enabling graduated response from gentle nudges to urgent reallocation suggestions.

Usage

let allocator = FeedAttentionAllocator()

let report = allocator.analyze(
    records: attentionRecords,
    customBudgets: myBudgets     // optional per-topic budgets
)

print(report?.diversityScore)      // 0-100 Shannon entropy-based
print(report?.attentionEfficiency) // 0-100 engagement-weighted
print(report?.sinks)               // detected attention traps
print(report?.reallocations)       // suggested attention shifts
print(report?.overallVerdict)      // human-readable summary

Key Outputs

• Diversity Score (0-100): Shannon entropy-based measurement of attention spread across topics
• Attention Efficiency (0-100): How well your reading time correlates with engagement
• Sink Detection: Automatic identification of wasteful reading patterns
• Reallocation Suggestions: Concrete recommendations to shift attention from over-served to neglected areas

🔍 Blind Spot Detector

FeedBlindSpotDetector — 747 lines

Identifies systematic gaps in your reading habits — topics and domains adjacent to your interests but consistently missing from your feeds. Uses keyword co-occurrence analysis, Shannon entropy per topic, and temporal pattern detection.

Blind Spot Categories

Usage

let detector = FeedBlindSpotDetector()

detector.ingest(BlindSpotArticle(
    id: "1", title: "Intro to ML",
    topics: ["machine learning", "neural networks"],
    feedURL: "https://blog.example.com/feed",
    feedName: "Tech Blog",
    readDate: Date(),
    sourcePerspective: "tech"))

let report = detector.analyze()
print(report.healthScore)       // 0-100 portfolio health
print(report.blindSpots)        // detected gaps with severity
print(report.insights)          // autonomous observations

Scoring

Each blind spot receives a composite severity score (0-100) weighted by category base severity: echo chambers score highest (0.9), followed by emerging misses (0.8), adjacent gaps (0.7), depth imbalances (0.6), and temporal decay (0.5). The overall portfolio health score translates to letter grades (A through F).

🧭 Editorial Drift Compass

FeedEditorialDriftCompass — 841 lines

Monitors feed sources for silent topic shifts. Detects when a feed's content diverges from its established editorial identity — for example, a tech blog starting to cover politics, or a science feed drifting toward opinion pieces.

Drift Type Classification

Usage

let compass = FeedEditorialDriftCompass()

compass.ingestArticle(
    feedURL: "https://techblog.com/feed",
    title: "New iPhone Review",
    topics: ["technology", "mobile", "apple"])

let report = compass.analyzeDrift(feedURL: "https://techblog.com/feed")
print(report.driftScore)         // 0-100 how much it has drifted
print(report.driftType)          // .topicInvasion, .identityErosion, etc.
print(report.invadingTopics)     // topics not part of original identity
print(report.erodingTopics)      // original topics that are fading
print(report.prediction)         // projected identity in 30 days

Key Capabilities

• Editorial Identity Profiling: Builds baseline topic distribution from historical articles
• Sliding Window Analysis: Compares recent topic proportions against the baseline
• Drift Velocity & Acceleration: Measures rate and acceleration of editorial change
• Predictive Forecasting: Projects future identity state if drift continues unchecked
• Subscriber Relevance Warnings: Alerts when drift affects topics you subscribed for

🔗 Cross-Reference Engine

FeedCrossReferenceEngine — 1,421 lines

The largest engine in FeedReader's intelligence suite. Extracts factual claims from articles (numbers, dates, percentages, named entities, statistics, attributions, causal statements) and cross-references them across sources to find corroborations, contradictions, and uncorroborated assertions.

Claim Types

Corroboration Levels

Autonomous Notifications

The engine posts NSNotification alerts in real time:

• .crossRefContradictionDetected — conflicting claims found across sources
• .crossRefConsensusFormed — multiple sources now agree on a claim
• .crossRefLowConfidenceClaim — claim has poor corroboration

Key Capabilities

• Claim Extraction: Regex-based identification of factual assertions from article text
• Topic-Similarity Matching: Finds related claims via keyword overlap and entity co-occurrence
• Confidence Scoring: Composite reliability based on source count, agreement, and diversity
• Full Provenance Tracking: Audit trail of which articles support or contradict each claim
• Fleet Health Score: Overall information reliability score (0-100) across all ingested sources

📖 Narrative Arc Tracker

FeedNarrativeArcTracker — 742 lines

Detects developing storylines across articles over time. Identifies when stories are emerging, building momentum, reaching climax, or resolving — and alerts users when stories they follow reach key turning points.

Narrative Phases

Turning Point Types

The tracker detects 8 types of turning points: .emergence, .accelerating, .peakReached, .sentimentShift, .newActor, .convergence, .reversal, and .resolution.

Autonomous Notifications

• .narrativeTurningPointDetected — story hit an inflection point
• .narrativePhaseChanged — story transitioned to a new phase
• .narrativeNewStoryEmerged — entirely new storyline detected

Key Capabilities

• Story Clustering: Groups related articles into coherent narrative threads
• Momentum Tracking: Measures publication velocity and sentiment shifts over time
• Story Following: Users mark narratives to follow; engine watches for updates
• Narrative Forecasting: Predicts likely next phase and estimated time-to-resolution
• Cross-Story Linking: Detects when separate narratives converge into one
• Health Score: Composite narrative awareness score (0-100)

🔮 Predictive Interest Engine

FeedPredictiveInterestEngine — 850 lines

Forecasts your future reading interests before you explicitly search for them. Analyzes interest trajectory vectors, detects emerging curiosity signals, and proactively surfaces articles aligned with predicted interests.

Interaction Types & Signal Weights

Interest Lifecycle Phases

Each tracked interest moves through phases: .latent → .emerging → .growing → .peak → .stable → .waning → .dormant. The engine measures velocity (first derivative) and acceleration (second derivative) of interest trajectories to detect emerging curiosity before it becomes conscious.

Usage

let engine = FeedPredictiveInterestEngine()

engine.recordInteraction(
    topic: "machine learning",
    feedURL: "https://blog.ai/feed",
    articleId: "a1",
    interactionType: .read,
    dwellSeconds: 180,
    timestamp: Date())

let forecast = engine.forecast()
print(forecast.predictions)       // predicted future interests
print(forecast.surfacedArticles)  // proactively recommended articles
print(forecast.healthScore)       // 0-100 prediction quality
print(forecast.insights)          // autonomous observations

Key Capabilities

• Trajectory Vectors: Interest velocity and acceleration tracking per topic
• Curiosity Signal Detection: Identifies repeated tangential exposure and dwell patterns
• Adjacent Interest Prediction: Co-occurrence analysis discovers related emerging interests
• Proactive Article Surfacing: Recommends articles matching predicted (not yet expressed) interests
• Self-Calibrating: Tracks prediction accuracy and adapts the model over time

📚 Contextual Primer

FeedContextualPrimer — 521 lines

Prepares you before diving into an article by analyzing it against your reading history. Produces a contextual primer with background refreshers, concept familiarity mapping, knowledge readiness scoring, and optimal reading order suggestions.

Familiarity Levels

Usage

let primer = FeedContextualPrimer()

// Register reading history
primer.recordReading(story: someStory)

// Get a primer for a new article
let brief = primer.preparePrimer(for: targetStory)
print(brief.readinessScore)         // 0-100 knowledge readiness
print(brief.backgroundRefreshers)   // related past articles
print(brief.blindSpots)             // concepts you haven't seen
print(brief.familiarityMap)         // term → familiarity level

// Optimal reading order for queued articles
let order = primer.suggestReadingOrder(for: queuedStories)

Key Capabilities

• Background Refresher: Surfaces related articles you've previously read, ranked by relevance
• Concept Familiarity Map: Scores every term in the article by your historical exposure
• Knowledge Readiness Score: 0-100 estimate of how prepared you are for the article
• Optimal Reading Order: For a queue of articles, suggests ordering that builds knowledge progressively (concept scaffolding)
• Blind Spot Identification: Flags important concepts in the article you've never encountered

📅 Content Calendar

FeedContentCalendar — 622 lines

Analyzes when feeds publish articles, detects regular schedules, predicts upcoming publications, and alerts when expected content is late or missing.

Schedule Patterns

Key Capabilities

• Day Profiles: Per-weekday statistics including total articles, averages, and peak publishing hours
• Schedule Detection: Automatically classifies each feed's publication rhythm
• Publication Forecasting: Predicts when the next article from a feed is expected
• Gap Alerts: Proactive notifications when expected content is late or a feed goes silent

📡 Sentiment Radar

FeedSentimentRadar — 620 lines

Lexicon-based sentiment tracking across RSS feeds. Analyzes article tone, detects mood shifts over time, and generates proactive alerts when sentiment changes significantly.

Sentiment Polarity Scale

Key Outputs

• Article Sentiment: Per-article compound score with polarity classification, top positive/negative words, and confidence level
• Feed Summaries: Aggregated sentiment statistics per feed source
• Mood Shift Alerts: SentimentAlert with severity (info/warning/critical), previous vs. current scores, and delta magnitude

✈️ Reading Autopilot

FeedReadingAutopilot — 818 lines

Curates optimal article sequences given a time budget. Considers priority scoring, reading time estimates, topic diversity, cognitive load balancing, and reading momentum to produce sessions that start accessible, build complexity, and wind down gracefully.

Cognitive Load Levels

Session Moods

Choose a session mood: .relaxed (prefer light content), .balanced (mix of everything), .focused (deep reads), or .exploratory (maximize topic diversity).

Usage

let autopilot = FeedReadingAutopilot()

let session = autopilot.planSession(
    articles: allArticles,
    timeBudgetMinutes: 20,
    preferences: .default)

print(session.playlist)          // ordered article list
print(session.totalMinutes)      // estimated total time
print(session.diversityScore)    // topic variety 0-100
print(session.cognitiveProfile)  // load curve description
print(session.sessionBrief)      // human-readable summary

💰 Subscription ROI

FeedSubscriptionROI — 784 lines

Measures the value each feed delivers relative to the attention it demands. Computes per-feed ROI scores based on engagement metrics (read rate, dwell time, save/share actions), content volume, and quality signals.

ROI Tiers

Anti-Pattern Detection

The engine detects 6 subscription anti-patterns: zombie feed (publishes but you never read), firehose (overwhelms with volume), guilt sub (read out of obligation, not interest), echo redundant (duplicate of another feed), stale premium (declining quality over time), and vanity sub (subscribed for image, not engagement).

Key Outputs

• Portfolio Health Score: 0-100 overall subscription health
• Per-Feed ROI Reports: Individual score, tier, trend, and engagement metrics
• Anti-Patterns: Detected problematic subscription behaviors
• Autonomous Recommendations: Prune, promote, or adjust suggestions
• Optimal Count Estimation: Recommended total number of subscriptions

📈 Trend Forecaster

FeedTrendForecaster — 465 lines

Detects emerging trends before they peak by analyzing keyword momentum across time windows, computing breakout probabilities, and generating proactive alerts for topics about to go viral.

Trend Phases

Trend Signal

Each detected trend produces a TrendSignal containing:

• Topic: The trending keyword
• Momentum: 0.0 (stagnant) to 1.0 (explosive growth)
• Breakout Probability: 0.0-1.0 likelihood of becoming viral
• Feed Sources: Which of your feeds mention this topic
• Phase: Current lifecycle position

Forecast Report

TrendForecast aggregates all signals with .topBreakouts (top 5 most likely to break out) and .proactiveInsights — autonomous recommendations about what's worth watching.

📋 Intelligence Brief Generator

FeedIntelligenceBrief — 603 lines

Generates structured daily intelligence briefings by correlating articles across feeds. Detects narrative threads, assesses signal-to-noise ratios, identifies emerging signals, and produces actionable insights.

Intelligence Priority Levels

Brief Components

• Executive Summary: Concise overview of the most important developments
• Narrative Threads: Clustered articles forming coherent storylines, each with headline, keywords, priority, and article list
• Signal-to-Noise Assessment: Ratio of clustered (signal) to standalone (noise) articles
• Emerging Signals: New keywords not seen in the previous period
• Cross-Feed Correlations: Topics spanning multiple sources — higher corroboration
• Blind Spots: News categories with no coverage in your feeds
• Actionable Insights: Specific recommendations based on the analysis

Usage

let briefer = FeedIntelligenceBrief()

let brief = briefer.generateBrief(
    articles: stories,
    feedMap: feedMap,
    previousKeywords: lastPeriodKeywords)

print(brief?.executiveSummary)
print(brief?.narrativeThreads)
print(brief?.actionableInsights)

📰 Digest Composer

ArticleDigestComposer — 62 lines (core)

Newsletter-style digest generator that composes formatted Markdown digests from article collections. Groups articles by feed source, includes reading time estimates, and supports configurable digest periods.

Digest Periods

Usage

let entries = [
    DigestEntry(title: "Article One",
                feedName: "Tech Blog",
                url: "https://example.com/1",
                snippet: "An overview of...",
                readingMinutes: 5)
]

let markdown = composeDigestMarkdown(
    title: "Weekly Reading Digest",
    entries: entries,
    period: .weekly)