AI Assistants

Metadata-Version: 2.4
Name: ai-assistants-whatsapp-control
Version: 0.1.0
Summary: WhatsApp control layer for Hermes Agent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1.0.0,>=0.116.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.35.0
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.4.0; extra == "dev"

# AI Assistants

WhatsApp Control Layer for Hermes Agent using Meta WhatsApp Cloud API.

## Purpose

This project keeps WhatsApp as a thin remote interface for Hermes Agent. Hermes stays the autonomous execution brain. The control layer receives WhatsApp webhook events, authenticates allowed numbers, stores messages and tasks, forwards actionable requests to Hermes, and sends progress or results back through Meta Graph API.

## Current MVP Scope

- Meta webhook verification endpoint
- Meta webhook signature validation
- WhatsApp allowlist authentication
- SQLite-backed storage for users, sessions, messages, tasks, approvals, files, webhook events, and audit logs
- Hermes bridge that runs the Hermes CLI
- Outbound WhatsApp text delivery
- Approval gate for risky prompts before Hermes execution
- Systemd unit for VPS deployment

## Project Structure

```text
AI Assistants/
  apps/whatsapp_control_api/app/
    api/                FastAPI routes
    core/               config, logging, security
    services/           Hermes bridge, Meta sender, store, payload parsing
    __init__.py
    db.py               SQLite schema and data helpers
    schemas.py          Pydantic response and domain schemas
  docs/
    WHATSAPP_CONTROL_LAYER_TECHNICAL_FLOW.md
  ecosystem/systemd/
    ai-assistants-whatsapp-control.service
  tests/
    test_payloads.py
    test_security.py
  .env.example
  pyproject.toml
  README.md
```

## Install

```bash
cd "/root/hermes-projects/AI Assistants"
python3 -m venv .venv
. .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"
cp .env.example .env
nano .env
```

## Run

```bash
cd "/root/hermes-projects/AI Assistants"
. .venv/bin/activate
uvicorn apps.whatsapp_control_api.app.api.main:app --host 0.0.0.0 --port 8040
```

Healthcheck:

```bash
curl http://127.0.0.1:8040/health
```

## Build

There is no separate build step for the Python MVP. Use these quality gates:

```bash
python3 -m compileall apps tests
pytest
```

## Environment Variables

Required:

- `META_APP_ID`
- `META_APP_SECRET`
- `META_BUSINESS_ID`
- `META_WABA_ID`
- `META_PHONE_NUMBER_ID`
- `META_ACCESS_TOKEN`
- `META_VERIFY_TOKEN`
- `WHATSAPP_WEBHOOK_URL`
- `DATABASE_URL`
- `HERMES_COMMAND`
- `HERMES_PROJECTS_ROOT`

Recommended:

- `WHATSAPP_ALLOWED_NUMBERS`
- `META_GRAPH_API_VERSION`
- `APPROVAL_CODE_TTL_SECONDS`
- `WEBHOOK_SIGNATURE_REQUIRED`
- `TASK_PROGRESS_THROTTLE_SECONDS`

## Manual Testing Checklist

- Verify callback URL returns `hub.challenge`.
- Invalid webhook signature is rejected.
- Allowed WhatsApp number creates inbound message and task.
- Unknown WhatsApp number is rejected safely.
- Risky prompt creates approval request instead of running Hermes.
- `APPROVE <task_id>` resumes pending task.
- Hermes output is written to `data/tasks/<task_id>/agent.log`.
- Final task result is sent back through Meta API.

## Next Development Steps

1. Replace SQLite with PostgreSQL and queue workers with Redis.
2. Add signed artifact delivery and document uploads.
3. Add interactive approval buttons instead of text-only approval.
4. Add richer session memory summarization per user.
5. Add admin observability page if needed, without changing Hermes workflow.