fedipulse

A fediverse feed aggregator with Bayesian interest learning. Subscribe to accounts and servers, vote posts up/down, and let the classifier surface what matters to you.

Features

• Subscribe to Mastodon accounts or entire server timelines
• Bayesian classifier (Naive Bayes) learns from your votes which posts are interesting
• LLM-friendly API (/llm/queue, /llm/vote) for automated initial training
• Mobile-optimised web UI: swipe to vote, read confident posts, threshold slider
• REST API with Prometheus metrics

Quick start

cp env.example .env
# Edit .env and set API_KEY
mkdir -p data
task migrate
task up

The app listens on port 8000.

Web UI

URL	Description
/queue	Swipe-to-vote interface for uncertain posts
/feed	Read posts the classifier is confident about

Security: The UI has no built-in authentication. Protect it with Basic Auth at your reverse proxy (nginx, Caddy, etc.). Example for Caddy:

basicauth /queue* {
    tim <bcrypt-hash>
}
basicauth /feed* {
    tim <bcrypt-hash>
}

The REST API (/posts, /subscriptions, /llm, etc.) is protected by X-API-Key header, configured via the API_KEY environment variable.

API

Interactive docs available at /docs when the app is running.

Key endpoints:

• POST /subscriptions — add an account or server subscription
• GET /posts — paginated feed with filters (sort_by, min_favourites, min_reblogs, scored_only)
• GET /posts/trending — top posts by engagement in the last 24h
• POST /posts/{id}/vote — vote a post up (+1) or down (-1)
• GET /llm/queue — plain-text post summaries for LLM voting
• POST /llm/vote — batch vote endpoint for LLM agents
• GET /metrics — Prometheus metrics

Environment variables

Variable	Default	Description
API_KEY	(required)	Shared API key for REST endpoints
DATABASE_URL	sqlite:///./data/fedipulse.db	SQLite database path
ACCOUNT_FETCH_INTERVAL	300	Seconds between account fetches
SERVER_FETCH_INTERVAL	600	Seconds between server timeline fetches
RETRAIN_EVERY_N_VOTES	10	Retrain classifier after every N votes
INTERESTING_THRESHOLD	0.95	Minimum score to show in the feed
UNCERTAIN_LOWER	0.05	Lower bound of uncertain range for voting queue
UNCERTAIN_UPPER	0.95	Upper bound of uncertain range for voting queue
LOG_LEVEL	INFO	Logging level

Development

python3 -m venv .venv
task venv   # installs deps
task test   # run tests
task lint   # ruff + mypy + bandit

Pre-commit hooks are configured. Install with .venv/bin/pre-commit install.

Releasing

1. Add a ## [x.y.z] section to CHANGELOG.md
2. Push to main
3. Push a vx.y.z tag — the CI workflow builds the Docker image and creates a Forgejo release automatically