Feature: whatsapp bridge integration

.github/workflows/ci.yml

@@ -34,6 +34,12 @@ jobs:
       matrix:
         python-version: ['3.12']
     steps:
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+        env:
+          OPENAI_API_KEY: sk-test
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
@@ -54,7 +60,6 @@ jobs:
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
-        if: matrix.python-version == '3.12'
         with:
           file: ./agentic-framework/coverage.xml
           fail_ci_if_error: false

.gitignore

@@ -45,3 +45,11 @@ htmlcov/
 # Logging
 agentic-framework/logs/
 !agentic-framework/logs/.gitkeep
+
+# Configuration files
+**/whatsapp.yaml
+agentic-framework/config/*.yaml
+
+# WhatsApp runtime data (sessions, databases, media)
+agentic-framework/storage/whatsapp/
+!agentic-framework/storage/whatsapp/.gitkeep

Dockerfile

@@ -8,14 +8,20 @@ WORKDIR /app
 # Copy from the official installer: https://github.com/astral-sh/uv
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
-# Install Search Tools
+# Install Search Tools and Network Diagnostics
 # ripgrep: ultra-fast text searching
 # fd-find: user-friendly alternative to 'find'
 # fzf: general-purpose command-line fuzzy finder
+# libmagic: Required by neonize/python-magic for file type detection
+# curl: For testing HTTP/HTTPS connections
+# dnsutils: For DNS resolution troubleshooting
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ripgrep \
     fd-find \
     fzf \
+    libmagic1 \
+    curl \
+    dnsutils \
     && rm -rf /var/lib/apt/lists/*
 
 # Note: In Debian/Ubuntu, the 'fd' executable is renamed to 'fdfind'.
@@ -33,6 +39,7 @@ ENV PYTHONUNBUFFERED=1 \
 COPY agentic-framework/pyproject.toml agentic-framework/uv.lock ./agentic-framework/
 COPY agentic-framework/README.md ./agentic-framework/
 COPY agentic-framework/src ./agentic-framework/src
+COPY agentic-framework/config ./agentic-framework/config
 
 # Install dependencies using uv
 # This installs the package in editable mode with all dependencies

README.md

@@ -3,7 +3,7 @@
 # 🤖 Agentic Framework
 **Build AI agents that *actually* do things.**
 
-[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue?style=plastic&logo=python&logoColor=white)](https://python.org)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue?style=plastic&logo=python&logoColor=white)](https://python.org)
 [![LangChain](https://img.shields.io/badge/langchain-%23007BA7.svg?style=plastic&logo=langchain&logoColor=white)](https://python.langchain.com/)
 [![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-green?style=plastic&logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io/)
 [![Docker Ready](https://img.shields.io/badge/docker-ready-blue?style=plastic&logo=docker&logoColor=white)](https://www.docker.com/)
@@ -124,9 +124,76 @@ Instead of spending days wiring together LLMs, tools, and execution environments
         </details>
       </td>
     </tr>
+    <tr>
+      <td><code>whatsapp</code></td>
+      <td><b>WhatsApp Agent:</b> Bidirectional WhatsApp communication (personal account).</td>
+      <td><code>webfetch</code><br><code>duckduckgo-search</code></td>
+      <td>-</td>
+    </tr>
   </tbody>
 </table>
 
+<details>
+<summary><strong>📱 WhatsApp Agent Setup</strong></summary>
+
+The WhatsApp agent enables bidirectional communication through your personal WhatsApp account using QR code authentication.
+
+**Requirements:**
+- Go 1.21+ and Git (for WhatsApp backend)
+- Python 3.13+
+- A configured LLM provider (see environment variables below)
+
+**Configuration:**
+```bash
+# 1. Copy example config
+cp agentic-framework/config/whatsapp.yaml.example agentic-framework/config/whatsapp.yaml
+
+# 2. Edit config/whatsapp.yaml with your settings:
+# - model: "claude-sonnet-4-6"  # Your LLM model
+# - privacy.allowed_contact: "+34 666 666 666"  # Your phone number (only this number can interact)
+# - channel.storage_path: "~/storage/whatsapp"  # Where to store session data
+# - mcp_servers: ["web-fetch", "duckduckgo-search"]  # Optional: MCP servers to use
+```
+
+**Usage:**
+```bash
+# Start the WhatsApp agent
+bin/agent.sh whatsapp --config config/whatsapp.yaml
+
+# With custom settings (overrides config file)
+bin/agent.sh whatsapp --allowed-contact "+1234567890" --storage ~/custom/path
+
+# Customize MCP servers
+bin/agent.sh whatsapp --mcp-servers "web-fetch,duckduckgo-search"
+bin/agent.sh whatsapp --mcp-servers none  # Disable MCP
+
+# Verbose mode for debugging
+bin/agent.sh whatsapp --verbose
+```
+
+**First Run:**
+1. Scan the QR code displayed in your terminal
+2. Wait for WhatsApp to authenticate
+3. Send a message from your configured phone number
+4. Agent will respond automatically
+
+**Privacy & Security:**
+- 🔒 Only processes messages from the configured contact
+- 🔒 Group chat messages are automatically filtered (not sent to LLM)
+- 🔒 All data stored locally (no cloud storage of conversations)
+- 🔒 Messages from other contacts are silently ignored
+- 🔒 Message deduplication prevents reprocessing
+
+**Configuration Options:**
+- `model`: LLM model to use (defaults to provider default)
+- `mcp_servers`: MCP servers for web search and content fetching
+- `privacy.allowed_contact`: Only this phone number can interact with the agent
+- `privacy.log_filtered_messages`: Log filtered messages for debugging
+- `channel.storage_path`: Directory for WhatsApp session and database files
+- `features.group_messages`: Currently disabled by default for privacy
+
+</details>
+
 ### 📦 Local Tools (Zero External Dependencies)
 
 <table>
@@ -565,6 +632,12 @@ bin/agent.sh developer -i "Hello" -v
 
 # 📜 Access logs (same location as local)
 tail -f agentic-framework/logs/agent.log
+
+# 📱 Run the WhatsApp agent (requires config)
+agentic-run whatsapp --config config/whatsapp.yaml
+
+# 📱 Run WhatsApp with custom settings
+agentic-run whatsapp --allowed-contact "+1234567890" --storage ~/custom/path
 ```
 
 ---
@@ -578,7 +651,7 @@ Prefer running without Docker? We got you.
 <summary><strong>System Requirements & Setup</strong></summary>
 
 **Requirements:**
-- Python 3.12+
+- Python 3.13+
 - `ripgrep`, `fd`, `fzf`
 
 ```bash

agentic-framework/config/whatsapp.yaml.example

@@ -0,0 +1,42 @@
+# WhatsApp Agent Configuration
+
+# Agent model configuration
+model: "claude-sonnet-4-6"  # or any supported model
+
+# MCP Servers (optional - overrides registry defaults)
+# By default, uses: web-fetch, duckduckgo-search
+# Set to empty list [] to disable MCP entirely
+# mcp_servers:
+#   - web-fetch
+#   - duckduckgo-search
+
+# Channel configuration
+channel:
+  type: "whatsapp"
+  storage_path: "~/storage/whatsapp"
+
+# Privacy and filtering
+privacy:
+  allowed_contact: "+34 666 666 666"  # Only process messages from this number
+  # Option: log_filtered_messages to file for debugging (default: false)
+  # log_filtered_messages: true
+
+# Feature flags
+features:
+  text_messages: true       # Enable text messages
+  media_messages: true       # Enable media (images, videos, documents, audio)
+  group_messages: false      # Enable group messages (disabled by default for privacy)
+  presence_updates: true      # Enable presence (online/typing status)
+  typing_indicators: true    # Send typing indicators when processing
+
+# whatsapp specific
+whatsapp_bridge:
+  auto_setup: true          # Auto-clone Go bridge on first run
+  auto_connect: true        # Auto-connect on startup
+  bridge_timeout_sec: 180   # Max wait for bridge startup
+  poll_interval_sec: 1      # Check for new messages every N seconds
+
+# Logging
+logging:
+  level: "INFO"              # DEBUG, INFO, WARNING, ERROR
+  file: "logs/agent.log"    # Log file location

agentic-framework/pyproject.toml

@@ -3,12 +3,15 @@ name = "agentic-framework"
 version = "0.1.0"
 description = "Agentic Framework"
 readme = "README.md"
-requires-python = ">=3.12,<3.14"
+requires-python = ">=3.12,<3.15"
 
 dependencies = [
+    "neonize",
+    "httpx>=0.28.0",
     "dotenv>=0.9.9",
+    "pyyaml>=6.0",
     "langchain>=1.1.3",
-    "langchain-openai>=1.1.1",
+    "langchain-openai>=1.1.10",
     "langchain-anthropic>=1.0.3",
     "langchain-model-profiles>=0.0.4",
     "langchain-community>=0.4.1",
@@ -32,6 +35,7 @@ dependencies = [
     "langchain-cohere>=0.5.0",
     "langchain-aws>=1.3.1",
     "langchain-huggingface>=1.2.0",
+    "pydantic>=2.12.5",
 ]
 
 [project.scripts]

agentic-framework/src/agentic_framework/channels/__init__.py

@@ -0,0 +1,25 @@
+"""Communication channels for agents (WhatsApp, Discord, Telegram, etc.)."""
+
+from agentic_framework.channels.base import (
+    Channel,
+    ChannelError,
+    ConfigurationError,
+    ConnectionError,
+    IncomingMessage,
+    MessageError,
+    OutgoingMessage,
+)
+from agentic_framework.channels.whatsapp import WhatsAppChannel
+from agentic_framework.channels.whatsapp_config import WhatsAppAgentConfig
+
+__all__ = [
+    "Channel",
+    "IncomingMessage",
+    "OutgoingMessage",
+    "ChannelError",
+    "ConnectionError",
+    "MessageError",
+    "ConfigurationError",
+    "WhatsAppChannel",
+    "WhatsAppAgentConfig",
+]