AI Assistants

# 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.

The UX is Hermes-first for real work: almost any natural-language request beyond simple greetings, help, and control commands is treated as a Hermes task. WhatsApp stays only as the remote control channel, while Hermes remains the autonomous execution brain.

## 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
- Hermes-first routing for freeform WhatsApp requests
- WhatsApp control commands for app settings and project `.env` files
- Signed task detail and raw log links for remote monitoring
- 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
```

Useful WhatsApp commands:

```text
task terakhir
tasks
status <task_id>
log <task_id>
settings show
settings set CHAT_PROVIDER=openrouter CHAT_MODEL=...
project env "Nama Project" set OPENAI_API_KEY=...
```

## 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`
- `CHAT_ENABLED`
- `CHAT_PROVIDER`
- `CHAT_BASE_URL`
- `CHAT_MODEL`
- `CHAT_API_KEY`
- `WEB_SEARCH_ENABLED`
- `WEB_SEARCH_PROVIDER`
- `WEB_SEARCH_API_KEY`
- `WEB_SEARCH_MAX_RESULTS`

## 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.
- `settings show` returns current app env summary.
- `settings set CHAT_PROVIDER=openrouter CHAT_MODEL=...` updates runtime chat config.
- `settings set WEB_SEARCH_ENABLED=true WEB_SEARCH_PROVIDER=bing` enables realtime source lookup.
- `/model` shows the active Hermes Agent model from `/root/.hermes/config.yaml`.
- `/model set openrouter deepseek-v4-flash` changes the Hermes Agent model used by future tasks.
- The dashboard scans every direct child under `/root/hermes-projects`, including projects created from Hermes CLI.
- Projects are grouped as Web, Mobile, Presentation, Document, Spreadsheet, Bot, or Other.
- Project ZIP downloads exclude `.env`, `.git`, virtual environments, caches, and `node_modules`.
- Project deletion requires a signed action URL, exact project name, confirmation checkbox, and `DASHBOARD_ADMIN_TOKEN`.
- `AI Assistants` is protected from dashboard deletion.
- `/control` is an authenticated Hermes Control Center for status, redacted config, memory, storage, installed skills, skill registry search/install/uninstall, tools enable/disable, and model updates.
- Control Center mutations call native Hermes commands instead of editing skill/tool state manually.
- Ask `carikan data AI terbaru` and verify the answer includes current web source URLs.
- Ask `apa itu AI?` and verify it stays as direct chat without task progress.
- Send `buat project landing page ...` and verify it becomes a Hermes task with progress.
- `project env "AI Assistants" set OPENAI_API_KEY=...` updates project `.env`.
- Hermes output is written to `data/tasks/<task_id>/agent.log`.
- `task terakhir`, `tasks`, and `status <task_id>` return task monitoring info.
- Task detail and raw log links open correctly from WhatsApp.
- 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.