ClearFeed/AGENTS.md

AGENTS.md — project law for dsh (DeepSeek Harness)

What this is

A story layer that sits next to a stock FreshRSS reader (Docker) and turns its syndicated feed items into ranked, deduplicated, optionally-LLM-summarized "stories". FreshRSS + RSSHub run in Docker. Everything in this repo is the thin Python layer on the host that does fetch → cluster → rank → optional LLM.

Hard rules (violating these fails the task)

1. Keep the test suite green. pytest in prototype/ must pass before and after every change. The core accept is "two reworded copies → one cluster".
2. Do NOT rebuild FreshRSS. It is a stock container. No fork, no replacement, no patches to it.
3. Do NOT add Kafka (or any broker). Async workers + SQLite/JSON is the ceiling.
4. Do NOT add a frontend framework. prototype/out/index.html is a generated, self-contained static page. No React/Vue/Next/HTMX build tooling.
5. Cap the LLM. Only the top-k ranked stories (default 10, flag --topk) get summarized; input is headline + first ~300 chars. Never the long tail.
6. Story summaries point at the HOST Hermes/llama.cpp, never at DeepSeek. LLM_BASE_URL defaults to http://127.0.0.1:8080/v1, model hermes. Coding work may use DeepSeek; news summaries must not — unless the operator explicitly overrides LLM_BASE_URL.
7. Do not change ports. FreshRSS = 8280, RSSHub = 1200, Hermes = 8080, --serve = 8765. 8280 exists so FreshRSS does not steal llama.cpp's 8080.

Feature backlog (already spec'd — just implement)

• cluster.py --serve :8765 — serve prototype/out/ on port 8765.
• LLM top-k cap — enforce --topk everywhere (done in current code; keep it).
• Snapshot mode — --snapshot JSON ingests a FreshRSS export with no Docker.

Interfaces

• python cluster.py [--opml feeds.opml | --snapshot x.json] [--llm] [--topk N] [--serve :8765]
• Env (only for --llm): LLM_BASE_URL, LLM_MODEL.
• Output: prototype/out/index.html + prototype/out/stories.json.