From bb92c9f22772d86726b26514b6a4b28c0232a666 Mon Sep 17 00:00:00 2001 From: kenneth Date: Thu, 5 Mar 2026 01:20:34 +0000 Subject: [PATCH] feat(backend): add LLM-powered feed enhancement Add enhancement harness that fills feed item slots and generates synthetic items via OpenRouter. - LLM client with 30s timeout, reusable SDK instance - Prompt builder with mini calendar and week overview - arktype schema validation + JSON Schema for structured output - Pure merge function with clock injection - Defensive fallback in feed endpoint on enhancement failure - Skips LLM call when no unfilled slots or no API key Co-authored-by: Ona --- apps/aris-backend/.env.example | 5 + apps/aris-backend/package.json | 3 + .../src/enhancement/enhance-feed.ts | 51 ++++ .../src/enhancement/llm-client.ts | 71 ++++++ .../src/enhancement/merge.test.ts | 150 ++++++++++++ apps/aris-backend/src/enhancement/merge.ts | 41 ++++ .../src/enhancement/prompt-builder.test.ts | 167 ++++++++++++++ .../src/enhancement/prompt-builder.ts | 218 ++++++++++++++++++ .../src/enhancement/prompts/system.txt | 21 ++ .../src/enhancement/schema.test.ts | 89 +++++++ apps/aris-backend/src/enhancement/schema.ts | 89 +++++++ apps/aris-backend/src/feed/http.test.ts | 61 +++++ apps/aris-backend/src/feed/http.ts | 24 +- apps/aris-backend/src/server.ts | 21 +- bun.lock | 5 + 15 files changed, 1012 insertions(+), 4 deletions(-) create mode 100644 apps/aris-backend/src/enhancement/enhance-feed.ts create mode 100644 apps/aris-backend/src/enhancement/llm-client.ts create mode 100644 apps/aris-backend/src/enhancement/merge.test.ts create mode 100644 apps/aris-backend/src/enhancement/merge.ts create mode 100644 apps/aris-backend/src/enhancement/prompt-builder.test.ts create mode 100644 apps/aris-backend/src/enhancement/prompt-builder.ts create mode 100644 apps/aris-backend/src/enhancement/prompts/system.txt create mode 100644 apps/aris-backend/src/enhancement/schema.test.ts create mode 100644 apps/aris-backend/src/enhancement/schema.ts diff --git a/apps/aris-backend/.env.example b/apps/aris-backend/.env.example index 85da9f8..416efc1 100644 --- a/apps/aris-backend/.env.example +++ b/apps/aris-backend/.env.example @@ -7,6 +7,11 @@ BETTER_AUTH_SECRET= # Base URL of the backend BETTER_AUTH_URL=http://localhost:3000 +# OpenRouter (LLM feed enhancement) +OPENROUTER_API_KEY= +# Optional: override the default model (default: openai/gpt-4.1-mini) +# OPENROUTER_MODEL=openai/gpt-4.1-mini + # Apple WeatherKit credentials WEATHERKIT_PRIVATE_KEY= WEATHERKIT_KEY_ID= diff --git a/apps/aris-backend/package.json b/apps/aris-backend/package.json index 129ef05..2d829dc 100644 --- a/apps/aris-backend/package.json +++ b/apps/aris-backend/package.json @@ -10,9 +10,12 @@ }, "dependencies": { "@aris/core": "workspace:*", + "@aris/source-caldav": "workspace:*", + "@aris/source-google-calendar": "workspace:*", "@aris/source-location": "workspace:*", "@aris/source-tfl": "workspace:*", "@aris/source-weatherkit": "workspace:*", + "@openrouter/sdk": "^0.9.11", "arktype": "^2.1.29", "better-auth": "^1", "hono": "^4", diff --git a/apps/aris-backend/src/enhancement/enhance-feed.ts b/apps/aris-backend/src/enhancement/enhance-feed.ts new file mode 100644 index 0000000..ae34da3 --- /dev/null +++ b/apps/aris-backend/src/enhancement/enhance-feed.ts @@ -0,0 +1,51 @@ +import type { FeedItem } from "@aris/core" + +import type { LlmClient } from "./llm-client.ts" + +import { mergeEnhancement } from "./merge.ts" +import { buildPrompt, hasUnfilledSlots } from "./prompt-builder.ts" + +/** Takes feed items, returns enhanced feed items. */ +export type FeedEnhancer = (items: FeedItem[]) => Promise + +export interface FeedEnhancerConfig { + client: LlmClient + /** Defaults to Date.now — override for testing */ + clock?: () => Date +} + +/** + * Creates a FeedEnhancer that uses the provided LlmClient. + * + * Skips the LLM call when no items have unfilled slots. + * Returns items unchanged on LLM failure. + */ +export function createFeedEnhancer(config: FeedEnhancerConfig): FeedEnhancer { + const { client } = config + const clock = config.clock ?? (() => new Date()) + + return async function enhanceFeed(items) { + if (!hasUnfilledSlots(items)) { + return items + } + + const currentTime = clock() + const { systemPrompt, userMessage } = buildPrompt(items, currentTime) + + let result + try { + result = await client.enhance({ systemPrompt, userMessage }) + } catch (err) { + console.error("[enhancement] LLM call failed:", err) + result = null + } + + if (!result) { + return items + } + + return mergeEnhancement(items, result, currentTime) + } +} + + diff --git a/apps/aris-backend/src/enhancement/llm-client.ts b/apps/aris-backend/src/enhancement/llm-client.ts new file mode 100644 index 0000000..1629ebd --- /dev/null +++ b/apps/aris-backend/src/enhancement/llm-client.ts @@ -0,0 +1,71 @@ +import { OpenRouter } from "@openrouter/sdk" + +import type { EnhancementResult } from "./schema.ts" + +import { enhancementResultJsonSchema, parseEnhancementResult } from "./schema.ts" + +const DEFAULT_MODEL = "openai/gpt-4.1-mini" +const DEFAULT_TIMEOUT_MS = 30_000 + +export interface LlmClientConfig { + apiKey: string + model?: string + timeoutMs?: number +} + +export interface LlmClientRequest { + systemPrompt: string + userMessage: string +} + +export interface LlmClient { + enhance(request: LlmClientRequest): Promise +} + +/** + * Creates a reusable LLM client backed by OpenRouter. + * The OpenRouter SDK instance is created once and reused across calls. + */ +export function createLlmClient(config: LlmClientConfig): LlmClient { + const client = new OpenRouter({ + apiKey: config.apiKey, + timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS, + }) + const model = config.model ?? DEFAULT_MODEL + + return { + async enhance(request) { + const response = await client.chat.send({ + chatGenerationParams: { + model, + messages: [ + { role: "system" as const, content: request.systemPrompt }, + { role: "user" as const, content: request.userMessage }, + ], + responseFormat: { + type: "json_schema" as const, + jsonSchema: { + name: "enhancement_result", + strict: true, + schema: enhancementResultJsonSchema, + }, + }, + stream: false, + }, + }) + + const content = response.choices?.[0]?.message?.content + if (typeof content !== "string") { + console.warn("[enhancement] LLM returned no content in response") + return null + } + + const result = parseEnhancementResult(content) + if (!result) { + console.warn("[enhancement] Failed to parse LLM response:", content) + } + + return result + }, + } +} diff --git a/apps/aris-backend/src/enhancement/merge.test.ts b/apps/aris-backend/src/enhancement/merge.test.ts new file mode 100644 index 0000000..6ba86a3 --- /dev/null +++ b/apps/aris-backend/src/enhancement/merge.test.ts @@ -0,0 +1,150 @@ +import type { FeedItem } from "@aris/core" + +import { describe, expect, test } from "bun:test" + +import type { EnhancementResult } from "./schema.ts" + +import { mergeEnhancement } from "./merge.ts" + +function makeItem(overrides: Partial = {}): FeedItem { + return { + id: "item-1", + type: "test", + timestamp: new Date("2025-01-01T00:00:00Z"), + data: { value: 42 }, + ...overrides, + } +} + +const now = new Date("2025-06-01T12:00:00Z") + +describe("mergeEnhancement", () => { + test("fills matching slots", () => { + const item = makeItem({ + slots: { + insight: { description: "Weather insight", content: null }, + }, + }) + const result: EnhancementResult = { + slotFills: { + "item-1": { insight: "Rain after 3pm" }, + }, + syntheticItems: [], + } + + const merged = mergeEnhancement([item], result, now) + + expect(merged).toHaveLength(1) + expect(merged[0]!.slots!.insight!.content).toBe("Rain after 3pm") + // Description preserved + expect(merged[0]!.slots!.insight!.description).toBe("Weather insight") + }) + + test("does not mutate original items", () => { + const item = makeItem({ + slots: { + insight: { description: "test", content: null }, + }, + }) + const result: EnhancementResult = { + slotFills: { "item-1": { insight: "filled" } }, + syntheticItems: [], + } + + mergeEnhancement([item], result, now) + + expect(item.slots!.insight!.content).toBeNull() + }) + + test("ignores fills for non-existent items", () => { + const item = makeItem() + const result: EnhancementResult = { + slotFills: { "non-existent": { insight: "text" } }, + syntheticItems: [], + } + + const merged = mergeEnhancement([item], result, now) + + expect(merged).toHaveLength(1) + expect(merged[0]!.id).toBe("item-1") + }) + + test("ignores fills for non-existent slots", () => { + const item = makeItem({ + slots: { + insight: { description: "test", content: null }, + }, + }) + const result: EnhancementResult = { + slotFills: { "item-1": { "non-existent-slot": "text" } }, + syntheticItems: [], + } + + const merged = mergeEnhancement([item], result, now) + + expect(merged[0]!.slots!.insight!.content).toBeNull() + }) + + test("skips null fills", () => { + const item = makeItem({ + slots: { + insight: { description: "test", content: null }, + }, + }) + const result: EnhancementResult = { + slotFills: { "item-1": { insight: null } }, + syntheticItems: [], + } + + const merged = mergeEnhancement([item], result, now) + + expect(merged[0]!.slots!.insight!.content).toBeNull() + }) + + test("passes through items without slots unchanged", () => { + const item = makeItem() + const result: EnhancementResult = { + slotFills: {}, + syntheticItems: [], + } + + const merged = mergeEnhancement([item], result, now) + + expect(merged[0]).toBe(item) + }) + + test("appends synthetic items with backfilled fields", () => { + const item = makeItem() + const result: EnhancementResult = { + slotFills: {}, + syntheticItems: [ + { + id: "briefing-morning", + type: "briefing", + text: "Light afternoon ahead.", + }, + ], + } + + const merged = mergeEnhancement([item], result, now) + + expect(merged).toHaveLength(2) + expect(merged[1]!.id).toBe("briefing-morning") + expect(merged[1]!.type).toBe("briefing") + expect(merged[1]!.timestamp).toEqual(now) + expect(merged[1]!.data).toEqual({ text: "Light afternoon ahead." }) + }) + + test("handles empty enhancement result", () => { + const item = makeItem() + const result: EnhancementResult = { + slotFills: {}, + syntheticItems: [], + } + + const merged = mergeEnhancement([item], result, now) + + expect(merged).toHaveLength(1) + expect(merged[0]).toBe(item) + }) +}) diff --git a/apps/aris-backend/src/enhancement/merge.ts b/apps/aris-backend/src/enhancement/merge.ts new file mode 100644 index 0000000..3a51c10 --- /dev/null +++ b/apps/aris-backend/src/enhancement/merge.ts @@ -0,0 +1,41 @@ +import type { FeedItem } from "@aris/core" + +import type { EnhancementResult } from "./schema.ts" + +/** + * Merges an EnhancementResult into feed items. + * + * - Writes slot content from slotFills into matching items + * - Appends synthetic items to the list + * - Returns a new array (no mutation) + * - Ignores fills for items/slots that don't exist + */ +export function mergeEnhancement(items: FeedItem[], result: EnhancementResult, currentTime: Date): FeedItem[] { + const merged = items.map((item) => { + const fills = result.slotFills[item.id] + if (!fills || !item.slots) return item + + const mergedSlots = { ...item.slots } + let changed = false + + for (const [slotName, content] of Object.entries(fills)) { + if (slotName in mergedSlots && content !== null) { + mergedSlots[slotName] = { ...mergedSlots[slotName]!, content } + changed = true + } + } + + return changed ? { ...item, slots: mergedSlots } : item + }) + + for (const synthetic of result.syntheticItems) { + merged.push({ + id: synthetic.id, + type: synthetic.type, + timestamp: currentTime, + data: { text: synthetic.text }, + }) + } + + return merged +} diff --git a/apps/aris-backend/src/enhancement/prompt-builder.test.ts b/apps/aris-backend/src/enhancement/prompt-builder.test.ts new file mode 100644 index 0000000..3a78422 --- /dev/null +++ b/apps/aris-backend/src/enhancement/prompt-builder.test.ts @@ -0,0 +1,167 @@ +import type { FeedItem } from "@aris/core" + +import { describe, expect, test } from "bun:test" + +import { buildPrompt, hasUnfilledSlots } from "./prompt-builder.ts" + +function makeItem(overrides: Partial = {}): FeedItem { + return { + id: "item-1", + type: "test", + timestamp: new Date("2025-01-01T00:00:00Z"), + data: { value: 42 }, + ...overrides, + } +} + +function parseUserMessage(userMessage: string): Record { + return JSON.parse(userMessage) +} + +describe("hasUnfilledSlots", () => { + test("returns false for items without slots", () => { + expect(hasUnfilledSlots([makeItem()])).toBe(false) + }) + + test("returns false for items with all slots filled", () => { + const item = makeItem({ + slots: { + insight: { description: "test", content: "filled" }, + }, + }) + expect(hasUnfilledSlots([item])).toBe(false) + }) + + test("returns true when at least one slot is unfilled", () => { + const item = makeItem({ + slots: { + insight: { description: "test", content: null }, + }, + }) + expect(hasUnfilledSlots([item])).toBe(true) + }) + + test("returns false for empty array", () => { + expect(hasUnfilledSlots([])).toBe(false) + }) +}) + +describe("buildPrompt", () => { + test("puts items with unfilled slots in items", () => { + const item = makeItem({ + slots: { + insight: { description: "Weather insight", content: null }, + filled: { description: "Already done", content: "done" }, + }, + }) + + const { userMessage } = buildPrompt([item], new Date("2025-06-01T12:00:00Z")) + const parsed = parseUserMessage(userMessage) + + expect(parsed.items).toHaveLength(1) + expect((parsed.items as Array>)[0]!.id).toBe("item-1") + expect((parsed.items as Array>)[0]!.slots).toEqual({ insight: "Weather insight" }) + expect((parsed.items as Array>)[0]!.type).toBeUndefined() + expect(parsed.context).toHaveLength(0) + }) + + test("puts slotless items in context", () => { + const withSlots = makeItem({ + id: "with-slots", + slots: { insight: { description: "test", content: null } }, + }) + const withoutSlots = makeItem({ id: "no-slots" }) + + const { userMessage } = buildPrompt([withSlots, withoutSlots], new Date("2025-06-01T12:00:00Z")) + const parsed = parseUserMessage(userMessage) + + expect(parsed.items).toHaveLength(1) + expect((parsed.items as Array>)[0]!.id).toBe("with-slots") + expect(parsed.context).toHaveLength(1) + expect((parsed.context as Array>)[0]!.id).toBe("no-slots") + }) + + test("includes time in ISO format", () => { + const { userMessage } = buildPrompt([], new Date("2025-06-01T12:00:00Z")) + const parsed = parseUserMessage(userMessage) + + expect(parsed.time).toBe("2025-06-01T12:00:00.000Z") + }) + + test("system prompt is non-empty", () => { + const { systemPrompt } = buildPrompt([], new Date()) + expect(systemPrompt.length).toBeGreaterThan(0) + }) + + test("includes schedule in system prompt", () => { + const calEvent = makeItem({ + id: "cal-1", + type: "caldav-event", + data: { + title: "Team standup", + startDate: "2025-06-01T10:00:00Z", + endDate: "2025-06-01T10:30:00Z", + isAllDay: false, + location: null, + }, + slots: { + insight: { description: "test", content: null }, + }, + }) + + const { systemPrompt } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z")) + + expect(systemPrompt).toContain("Schedule:\n") + expect(systemPrompt).toContain("Team standup") + expect(systemPrompt).toContain("10:00") + }) + + test("includes location in schedule", () => { + const calEvent = makeItem({ + id: "cal-1", + type: "caldav-event", + data: { + title: "Therapy", + startDate: "2025-06-02T18:00:00Z", + endDate: "2025-06-02T19:00:00Z", + isAllDay: false, + location: "92 Tooley Street, London", + }, + }) + + const { systemPrompt } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z")) + + expect(systemPrompt).toContain("Therapy @ 92 Tooley Street, London") + }) + + test("includes week calendar but omits schedule when no calendar items", () => { + const weatherItem = makeItem({ + type: "weather-current", + data: { temperature: 14 }, + }) + + const { systemPrompt } = buildPrompt([weatherItem], new Date("2025-06-01T12:00:00Z")) + + expect(systemPrompt).toContain("Week:") + expect(systemPrompt).not.toContain("Schedule:") + }) + + test("user message is pure JSON", () => { + const calEvent = makeItem({ + id: "cal-1", + type: "caldav-event", + data: { + title: "Budget Review", + startTime: "2025-06-01T14:00:00Z", + endTime: "2025-06-01T15:00:00Z", + isAllDay: false, + location: "https://meet.google.com/abc", + }, + }) + + const { userMessage } = buildPrompt([calEvent], new Date("2025-06-01T12:00:00Z")) + + expect(userMessage.startsWith("{")).toBe(true) + expect(() => JSON.parse(userMessage)).not.toThrow() + }) +}) diff --git a/apps/aris-backend/src/enhancement/prompt-builder.ts b/apps/aris-backend/src/enhancement/prompt-builder.ts new file mode 100644 index 0000000..1a7b3ae --- /dev/null +++ b/apps/aris-backend/src/enhancement/prompt-builder.ts @@ -0,0 +1,218 @@ +import type { FeedItem } from "@aris/core" + +import { CalDavFeedItemType } from "@aris/source-caldav" +import { CalendarFeedItemType } from "@aris/source-google-calendar" + +import systemPromptBase from "./prompts/system.txt" + +const CALENDAR_ITEM_TYPES = new Set([ + CalDavFeedItemType.Event, + CalendarFeedItemType.Event, + CalendarFeedItemType.AllDay, +]) + +/** + * Builds the system prompt and user message for the enhancement harness. + * + * Includes a pre-computed mini calendar so the LLM doesn't have to + * parse timestamps to understand the user's schedule. + */ +export function buildPrompt( + items: FeedItem[], + currentTime: Date, +): { systemPrompt: string; userMessage: string } { + const schedule = buildSchedule(items, currentTime) + + const enhanceItems: Array<{ + id: string + data: Record + slots: Record + }> = [] + const contextItems: Array<{ + id: string + type: string + data: Record + }> = [] + + for (const item of items) { + const hasUnfilledSlots = + item.slots && + Object.values(item.slots).some((slot) => slot.content === null) + + if (hasUnfilledSlots) { + enhanceItems.push({ + id: item.id, + data: item.data, + slots: Object.fromEntries( + Object.entries(item.slots!) + .filter(([, slot]) => slot.content === null) + .map(([name, slot]) => [name, slot.description]), + ), + }) + } else { + contextItems.push({ + id: item.id, + type: item.type, + data: item.data, + }) + } + } + + const userMessage = JSON.stringify({ + time: currentTime.toISOString(), + items: enhanceItems, + context: contextItems, + }) + + const weekCalendar = buildWeekCalendar(currentTime) + let systemPrompt = systemPromptBase + systemPrompt += `\n\nWeek:\n${weekCalendar}` + if (schedule) { + systemPrompt += `\n\nSchedule:\n${schedule}` + } + + return { systemPrompt, userMessage } +} + +/** + * Returns true if any item has at least one unfilled slot. + */ +export function hasUnfilledSlots(items: FeedItem[]): boolean { + return items.some( + (item) => + item.slots && + Object.values(item.slots).some((slot) => slot.content === null), + ) +} + +// -- Helpers -- + +interface CalendarEntry { + date: Date + title: string + location: string | null + isAllDay: boolean + startTime: Date + endTime: Date +} + +function toValidDate(value: unknown): Date | null { + if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value + if (typeof value === "string" || typeof value === "number") { + const date = new Date(value) + return Number.isNaN(date.getTime()) ? null : date + } + return null +} + +function extractCalendarEntry(item: FeedItem): CalendarEntry | null { + if (!CALENDAR_ITEM_TYPES.has(item.type)) return null + + const d = item.data + const title = d.title + if (typeof title !== "string" || !title) return null + + // CalDAV uses startDate/endDate, Google Calendar uses startTime/endTime + const startTime = toValidDate(d.startDate ?? d.startTime) + if (!startTime) return null + + const endTime = toValidDate(d.endDate ?? d.endTime) ?? startTime + + return { + date: startTime, + title, + location: typeof d.location === "string" ? d.location : null, + isAllDay: typeof d.isAllDay === "boolean" ? d.isAllDay : false, + startTime, + endTime, + } +} + +const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const +const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const + +function pad2(n: number): string { + return n.toString().padStart(2, "0") +} + +function formatTime(date: Date): string { + return `${pad2(date.getUTCHours())}:${pad2(date.getUTCMinutes())}` +} + +function formatDayShort(date: Date): string { + return `${DAYS[date.getUTCDay()]}, ${date.getUTCDate()} ${MONTHS[date.getUTCMonth()]}` +} + +function formatDayLabel(date: Date, currentTime: Date): string { + const currentDay = Date.UTC(currentTime.getUTCFullYear(), currentTime.getUTCMonth(), currentTime.getUTCDate()) + const targetDay = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()) + const diffDays = Math.round((targetDay - currentDay) / (1000 * 60 * 60 * 24)) + + const dayName = formatDayShort(date) + + if (diffDays === 0) return `Today: ${dayName}` + if (diffDays === 1) return `Tomorrow: ${dayName}` + return dayName +} + +/** + * Builds a week overview mapping day names to dates, + * so the LLM can easily match ISO timestamps to days. + */ +function buildWeekCalendar(currentTime: Date): string { + const lines: string[] = [] + for (let i = 0; i < 7; i++) { + const date = new Date(currentTime) + date.setUTCDate(date.getUTCDate() + i) + const label = i === 0 ? "Today" : i === 1 ? "Tomorrow" : "" + const dayStr = formatDayShort(date) + const iso = date.toISOString().slice(0, 10) + const prefix = label ? `${label}: ` : "" + lines.push(`${prefix}${dayStr} = ${iso}`) + } + return lines.join("\n") +} + +/** + * Builds a compact text calendar from all calendar-type items. + * Groups events by day relative to currentTime. + */ +function buildSchedule(items: FeedItem[], currentTime: Date): string { + const entries: CalendarEntry[] = [] + for (const item of items) { + const entry = extractCalendarEntry(item) + if (entry) entries.push(entry) + } + + if (entries.length === 0) return "" + + entries.sort((a, b) => a.startTime.getTime() - b.startTime.getTime()) + + const byDay = new Map() + for (const entry of entries) { + const key = entry.date.toISOString().slice(0, 10) + const group = byDay.get(key) + if (group) { + group.push(entry) + } else { + byDay.set(key, [entry]) + } + } + + const lines: string[] = [] + for (const [, dayEntries] of byDay) { + lines.push(formatDayLabel(dayEntries[0]!.startTime, currentTime)) + for (const entry of dayEntries) { + if (entry.isAllDay) { + const loc = entry.location ? ` @ ${entry.location}` : "" + lines.push(` all day ${entry.title}${loc}`) + } else { + const timeRange = `${formatTime(entry.startTime)}–${formatTime(entry.endTime)}` + const loc = entry.location ? ` @ ${entry.location}` : "" + lines.push(` ${timeRange} ${entry.title}${loc}`) + } + } + } + + return lines.join("\n") +} diff --git a/apps/aris-backend/src/enhancement/prompts/system.txt b/apps/aris-backend/src/enhancement/prompts/system.txt new file mode 100644 index 0000000..80eb816 --- /dev/null +++ b/apps/aris-backend/src/enhancement/prompts/system.txt @@ -0,0 +1,21 @@ +You are ARIS, a personal assistant. You enhance a user's feed by filling slots and optionally generating synthetic items. + +The user message is a JSON object with: +- "items": feed items with data and named slots to fill. Each slot has a description of what to write. +- "context": other feed items (no slots) for cross-source reasoning. +- "time": current ISO timestamp. + +Your output has two fields: +- "slotFills": map of item ID → slot name → short text (or null if you can't fill it or cannot provide answer). Each item ID appears ONCE with ALL its slots in a single object. +- "syntheticItems": array of { id, type, text } for new items (briefings, nudges, insights). Only when genuinely useful and when not redundant. + +Rules: +- DO NOT USE EMDASH OR DASH OR ATTEMPT TO USE SYMBOLS TO CIRCUMVENT THIS RULE. +- One sentence per slot. Two max if absolutely necessary. Be direct. +- Say "I" not "we." +- Hedge when inferring. Don't state guesses as facts. +- Use the week and schedule below to understand when events happen. Match weather data to the correct date. +- Look for connections across items. +- Don't pad — return null for slots you can't meaningfully fill, and skip synthetic items if there's nothing useful to add. +- Never fabricate information not present in the feed. If you don't have data to support a fill, return null. +- Read each slot's description carefully — it defines when to return null. \ No newline at end of file diff --git a/apps/aris-backend/src/enhancement/schema.test.ts b/apps/aris-backend/src/enhancement/schema.test.ts new file mode 100644 index 0000000..403b3ab --- /dev/null +++ b/apps/aris-backend/src/enhancement/schema.test.ts @@ -0,0 +1,89 @@ +import { describe, expect, test } from "bun:test" + +import { emptyEnhancementResult, parseEnhancementResult } from "./schema.ts" + +describe("parseEnhancementResult", () => { + test("parses valid result", () => { + const input = JSON.stringify({ + slotFills: { + "weather-1": { + insight: "Rain after 3pm", + "cross-source": null, + }, + }, + syntheticItems: [ + { + id: "briefing-morning", + type: "briefing", + text: "Light afternoon ahead.", + }, + ], + }) + + const result = parseEnhancementResult(input) + + expect(result).not.toBeNull() + expect(result!.slotFills["weather-1"]!.insight).toBe("Rain after 3pm") + expect(result!.slotFills["weather-1"]!["cross-source"]).toBeNull() + expect(result!.syntheticItems).toHaveLength(1) + expect(result!.syntheticItems[0]!.id).toBe("briefing-morning") + expect(result!.syntheticItems[0]!.text).toBe("Light afternoon ahead.") + }) + + test("parses empty result", () => { + const input = JSON.stringify({ + slotFills: {}, + syntheticItems: [], + }) + + const result = parseEnhancementResult(input) + + expect(result).not.toBeNull() + expect(Object.keys(result!.slotFills)).toHaveLength(0) + expect(result!.syntheticItems).toHaveLength(0) + }) + + test("returns null for invalid JSON", () => { + expect(parseEnhancementResult("not json")).toBeNull() + }) + + test("returns null for non-object", () => { + expect(parseEnhancementResult('"hello"')).toBeNull() + expect(parseEnhancementResult("42")).toBeNull() + expect(parseEnhancementResult("null")).toBeNull() + }) + + test("returns null when slotFills is missing", () => { + const input = JSON.stringify({ syntheticItems: [] }) + expect(parseEnhancementResult(input)).toBeNull() + }) + + test("returns null when syntheticItems is missing", () => { + const input = JSON.stringify({ slotFills: {} }) + expect(parseEnhancementResult(input)).toBeNull() + }) + + test("returns null when slotFills has non-string values", () => { + const input = JSON.stringify({ + slotFills: { "item-1": { slot: 42 } }, + syntheticItems: [], + }) + expect(parseEnhancementResult(input)).toBeNull() + }) + + test("returns null when syntheticItem is missing required fields", () => { + const input = JSON.stringify({ + slotFills: {}, + syntheticItems: [{ id: "x" }], + }) + expect(parseEnhancementResult(input)).toBeNull() + }) +}) + +describe("emptyEnhancementResult", () => { + test("returns empty slotFills and syntheticItems", () => { + const result = emptyEnhancementResult() + expect(result.slotFills).toEqual({}) + expect(result.syntheticItems).toEqual([]) + }) +}) diff --git a/apps/aris-backend/src/enhancement/schema.ts b/apps/aris-backend/src/enhancement/schema.ts new file mode 100644 index 0000000..b00b972 --- /dev/null +++ b/apps/aris-backend/src/enhancement/schema.ts @@ -0,0 +1,89 @@ +import { type } from "arktype" + +const syntheticItemSchema = type({ + id: "string", + type: "string", + text: "string", +}) + +const enhancementResultSchema = type({ + slotFills: "Record>", + syntheticItems: syntheticItemSchema.array(), +}) + +export type SyntheticItem = typeof syntheticItemSchema.infer +export type EnhancementResult = typeof enhancementResultSchema.infer + +/** + * JSON Schema passed to OpenRouter's structured output. + * OpenRouter doesn't support arktype, so this is maintained separately. + * + * ⚠️ Must stay in sync with enhancementResultSchema above. + * If you add/remove fields, update both schemas. + */ +export const enhancementResultJsonSchema = { + type: "object", + properties: { + slotFills: { + type: "object", + description: + "Map of feed item ID to an object of slot name to filled text content. Use null for slots that cannot be meaningfully filled.", + additionalProperties: { + type: "object", + additionalProperties: { + type: ["string", "null"], + }, + }, + }, + syntheticItems: { + type: "array", + description: + "New feed items to inject (briefings, nudges, cross-source insights). Keep these short and actionable.", + items: { + type: "object", + properties: { + id: { + type: "string", + description: "Unique ID, e.g. 'briefing-morning'", + }, + type: { + type: "string", + description: "One of: 'briefing', 'nudge', 'insight'", + }, + text: { + type: "string", + description: "Display text, 1-3 sentences", + }, + }, + required: ["id", "type", "text"], + additionalProperties: false, + }, + }, + }, + required: ["slotFills", "syntheticItems"], + additionalProperties: false, +} as const + +/** + * Parses a JSON string into an EnhancementResult. + * Returns null if the input is malformed. + */ +export function parseEnhancementResult(json: string): EnhancementResult | null { + let parsed: unknown + try { + parsed = JSON.parse(json) + } catch { + return null + } + + const result = enhancementResultSchema(parsed) + if (result instanceof type.errors) { + return null + } + + return result +} + +export function emptyEnhancementResult(): EnhancementResult { + return { slotFills: {}, syntheticItems: [] } +} diff --git a/apps/aris-backend/src/feed/http.test.ts b/apps/aris-backend/src/feed/http.test.ts index a87c522..ab7b9b4 100644 --- a/apps/aris-backend/src/feed/http.test.ts +++ b/apps/aris-backend/src/feed/http.test.ts @@ -41,6 +41,7 @@ function buildTestApp(sessionManager: UserSessionManager, userId?: string) { registerFeedHttpHandlers(app, { sessionManager, authSessionMiddleware: mockAuthSessionMiddleware(userId), + feedEnhancer: null, }) return app } @@ -109,6 +110,66 @@ describe("GET /api/feed", () => { expect(body.errors).toHaveLength(0) }) + test("returns enhanced items when feedEnhancer is provided", async () => { + const items: FeedItem[] = [ + { + id: "item-1", + type: "test", + timestamp: new Date("2025-01-01T00:00:00.000Z"), + data: { value: 42 }, + }, + ] + const manager = new UserSessionManager([() => createStubSource("test", items)]) + + const enhancer = async (feedItems: FeedItem[]) => + feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } })) + + const app = new Hono() + registerFeedHttpHandlers(app, { + sessionManager: manager, + authSessionMiddleware: mockAuthSessionMiddleware("user-1"), + feedEnhancer: enhancer, + }) + + const res = await app.request("/api/feed") + + expect(res.status).toBe(200) + const body = (await res.json()) as FeedResponse + expect(body.items).toHaveLength(1) + expect(body.items[0]!.data.enhanced).toBe(true) + }) + + test("falls back to raw items when feedEnhancer throws", async () => { + const items: FeedItem[] = [ + { + id: "item-1", + type: "test", + timestamp: new Date("2025-01-01T00:00:00.000Z"), + data: { value: 42 }, + }, + ] + const manager = new UserSessionManager([() => createStubSource("test", items)]) + + const enhancer = async () => { + throw new Error("enhancement exploded") + } + + const app = new Hono() + registerFeedHttpHandlers(app, { + sessionManager: manager, + authSessionMiddleware: mockAuthSessionMiddleware("user-1"), + feedEnhancer: enhancer, + }) + + const res = await app.request("/api/feed") + + expect(res.status).toBe(200) + const body = (await res.json()) as FeedResponse + expect(body.items).toHaveLength(1) + expect(body.items[0]!.id).toBe("item-1") + expect(body.items[0]!.data.value).toBe(42) + }) + test("serializes source errors as message strings", async () => { const failingSource: FeedSource = { id: "failing", diff --git a/apps/aris-backend/src/feed/http.ts b/apps/aris-backend/src/feed/http.ts index e269663..545104e 100644 --- a/apps/aris-backend/src/feed/http.ts +++ b/apps/aris-backend/src/feed/http.ts @@ -3,21 +3,29 @@ import type { Context, Hono } from "hono" import { createMiddleware } from "hono/factory" import type { AuthSessionMiddleware } from "../auth/session-middleware.ts" +import type { FeedEnhancer } from "../enhancement/enhance-feed.ts" import type { UserSessionManager } from "../session/index.ts" -type Env = { Variables: { sessionManager: UserSessionManager } } +type Env = { + Variables: { + sessionManager: UserSessionManager + feedEnhancer: FeedEnhancer | null + } +} interface FeedHttpHandlersDeps { sessionManager: UserSessionManager authSessionMiddleware: AuthSessionMiddleware + feedEnhancer: FeedEnhancer | null } export function registerFeedHttpHandlers( app: Hono, - { sessionManager, authSessionMiddleware }: FeedHttpHandlersDeps, + { sessionManager, authSessionMiddleware, feedEnhancer }: FeedHttpHandlersDeps, ) { const inject = createMiddleware(async (c, next) => { c.set("sessionManager", sessionManager) + c.set("feedEnhancer", feedEnhancer) await next() }) @@ -31,8 +39,18 @@ async function handleGetFeed(c: Context) { const feed = session.engine.lastFeed() ?? (await session.engine.refresh()) + let items = feed.items + const enhance = c.get("feedEnhancer") + if (enhance) { + try { + items = await enhance(feed.items) + } catch (err) { + console.error("[enhancement] Unexpected error, returning unenhanced feed:", err) + } + } + return c.json({ - items: feed.items, + items, errors: feed.errors.map((e) => ({ sourceId: e.sourceId, error: e.error.message, diff --git a/apps/aris-backend/src/server.ts b/apps/aris-backend/src/server.ts index a350cce..a1af4b2 100644 --- a/apps/aris-backend/src/server.ts +++ b/apps/aris-backend/src/server.ts @@ -3,6 +3,8 @@ import { Hono } from "hono" import { registerAuthHandlers } from "./auth/http.ts" import { requireSession } from "./auth/session-middleware.ts" +import { createFeedEnhancer } from "./enhancement/enhance-feed.ts" +import { createLlmClient } from "./enhancement/llm-client.ts" import { registerFeedHttpHandlers } from "./feed/http.ts" import { registerLocationHttpHandlers } from "./location/http.ts" import { UserSessionManager } from "./session/index.ts" @@ -21,12 +23,29 @@ function main() { }), ]) + const openrouterApiKey = process.env.OPENROUTER_API_KEY + const feedEnhancer = openrouterApiKey + ? createFeedEnhancer({ + client: createLlmClient({ + apiKey: openrouterApiKey, + model: process.env.OPENROUTER_MODEL || undefined, + }), + }) + : null + if (!feedEnhancer) { + console.warn("[enhancement] OPENROUTER_API_KEY not set — feed enhancement disabled") + } + const app = new Hono() app.get("/health", (c) => c.json({ status: "ok" })) registerAuthHandlers(app) - registerFeedHttpHandlers(app, { sessionManager, authSessionMiddleware: requireSession }) + registerFeedHttpHandlers(app, { + sessionManager, + authSessionMiddleware: requireSession, + feedEnhancer, + }) registerLocationHttpHandlers(app, { sessionManager }) return app diff --git a/bun.lock b/bun.lock index 02c33a5..9054a04 100644 --- a/bun.lock +++ b/bun.lock @@ -18,9 +18,12 @@ "version": "0.0.0", "dependencies": { "@aris/core": "workspace:*", + "@aris/source-caldav": "workspace:*", + "@aris/source-google-calendar": "workspace:*", "@aris/source-location": "workspace:*", "@aris/source-tfl": "workspace:*", "@aris/source-weatherkit": "workspace:*", + "@openrouter/sdk": "^0.9.11", "arktype": "^2.1.29", "better-auth": "^1", "hono": "^4", @@ -543,6 +546,8 @@ "@oclif/screen": ["@oclif/screen@3.0.8", "", {}, "sha512-yx6KAqlt3TAHBduS2fMQtJDL2ufIHnDRArrJEOoTTuizxqmjLT+psGYOHpmMl3gvQpFJ11Hs76guUUktzAF9Bg=="], + "@openrouter/sdk": ["@openrouter/sdk@0.9.11", "", { "dependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-BgFu6NcIJO4a9aVjr04y3kZ8pyM71j15I+bzfVAGEvxnj+KQNIkBYQGgwrG3D+aT1QpDKLki8btcQmpaxUas6A=="], + "@oxfmt/darwin-arm64": ["@oxfmt/darwin-arm64@0.24.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-aYXuGf/yq8nsyEcHindGhiz9I+GEqLkVq8CfPbd+6VE259CpPEH+CaGHEO1j6vIOmNr8KHRq+IAjeRO2uJpb8A=="], "@oxfmt/darwin-x64": ["@oxfmt/darwin-x64@0.24.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-vs3b8Bs53hbiNvcNeBilzE/+IhDTWKjSBB3v/ztr664nZk65j0xr+5IHMBNz3CFppmX7o/aBta2PxY+t+4KoPg=="],