agentvibes 2.4.0 → 2.4.2

package/docs/whatsapp-plugin-github-issue.md

@@ -0,0 +1,393 @@
+# GitHub Issue: WhatsApp TTS Notifications Plugin
+
+## Title
+🔔 Feature: WhatsApp TTS Notifications Plugin with Voice Round-Robin
+
+## Labels
+`enhancement`, `plugin`, `tts`, `whatsapp`, `mcp-server`
+
+## Description
+
+### Summary
+Create a **standalone plugin** in an independent repository that enables voice notifications for incoming WhatsApp messages through the MCP (Model Context Protocol) server. The plugin will integrate with AgentVibes (via subprocess) and provide natural language control to enable/disable notifications per contact/channel with round-robin voice assignment for speaker differentiation in group chats.
+
+**Repository**: New standalone repo: `whatsapp-agentvibes` or `agentvibes-whatsapp-plugin`
+**Distribution**: PyPI package (`pip install whatsapp-agentvibes`)
+**Architecture**: Independent MCP server that calls AgentVibes TTS via subprocess
+
+### Problem Statement
+Users who integrate WhatsApp with Claude (via whatsapp-mcp) want audible notifications for important messages, with the ability to:
+- Selectively enable/disable notifications per contact or group
+- Distinguish between speakers in group chats through different voices
+- Control notifications using natural language commands
+- Leverage AgentVibes' existing voice library (27+ voices)
+
+### Proposed Solution
+Build a **standalone MCP server in an independent repository** that bridges the WhatsApp MCP server with AgentVibes TTS capabilities, providing:
+
+1. **Voice Notifications**: Automatically read incoming WhatsApp messages aloud
+2. **Round-Robin Voice Assignment**: Different contacts get different voices (consistent per contact)
+3. **MCP Commands**: Natural language control for notification management
+4. **Group Chat Support**: Per-sender voice assignment within groups
+5. **Clean Architecture**: Standalone repo with AgentVibes as external dependency (subprocess calls)
+6. **Independent Distribution**: pip package on PyPI
+
+**Why Standalone?**
+- ✅ Separation of concerns (TTS engine vs messaging integration)
+- ✅ Independent versioning and releases
+- ✅ Easier maintenance and community contributions
+- ✅ Opens path for plugin ecosystem (Signal, Telegram, Slack)
+- ✅ Users install only what they need
+
+### Architecture Overview
+
+**Standalone Repository Architecture:**
+
+```
+┌─────────────────────────────────────┐
+│   whatsapp-agentvibes               │ ← New Standalone Repo (pip package)
+│   (Independent MCP Server)          │
+│                                     │
+│  - Message monitoring (SQLite poll) │
+│  - Voice assignment (round-robin)   │
+│  - Notification config management   │
+│  - MCP command handlers             │
+└──────────────┬──────────────────────┘
+               │ depends on (subprocess calls)
+               │
+      ┌────────┴─────────┬────────────────┐
+      ▼                  ▼                ▼
+┌────────────┐   ┌──────────────┐   ┌─────────────┐
+│ WhatsApp   │   │ AgentVibes   │   │ FastMCP     │
+│ MCP Server │   │ (installed)  │   │ (Python)    │
+│            │   │ play-tts.sh  │   │             │
+└────────────┘   └──────────────┘   └─────────────┘
+     (data)         (subprocess)        (framework)
+```
+
+**Integration Method:**
+- **WhatsApp**: Direct SQLite database reads (read-only)
+- **AgentVibes**: Subprocess calls to `~/.claude/hooks/play-tts.sh`
+- **No code imports**: Plugin is fully independent
+
+### Key Features
+
+#### 1. New MCP Commands
+- **`whatsapp_enable_notifications(contact_or_chat: str)`** - Enable TTS for a contact/group
+- **`whatsapp_disable_notifications(contact_or_chat: str)`** - Disable TTS for a contact/group
+- **`whatsapp_list_notification_channels()`** - Show all enabled notification channels
+- **`whatsapp_set_contact_voice(contact: str, voice: str)`** - Override automatic voice assignment
+- **`whatsapp_get_notification_status()`** - Show notification statistics
+
+#### 2. Round-Robin Voice Assignment
+- Hash-based voice selection: Same contact always gets same voice
+- Persistent mapping stored in `.claude/whatsapp-notifications.json`
+- Automatic distribution across 27+ available voices
+- Manual override capability per contact
+
+#### 3. Group Chat Voice Differentiation
+- Per-sender voice assignment within groups
+- Announces sender name: "John says: Hello there"
+- Consistent voices across all group interactions
+
+#### 4. Message Monitoring
+- Polls WhatsApp SQLite database every 2 seconds
+- Filters messages by enabled contacts only
+- Skips self-sent messages (is_from_me = true)
+- Handles text messages and media notifications
+
+### Example Usage
+
+**Scenario 1: Enable notifications for a contact**
+```
+User: "Enable WhatsApp notifications for my mom"
+Claude: [Searches contacts for "mom"]
+        [Finds: Jane Smith, +1234567890]
+        [Enables notifications]
+        ✅ Enabled notifications for Jane Smith with voice "Aria"
+
+[Message arrives from Jane]
+TTS (Aria): "Message from Jane Smith: Don't forget to call me tonight"
+```
+
+**Scenario 2: Group chat with multiple voices**
+```
+User: "Enable notifications for the Family group"
+Claude: ✅ Enabled notifications for Family group
+        Voices will be assigned per sender automatically
+
+[Messages arrive]
+TTS (Aria): "Dad: Can someone pick up milk?"
+TTS (Terry): "Mom: I'll get it on the way home"
+TTS (Bob): "Sister: Thanks Mom!"
+```
+
+**Scenario 3: Managing notifications**
+```
+User: "Show me all WhatsApp notification channels"
+Claude: 🔔 WhatsApp Notifications Active:
+        1. Jane Smith (+1234567890) - Voice: Aria
+        2. Family Group - 3 senders with voices
+        3. Work Team - Voice: Jenny
+```
+
+### Implementation Plan
+
+#### Phase 0: Repository Setup (Day 1-2)
+- [ ] Create new GitHub repository: `whatsapp-agentvibes`
+- [ ] Set up Python package structure with pyproject.toml
+- [ ] Configure GitHub Actions for testing/linting
+- [ ] Create initial README with installation instructions
+- [ ] Set up issue templates and contributing guidelines
+
+#### Phase 1: Core Integration (Week 1)
+- [ ] Implement `AgentVibesClient` class (subprocess wrapper)
+  - Detect AgentVibes installation
+  - Call play-tts.sh script
+  - List available voices
+  - Handle errors gracefully
+- [ ] Set up configuration management (JSON file in `~/.config/`)
+- [ ] Add hash-based voice assignment logic
+- [ ] Implement basic MCP tools:
+  - `whatsapp_enable_notifications`
+  - `whatsapp_disable_notifications`
+  - `whatsapp_list_notification_channels`
+- [ ] Write unit tests for voice assignment and config
+
+#### Phase 2: Message Monitoring (Week 2)
+- [ ] Implement SQLite database polling (2-second interval)
+- [ ] Add timestamp tracking for incremental message fetch
+- [ ] Implement message filtering by enabled contacts
+- [ ] Integrate with AgentVibes `play-tts.sh` script
+- [ ] Handle group vs direct message differentiation
+
+#### Phase 3: Advanced Features (Week 3)
+- [ ] Add manual voice override tool: `whatsapp_set_contact_voice`
+- [ ] Implement status/statistics tool: `whatsapp_get_notification_status`
+- [ ] Add group chat per-sender voice assignment
+- [ ] Implement media message announcements ("John sent a photo")
+- [ ] Add sender name prefixing for group messages
+
+#### Phase 4: Testing & Documentation (Week 4)
+- [ ] Write unit tests for voice assignment logic
+- [ ] Create end-to-end integration tests
+- [ ] Write comprehensive documentation:
+  - Installation guide
+  - Configuration reference
+  - Usage examples
+  - Troubleshooting section
+- [ ] Create demo video showing the feature
+- [ ] Update main AgentVibes README
+
+### Technical Specifications
+
+**Technology Stack**:
+- Python 3.8+ (MCP server)
+- FastMCP framework (existing)
+- SQLite (WhatsApp message database - read-only)
+- Bash (AgentVibes TTS scripts)
+- JSON (configuration storage)
+
+**Database Interaction**:
+```python
+# Poll for new messages
+query = """
+    SELECT id, chat_jid, sender, content, timestamp, is_from_me
+    FROM messages
+    WHERE timestamp > ? AND is_from_me = 0
+    ORDER BY timestamp ASC
+"""
+```
+
+**Voice Assignment Algorithm**:
+```python
+def assign_voice_to_contact(contact_jid: str, available_voices: list) -> str:
+    """Assigns consistent voice using hash-based selection"""
+    contact_hash = hash(contact_jid) % len(available_voices)
+    return available_voices[contact_hash]
+```
+
+**Configuration Format**:
+```json
+{
+  "enabled_contacts": [
+    "1234567890@s.whatsapp.net",
+    "group123@g.us"
+  ],
+  "contact_voices": {
+    "1234567890@s.whatsapp.net": "Aria",
+    "group123@g.us": {
+      "sender1@s.whatsapp.net": "Northern Terry",
+      "sender2@s.whatsapp.net": "Kristin"
+    }
+  },
+  "last_checked_timestamp": "2025-11-12T10:30:00Z"
+}
+```
+
+### Dependencies
+
+**Prerequisites (Must Be Installed)**:
+- WhatsApp MCP Server (https://github.com/lharries/whatsapp-mcp)
+- AgentVibes TTS system (https://github.com/paulpreibisch/AgentVibes)
+  - Called via subprocess, not imported
+- Python 3.8+
+
+**Python Dependencies (requirements.txt)**:
+```txt
+mcp>=0.9.0
+aiosqlite>=0.19.0
+```
+
+**Note**: AgentVibes is NOT listed as a pip dependency because it's called via subprocess.
+
+### Repository Structure
+
+**New Standalone Repository: `whatsapp-agentvibes`**
+
+```
+whatsapp-agentvibes/
+├── README.md                          # Installation & usage
+├── LICENSE                            # Apache 2.0
+├── requirements.txt                   # Python dependencies
+├── pyproject.toml                     # Package metadata
+├── setup.py                           # Installation script
+│
+├── src/
+│   └── whatsapp_agentvibes/
+│       ├── __init__.py
+│       ├── server.py                  # Main MCP server
+│       ├── monitor.py                 # WhatsApp message monitoring
+│       ├── voice_manager.py           # Voice assignment logic
+│       ├── config.py                  # Configuration management
+│       └── agentvibes_client.py       # AgentVibes subprocess wrapper
+│
+├── config/
+│   ├── notifications.json.example     # Example configuration
+│   └── claude_desktop_config.json     # MCP setup example
+│
+├── tests/
+│   ├── test_voice_assignment.py
+│   ├── test_monitor.py
+│   ├── test_config.py
+│   └── test_agentvibes_client.py
+│
+├── docs/
+│   ├── installation.md
+│   ├── configuration.md
+│   ├── troubleshooting.md
+│   └── development.md
+│
+└── .github/
+    └── workflows/
+        ├── test.yml                   # CI tests
+        └── publish.yml                # PyPI publish
+```
+
+**Configuration Location**: `~/.config/whatsapp-agentvibes/config.json`
+
+### Benefits
+
+✅ **Standalone architecture** - Independent repo, separate from AgentVibes codebase
+✅ **Zero modification to existing systems** - WhatsApp bridge and AgentVibes core remain unchanged
+✅ **Independent versioning** - Plugin releases independently from AgentVibes
+✅ **Native MCP integration** - Works seamlessly with Claude Desktop and Claude Code
+✅ **Natural language control** - "Enable notifications for Mom" vs manual commands
+✅ **Voice variety** - 27+ voices for rich speaker differentiation
+✅ **Consistent voice assignment** - Same contact always gets same voice
+✅ **Privacy-focused** - All processing local, no external data transmission
+✅ **Plugin ecosystem** - Opens path for Signal-TTS, Telegram-TTS, Slack-TTS
+✅ **Easy installation** - `pip install whatsapp-agentvibes`
+
+### Challenges & Solutions
+
+| Challenge | Solution |
+|-----------|----------|
+| Polling latency (1-5 sec delay) | Acceptable for notifications; 2-second interval balances responsiveness with CPU usage |
+| Voice assignment persistence | JSON config file in `.claude/` directory with hash-based stable assignment |
+| Group chat complexity | Extend mapping to `{group_jid: {sender_jid: voice}}` structure |
+| Media message handling | Announce metadata: "[Name] sent a photo/video/voice message" |
+| Database schema changes | Read-only access to existing schema; no modifications needed |
+
+### Testing Strategy
+
+1. **Unit Tests**:
+   - Voice assignment hash consistency
+   - Configuration save/load
+   - Message filtering logic
+
+2. **Integration Tests**:
+   - SQLite database polling
+   - AgentVibes TTS integration
+   - MCP command execution
+
+3. **End-to-End Tests**:
+   - Enable/disable notifications flow
+   - Group message voice differentiation
+   - Configuration persistence across restarts
+
+### Documentation Requirements
+
+1. **Installation Guide**:
+   - Prerequisites (WhatsApp MCP + AgentVibes)
+   - MCP server configuration
+   - Claude Desktop integration
+
+2. **Usage Guide**:
+   - Enabling/disabling notifications
+   - Voice management
+   - Group chat handling
+
+3. **Configuration Reference**:
+   - JSON structure
+   - MCP command reference
+   - Troubleshooting section
+
+4. **Developer Guide**:
+   - Architecture overview
+   - Adding new commands
+   - Extending voice assignment logic
+
+### Success Criteria
+
+- [ ] All MCP commands functional and tested
+- [ ] Voice round-robin working consistently
+- [ ] Group chat voice differentiation operational
+- [ ] Polling latency under 3 seconds
+- [ ] Documentation complete and accurate
+- [ ] Demo video created
+- [ ] Zero breaking changes to AgentVibes core
+- [ ] Zero breaking changes to WhatsApp MCP
+
+### Estimated Effort
+
+- **Development**: 25-35 hours
+- **Testing**: 8-12 hours
+- **Documentation**: 6-8 hours
+- **Total**: ~40-55 hours (~1-2 weeks for full-time developer)
+
+### Related Resources
+
+- **Standalone Architecture Document**: [/docs/whatsapp-tts-standalone-plugin.md](https://github.com/paulpreibisch/AgentVibes/blob/main/docs/whatsapp-tts-standalone-plugin.md)
+- **Feasibility Analysis**: [/docs/whatsapp-tts-plugin-feasibility.md](https://github.com/paulpreibisch/AgentVibes/blob/main/docs/whatsapp-tts-plugin-feasibility.md)
+- **WhatsApp MCP Server**: https://github.com/lharries/whatsapp-mcp
+- **AgentVibes TTS System**: https://github.com/paulpreibisch/AgentVibes
+- **AgentVibes Voice Library**: https://github.com/paulpreibisch/AgentVibes/blob/main/docs/voice-library.md
+
+### Community Feedback
+
+Before starting implementation, please provide feedback on:
+1. Is the MCP command naming intuitive?
+2. Should we support custom notification sounds (in addition to TTS)?
+3. Any concerns about the 2-second polling interval?
+4. Should we add a "Do Not Disturb" schedule feature?
+5. Interest in extending to other messaging platforms (Signal, Telegram)?
+
+---
+
+**Ready to implement!** Please comment if you have questions or suggestions before we proceed.
+
+**Related Issues**: None yet
+**Milestone**: AgentVibes v2.4.0
+**Assignees**: TBD
+**Priority**: High (highly requested feature)