https://github.com/ofir5300/tupac-almighty
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.
https://github.com/ofir5300/tupac-almighty
docker genai genai-chatbot huggingface huggingface-transformers llm openai-whisper raspberry-pi rpi telegram telegram-bot whisper-ivr
Last synced: about 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/ofir5300/tupac-almighty
- Owner: ofir5300
- Created: 2025-06-21T15:28:11.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-21T16:05:32.000Z (about 1 year ago)
- Last Synced: 2025-06-21T16:37:39.143Z (about 1 year ago)
- Topics: docker, genai, genai-chatbot, huggingface, huggingface-transformers, llm, openai-whisper, raspberry-pi, rpi, telegram, telegram-bot, whisper-ivr
- Language: Python
- Homepage:
- Size: 98.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
🪓 Tupac Almighty 🔫
Docker & RPI Deployment Guide
### About This Project
**Tupac Almighty** is a personal Telegram bot that runs 24/7 on a **Raspberry Pi** and uses a local **Mac** for heavy-duty tasks.
It 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.
**Key Features:**
- 🤖 **Ask AI:** Chat with various local Large Language Models (LLMs).
- 🎙️ **Voice-to-Text:** Transcribe audio messages using Whisper.
- 🎯 **Appointment Sniper:** Automatically checks a website for open shooting range appointments.
- 🗓️ **Activity Tracker:** Fetches events from Google Calendar to track personal goals.
---
This guide covers **local development**, **Docker usage**, and **Raspberry Pi deployment**—including systemd integration for robust service management.
---
## 🛡️ Environment Setup
1. Copy `.env.example` to `.env` and fill in all required values:
```sh
cp .env.example .env
```
---
## 📦 Local Development
> **Recommended:** Use pyenv & pyenv-virtualenv for Python isolation.
1. _(Optional but recommended)_ **Set up a virtual environment:**
```sh
pyenv install 3.13.2
pyenv virtualenv 3.13.2 "$PROJECT_NAME"
pyenv local "$PROJECT_NAME"
```
2. **Install dependencies:**
```sh
pip install -r requirements.txt
```
3. **Run the application:**
```sh
python main.py
```
> You can skip the virtualenv steps and use your system Python if you prefer, but isolation is safer for dependencies.
---
## 🐳 Running with Docker
1. **Build the Docker image (ARM64 for RPi):**
```sh
docker build --platform linux/arm64 -t tupac .
```
2. **Run the container:**
```sh
docker run --rm -it tupac
```
3. **Detached mode:**
```sh
docker run -d --name tupac tupac
```
---
## 🔄 Deploying to Raspberry Pi
### 1️⃣ Automated Deployment
Use the deployment script for a full build-transfer-deploy cycle:
```sh
chmod +x scripts/deploy.sh
./scripts/deploy.sh
```
- Builds the image locally for ARM64
- Saves as a tarball
- Transfers image, `.env`, `docker-compose.yml`, and `config/` to the Pi
- Loads and runs via Docker Compose on the Pi
**Paths:**
- Script: `scripts/deploy.sh`
- Service file: `config/telegram-bot.service.ini`
### 2️⃣ Manual Deployment (Advanced)
```sh
docker save -o tupac.tar tupac
scp tupac.tar pi@:/home/pi/
ssh pi@ "docker load -i /home/pi/tupac.tar && docker compose up -d --force-recreate"
```
---
## 🛠 Docker Management
- **Check containers:** `docker ps`
- **Logs:** `docker logs tupac`
- **Stop:** `docker stop tupac`
- **Restart:** `docker start tupac`
- **Prune:** `docker system prune -a`
---
## 🖥️ Systemd Integration (Recommended for RPi)
1. **Copy the service file to your Pi:**
```sh
scp config/telegram-bot.service.ini pi@:/etc/systemd/system/telegram-bot.service
```
2. **Enable and manage the service:**
```sh
sudo systemctl daemon-reload
sudo systemctl enable telegram-bot
sudo systemctl start telegram-bot
sudo systemctl status telegram-bot
sudo systemctl stop telegram-bot
```
- This ensures the bot starts on boot and restarts on failure.