Last updated
3/14/2025
Get started
Fetch Posts & Generate Embeddings with LLM
Personalized Timeline
Build Your Own Timeline Algorithm
This blueprint introduces an approach to personal, local timeline algorithms that people can either run out-of-the-box or customize. It relies on a stack which makes use of Mastodon.py to get recent timeline data, llamafile to calculate post embeddings locally, and marimo to provide a UI that runs in one’s own browser. Using this stack, you can visualize, search, and re-rank posts from the fediverse without any of them leaving your computer
Time
10 min
Complexity
Medium
Moderately complex. Some challenges but manageable
Preview this Blueprint in action
Hosted demo
Step by step walkthrough
Tools used to create
Trusted open source tools used for this Blueprint
Choices
Insights into our motivations and key technical decisions throughout the development process.
Focus
Decision
Rationale
Alternatives Considered
Trade-offs
Overall Motivation
Overall Motivation
Build a local, privacy-friendly, customizable timeline algorithm for the Fediverse.
Empower users and developers to experiment with different algorithms to run on their timelines.
Grounded in previous experiments on the Fediverse such as those in slide 12 (https://fosdem.org/2025/events/attachments/fosdem-2025-5601-build-your-own-timeline-algorithm/slides/238176/20250201_FKfeAcS.pdf)
While timeline algorithms should always be optional, giving people a choice without compromising on privacy can improve their experience (possibly helping with migration from closed platforms to open ones).
Data Source
Data Source
Use Mastodon.py to fetch posts from Mastodon timelines.
Powerful, well documented, open-source Python client with good API coverage. Mastodon API is open and aligned with user privacy (see e.g. the “discoverability” flag for user accounts).
As we are currently working mainly on textual content, we could support any open API, or even closed ones for ComCom (https://www.eff.org/deeplinks/2020/12/competitive-compatibility-year-review) from social media or other content sources (e.g. RSS).
Mastodon covers a good part of the Fediverse, but just a part.
Model Server
Model Server
Use llamafile for local model serving; support for Ollama.
Local-first and reasonably fast, no GPU requirement.
Running a local HF pipeline (often too slow). Hitting a remote API for embeddings (not privacy preserving).
Local requires smaller model (but that’s also a good excuse to show we do not need LLMs for everything 🙂). We are still compatible with remote APIs, if users wanted to share a trusted, open embedding server.
Embeddings Model
Embeddings Model
Use all-MiniLM-L6-v2 (https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2).
Tiny (50MB), has open code, research papers, and training datasets available.
Larger models (https://fosstodon.org/@mala/113967543519771440), based either on bert or llama architectures.
Larger models can take up to 10x the time on older hardware. Most LLMs are not really open (as they lack information about training data).
Algorithmic Approach
Algorithmic Approach
Semantic text similarity.
Fast, interpretable and easy to understand. Can be used not just for ranking but also for search, clustering, recommendations. Collection of posts can describe users, lists, timelines, even Mastodon instances to some extent.
Similarity based on non-textual features.
Text similarity is definitely limited in the context of a commercial platform recommender, but we are not competing with them as we have no metrics to satisfy, but just want to be helpful to people.
UI Front-end
UI Front-end
Marimo notebook.
Easily write simple Web applications in python. Powerful for developers, simple for end users. Share applications as html+WASM, which means they run 100% on the client.
Jupyter notebook, Streamlit, Gradio.
Marimo less widely adopted, but allows both for easy prototyping and easy sharing/demoing while preserving user privacy.
Deployment Options
Deployment Options
Supports Hugging Face Spaces, Docker, and local runs.
Flexible to test quickly or fully customize locally.
Single way to use it.
Maintaining multiple paths adds overhead, which we are trying to tackle with automation (GH actions).
Ready? Try it yourself!
System Requirments
OS: Windows, macOS, or Linux; Python 3.11 or higher; Minimum RAM: 1GB (double check); Disk space: 1.3GB for the Docker image, or ~1GB for local installation (~800MB for code + deps, plus the embedding model of your choice). If you want to compile llamafile yourself, you'll need ~5GB extra (NOTE: the Docker image already contains it).
Learn More
Discussion Points
Get involved in improving the Blueprint by visiting the GitHub Blueprint issues.
Join in
Explore Blueprints Extensions
See examples of extended blueprints unlocking new capabilities and adjusted configurations enabling tailored solutions—or try it yourself.
Load more
