managarten/docs/plans/news-research-module.md

News Research — Module Plan

Status (2026-04-15)

Planung. Noch kein Code. Geschwistermodul zu news/, teilt Low-Level-Primitives, eigene Pipeline.

Ziel

Ein Research-Tool, das zu einem Thema passende RSS-Feeds findet, sie filtert, die Artikel nach Relevanz durchsucht und das Ergebnis als KI-Kontext-Paket ausliefert. Agent-facing, nicht consumer-facing.

Abgrenzung zum bestehenden news/-Modul:

• news/ = kuratierter Consumer-Feed, persistent, verschlüsselt, synced, Lern-Reaktionen.
• news-research/ = Discovery + Query, ephemer pro Session, eigenes Scoring (Relevanz statt Recency).
• Brücke: "Save article" → landet in der bestehenden newsArticles-Tabelle (type='saved'). Einzige Reading-List bleibt dort.
• Brücke: "Pin feed" → persistiert einen entdeckten Feed in customFeeds (Preferences-Erweiterung) — damit ist gleichzeitig die eigene RSS-Abo-Funktion abgedeckt, die zuvor im news/-Modul fehlte.

Shared Primitives zuerst

Vor dem Modul: packages/shared-rss (neues Workspace-Package) extrahieren.

• parseFeed(url | xml) — RSS/Atom Parser (wandert aus services/news-ingester)
• extractArticle(url, html?) — Readability-Fallback (wandert aus apps/api/src/modules/news/routes.ts)
• discoverFeeds(siteUrl) — neu: <link rel="alternate" type="application/rss+xml">-Discovery + Sitemap-Heuristik
• validateFeed(url) — Health-Check (fetchbar, parsebar, min. N Items)
• Typen: FeedMeta, FeedItem, ExtractedArticle

news-ingester und der news/extract-Endpoint werden migriert, damit nur eine Parser-Implementation existiert.

Discovery-Strategie (einfache Variante)

Kein Feedly/RSS.app. Alles in-house, zwei Quellen:

1. Direkte URL: User pastet Site-URL → Server holt HTML → sucht <link rel="alternate" type="application/rss+xml"> → validiert → gibt Feed-Metadaten zurück.
2. Thema-Suche: Query "klimawandel" rss oder ähnlich an eine Websuche (reuse was bei mana-search/crawler vorhanden ist), Top-N Ergebnisse filtern → für jedes Top-Result Discovery-Schritt 1 ausführen.

Phase 2 kann später externe APIs hinzufügen.

Modul-Struktur

apps/mana/apps/web/src/lib/modules/news-research/
├── types.ts                 # ResearchSession, DiscoveredFeed, ResearchArticle
├── stores/
│   ├── session.svelte.ts    # Aktuelle Research-Session (ephemer, kein Dexie)
│   └── pinned.svelte.ts     # customFeeds-Verwaltung (persistiert über news-Preferences)
├── engine/
│   ├── relevance.ts         # BM25 / Keyword-Scoring Artikel vs. Query
│   └── filter.ts            # Thema-Filter Feed + Artikel
├── api.ts                   # Client für /api/v1/news-research/*
└── components/              # UI

apps/api/src/modules/news-research/routes.ts
├── POST /discover           # { query | siteUrl } → DiscoveredFeed[]
├── POST /validate           # { url } → FeedMeta + Sample-Items
├── POST /search             # { feeds[], query, filters } → ScoredArticle[]
└── POST /extract            # { url } → ExtractedArticle (reuse shared-rss)

Kein eigener Background-Service. Alles on-demand request/response. Session läuft im Browser-Memory + SessionStorage.

Data Model

Ephemer (nur Session):

type ResearchSession = {
  id: string
  query: string
  topics: string[]
  discoveredFeeds: DiscoveredFeed[]
  selectedFeedIds: string[]
  results: ScoredArticle[]
  createdAt: number
}

Persistent — Erweiterung von newsPreferences:

customFeeds: Array<{
  id: string
  url: string
  title: string
  topic?: NewsTopic
  pinnedAt: number
}>

Kein neues Dexie-Table. Reading-List-Saves gehen in newsArticles wie bisher.

UI-Flow

1. /news-research Landing: Query-Feld + Site-URL-Feld.
2. Discovery-Ergebnis: Liste gefundener Feeds (Name, Item-Count, Sample-Topics). User hakt relevante an, kann pinnen.
3. Filter: Thema-Chips, Keyword-Filter, Zeitraum.
4. Ergebnis: Artikel-Liste sortiert nach Relevanz. Actions pro Artikel: Save (→ newsArticles), Open, Add to Context.
5. Context-Paket: Button "Export as AI Context" → erzeugt einen strukturierten Markdown-/JSON-Block, der in eine Mission/Chat übernommen werden kann.

KI-Integration

• Neues LLM-Tool research_news(query, options) in tools.ts (Geschwister zu save_news_article).
• Rückgabe: Context-Paket (Top-N Artikel mit Excerpt + URL + Publish-Date).
• Agent kann eigenständig eine Research-Session fahren, ohne UI.

Milestones

M1 — packages/shared-rss extrahieren

• Neues Workspace-Package anlegen
• Parser aus news-ingester verschieben, Service migrieren
• extractArticle aus apps/api verschieben, Endpoint migrieren
• discoverFeeds neu implementieren (rel=alternate)
• validateFeed neu

M2 — API Routes

• apps/api/src/modules/news-research/routes.ts mit /discover, /validate, /extract
• Websuche-Integration für Query-basierte Discovery
• /search — lädt Feeds parallel, wendet Relevanz-Scoring an

M3 — Frontend-Modul

• Modulstruktur + types
• Session-Store, Pinned-Store
• /news-research Route + UI (Discovery → Filter → Ergebnis)
• Save-Action in newsArticles (reuse articlesStore.saveFromUrl)
• "Export as AI Context"

M4 — customFeeds als Abo-Funktion

• newsPreferences.customFeeds Field + Encryption-Allowlist
• UI in news/ zur Verwaltung
• Optional: feed-cache lädt auch customFeeds und merged im globalen Feed-Engine

M5 — KI-Tool

• research_news LLM-Tool
• Context-Paket-Format dokumentieren
• Mission-Beispiel in missions/debug.ts oder neue Mission

Offene Fragen

• Websuche-Backend: mana-search nutzen oder direkt SearXNG/Brave-API? → Entscheidung vor M2.
• Relevanz-Scoring: Reicht lokales BM25 über Excerpts, oder Embedding-basiert via mana-llm? → Lokal starten, Embeddings als Phase 2.
• Feed-Caching serverseitig: Feeds pro Query erneut fetchen (Kaltstart) oder kurzlebiger Redis-Cache? → Ohne Cache starten, messen.
• Topic-Taxonomie: Die 7 News-Topics übernehmen oder frei (Tags)? → Frei, mit Vorschlägen aus News-Topics.