Metadata-Version: 2.5
Name: rss-digest
Version: 0.0.8
Summary: Generate an RSS digest from any GReader-compatible feed reader using an LLM
Project-URL: Homepage, https://github.com/edsu/rss-digest
Project-URL: Repository, https://github.com/edsu/rss-digest
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx
Requires-Dist: litellm
Requires-Dist: markdown
Requires-Dist: pydantic-settings
Requires-Dist: python-dotenv
Description-Content-Type: text/markdown

<div align="center">
<pre>
══════════════════════════
    R S S  D I G E S T
══════════════════════════
</pre>
</div>

[![CI](https://github.com/edsu/rss-digest/actions/workflows/ci.yml/badge.svg)](https://github.com/edsu/rss-digest/actions/workflows/ci.yml)

Generates a digest from your self-hosted RSS reader using your choice of LLM. Instead of scrolling through hundreds of unread articles, you get a single readable summary grouped by theme — delivered as a Markdown or HTML file.

## What you need

- A self-hosted RSS reader that supports the [GReader API](#compatible-readers) (FreshRSS, Miniflux, etc.)
- An API key for an AI service (Anthropic, OpenAI, or a local model — see [Choosing a model](#choosing-a-model))
- [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/) for installation

## Installation

```bash
# with uv
uv tool install rss-digest

# with pipx
pipx install rss-digest
```

## Quick start

```bash
# Set your secrets
export GREADER_PASSWORD=yourpassword
export ANTHROPIC_API_KEY=sk-ant-...

# Generate a digest of the last 24 hours
rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname
```

The digest is written to `digest-YYYY-MM-DD.md` in the current directory. Pass `--html` to get an HTML file instead.

## Configuration

Settings are passed on the command line, grouped by the service they configure. Only secrets come from the environment: the GReader password from `GREADER_PASSWORD`, and your LLM provider's API key from its own variable (see [Choosing a model](#choosing-a-model)).

Instead of exporting them, you can put the secrets in a `.env` file in the directory you run `rss-digest` from. Variables already set in the environment take precedence over the file.

```bash
# .env
GREADER_PASSWORD=yourpassword
ANTHROPIC_API_KEY=sk-ant-...
```

**Feed reader (GReader API)**

| Option | Default |
|--------|---------|
| `--greader-url URL` | *(required)* the reader's GReader API endpoint (see [Compatible readers](#compatible-readers)) |
| `--greader-username USER` | *(required)* |
| `--mark-read` | off |

**LLM**

| Option | Default |
|--------|---------|
| `--model MODEL` | `anthropic/claude-sonnet-5` |
| `--model-url URL` | the provider's endpoint |
| `--prompt-file FILE` | built-in prompt |
| `--print-prompt` | off ([print the prompt and exit](#inspecting-the-prompt)) |

**Digest**

| Option | Default |
|--------|---------|
| `--hours N` | `24` |
| `--archive-dir DIR` | off (no history) |
| `--history N` | `3` |
| `--summary-length N` | `1000` ([how much of each article is sent](#how-much-of-each-article-is-sent)) |
| `--html` | off |
| `--output PATH` | `./digest-YYYY-MM-DD.md` |
| `--quiet` | off |
| `--verbose` | off |
| `--log-file FILE` | off |

The examples below leave out `--greader-url` and `--greader-username` to keep them short; every real run needs both.

```bash
# Last 48 hours, HTML output
rss-digest --hours 48 --html

# Use a different model
rss-digest --model openai/gpt-4o
```

## How much of each article is sent

Each article reaches the LLM as its title, link, feed name and the first
`--summary-length` characters of the text the feed published (default 1000).
That's what the digest has to work with: from a headline and a one-line lede the
model can only restyle the headline, while a few paragraphs let it say what the
piece actually argues or reports.

How much text there is depends on the feed. Many blogs and long-form publications
put the whole article in the feed; news sites often send a teaser of a sentence
or two, and some send nothing at all. `--verbose` prints, for each feed, how many
articles came in and the median and longest text length, thinnest feeds first:

```
Summary length per feed (characters, before --summary-length):
feed                                             n  median     max
Hugging Face - Blog                              3       0       0
NYT > Technology                                 9     263     404
3 Quarks Daily                                  12    1130    7320
ProPublica                                       2   11715   14533
```

A longer `--summary-length` only helps feeds that have the text. It costs prompt
tokens in proportion: about 150 articles at 2000 characters is roughly
60k tokens. A busy reader with many hundreds of articles a day may need a lower
setting to stay inside the model's context window; `--summary-length 0` sends
titles only.

### Link roundups

Posts that are mostly a list of other people's links (Hacker News Daily,
newsletters, links blogs) are sent differently. Reduced to text, such a post is a
run of headlines with no URLs, so the model could neither link nor weigh them.
Instead each recommended link is sent as an item of its own, under a heading that
names the roundup, and the model is asked to file them by theme alongside
everything else and credit the roundup in passing ("via Hacker News Daily").

A post counts as a roundup when most of its text is link text and the links open
their list items or headings, as headlines do. Essays that cite heavily, and posts
with a link in each paragraph, are left as they are. Links back to the roundup's
own site, front-page links and "(comments)"-style links are skipped. With
`--print-prompt` you can see which posts were split.

## Continuity between digests

Point `--archive-dir` at a folder of past digests and they're sent along with the
new articles, inside a `<previous_digests>` block, so the LLM can follow up on
ongoing stories and avoid re-telling one it already covered — feeds echo each
other, and the same story often arrives from three sources over two days.

```bash
# Keep the digests you've read in one folder, then feed them back
rss-digest --archive-dir ~/Documents/rss-digests
```

**Nothing is ever written to `--archive-dir`.** You file digests there yourself,
which is the point: the folder holds only what you actually read, so that's what
shapes the next digest.

Any `.md` or `.html` file in the folder counts, whatever it's named — so however
you set `--output`, it works. HTML is converted back to markdown, and the
generated header, stats line and footer are stripped. Each digest is dated by the
date in its filename if there is one, otherwise by when the file was created;
anything dated today is skipped, so running twice in one day won't feed a digest
to itself.

Without `--archive-dir` there's no history and nothing changes. `--history N`
tunes how many digests to send (default 3) and requires `--archive-dir`.

There is no separate "context" parameter in a chat completion — the block is just
text prepended to the user message. Measured on a 151-article day with
`count_tokens`, at an earlier 300-character summary length: 25.5k tokens for the articles and ~3k per digest of history, so
`--history 3` puts the whole prompt near 35k. History is a real third of the
prompt at that setting, but a fraction of a cent per run — nothing worth
compressing.

The trade-off worth watching is anchoring: given yesterday's digest, a model will
happily reproduce yesterday's section headings and manufacture continuity where
there is none. The system prompt guards against this explicitly, and that guidance
is appended to your own prompt too when you use `--prompt-file`, so custom
prompts don't lose it. If a digest still reads like the previous day's, compare
against a run with `--archive-dir` left off.

## Choosing a model

`rss-digest` uses [LiteLLM](https://docs.litellm.ai/), so any model it supports works. Set the `--model` flag to a LiteLLM model string and export the corresponding API key. To use an OpenAI-compatible API or a LiteLLM gateway, point `--model-url` at it.

**Anthropic (default)**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
rss-digest --model anthropic/claude-sonnet-5
```

**OpenAI**
```bash
export OPENAI_API_KEY=sk-...
rss-digest --model openai/gpt-4o
```

**Local model via [LM Studio](https://lmstudio.ai)**

LM Studio lets you run models on your own machine with no API key or usage costs.

1. Download and open LM Studio, load a model (Mistral, Llama, Gemma, etc.)
2. Start the local server: **Local Server** tab → **Start Server**
3. Copy the [model identifier] shown in the UI (e.g. `google/gemma-4-12b-qat`)
4. Invoke `rss-digest` with the `--model` parameter, but prefixing the model
   identifier with `openai/`, e.g. `openai/google/gemma-4-12b-qat`.

```bash
export OPENAI_API_KEY=lm-studio

rss-digest --model-url http://localhost:1234/v1 --model openai/google/gemma-4-12b-qat
```

The `OPENAI_API_KEY` value is ignored by LM Studio but required by the LiteLLM library — set it to anything. The model name after `openai/` must match the identifier shown in LM Studio's server tab.

**LiteLLM gateway or other OpenAI-compatible API**

Hosted gateways built on [LiteLLM](https://docs.litellm.ai/docs/simple_proxy), such as [Inference Coop](https://inference.coop), let you use many models through one account. Prefix the gateway's model name with `litellm_proxy/` and put your gateway key in `LITELLM_PROXY_API_KEY`:

```bash
export LITELLM_PROXY_API_KEY=sk-...

rss-digest --model-url https://gateway.inference.coop --model litellm_proxy/MODEL_NAME
```

To list the model names the gateway offers:

```bash
curl -H "Authorization: Bearer $LITELLM_PROXY_API_KEY" https://gateway.inference.coop/v1/models
```

For any other OpenAI-compatible API, use the `openai/` prefix and `OPENAI_API_KEY` instead, as in the LM Studio example above.

For digest-length tasks, a 7B–14B instruction-tuned model works well. Larger context windows (32k+) are helpful if you have many unread articles.

## Customizing the prompt

The built-in prompt decides how articles are grouped and how much to include. For ≤25 articles it lists everything; for larger batches it writes a curated prose summary.

```
You are producing a digest of RSS articles.

Format rules:
- ≤25 articles: Reading queue. Group by theme under ### headings. List every
  article as a bullet with a markdown link. Include the feed name.
- >25 articles: Curated TL;DR. Themed prose under ### headings. Cover roughly
  ⅓ of articles. Drop filler (sponsored posts, job listings, police blotters,
  sub-100-word link-outs). Dense single-feed clusters (6+ posts): pick 2–3
  representatives, then "and N more from [feed name]".

Every article title you mention must be an inline markdown link. Be concise.
```

To use your own prompt, write it to a text file and pass it with `--prompt-file`:

```bash
rss-digest --prompt-file my-prompt.txt
```

Example prompt that keeps things very short:

```
You are summarizing RSS articles for a busy reader.
Write a single short paragraph (5–8 sentences) covering the most important stories.
Do not use bullet points or headings. Every article title must be a markdown link.
```

The user message sent to the model is always a structured list of articles grouped by feed, so your prompt only needs to describe the desired output format.

### Inspecting the prompt

To see the exact system prompt and user message that would be sent to the model — without making any LLM call — use `--print-prompt`:

```bash
rss-digest --print-prompt
```

This is useful for iterating on a custom prompt, checking which articles were fetched, or piping the content to another tool.

## Example output

See [example.md](example.md) for a real digest. A short excerpt:

```markdown
# RSS Digest — 2026-06-10

*137 articles · 53 sites*

### Science & Environment

NASA [announced the all-male Artemis III crew](https://www.nytimes.com/2026/06/09/science/space/artemis-iii-astronauts-nasa-crew.html) and faces questions about [whether a 2028 moon landing is realistic](https://www.nytimes.com/2026/06/09/science/space/nasa-artemis-moon-landing.html) given dependence on Musk and Bezos. Indonesia's landslides [wiped out over 5% of the endangered orangutan population](https://www.nytimes.com/2026/06/10/climate/indonesia-floods-organgutans.html). And scientists [accidentally found that crowds worldwide spontaneously walk counterclockwise](https://www.404media.co/scientists-just-accidentally-discovered-a-strange-hidden-rule-of-human-nature/).

### Culture & Ideas

3 Quarks Daily examines [what AGI means for the future of physics](https://3quarksdaily.com/3quarksdaily/2026/06/adam-brown-agi-the-future-of-physics.html), and Dina Nayeri writes on [Iran's stolen revolution and the failures of diaspora narrative](https://3quarksdaily.com/3quarksdaily/2026/06/stolen-revolution.html). Iron & Wine's Sam Beam [reflects on always developing and changing as an artist](https://thecreativeindependent.com/people/musician-sam-beam-iron-and-wine-on-always-developing-and-changing/). A fascinating science/humanities crossover: [ELIZA and what a 1966 chatbot's horrified inventor tells us about modern voice AI](https://cafebedouin.org/2026/06/10/eliza-learned-to-breathe/).
```

## Running on a schedule

To get a fresh digest every morning, add a crontab entry. Cron runs jobs with a minimal environment, starting in your home directory, so use the full path to the binary and give it its secrets explicitly.

```bash
# find the full path first
which rss-digest
```

The simplest way to supply the secrets is a `.env` file (see [Configuration](#configuration)) in a directory of your choice, which the job `cd`s into first. Open your crontab with `crontab -e` and add:

```crontab
# Run at 6am every day, write an HTML digest to a specific folder
0 6 * * * cd /Users/yourname/rss-digest && /Users/yourname/.local/bin/rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname --html --quiet --log-file /tmp/rss-digest.log --output /Users/yourname/Documents/digest.html
```

Alternatively, set the secrets in the crontab itself. Crontab env-var lines apply to every job below them in the file, including unrelated ones, which is one reason to prefer `.env`:

```crontab
GREADER_PASSWORD=yourpassword
ANTHROPIC_API_KEY=sk-ant-...

0 6 * * * /Users/yourname/.local/bin/rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname --html --quiet --log-file /tmp/rss-digest.log --output /Users/yourname/Documents/digest.html
```

### Using digests you've read as context

Write each morning's digest somewhere you'll see it, and file the ones you read
into a folder you pass as `--archive-dir`. Continuity then reflects only what you
actually read, and the job never writes into the folder you curate by hand:

```crontab
0 6 * * * cd /Users/yourname/rss-digest && /Users/yourname/.local/bin/rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname --html --quiet --archive-dir /Users/yourname/Documents/rss-digests --output /Users/yourname/Desktop/`date +\%Y-\%m-\%d`.html
```

## Development

```bash
uv sync              # install, including dev dependencies
uv run pytest        # tests
uv run ty check      # type checking
uv run ruff format   # formatting
```

CI runs all three on Python 3.12 and 3.13 for every push to `main` and every
pull request, with `ruff format --check` so unformatted code fails the build.
`ty` and `ruff` are unpinned in `pyproject.toml`, but CI installs from `uv.lock`,
so the version only moves when you run `uv lock` — both are pre-1.0, and a new
release can add checks or change formatting, so it's better to see that as a
diff than as a surprise red build.

This project was bulk-reformatted once. To keep that commit out of `git blame`:

```bash
git config blame.ignoreRevsFile .git-blame-ignore-revs
```

## Compatible readers

Any RSS reader that implements the GReader API should work:

| Reader | `--greader-url` | Notes |
|--------|-----------------|-------|
| [FreshRSS](https://freshrss.org) | `https://freshrss.example.com/api/greader.php` | Enable the GReader API in Settings → Authentication |
| [Miniflux](https://miniflux.app) | `https://miniflux.example.com` | Enable Google Reader API in Settings |
| [Tiny Tiny RSS](https://tt-rss.org) | see the plugin's documentation | Requires the [News+/GReader plugin](https://github.com/hrk/tt-rss-newsplus-plugin) |
| [The Old Reader](https://theoldreader.com) | `https://theoldreader.com` | Hosted service with GReader-compatible API |

`--greader-url` is the address that the GReader API paths (`/accounts/ClientLogin`, `/reader/api/0/...`) hang off. If your reader's documentation gives a "Google Reader API" or "GReader API" URL, use that.
