{"id":28939216,"url":"https://github.com/ofir5300/tupac-almighty","last_synced_at":"2026-05-08T15:40:24.340Z","repository":{"id":300426798,"uuid":"1006139956","full_name":"ofir5300/tupac-almighty","owner":"ofir5300","description":"A Telegram bot with a hybrid architecture. Its core runs on a Raspberry Pi for 24/7 reliability, offloading heavy LLM and audio processing to a local Mac via a mac-as-a-server connection for personal assistance.","archived":false,"fork":false,"pushed_at":"2025-06-21T16:05:32.000Z","size":101,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T16:37:39.143Z","etag":null,"topics":["docker","genai","genai-chatbot","huggingface","huggingface-transformers","llm","openai-whisper","raspberry-pi","rpi","telegram","telegram-bot","whisper-ivr"],"latest_commit_sha":null,"homepage":"","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/ofir5300.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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T15:28:11.000Z","updated_at":"2025-06-21T16:06:17.000Z","dependencies_parsed_at":"2025-06-21T16:47:52.341Z","dependency_job_id":null,"html_url":"https://github.com/ofir5300/tupac-almighty","commit_stats":null,"previous_names":["ofir5300/tupac-almighty"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ofir5300/tupac-almighty","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofir5300%2Ftupac-almighty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofir5300%2Ftupac-almighty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofir5300%2Ftupac-almighty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofir5300%2Ftupac-almighty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ofir5300","download_url":"https://codeload.github.com/ofir5300/tupac-almighty/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofir5300%2Ftupac-almighty/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261386809,"owners_count":23150873,"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":["docker","genai","genai-chatbot","huggingface","huggingface-transformers","llm","openai-whisper","raspberry-pi","rpi","telegram","telegram-bot","whisper-ivr"],"created_at":"2025-06-23T00:07:15.581Z","updated_at":"2026-05-08T15:40:24.335Z","avatar_url":"https://github.com/ofir5300.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ctable border=\"0\" cellspacing=\"0\" cellpadding=\"0\" style=\"border: none; border-collapse: collapse;\"\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"border: none; padding-right: 20px;\"\u003e\n      \u003cimg src=\"assets/2pac-shakurliza.jpg\" alt=\"2Pac\" width=\"100\"/\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"border: none;\"\u003e\n      \u003cspan style=\"font-size:2em;font-weight:bold;\"\u003e🪓 Tupac Almighty 🔫\u003c/span\u003e\u003cbr\u003e\n      \u003cspan style=\"font-size:1.2em;font-weight:bold;\"\u003eDocker \u0026 RPI Deployment Guide\u003c/span\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/div\u003e\n\n### About This Project\n\n**Tupac Almighty** is a personal Telegram bot that runs 24/7 on a **Raspberry Pi** and uses a local **Mac** for heavy-duty tasks.\n\nIt uses a \"mac-as-a-server\" setup: the RPi handles simple commands, but for demanding tasks like AI chats or transcribing voice notes, it connects to the Mac to borrow its power. This makes the bot both efficient and powerful, without any cloud costs.\n\n**Key Features:**\n\n- 🤖 **Ask AI:** Chat with various local Large Language Models (LLMs).\n- 🎙️ **Voice-to-Text:** Transcribe audio messages using Whisper.\n- 🎯 **Appointment Sniper:** Automatically checks a website for open shooting range appointments.\n- 🗓️ **Activity Tracker:** Fetches events from Google Calendar to track personal goals.\n\n---\n\nThis guide covers **local development**, **Docker usage**, and **Raspberry Pi deployment**—including systemd integration for robust service management.\n\n---\n\n## 🛡️ Environment Setup\n\n1. Copy `.env.example` to `.env` and fill in all required values:\n   ```sh\n   cp .env.example .env\n   ```\n\n---\n\n## 📦 Local Development\n\n\u003e **Recommended:** Use pyenv \u0026 pyenv-virtualenv for Python isolation.\n\n1. _(Optional but recommended)_ **Set up a virtual environment:**\n\n   ```sh\n   pyenv install 3.13.2\n   pyenv virtualenv 3.13.2 \"$PROJECT_NAME\"\n   pyenv local \"$PROJECT_NAME\"\n   ```\n\n2. **Install dependencies:**\n\n   ```sh\n   pip install -r requirements.txt\n   ```\n\n3. **Run the application:**\n   ```sh\n   python main.py\n   ```\n\n\u003e You can skip the virtualenv steps and use your system Python if you prefer, but isolation is safer for dependencies.\n\n---\n\n## 🐳 Running with Docker\n\n1. **Build the Docker image (ARM64 for RPi):**\n\n   ```sh\n   docker build --platform linux/arm64 -t tupac .\n   ```\n\n2. **Run the container:**\n\n   ```sh\n   docker run --rm -it tupac\n   ```\n\n3. **Detached mode:**\n   ```sh\n   docker run -d --name tupac tupac\n   ```\n\n---\n\n## 🔄 Deploying to Raspberry Pi\n\n### 1️⃣ Automated Deployment\n\nUse the deployment script for a full build-transfer-deploy cycle:\n\n```sh\nchmod +x scripts/deploy.sh\n./scripts/deploy.sh\n```\n\n- Builds the image locally for ARM64\n- Saves as a tarball\n- Transfers image, `.env`, `docker-compose.yml`, and `config/` to the Pi\n- Loads and runs via Docker Compose on the Pi\n\n**Paths:**\n\n- Script: `scripts/deploy.sh`\n- Service file: `config/telegram-bot.service.ini`\n\n### 2️⃣ Manual Deployment (Advanced)\n\n```sh\ndocker save -o tupac.tar tupac\nscp tupac.tar pi@\u003cPI_HOST\u003e:/home/pi/\nssh pi@\u003cPI_HOST\u003e \"docker load -i /home/pi/tupac.tar \u0026\u0026 docker compose up -d --force-recreate\"\n```\n\n---\n\n## 🛠 Docker Management\n\n- **Check containers:** `docker ps`\n- **Logs:** `docker logs tupac`\n- **Stop:** `docker stop tupac`\n- **Restart:** `docker start tupac`\n- **Prune:** `docker system prune -a`\n\n---\n\n## 🖥️ Systemd Integration (Recommended for RPi)\n\n1. **Copy the service file to your Pi:**\n\n   ```sh\n   scp config/telegram-bot.service.ini pi@\u003cPI_HOST\u003e:/etc/systemd/system/telegram-bot.service\n   ```\n\n2. **Enable and manage the service:**\n   ```sh\n   sudo systemctl daemon-reload\n   sudo systemctl enable telegram-bot\n   sudo systemctl start telegram-bot\n   sudo systemctl status telegram-bot\n   sudo systemctl stop telegram-bot\n   ```\n\n- This ensures the bot starts on boot and restarts on failure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofir5300%2Ftupac-almighty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fofir5300%2Ftupac-almighty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofir5300%2Ftupac-almighty/lists"}