SMS Agent for Raspberry Pi

A local service that ingests Google Voice SMS from Gmail notifications and performs intelligent task execution via skill-based intent routing.

Overview

This agent polls your Gmail for Google Voice SMS notifications, parses messages from a specific allowed sender, recognizes intent (help, status, search, gmail operations, news, weather), executes the appropriate skill, and logs replies for future outbound delivery.

Features

• 📧 Gmail Integration: Uses Gmail API OAuth to read Google Voice notifications
• 🎯 Intent Recognition: Rule-based router for common commands
• 🔧 Extensible Skills: Web search, Gmail summary, weather, and more
• 🔄 Polling Service: APScheduler-based background task
• 🚀 REST API: Health checks and reply preview endpoints
• 🔐 Security: Least-privilege OAuth scopes, number whitelisting
• 📊 Systemd Ready: Production-ready service configuration

Prerequisites

• Raspberry Pi (Bullseye/Bookworm)
• Python 3.11+
• Gmail account with Google Voice
• Google Cloud Project with Gmail API enabled

Quick Start

1. Clone and Setup Environment

cd /opt
sudo mkdir sms-agent
sudo chown $USER:$USER sms-agent
cd sms-agent
git clone <your-repo> .

python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
nano .env

Set your allowed sender number in E.164 format (e.g., +14155550123):

ALLOWED_SENDER_E164=+1XXXXXXXXXX

3. Setup Gmail OAuth

Follow instructions in scripts/setup_gmail_oauth.md to:

• Enable Gmail API in Google Cloud Console
• Create OAuth 2.0 Desktop credentials
• Run authorization flow to generate token

python -m src.google.gmail_client --authorize

4. Run the Service

Development Mode

source venv/bin/activate
python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Production Mode (systemd)

sudo cp deploy/sms-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable sms-agent
sudo systemctl start sms-agent
sudo systemctl status sms-agent

See scripts/install_systemd.md for detailed instructions.

API Endpoints

Health Check

curl http://localhost:8000/healthz

Response:

{
  "status": "ok",
  "timestamp": "2025-10-06T12:34:56.789Z",
  "poller_running": true
}

Reply Preview

View the last N generated replies:

curl http://localhost:8000/reply-preview?limit=10

Response:

{
  "replies": [
    {
      "timestamp": "2025-10-06T12:30:00.000Z",
      "from_number": "+14155550123",
      "original_message": "weather san francisco",
      "reply_text": "San Francisco: ⛅️ Partly cloudy +15°C"
    }
  ],
  "total": 1
}

Supported Commands

Send these via SMS to your Google Voice number:

• help - Show available commands
• status - Show agent status and recent activity
• search <query> - Search Wikipedia/web for information
• gmail_unread - Summarize unread emails
• gmail_from <email> - Show emails from specific sender
• news <topic> - Search news about a topic
• weather <city> - Get current weather

Configuration

All configuration is managed via .env file:

Variable	Description	Default
ALLOWED_SENDER_E164	Phone number allowed to control the agent	Required
GOOGLE_CLIENT_ID	OAuth 2.0 client ID	Required
GOOGLE_CLIENT_SECRET	OAuth 2.0 client secret	Required
GOOGLE_TOKEN_PATH	Path to store OAuth token	./token.json
POLL_INTERVAL_SECONDS	Gmail polling frequency	60
TIMEZONE	Timezone for logs	America/Los_Angeles
SEEN_IDS_PATH	Path to seen message IDs storage	./seen_message_ids.jsonl
REPLY_LOG_PATH	Path to reply log file	./replies.log
MAX_REPLIES_MEMORY	Ring buffer size for replies	100

Logs

Logs are written to:

• ./logs/sms-agent.log (rotating, 10MB max, 5 backups)
• systemd journal: sudo journalctl -u sms-agent -f

Security Notes

• OAuth token stored locally (keep token.json secure)
• Only messages from ALLOWED_SENDER_E164 are processed
• Gmail scopes limited to read-only: gmail.readonly
• No external API keys stored (uses free services)
• Rate limiting on polling to respect Gmail API quotas

Troubleshooting

No messages being processed

1. Check Gmail API is enabled in Google Cloud Console
2. Verify OAuth token is valid: ls -la token.json
3. Check allowed sender number format: must be E.164 (+1XXXXXXXXXX)
4. View logs: tail -f logs/sms-agent.log

Poller not running

# Check service status
sudo systemctl status sms-agent

# View recent logs
sudo journalctl -u sms-agent -n 50

# Restart service
sudo systemctl restart sms-agent

OAuth token expired

Re-run authorization:

cd /opt/sms-agent
source venv/bin/activate
python -m src.google.gmail_client --authorize

Development

Run Tests

pytest tests/ -v

Project Structure

See agents.md for architecture details and project_stages.md for development roadmap.

Future Enhancements

• Outbound SMS via Twilio or Google Apps Script
• LLM-based intent recognition and response generation
• Multi-user support with per-sender permissions
• Webhook receivers for real-time notifications
• Voice command processing

License

MIT

Contributing

See agents.md and project_stages.md for contribution guidelines and development stages.