Hermes architecture: a 10-minute tour (as of 2026-10-17) A developer has published a specification for Hermes, a nightly Python agent that assembles a personalized "serendipity dispatch" of one discovery, one deep dive, one build idea and one markets note. The design keeps the LLM confined to selecting numbered indices from a pre-verified shortlist, so all fetching, URL verification and rendering stay deterministic and the model cannot hallucinate a link. The pipeline pulls from Hacker News, arXiv, GitHub Trending and RSS feeds, ranks candidates by keyword and recency, checks links before curation, and falls back to deterministic picks if the LLM call fails three times. A single Python agent that runs nightly and produces a serendipity dispatch: one surprising discovery, one deep dive, one build idea, and one markets note. Not morning news — things the owner wouldn't have found on their own. Feed this document to an AI assistant Muse, etc. and ask it to implement the agent. Everything below is a specification, not code. 1. What it does pipeline Discovery no LLM → interest-aware ranking → URL verification → LLM curation picks by index → deterministic rendering → dispatch + teaser Key design rule: the LLM only selects returns indices . All fetching, rendering, and link insertion is deterministic code. The model can never hallucinate a URL because it never writes one. 2. Schedule Runs once nightly at 2:00 AM local time via cron. Single-flight: use a lock file so overlapping runs are impossible. Timeout budget: ~15 minutes max LLM retries are the long pole . 3. Discovery sources no LLM, pure HTTP Source What to fetch Hacker News Top stories via the official Firebase API hacker-news.firebaseio.com arXiv Recent papers via the arXiv API, filtered to the owner's interest areas GitHub Trending Scrape github.com/trending daily RSS feeds A configurable list of feeds tech, science, finance ; parse with stdlib xml.etree Each candidate is a dict: {title, url, source, summary, published at}. Respectful fetching: declare a User-Agent identifying the bot. For SEC EDGAR if used , the UA must contain an email-shaped contact or requests get 403. 4. Interest-aware ranking no LLM Maintain a keyword list representing the owner's interests e.g. AI agents, local LLMs, prediction markets, options, FPL, home automation . Score each candidate: keyword hits in title/summary, recency boost, source diversity cap max N per source so one source can't dominate . Dedupe against a seen.json of URLs already dispatched persist across runs . 5. URL verification no LLM HEAD/GET each shortlisted URL with a short timeout ~8s . Drop dead links before they reach the LLM. A dispatch with a 404 is a failure. 6. LLM curation Send the verified shortlist numbered, with titles + summaries to the LLM with a prompt like: "You are curating a nightly serendipity dispatch. Pick the 4 most surprising, non-obvious items from the list below. Return ONLY the indices, e.g. 3, 7, 12, 18. One pick each for: a discovery something new , a deep dive worth 20 minutes , a build idea something to make , a markets note interesting prediction-market or options movement . Skip anything that reads like press-release hype." The model returns indices only. Map them back to candidates in code. Retry the LLM call up to 3 times on failure; after that, fall back to the top-ranked deterministic picks so the dispatch still ships. 7. Markets note deterministic Query the Kalshi public API anonymous, read-only for the biggest price movers in the last 24h. Render the top 5 movers with before/after prices. No LLM needed, no trading, no orders — read-only market data. 8. Wonderings rotation Keep a wonderings.md file: a running list of open questions/curiosities. Each night, pick the oldest uncovered wondering for the deep-dive slot, then mark it covered. When the list is exhausted, the LLM generates fresh wonderings from recent discoveries. Never repeat a covered wondering. 9. Output Two files per night in data/dispatches/YYYY-MM-DD.md: Dispatch — markdown with the 4 sections, each with title, link, 2–3 sentence why-it-matters, and source attribution. Teaser — a 2-line push notification text sent via ntfy, see below . Also write data/latest.md symlink or copy of the newest dispatch and data/teaser.txt for the notification pipeline. 10. Notifications Send the teaser via ntfy self-hosted or ntfy.sh when the dispatch is ready. If the run fails entirely, send a failure notice instead of staying silent. Never send "ready" if the dispatch wasn't actually written. 11. State files all JSON, atomic writes File Purpose data/seen.json URLs already dispatched dedupe data/wonderings.md Open questions rotation data/status.json Last run status: ok flag, source counts, timestamp data/dispatches/ One markdown file per night, kept indefinitely Write state atomically temp file + rename , never in-place rewrites. 12. Failure discipline non-negotiable Never mark a candidate seen until it is successfully dispatched. Every retry loop: attempt counting, a ceiling, a fallback, a notification. If all LLM calls fail, still write the dispatch from deterministic picks — a thinner dispatch beats a missing one. Log every run; a silent failure is the worst outcome. 13. Dependencies Python 3 stdlib + requests. That's it. One LLM API endpoint any OpenAI-compatible API works — LiteLLM proxy, OpenAI, Groq, local Ollama, etc. . Cron. A lock file. A directory. 14. What it is NOT Not a news aggregator — no headlines the owner already saw. Not a trading bot — the markets note is observational only. Not a chatbot — it produces one artifact per night, no conversation. Status as of 2026-10-17. Diagrams are Mermaid and render on GitHub. Facts that drift agent list, schedules are in CLAUDE.md and manifests/; this document explains how it fits together and why. 1. What Hermes is About 15 small, cron-driven Python agents on one free Oracle Cloud ARM VM, plus a phone-first dashboard, a private push-notification server, and two paper forecasting/trading labs. It watches email, school, flyers, fantasy football, prediction markets and options, and tells the owner only what matters. Everything is $0: free VM, free-tier model APIs, local Ollama. flowchart LR subgraph World "Outside world read-only " MAIL iCloud mail