{"id":13595425,"url":"https://github.com/tkellogg/fossil","last_synced_at":"2026-04-17T10:31:59.063Z","repository":{"id":213292254,"uuid":"733500694","full_name":"tkellogg/fossil","owner":"tkellogg","description":"A quick \u0026 dirty mastodon client that groups toots by topic","archived":false,"fork":false,"pushed_at":"2023-12-19T13:28:37.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2023-12-19T16:11:42.743Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkellogg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-12-19T13:20:11.000Z","updated_at":"2023-12-19T16:11:45.529Z","dependencies_parsed_at":"2023-12-19T16:11:45.122Z","dependency_job_id":"e58a0eea-bab6-4010-a048-184311b943a6","html_url":"https://github.com/tkellogg/fossil","commit_stats":null,"previous_names":["tkellogg/fossil"],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/tkellogg/fossil","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Ffossil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Ffossil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Ffossil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Ffossil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkellogg","download_url":"https://codeload.github.com/tkellogg/fossil/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Ffossil/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31925346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T10:19:20.377Z","status":"ssl_error","status_checked_at":"2026-04-17T10:19:18.682Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T16:01:49.761Z","updated_at":"2026-04-17T10:31:59.031Z","avatar_url":"https://github.com/tkellogg.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Fossil, a Mastodon Client for Reading\n\nA mastodon client optimized for reading, with a configurable and \nhackable timeline algorithm powered by Simon Wilison's [llm](https://llm.datasette.io/en/stable/index.html) tool. Try making your own algorithm!\n\n\nSneak peek:\n\n![image](https://gist.github.com/assets/437044/3152e5ae-bac7-4a67-a01b-82a712e90e26)\n\n\n# Installing \u0026 Running\n\n## From PyPi\n\nI highly suggest not installing any Python app directly into your global Python. Create a virtual environment:\n\n```\npython -m venv fossil\n```\n\nAnd then activate it (see [here](https://docs.python.org/3/library/venv.html))\n\n```\nsource fossil/bin/activate\n```\n\nAlternatively, **use [`pipx`](https://pipx.pypa.io/stable/installation/)**:\n\n```\npip install pipx\npipx install fossil-mastodon\n```\n\n## From Source\n\nClone this repo:\n\n```\ngit clone https://github.com/tkellogg/fossil.git\n```\n\nAnd then `cd fossil` to get into the correct directory.\n\n\n## Configure the `.env` file\n\nBefore that, you'll need a `.env` file with these keys:\n\n```\nACCESS_TOKEN=\n```\n\nAlternatively, you can set them as environment variables. All available keys are here:\n\n| Variable            | Required? | Value                                    |\n| ---                 | ---       | ---                                      |\n| OPENAI_API_BASE     |        no | eg. https://api.openai.com/v1            |\n| MASTO_BASE          |       no? | eg. https://hackyderm.io                 |\n| ACCESS_TOKEN        |       yes | In your mastodon UI, create a new \"app\" and copy the access token here |\n\n### Connecting to Mastodon\n\nTo get `MASTO_BASE` and `ACCESS_TOKEN`:\n\n1. Go to Mastodon web UI\n2. Preferences -\u003e Development\n3. Click \"New Application\"\n4. Set the name\n5. Set \"Redirect URI\" to `urn:ietf:wg:oauth:2.0:oob`\n6. Set scopes to all `read` and `write` (contribution idea: figure out what's strictly necessary and send a pull request to update this)\n7. Click Submit\n8. Copy your access token into `ACCESS_TOKEN` in the `.env` file.\n9. Set `MAST_BASE`. You should be able to copy the URL from your browser and then remove the entire path (everything after `/`, inclusive).\n\n## Usage\n1. Ensure the settings are correct\n2. \"Load More\" to populate the database with toots\n3. \"Re-Train Algorithm\" to categorize and label those toots.\n\n# Configure Models\nModels can be configured and/or added via `llm`.\n\n## OpenAI\nHere's how to set your OpenAI API key, which gives you access to OpenAI models:\n\n```\n$ llm keys set openai\nEnter key: ...\n```\n## Local (Experimental)\nYou will need to install an embedding model and a large language model. The instructions here use the `llm-sentence-transformers` and `llm-gpt4all` plugins to do so.\n\n```sh\n$ llm install llm-sentence-transformers # An Embedding Model Plugin\n$ llm install llm-gpt4all # A Large Language Model Plugin\n$ llm sentence-transformers register all-mpnet-base-v2 --alias mpnet # Download/Register one of the Embedding Models\n```\n\n### Notes\n- A full list of possible embedding models is composed of [the default list](https://www.sbert.net/docs/pretrained_models.html) and [these models from huggingface](https://huggingface.co/models?library=sentence-transformers).\n- The [llm-gpt4all](https://github.com/simonw/llm-gpt4all) README gives a list of models and their requirements\n- The first time you use a model, `llm` will need to download it. This will add to the overall time it takes to process \n- The \"Re-Train Algorithm\" step will take a long time depending on your hardware; a progress bar is shown in the console window\n- The quality of the categorization and labels are not guaranteed\n\n## Run the server\n\nIf you installed from PyPi:\n\n```\nuvicorn --host 0.0.0.0 --port 8888 fossil_mastodon.server:app\n```\n\nIf you installed from source:\n\n```\npoetry run uvicorn --host 0.0.0.0 --port 8888 --reload fossil_mastodon.server:app\n```\n\nIf you're working on CSS or HTML files, you should include them:\n\n```\npoetry run uvicorn --host 0.0.0.0 --port 8888 --reload --reload-include '*.html' --reload-include '*.css' fossil_mastodon.server:app\n```\n\n(Note the `--reload` makes it much easier to develop, but is generally unneccessary if you're not developing)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkellogg%2Ffossil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkellogg%2Ffossil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkellogg%2Ffossil/lists"}