Marius Mutu
23666f7910
Central voice pipeline (~250 LOC + docstrings = ~430 lines):
VoiceSession (context manager + idempotent cleanup pe 5 căi):
- __enter__: acquire _lock, open JSONL (record=on)
- __exit__: calls cleanup("exit"), nu suprimă exceptions
- cleanup(reason): IDEMPOTENT, side effects o singură dată — JSONL
flush+close (record=on) sau delete (record=off), bot presence cleared,
voice_client.cleanup(), ttsq.stop(), cancel filler task, lock release,
structured log la logs/voice_metrics.jsonl
- on_segment_done(speaker_id, text, no_speech_prob): mirror text channel,
append JSONL, arm 3s filler timer, route_message cu on_text callback
+ cancel filler la first block
- last_activity_ts: time.monotonic() — caller-driven 5min auto-leave
EchoVoiceSink(session, bot_user_id):
- wants_opus() False (PCM)
- write() runs în voice_recv reader thread (threading primitives only):
- GUARD 1: user None/id==0/id==bot_user_id → return (load-bearing
echo prevention)
- GUARD 2: whitelist filter (empty = allow all)
- Buffer 20ms packets per-user → batch 100ms (5×20ms = 19200 bytes)
→ silero-vad threshold 0.5 → 800ms cumulative silence flush
- _flush_to_stt: faster-whisper small int8 cpu_threads=4 lang=ro
beam_size=1, no_speech_prob > 0.6 drop, schedule on_segment_done
via run_coroutine_threadsafe pe session.loop
Module helpers (lazy thread-safe singletons): _get_whisper_model,
_get_silero_vad. Constants: FILLER_DELAY_S=3.0, SILENCE_FLUSH_MS=800,
VAD_THRESHOLD=0.5, VAD_WINDOW_MS=100, NO_SPEECH_DROP_THRESHOLD=0.6.
Decisions:
- STT runs in audio thread — acceptable la 2.25s p50 (user just stopped
talking, no batching contention). Wrap în ThreadPoolExecutor.submit
if perf bites later.
- Downsample 48k→16k via 3-sample averaging (no scipy dep). Whisper
robust la mild aliasing.
- Energy-RMS VAD fallback dacă torch import fail — graceful degrade.
- router_route_message injection seam ca kwarg pentru testabilitate.
- bot.change_presence handling cross-thread via run_coroutine_threadsafe.
tests/test_voice_session_cleanup.py — 6 tests:
- voice_leave / disconnect / crash via __exit__ / auto_leave /
user_left_channel (5 cleanup paths each verified for: JSONL state,
presence cleared, voice_client.cleanup, ttsq.stop, lock release,
idempotency)
- 1 robustness cross-cut (double-cleanup safety)
6/6 PASS. Regression suite 63/63 PASS (normalize + adapter + mutex).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Echo Core
AI-powered personal assistant bot with Discord, Telegram, and WhatsApp bridges. Uses Claude Code CLI for conversation, with persistent sessions, cron scheduling, semantic memory search, and heartbeat monitoring.
Quick Start
# Interactive setup wizard (recommended for first install)
bash setup.sh
The wizard handles prerequisites, virtual environment, bridge tokens, config, and systemd services in 10 guided steps.
Manual Setup
# 1. Create venv and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 2. Store Discord token in keyring
./cli.py secrets set discord_token
# 3. Edit config.json (bot name, owner ID, channels)
# 4. Start
systemctl --user start echo-core
Architecture
┌─────────────┐
│ Claude CLI │
└──────┬──────┘
│
┌──────┴──────┐
│ Router │
└──────┬──────┘
┌────────────┼────────────┐
│ │ │
┌─────┴─────┐ ┌───┴───┐ ┌──────┴──────┐
│ Discord │ │Telegram│ │ WhatsApp │
│ (d.py) │ │(ptb) │ │(Baileys+py) │
└────────────┘ └────────┘ └─────────────┘
- Discord: slash commands via discord.py
- Telegram: commands + inline keyboards via python-telegram-bot
- WhatsApp: Node.js Baileys bridge + Python polling adapter
- All three run concurrently in the same asyncio event loop
Key Components
| Component | Description |
|---|---|
src/main.py |
Entry point — starts all adapters + scheduler + heartbeat |
src/router.py |
Routes messages to Claude or handles commands |
src/claude_session.py |
Claude Code CLI wrapper with --resume sessions |
src/credential_store.py |
Keyring-based secrets manager |
src/scheduler.py |
APScheduler cron jobs |
src/heartbeat.py |
Periodic health checks |
src/memory_search.py |
Ollama embeddings + SQLite semantic search |
cli.py |
CLI tool — status, doctor, logs, secrets, cron, etc. |
setup.sh |
Interactive 10-step setup wizard |
bridge/whatsapp/ |
Node.js WhatsApp bridge (Baileys + Express) |
CLI Usage
The setup wizard installs eco as a global command (~/.local/bin/eco):
eco status # Bot online/offline, uptime
eco doctor # Full diagnostic check
eco restart # Restart the service
eco restart --bridge # Restart bot + WhatsApp bridge
eco stop # Stop the service
eco logs # Tail echo-core.log (last 20 lines)
eco logs 50 # Last 50 lines
eco secrets list # Show stored credentials
eco secrets set <name> # Store a secret in keyring
eco secrets test # Check required secrets
eco sessions list # Active Claude sessions
eco sessions clear # Clear all sessions
eco channel list # Registered Discord channels
eco cron list # Show scheduled jobs
eco cron run <name> # Force-run a cron job
eco memory search "<query>" # Semantic search in memory
eco memory reindex # Rebuild search index
eco heartbeat # Run health checks
eco whatsapp status # WhatsApp bridge connection
eco whatsapp qr # QR code pairing instructions
eco send <alias> <message> # Send message via router
Configuration
config.json — runtime configuration:
{
"bot": {
"name": "Echo",
"default_model": "opus",
"owner": "DISCORD_USER_ID",
"admins": ["TELEGRAM_USER_ID"]
},
"channels": { },
"telegram_channels": { },
"whatsapp": {
"enabled": true,
"bridge_url": "http://127.0.0.1:8098",
"owner": "PHONE_NUMBER"
},
"whatsapp_channels": { }
}
Secrets (Discord/Telegram tokens) are stored in the system keyring, not in config files.
Services
Echo Core runs as systemd user services:
systemctl --user start echo-core # Start bot
systemctl --user start echo-whatsapp-bridge # Start WA bridge
systemctl --user status echo-core # Check status
journalctl --user -u echo-core -f # Follow logs
Requirements
- Python 3.12+
- Claude Code CLI
- Node.js 22+ (only for WhatsApp bridge)
Tests
source .venv/bin/activate
pytest tests/
440 tests, zero failures.