feat: add AI-powered "For You" feed personalization

Reranks the feed by free-text reader interests using Cloudflare Workers
AI, with graceful degradation to chronological order on any model or
ranking failure. Settings live in the existing Reader settings dialog
(disabled by default); personalization is opt-in per browser.

The backend ranks once per (interests, source filter, freshness) via the
Cache API and re-projects the cached order onto a freshly-fetched item
page each request, so pagination behaves exactly like /api/items
(true offset/limit, real has_next) without re-invoking the LLM per page.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: phatpham9

core/personalize/rank.ts

@@ -0,0 +1,120 @@
+// Pure helpers for the "For You" LLM ranking feature. No I/O — adapters
+// (e.g. platforms/cloudflare/src/llmRanker.ts) own the actual model call and
+// use these to build the prompt and interpret the response.
+
+import type { FeedItem } from "../domain.ts";
+
+export const MAX_INTERESTS_LENGTH = 300;
+const MAX_ITEM_TEXT_LENGTH = 160;
+
+export function buildRankingPrompt(
+  items: FeedItem[],
+  interests: string,
+): string {
+  const lines = items.map((item, i) => {
+    const title = item.title.trim().slice(0, MAX_ITEM_TEXT_LENGTH);
+    const summary = (item.summary ?? "").trim().slice(0, MAX_ITEM_TEXT_LENGTH);
+    return `${i}: ${title}${summary ? ` — ${summary}` : ""}`;
+  });
+  return [
+    "You are ranking a list of feed items by relevance to a reader's stated interests.",
+    `Reader interests: ${interests.trim().slice(0, MAX_INTERESTS_LENGTH)}`,
+    "Items (index: title — summary):",
+    ...lines,
+    "",
+    "Respond with ONLY a JSON array of the item indices above, ordered from most to least relevant to the interests. Include every index exactly once. No other text, no markdown.",
+  ].join("\n");
+}
+
+/**
+ * Defensively extracts a ranked index list from a raw model response.
+ * Never throws — a malformed or empty response yields []. Indices outside
+ * [0, itemCount) or repeated are dropped (first occurrence wins).
+ */
+export function parseRankedIndices(raw: string, itemCount: number): number[] {
+  const match = /\[[\s\S]*\]/.exec(raw);
+  if (!match) return [];
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(match[0]);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+
+  const seen = new Set<number>();
+  const out: number[] = [];
+  for (const value of parsed) {
+    const index = typeof value === "number" ? value : Number(value);
+    if (
+      !Number.isInteger(index) ||
+      index < 0 ||
+      index >= itemCount ||
+      seen.has(index)
+    ) {
+      continue;
+    }
+    seen.add(index);
+    out.push(index);
+  }
+  return out;
+}
+
+/**
+ * Places ranked items first (in model order), then appends any remaining
+ * items in their original order — guarantees a full, valid list even when
+ * the ranker returns a partial or empty result.
+ */
+export function mergeRankedOrder(
+  items: FeedItem[],
+  rankedIndices: number[],
+): FeedItem[] {
+  const used = new Set<number>();
+  const out: FeedItem[] = [];
+  for (const index of rankedIndices) {
+    const item = items[index];
+    if (!item || used.has(index)) continue;
+    used.add(index);
+    out.push(item);
+  }
+  for (let i = 0; i < items.length; i++) {
+    if (!used.has(i)) out.push(items[i]!);
+  }
+  return out;
+}
+
+/** Stable identifier for a FeedItem — the domain type has no numeric id,
+ * so (source, externalId) is the natural key for referencing an item
+ * across requests (e.g. in a cached ranking). */
+export function itemKey(item: FeedItem): string {
+  return `${item.source} ${item.externalId}`;
+}
+
+/**
+ * Projects a previously-computed ranked key order (from a cached ranking,
+ * possibly over a different/smaller pool) onto a freshly-fetched item
+ * list: ranked items appear first, in cached order; anything not in
+ * rankedKeys — new items, or items the cache doesn't cover — keeps its
+ * original relative order at the end. Unlike mergeRankedOrder, this
+ * tolerates the two lists having different lengths or contents, since
+ * `items` is re-fetched live while rankedKeys may be stale or partial.
+ */
+export function mergeRankedKeysOrder(
+  items: FeedItem[],
+  rankedKeys: string[],
+): FeedItem[] {
+  const byKey = new Map(items.map((item) => [itemKey(item), item]));
+  const used = new Set<string>();
+  const out: FeedItem[] = [];
+  for (const key of rankedKeys) {
+    const item = byKey.get(key);
+    if (!item || used.has(key)) continue;
+    used.add(key);
+    out.push(item);
+  }
+  for (const item of items) {
+    if (!used.has(itemKey(item))) out.push(item);
+  }
+  return out;
+}

core/personalize/test/fakeLlmRanker.ts

@@ -0,0 +1,17 @@
+import type { FeedItem } from "../../domain.ts";
+import type { LlmRanker } from "../../ports.ts";
+
+/** In-memory LlmRanker for tests — no network calls. `script` decides the
+ * returned ranking (or throws, to simulate a transport/availability failure). */
+export class FakeLlmRanker implements LlmRanker {
+  constructor(
+    private readonly script: (
+      items: FeedItem[],
+      interests: string,
+    ) => number[],
+  ) {}
+
+  async rank(items: FeedItem[], interests: string): Promise<number[]> {
+    return this.script(items, interests);
+  }
+}

core/personalize/test/rank.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import type { FeedItem } from "../../domain.ts";
+import {
+  buildRankingPrompt,
+  itemKey,
+  mergeRankedKeysOrder,
+  mergeRankedOrder,
+  parseRankedIndices,
+} from "../rank.ts";
+import { FakeLlmRanker } from "./fakeLlmRanker.ts";
+
+function item(overrides: Partial<FeedItem>): FeedItem {
+  return {
+    source: "hackernews",
+    externalId: "1",
+    title: "title",
+    url: "https://example.com",
+    sourceRank: 1,
+    metadata: {},
+    ...overrides,
+  };
+}
+
+describe("buildRankingPrompt", () => {
+  it("numbers items by index and includes title, summary, and interests", () => {
+    const items = [
+      item({ title: "Rust async runtime", summary: "a new executor" }),
+      item({ title: "No summary item" }),
+    ];
+    const prompt = buildRankingPrompt(items, "rust, distributed systems");
+    expect(prompt).toContain("0: Rust async runtime — a new executor");
+    expect(prompt).toContain("1: No summary item");
+    expect(prompt).toContain("Reader interests: rust, distributed systems");
+  });
+
+  it("truncates oversized interests text", () => {
+    const prompt = buildRankingPrompt([], "x".repeat(1000));
+    const line = prompt.split("\n").find((l) => l.startsWith("Reader interests:"))!;
+    expect(line.length).toBeLessThan(320);
+  });
+});
+
+describe("parseRankedIndices", () => {
+  it("parses a well-formed JSON array", () => {
+    expect(parseRankedIndices("[2, 0, 1]", 3)).toEqual([2, 0, 1]);
+  });
+
+  it("tolerates surrounding prose/markdown around the array", () => {
+    expect(parseRankedIndices("Sure! ```json\n[1, 0]\n```", 2)).toEqual([
+      1, 0,
+    ]);
+  });
+
+  it("drops out-of-range and duplicate indices", () => {
+    expect(parseRankedIndices("[1, 1, 5, -1, 0]", 2)).toEqual([1, 0]);
+  });
+
+  it("returns [] for garbage output instead of throwing", () => {
+    expect(parseRankedIndices("not even close to json", 3)).toEqual([]);
+    expect(parseRankedIndices("", 3)).toEqual([]);
+  });
+});
+
+describe("mergeRankedOrder", () => {
+  const items = [item({ externalId: "a" }), item({ externalId: "b" }), item({ externalId: "c" })];
+
+  it("places ranked items first in model order, then appends the rest", () => {
+    const merged = mergeRankedOrder(items, [2, 0]);
+    expect(merged.map((i) => i.externalId)).toEqual(["c", "a", "b"]);
+  });
+
+  it("passes through original order when ranking is empty", () => {
+    expect(mergeRankedOrder(items, []).map((i) => i.externalId)).toEqual([
+      "a",
+      "b",
+      "c",
+    ]);
+  });
+
+  it("ignores indices it doesn't recognize without throwing", () => {
+    const merged = mergeRankedOrder(items, [99, 1]);
+    expect(merged.map((i) => i.externalId)).toEqual(["b", "a", "c"]);
+  });
+});
+
+describe("mergeRankedKeysOrder", () => {
+  const items = [
+    item({ source: "hackernews", externalId: "a" }),
+    item({ source: "github", externalId: "b" }),
+    item({ source: "hackernews", externalId: "c" }),
+  ];
+
+  it("places ranked items first by cached key order, then appends the rest", () => {
+    const merged = mergeRankedKeysOrder(items, [
+      itemKey(items[2]!),
+      itemKey(items[0]!),
+    ]);
+    expect(merged.map((i) => i.externalId)).toEqual(["c", "a", "b"]);
+  });
+
+  it("tolerates a cached key for an item that no longer exists", () => {
+    const merged = mergeRankedKeysOrder(items, [
+      "hackernews missing-id",
+      itemKey(items[1]!),
+    ]);
+    expect(merged.map((i) => i.externalId)).toEqual(["b", "a", "c"]);
+  });
+
+  it("tolerates duplicate cached keys", () => {
+    const key = itemKey(items[1]!);
+    const merged = mergeRankedKeysOrder(items, [key, key]);
+    expect(merged.map((i) => i.externalId)).toEqual(["b", "a", "c"]);
+  });
+
+  it("passes through original order when there is no cached ranking", () => {
+    expect(mergeRankedKeysOrder(items, []).map((i) => i.externalId)).toEqual([
+      "a",
+      "b",
+      "c",
+    ]);
+  });
+});
+
+describe("FakeLlmRanker + degrade pattern", () => {
+  const items = [item({ externalId: "a" }), item({ externalId: "b" })];
+
+  it("a successful rank reorders items", async () => {
+    const ranker = new FakeLlmRanker(() => [1, 0]);
+    const ranked = await ranker.rank(items, "anything");
+    expect(mergeRankedOrder(items, ranked).map((i) => i.externalId)).toEqual([
+      "b",
+      "a",
+    ]);
+  });
+
+  it("a thrown error is the caller's signal to degrade to chronological order", async () => {
+    const ranker = new FakeLlmRanker(() => {
+      throw new Error("model unavailable");
+    });
+    await expect(ranker.rank(items, "anything")).rejects.toThrow(
+      "model unavailable",
+    );
+  });
+});

core/ports.ts

@@ -29,3 +29,17 @@ export interface FeedRepository {
   ): Promise<FeedItem[]>;
   countTotalItems(): Promise<number>;
 }
+
+/**
+ * Ranks `items` by relevance to a free-text `interests` description.
+ * Returns a best-effort ordering of 0-based indices into `items`, most
+ * relevant first — FeedItem has no stable numeric id, so position in the
+ * input array is the only identifier the ranker needs. The result may be a
+ * subset (the caller appends any indices the ranker omitted, in their
+ * original order) and may be empty if ranking failed entirely; it must
+ * never throw for a malformed model response, only for genuine
+ * transport/availability failures.
+ */
+export interface LlmRanker {
+  rank(items: FeedItem[], interests: string): Promise<number[]>;
+}

core/render.ts

@@ -298,6 +298,21 @@ export function renderIndexPage(data: PageData): string {
           </div>
         </section>
         </div>
+        <section class="config-section" aria-labelledby="config-personalization-title">
+          <div class="config-section-header">
+            <h3 id="config-personalization-title" class="config-section-title">AI personalization</h3>
+            <p class="config-section-copy">Rerank your feed by your interests using AI. Stored only in this browser.</p>
+          </div>
+          <div class="config-options">
+            <label class="config-option">
+              <input type="checkbox" data-ai-personalization-toggle />
+              <span class="config-option-body">
+                <span class="config-option-title">Enable personalized ranking</span>
+              </span>
+            </label>
+          </div>
+          <textarea class="interests-input" data-interests-input rows="3" maxlength="300" placeholder="fullstack development, software engineering, computer science, AI, machine learning, LLMs"></textarea>
+        </section>
         <section class="config-section" aria-labelledby="config-sources-title">
           <div class="config-section-header">
             <h3 id="config-sources-title" class="config-section-title">Sources</h3>
@@ -389,6 +404,7 @@ export function renderIndexPage(data: PageData): string {
     </dialog>
 ${errorsBlock}
     <main class="shell page-body">
+      <p class="personalized-indicator is-hidden" data-personalized-indicator>✦ Personalized by AI</p>
       <section class="cards-grid${cardsHiddenClass}" data-card-grid data-current-source="${escapeHtml(data.currentSource)}" data-page-size="${data.pageSize}" data-has-next="${data.hasNext ? "true" : "false"}" aria-busy="false">
         ${data.cards.map(renderCard).join("\n        ")}
       </section>

platforms/cloudflare/src/env.d.ts

@@ -5,8 +5,12 @@ export interface Env {
    * refreshes as fresh invocations (fresh 10ms CPU budget each), instead of
    * a public-internet self-fetch that would need a known hostname. */
   SELF: Fetcher;
+  /** Workers AI binding backing the "For You" LlmRanker — see
+   * platforms/cloudflare/src/llmRanker.ts. No secret needed. */
+  AI: Ai;
   REFRESH_SECRET: string;
   APP_VERSION?: string;
   FEEDREADER_ITEMS_PER_SOURCE?: string;
   FEEDREADER_USER_AGENT?: string;
+  FEEDREADER_PERSONALIZE_POOL_SIZE?: string;
 }