Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs(spec): add WhatsApp messaging adapter evaluation and decision do…#950

Merged
itomek merged 9 commits into
amd:mainfrom
theonlychant:docs/whatsapp-evaluation
May 11, 2026
Merged

docs(spec): add WhatsApp messaging adapter evaluation and decision do…#950
itomek merged 9 commits into
amd:mainfrom
theonlychant:docs/whatsapp-evaluation

Conversation

@theonlychant

@theonlychant theonlychant commented May 3, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a decision document evaluating WhatsApp as a messaging surface for
GAIA, covering all four integration paths and producing a recommended
approach for the Phase 1 implementation issue.

Why

Before committing engineering effort to a WhatsApp adapter, the team
needed a clear-eyed evaluation of the available integration paths — each
with very different cost, risk, and UX profiles. This document provides
that evaluation so the Phase 1 PR can be scoped with confidence.

Linked issue

Closes #891

Changes

  • Added docs/spec/whatsapp-evaluation.md covering:

Test plan

  • Reviewer reads docs/spec/whatsapp-evaluation.md and confirms all
    four paths are covered with sufficient detail to make a decision
  • Privacy posture section is explicit about which messages travel to
    Meta or partner servers vs. stay local

Checklist

  • I have linked a GitHub issue above (Closes #891).
  • I have described why this change is being made, not just what changed.
  • No code changes - linting and tests not applicable.
  • Documentation added as requested by the issue.

@github-actions github-actions Bot added the documentation Documentation changes label May 3, 2026
@theonlychant

theonlychant commented May 3, 2026

Copy link
Copy Markdown
Contributor Author

I will add in the Telegram adapter and a CLI start command stub

@github-actions github-actions Bot added dependencies Dependency updates cli CLI changes tests Test changes labels May 3, 2026
@theonlychant theonlychant mentioned this pull request May 3, 2026
Closed
6 tasks
@kovtcharov

kovtcharov commented May 4, 2026

Copy link
Copy Markdown
Collaborator

@claude review this PR. Sounds like best move is to skip WhatsApp and add telegram.

kovtcharov
kovtcharov previously approved these changes May 4, 2026
View reviewed changes
@github-actions

github-actions Bot commented May 4, 2026

Copy link
Copy Markdown
Contributor

PR Review

@kovtcharov — agreeing with your read: the spec itself recommends deferring WhatsApp and focusing on Telegram first (see docs/spec/whatsapp-evaluation.md line 8). So the conclusion is sound. The problem is the shape of this PR — it has drifted well past its stated scope.

🔴 Critical: PR is in a broken state

The title and description say this is a docs-only evaluation PR ("No code changes - linting and tests not applicable" in the checklist), but the diff includes:

  • setup.py — adds telegram extras (python-telegram-bot>=20.3)
  • src/gaia/cli.py — adds a full gaia telegram start|stop|status subcommand (~150 lines)
  • experiments/whatsapp-webjs/ — Node.js prototype + 2,109-line package-lock.json

The CLI handler at src/gaia/cli.py:2528 imports gaia.messaging.telegram — this module does not exist in this branch. I confirmed there is no src/gaia/messaging/ directory and no telegram.py anywhere under src/gaia/. Running gaia telegram start --token … will fail with the broad except Exception swallowing the real ImportError and printing ❌ Telegram support is not available, leaving users with no idea why.

The commit 0823347f chore: move Telegram files to correct branch suggests the implementation was relocated but the dependent CLI/setup wiring was not removed — half-finished work, which CLAUDE.md explicitly disallows for commits ("every function has a body, every import is used, no tests referencing deleted code").

🟡 Important: Split this PR

To unblock the WhatsApp decision without merging broken code, split into two PRs:

  1. This PR (docs only) — keep docs/spec/whatsapp-evaluation.md, the two docs/spikes/*.md, and (if you want it in tree) experiments/whatsapp-webjs/. Drop the setup.py and cli.py Telegram changes. Title should be the existing docs(spec): add WhatsApp evaluation. This is mergeable today.
  2. A new PR for Telegram — track Telegram messaging adapter (Phase 0) — pull forward from v0.23.0 #889. Should bundle:
    • src/gaia/messaging/telegram.py with the actual run_telegram implementation
    • The CLI subcommand (currently in this PR)
    • The setup.py telegram extras
    • Unit tests for the adapter (CLAUDE.md: "Every new feature requires tests")
    • docs/guides/telegram.mdx + entry in docs/docs.json + entry in docs/reference/cli.mdx

That gives @theonlychant a clean Phase 0 PR that closes #889 cleanly.

🟡 Important: Update the PR description

The Test plan checklist says "No code changes - linting and tests not applicable" — that's now inaccurate. After the split above, the docs-only version of this PR will be honest again.

🟢 Minor: WhatsApp evaluation doc itself

The doc is good, well-structured, and reaches a defensible conclusion. Two small suggestions before merge:

  • Lead with the decision. Right now the Summary hedges ("only if … otherwise defer"). Given how the rest of the doc reads, a one-line "Decision: defer WhatsApp post-v0.20.0; ship Telegram first (Telegram messaging adapter (Phase 0) — pull forward from v0.23.0 #889)" at the top would save readers 90 seconds.
  • Update Status from draft → accepted once @kovtcharov signs off, so future readers don't reopen the question.

🟢 Minor: experiments/whatsapp-webjs/ is large

The 2,109-line package-lock.json is a lot of churn for a spike that the doc itself says is not viable for production (line 51). Two options: (a) keep it but add an experiments/README.md clarifying nothing in experiments/ is shipped, or (b) move the spike to a throwaway branch and just keep docs/spikes/whatsapp-webjs.md in main with the findings. Either is fine — flagging because reviewers will ask.

🟢 Minor: Silent fallback in CLI status handler

src/gaia/cli.py:2600 — except urllib.error.URLError: pass silently swallows the health-check failure before falling back to PID file existence. CLAUDE.md "No Silent Fallbacks — Fail Loudly" says fallbacks like this should at least log why the health endpoint was unreachable (connection refused vs. timeout vs. DNS), so users debugging "why is status wrong" have something to grep for. Minor since this lands in the Telegram PR after the split.

Suggested next steps

  • @theonlychant — drop the setup.py and src/gaia/cli.py changes from this branch (git restore --source=main -- setup.py src/gaia/cli.py) and force-push, leaving this as docs-only
  • Open a separate Telegram PR against Telegram messaging adapter (Phase 0) — pull forward from v0.23.0 #889 with the missing src/gaia/messaging/telegram.py, the CLI bits, tests, and docs
  • Tighten the WhatsApp spec's top-line decision and flip Status to accepted after maintainer sign-off

Happy to take another pass once it's split.

@theonlychant

theonlychant commented May 4, 2026

Copy link
Copy Markdown
Contributor Author

@claude review this PR. Sounds like best move is to skip WhatsApp and add telegram.

Yea to be honest I'm not too sure how to move forward with the whatsapp part

@itomek itomek self-assigned this May 6, 2026
@itomek itomek marked this pull request as draft May 7, 2026 13:30
@theonlychant theonlychant marked this pull request as ready for review May 8, 2026 21:18
@itomek itomek added this pull request to the merge queue May 11, 2026
Merged via the queue into amd:main with commit 91f5872 May 11, 2026
24 checks passed
@itomek itomek mentioned this pull request May 14, 2026
Merged
6 tasks
pull Bot pushed a commit to bhardwajRahul/gaia that referenced this pull request May 15, 2026
@itomek
Release v0.18.0 (amd#1055)
f89ba07 
## Why this matters

v0.18.0 ships agent memory v2 (hybrid-search second brain with LLM
extraction and observability dashboard), ChatAgent split into three
composable agents (Chat/FileIO/DocumentQA), parallel tool calls, and a
Telegram adapter scaffold — plus fixes the RAG-on-PDF timeout with Gemma
4 that broke document Q&A since v0.17.6 and adds CI gates that enforce
RAG quality baselines on every future PR.

Full notes: `docs/releases/v0.18.0.mdx`.

## What's New

- **Agent memory v2** ([amd#606](amd#606)) —
Hybrid semantic + keyword search, LLM extraction, observability
dashboard via SSE streaming
([amd#1032](amd#1032)). Per-user isolation
enforced; extraction runs async so it doesn't add latency.
- **ChatAgent split** ([amd#979](amd#979)) —
`ChatAgent`, `FileIOAgent`, and `DocumentQAAgent` replace the monolithic
class; each composable via `tools=`. Backward-compatible shim preserved.
- **Parallel tool calls** ([amd#946](amd#946))
— Multiple `tool_calls` from a single LLM turn are executed
concurrently, cutting round-trips for multi-tool workflows.
- **Telegram adapter scaffold, Phase 0**
([amd#951](amd#951)) — `gaia telegram
start|stop|status`, per-user session isolation, `[telegram]` extras.
Phase 1 (message handling + allowed-users gate) tracked in
[amd#889](amd#889).
- **Connectors: per-MCP toggle + single-writer enforcement**
([amd#1018](amd#1018),
[amd#998](amd#998)) — Disable individual MCP
servers without removing them; concurrent writes serialised with
actionable errors on contention.
- **File navigation, web browsing, and write security**
([amd#495](amd#495)) — `FileSearchToolsMixin`,
web browsing tool, and scratchpad mixin in `KNOWN_TOOLS`; write tools
check `allowed_paths` before dispatch.
- **Email UI and policy alerts**
([amd#995](amd#995),
[amd#1039](amd#1039),
[amd#952](amd#952)) — Pre-scan triage card,
in-chat Connect, policy alert cards, and durable receipts for
confirmation-gated actions.

## Bug Fixes

- **RAG-on-PDF timeouts on Gemma 4**
([amd#1034](amd#1034), closes
[amd#1030](amd#1030)) — Prompt-size budget
check added at composition time; CI gates enforce it on every PR
([amd#1040](amd#1040)).
- **Envelope-level parse failure crashed SD recovery**
([amd#1047](amd#1047), closes
[amd#1023](amd#1023)) — Falls through to a
clean recovery path with step-1 context preserved.
- **Windows-path tool args corrupted**
([amd#1027](amd#1027)) — Backslash
normalisation now happens after argument parsing.
- **Blender `send_command` hung**
([amd#1026](amd#1026), closes
[amd#1022](amd#1022)) — Read timeout applied
to persistent-connection servers.
- **`gaia chat init` in post-install banner**
([amd#1029](amd#1029), closes
[amd#1024](amd#1024)) — Replaced with the
correct `gaia init`.
- **Keyring treated as required**
([amd#1028](amd#1028)) — Import guarded;
optional on systems without `keyring`.
- **electron-builder URLs stale**
([amd#953](amd#953)) — Three doc/installer
files updated to current download paths.

## Tooling & Docs

- **RAG eval CI gates** ([amd#1040](amd#1040),
closes [amd#1033](amd#1033)) — RAG quality
baselines + prompt-size budget enforced on every PR.
- **Fork-PR authors now receive Claude review**
([amd#932](amd#932)) —
`allowed_non_write_users: "*"` with prompt-injection mitigations
documented.
- **Eval runs mandated before merging**
([amd#1036](amd#1036)) — `CLAUDE.md` requires
`gaia eval agent` for LLM-affecting changes.
- **GAIA website** ([amd#369](amd#369)) —
[amd-gaia.ai](https://amd-gaia.ai) live.
- **Custom agent guide reorganised**
([amd#997](amd#997)), Lemonade PPA docs
([amd#801](amd#801)), broken Lemonade CLI URL
fixed ([amd#996](amd#996)), WhatsApp adapter
evaluation spec ([amd#950](amd#950)).

## Release checklist

- [x] `util/validate_release_notes.py docs/releases/v0.18.0.mdx --tag
v0.18.0` passes
- [x] `src/gaia/version.py` → `0.18.0`
- [x] `src/gaia/apps/webui/package.json` → `0.18.0`
- [x] Navbar label in `docs/docs.json` → `v0.18.0 · Lemonade 10.2.0`
- [x] All 28 commits in range (v0.17.6..HEAD) are represented in the
notes
- [ ] Review from @kovtcharov-amd addressed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@itomek itomek itomek approved these changes
@kovtcharov kovtcharov kovtcharov left review comments
@kovtcharov-amd kovtcharov-amd Awaiting requested review from kovtcharov-amd kovtcharov-amd is a code owner

Assignees

@itomek itomek

Labels

cli CLI changes dependencies Dependency updates documentation Documentation changes tests Test changes

Projects

None yet

Milestone

v0.18.0 — Agent UI guide rewrite [OSS]

Development

Successfully merging this pull request may close these issues.

WhatsApp messaging adapter — evaluation + decision document

3 participants

@theonlychant @kovtcharov @itomek