1<h1 align="center">llm_aggregator</h1>
  2
  3<p align="center">
  4    <img src="assets/logo.svg" alt="LLM Aggregator logo" width=500>
  5    <br>
  6    <strong>Aggregate RSS feeds and summarise them with LLMs</strong>
  7</p>
  8
  9![Codeberg Release](https://img.shields.io/gitea/v/release/maxwelljensen/llm_aggregator?gitea_url=https%3A%2F%2Fcodeberg.org&style=for-the-badge)
 10![Codeberg License](assets/eupl-12-badge.svg)
 11
 12---
 13
 14## What is it?
 15
 16`llm_aggregator` fetches articles from multiple RSS/Atom feeds, filters and
 17processes the content, and sends it to any OpenAI-compatible LLM to produce a
 18concise summary, without reading dozens of posts.
 19
 20**Supports**: RSS 2.0, Atom, JSON Feed | OpenAI-compatible APIs | Local LLMs
 21(Ollama, etc.) | TUI with live progress | Text/Markdown/JSON output
 22
 23---
 24
 25## Quick start
 26
 27```bash
 28# Create a feeds file
 29cat > feeds.txt << 'EOF'
 30https://news.ycombinator.com/rss
 31https://lwn.net/headlines/newrss
 32EOF
 33
 34# Run
 35llm_aggregator --api-key <YOUR_KEY> --base-url <URL> \
 36-f feeds.txt -p "What are the top tech stories today?"
 37```
 38
 39**First run?** See [docs/USAGE.md](docs/USAGE.md) for installation, configuration,
 40and all available options.
 41
 42---
 43
 44## Key features
 45
 46| | |
 47|--|--|
 48| 🚀 | Concurrent feed fetching with rate limiting |
 49| 🔍 | Keyword filtering (include/exclude, case‑insensitive) |
 50| 📅 | Date‑based filtering and sorting (date/title/source) |
 51| 🤖 | Any OpenAI-compatible API (Deepseek, Ollama, OpenRouter, …) |
 52| 🖥️ | Interactive TUI with progress bar and mouse scrolling |
 53| 📦 | Config file, environment variables, and CLI flags |
 54| 📄 | Read feeds directly from stdin via `--stdin` |
 55| 🔧 | Dry‑run mode to validate config without API calls |
 56
 57---
 58
 59## TUI mode
 60
 61Enable the TUI with `-t` for a colourful progress bar, live article counters,
 62and elapsed time. The TUI renders LLM output as styled Markdown (headers,
 63bold, code blocks, lists) and supports keyboard navigation (j/k, arrows, b,
 64g/G) and mouse wheel scrolling.
 65
 66![LLM Aggregator action in GIF](./assets/demo.gif)
 67
 68---
 69
 70## Architecture
 71
 72```
 73Feeds file / stdin
 74        ↓
 75  ┌─────────────┐
 76  │  aggregator │   RSS/Atom/JSON Feed parsing, concurrent fetching
 77  └─────────────┘
 78        ↓
 79  ┌─────────────┐
 80  │  processor  │   Filter by keywords/age, sort, truncate
 81  └─────────────┘
 82        ↓
 83  ┌─────────────┐
 84  │     llm     │   OpenAI-compatible API call
 85  └─────────────┘
 86        ↓
 87  ┌─────────────┐
 88  │   output    │   Text / Markdown / JSON
 89  └─────────────┘
 90```
 91
 92## Configuration precedence
 93
 94```
 95CLI flags  >  Environment variables  >  Config file  >  Defaults
 96```
 97
 98Create `~/.config/llm_aggregator/config.toml` (see
 99[docs/USAGE.md](docs/USAGE.md#configuration) for the full reference).
100
101## Building
102
103Detailed build instructions (standard build, goreleaser, cross-compilation,
104man page installation, tests, and linting) are in
105[docs/BUILD.md](docs/BUILD.md).
106
107---
108
109## Licence
110
111This project is licensed under [European Union Public Licence
1121.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12).