Metadata-Version: 2.4
Name: fitolit
Version: 0.1.0
Summary: Monitor journal RSS feeds and let an LLM surface only the papers that match your research profile.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: dataclasses-json>=0.6.7
Requires-Dist: feedgen>=1.0.0
Requires-Dist: feedparser>=6.0.12
Requires-Dist: json5>=0.14.0
Requires-Dist: openai>=2.40.0
Requires-Dist: platformdirs>=4.10.0
Requires-Dist: requests>=2.34.2
Requires-Dist: trafilatura>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Fitolit

A simple Python tool that finds new scientific papers that match your research interests.

## Why?

SO MANY PAPERS are published every day. Some people have the magic ability to sift through this noise and find the papers that are nice and/or relevant. I am not one of them. I wrote Fitolit to automate the process of finding papers that match my interests. It is not perfect, but it does a good job of filtering out irrelevant papers, and reducing the volume of papers you need to sift through.

Fitolit monitors the RSS feeds of journals you care about, sends each paper's abstract to an LLM, and writes the papers that match your profile to a personal RSS feed. Follow that feed in any RSS reader (e.g. [FreshRSS](https://github.com/FreshRSS/FreshRSS), [Newsflash](https://gitlab.com/news-flash/news_flash_gtk), ...). And that is all there is to it.

## How it works

```
Journal RSS feeds  →  fetch abstracts  →  LLM (via OpenRouter)  →  personal RSS feed
```

1. Fitolit polls the RSS feeds of papers, listed in the `paper_feed.json5` config file.
2. For each new paper, it fetches the abstract and sends it to an LLM along with your profile prompt.
3. Papers the LLM marks as relevant are appended to an RSS file on your machine.

## Prerequisites

- An [OpenRouter](https://openrouter.ai) account and API key: used to call the LLM.
- [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) installed: most/all journal websites block automated requests. Running FlareSolverr in a Docker container is the easiest workaround.

## Installation

```bash
pipx install fitolit
```

(or use `uvx fitolit`)

Then initialise the config files:

```bash
fitolit initialize
```

This creates `settings.json5`, `paper_feed.json5`, and `secrets.json5` in your platform's config directory and prints their exact paths. During initialisation you will be asked where to save the output RSS feed.

## Configuration

All three config files use [JSON5](https://json5.org/) syntax (supports comments and trailing commas).

### `settings.json5`

#### `llm`

| Key | Description |
|---|---|
| `model_to_use` | The OpenRouter model identifier to use, e.g. `z-ai/glm-4.5-air`. Cheaper models work ok. See the [OpenRouter model list](https://openrouter.ai/models). |
| `prompt` | A description of your research interests. See [the example settings file](./fitolit/example_settings/example_settings.json5) for a prompt template. **Do not remove the final sentence about the JSON schema.** Adding a few example paper titles (good and bad) works well for fine-tuning. |
| `max_length` | Maximum number of characters read from each abstract. Prevents a 50-page review article accidentally eating all your tokens. |

#### `rss`

| Key | Description |
|---|---|
| `final_feed` | Path to the output RSS file on your machine, e.g. `/home/user/papers.xml`. |

#### `flaresolverr_url`

URL of your FlareSolverr instance, e.g. `http://localhost:8191/v1`.

### `paper_feed.json5`

A JSON5 array of RSS feed URLs for the journals you want to monitor. The example file includes some random feeds for Nature, Science, ACS, arXiv, and others. Edit it to match your interests.

If a journal's RSS feed isn't easy to find, try [Lighthouse Feed Finder](https://lighthouseapp.io/tools/feed-finder).

### `secrets.json5`

```json5
{
  "openrouter_key": "your-api-key-here"
}
```

Storing the key here is convenient but saves it as plain text. Alternatively, pass it at runtime with `--openrouter_key` (see below).

## Usage

```bash
fitolit run
```

If you did not set the API key in `secrets.json5`, pass it directly:

```bash
fitolit run --openrouter_key YOUR_KEY
```

Add `--log-to-file` to write logs to a file instead of the terminal (useful when running in the background).

## Running on a schedule

A run is pretty slow - the LLM has a lot of papers to churn trough. Especially the first run may take a while. The first time, run it where you can check in on it once every few minutes. Once you have confirmed things works, set up a daily cron job:

```
30 8 * * * fitolit run --log-to-file
```

## Costs

Running this will cost you roughly €2/month using a cheap model (e.g. `z-ai/glm-4.5-air`). Cost will go up if you:
- use an expensive model,
- monitor many journals, 
- have a high `max_length`, or 
- have a long research profile

So keep that in mind. It is probably wise to configure some usage limits in OpenRouter, and check in once in a while.
