{"id":18731318,"url":"https://github.com/christopher-besch/chore_planner","last_synced_at":"2025-04-12T17:53:06.403Z","repository":{"id":256989211,"uuid":"842487203","full_name":"christopher-besch/chore_planner","owner":"christopher-besch","description":"Chat Bot scheduling your Shared Apartment's Chores.","archived":false,"fork":false,"pushed_at":"2025-03-20T08:51:32.000Z","size":13412,"stargazers_count":13,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-20T09:39:37.619Z","etag":null,"topics":["chores","clap","planning","rust","scheduling","self-hosted","shared-apartment","signal","signal-bot","signal-chat","telegram-bot"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/chrisbesch/chore_planner","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/christopher-besch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-14T13:01:16.000Z","updated_at":"2025-03-20T08:51:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"a6713fe3-0a31-46d1-a467-ffa7f1804f51","html_url":"https://github.com/christopher-besch/chore_planner","commit_stats":null,"previous_names":["christopher-besch/chore_planner"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopher-besch%2Fchore_planner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopher-besch%2Fchore_planner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopher-besch%2Fchore_planner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christopher-besch%2Fchore_planner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christopher-besch","download_url":"https://codeload.github.com/christopher-besch/chore_planner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248610407,"owners_count":21132920,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["chores","clap","planning","rust","scheduling","self-hosted","shared-apartment","signal","signal-bot","signal-chat","telegram-bot"],"created_at":"2024-11-07T14:57:11.011Z","updated_at":"2025-04-12T17:53:06.381Z","avatar_url":"https://github.com/christopher-besch.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chore_planner\nChat Bot scheduling your Shared Apartment's Chores.\n\nSimply add it to your group chat to have an\n- **unintrusive** (no one has to install an app, create an account or even open a website),\n- **easy to administrate** (with an easy to use chat command interface),\n- **platform-independent** (implementing other chats protocols is easy) and\n- **privacy friendly** (your data is stored on your server and nowhere else)\n\nway of handling your chores.\n\nThe chore_planner supports complex chore and exemption structures **fairly** assigning tenants in a way you can **trust**.\n\n# Currently Supported Chat Protocols\n- Telegram\n- Signal (Tagging and Polls not supported)\n\n# Weekly Action\nhttps://github.com/user-attachments/assets/e46e64ad-d43b-473f-8171-3fdebad0fc38\n\nHere you see the three messages the chore_planner sends at the start of each week:\n1. This week's assignments (I.e., who needs to do what in the new week?)\n2. Poll for rating how the last week went\n3. Future assignment plan\n\n# Administration\nhttps://github.com/user-attachments/assets/6dcd56ed-f12b-4f27-b1aa-13ba824b1b40\n\nAnd here is what you need to do once the bot is [running on your server](#deployment-and-config).\nThe entire administration can be performed from the comfort of your chat.\nSend `@name_of_your_bot --help` for an overview over all commands.\n\nOnce you have performed this administration send the chore_planner a manual SIGHUP with `docker kill -s HUP NameOfContainer`.\nThis sends the first weekly message announcing who needs to do what in the first week.\n\nThere are more things you can change that aren't implemented in the chat administration yet.\nYou can perform those directly on the SQLite Database using the [SQLiteBrowser](https://sqlitebrowser.org) or similar tools.\nWhen the chore_planner boots up it checks the database integrity and explains if your changes have broken something.\n\n# Chores\nA possible **chore** could be the \"Dishwashing Duty\" / \"Spüldienst\", which involves emptying the dishwasher for a week.\n\nYou can define as many **chores** as you like, each with their own name and description.\nA **chore** is some task one **tenant** performs for one week.\nThe chore_planner assigns a **tenant** for each **chore** for each week (See [ChoreLog Assignment](#chorelog-assignment)).\n\nIf some job is to be done by two tenants, simply split it into two chores.\n\n# Exemptions\nIf, for example, the **tenant** \"Hanna\" is the \"Minister of Beverages\" they can be exempt from certain **chores**, say the \"Dishwashing Duty\".\n\nIn this case \"Minister of Beverages\" is the **exemption reason** currently granted to \"Hanna\" and applied to the \"Dishwashing Duty\".\n\n# Rooms and Tenants\nThe **tenant** \"Hanna\" might live in the **room** \"M405\".\n\n**Tenants** having moved into a **room** and haven't moved out yet are called **current tenant**.\nA **tenant** can change her **room** by moving out of her current **room** and immediately moving into a new **room**.\n\n# ChoreLog Assignment\nThe \"Dishwashing Duty\" on week \"32/2024\" is an example **ChoreLog**.\nWhen \"Hanna\" performs this **ChoreLog** everyone on her flat profits from that.\nThe chore_planner needs to remember this.\n\nTo achieve a fair and flexible **ChoreLog** assignment every **tenant** has a score for each chore.\nIn the example above the chore_planner rewards \"Hanna\" by increasing her \"Dishwashing Duty\" score by `1`.\nEveryone else's \"Dishwashing Duty\" score is reduced by `1/(N-1)` with `N` being the number of profiting **tenants**.\n\nThe chore_planner randomly chooses a **tenant** for the **ChoreLog**, each with their own probability.\nLow scores imply the **tenant** didn't do their chores often enough and are thus punished with a higher probability of being chosen.\nHigh scores reduce the **tenant**'s probability.\nHow drastically the chore_planner punished negative scores is affected by the **gamma** value in the [config](#deployment-and-config).\n\nExempt tenants, unwilling tenants and tenants not living in a room are not considered.\nWhen `CHORE_PLANNER_TRY_EXCLUDE_BUSY_TENANTS` is enabled busy tenants are excluded at first.\nBusy tenants are those already doing a chore the last, this or the next week.\nOnly when there are only busy tenants available they are considered, too.\n\nThere is a [(german) mathematical explanation](docs/probability_distribution.pdf) of the chore_planner's probability distribution.\n\n# Unwilling Tenants\nSay the \"Dishwashing Duty\" on week \"32/2024\" was assigned to \"Hanna\" as usual.\nBut this week her parents are coming over and she doesn't have the time to do the chore.\n\"Hanna\" can use the `replan` command to mark herself **unwilling** for that week.\n\nUnwilling tenants won't be considered for assignment.\nBut \"Hanna\" is still profiting from someone else doing the chore so her score is reduced.\nHenceforth, she has a higher probability of being chosen in the following weeks.\n\nThis is the difference between unwilling tenants and (temporarily) moved out tenants.\nThe latter aren't profiting from done chores.\n\n# ChoreLog Rating and History\nAt the end of a week the chore_planner asks all tenants to rate how the last week went.\nTherefore we don't forget that \"Hanna\" did a terrible job at the \"Dishwashing Duty\" last week.\n\nThese ratings have no effect on the **ChoreLog** assignment.\nBut once or twice a year you might want to use the `report` command to get an overview over the past weeks.\nMaybe you can think of nice rewards for those doing a good job.\n\n# Deployment and Config\nThough you can host the chore_planner directly on your server, the easier approach is a Docker Compose deployment.\nSee [the example docker-compose.yml](example_deployment/docker-compose.yml) for an explanation of all configuration options.\nThis uses the [docker_cron container](https://github.com/christopher-besch/docker_cron) to send a [SIGHUP](https://en.wikipedia.org/wiki/SIGHUP) to trigger the [weekly action](#weekly-action).\n\n## Telegram\nTo test the chore_planner [create a telegram bot](https://core.telegram.org/bots), disable [the bot's privacy mode](https://core.telegram.org/bots/features#privacy-mode) and start the chore_planner with `CHORE_PLANNER_CHAT_PROTOCOL=Telegram TELEGRAM_CHAT_ID=your_id TELEGRAM_BOT_TOKEN=your_token docker compose up` in the example_deployment directory.\nYou can figure out your chat's id by setting a random value, sending some message to your chat and looking at the chore_planner's log.\n\nFor an ansible setup see [github.com/christopher-besch/docker_setups](https://github.com/christopher-besch/docker_setups/tree/main/ansible/playbook/roles/docker_chore_planner).\n\n## Signal\nSignal doesn't have good bot support so expect the deployment process to be a less pleasant one.\nThe chore_planner uses the [signal-cli](https://github.com/AsamK/signal-cli), which needs to be installed on the host or (preferably) in another docker container.\n\nFirst you have to [register](https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha) or [link](https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-%28Provisioning%29) the signal-cli to a Signal account.\nDo that on your host or in a docker container with the [docker image](https://github.com/AsamK/signal-cli/wiki/Binary-distributions#docker).\nDon't forget you need a new telephone number for the registration.\nYour setup is stored in `/var/lib/signal-cli`—copy that directory to someplace secure, you'll need to mount it in the production signal-cli container.\n\nYou can just run `docker run --rm --user root -ti -v ./example_deployment/signal_cli:/var/lib/signal-cli --entrypoint /bin/bash registry.gitlab.com/packaging/signal-cli/signal-cli-native` and perform the registration/linking there.\nAdjust all signal-cli commands to use `--config /var/lib/signal-cli`, so for example `signal-cli --config /var/lib/signal-cli link`.\n\nTo test the chore_planner with Signal place your signal-cli setup in `example_deployment/signal_cli` and start the chore_planner with `CHORE_PLANNER_CHAT_PROTOCOL=Signal SIGNAL_GROUP_ID=your_id SIGNAL_ACCOUNT_NAME=your_bots_phone_number docker compose up` in the example_deployment directory.\n\n# Database Structure\nAll data is stored in the database removing the risk of crashes.\n\n### EER Model in Standard Cardinality\n![EER model of database scheme in standard cardinality](./docs/eer_model.png)\n\nThe database scheme uses both ids and unique names for most relations.\nThat way the name of e.g., a **tenant** can easily be changed while letting the application use names for indexing.\n\nAll relations are normalized making changes easy.\nMore high level concepts are implemented using SQL views.\n\nFor example the **tenant** scores are implemented in the TenantScore view.\nInstead of storing the scores directly they are calculated every time they are needed.\nThis creates a single source of truth.\n\n# Extensibility\nThough only Telegram and Signal is supported for now, the chore_planner is designed with extensibility in mind.\nA new chat integration like Discord or Matrix only needs to implement the `MessagableBot` and optionally the `PollableBot` trait from src/bot.rs.\n\n# Testing\nThe entire database interaction written in SQL is thoroughly unit tested.\nThis ensures the SQL statements do what they're designed to do.\n\n# Building Multiarch Docker Image\nThe Dockerfile can build amd64 and arm64 images.\nBuild them with (2.0.0 example):\n\n```\ndocker build --build-arg TARGETARCH=amd64 -t chrisbesch/chore_planner:2.0.0_amd64 . \u0026\u0026\ndocker build --build-arg TARGETARCH=arm64 -t chrisbesch/chore_planner:2.0.0_arm64 . \u0026\u0026\ndocker push chrisbesch/chore_planner:2.0.0_amd64 \u0026\u0026\ndocker push chrisbesch/chore_planner:2.0.0_arm64 \u0026\u0026\ndocker manifest create chrisbesch/chore_planner:2.0.0 \\\n    chrisbesch/chore_planner:2.0.0_amd64 \\\n    chrisbesch/chore_planner:2.0.0_arm64 \u0026\u0026\ndocker manifest inspect chrisbesch/chore_planner:2.0.0 \u0026\u0026\ndocker manifest push chrisbesch/chore_planner:2.0.0\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristopher-besch%2Fchore_planner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristopher-besch%2Fchore_planner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristopher-besch%2Fchore_planner/lists"}