2026-07-11 09:45:06 +02:00
|
|
|
# Gogo Telefon
|
|
|
|
|
|
|
|
|
|
Voice-first AI receptionist for small service businesses in Bosnia and Herzegovina.
|
|
|
|
|
The agent answers forwarded calls (and web chat), speaks Bosnian, checks real
|
|
|
|
|
availability and sends **booking proposals** to the salon owner — it never books
|
|
|
|
|
appointments itself. See `docs/` and the product spec for details.
|
|
|
|
|
|
|
|
|
|
## Architecture (short version)
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
caller → salon number (conditional forwarding) → GSM gateway → Asterisk
|
|
|
|
|
→ ring group (staff softphones) → no answer → voice agent (Pipecat)
|
|
|
|
|
→ tools HTTP → FastAPI backend → SchedulingProvider (Google Calendar | Partner API)
|
|
|
|
|
→ proposal email / partner push → owner action → (optional) SMS to client
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Everything self-hosted except LLM + TTS APIs (swappable interfaces).
|
|
|
|
|
|
|
|
|
|
## Development
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
uv venv && uv pip install -e '.[dev]'
|
|
|
|
|
docker compose up -d db # Postgres 16 on localhost:5433 (or use your own)
|
|
|
|
|
export GOGO_DATABASE_URL=postgresql+psycopg://gogo:gogo@localhost:5432/gogo
|
|
|
|
|
.venv/bin/alembic upgrade head
|
|
|
|
|
.venv/bin/uvicorn gogo.main:app --reload
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Run tests (SQLite, no services needed):
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
.venv/bin/python -m pytest
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The fake partner booking API used in tests (`tests/fake_partner.py`) doubles as
|
|
|
|
|
the **reference implementation of Appendix B** for partner IT teams:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
.venv/bin/uvicorn tests.fake_partner:app --port 9100
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Layout
|
|
|
|
|
|
|
|
|
|
| Path | What |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `gogo/scheduling/` | `SchedulingProvider` interface + `google_calendar`, `partner_api`, `mock` |
|
|
|
|
|
| `gogo/proposals/` | proposal engine, action tokens, owner emails, .ics |
|
|
|
|
|
| `gogo/sms/` | `SmsProvider` (console now, GSM gateway in M5) + Bosnian templates |
|
|
|
|
|
| `gogo/api/` | action links, partner webhook, health |
|
|
|
|
|
| `gogo/agent/` | LLM agent: prompt composition, tools, conversation loop (M2) |
|
|
|
|
|
| `gogo/voice/` | Pipecat voice pipeline (M4) |
|
|
|
|
|
| `gogo/telephony/` | Asterisk/GSM/forwarding codes (M4/M5) |
|
|
|
|
|
| `tests/fake_partner.py` | Appendix B reference implementation |
|
|
|
|
|
|
|
|
|
|
All code/comments in English; all client- and owner-facing text in Bosnian (Latin).
|
M6 + M0: hardening, deploy docs, PoC scripts
- Pipeline-down fallback: dialplan plays gogo-fallback after a failed
AudioSocket (§15) + script to synthesize the Bosnian prompt via TTS
- Voice heartbeat file → /health/voice endpoint + live status in admin panel
- Retention job also purges stale call registrations; chat sessions metered;
100%-usage super-admin alert email (GOGO_ADMIN_ALERT_EMAIL)
- .env.example, docs/DEPLOY.md (compose stack, GPU node, backups pg_dump,
update procedure, security notes)
- §16 Definition of Done as an automated test: softphone-style call → fake
partner availability → request pushed → webhook confirm → console SMS
- M0 PoC scripts: STT accuracy harness (CER/WER + spoken-digit check; dry-run
verified with espeak-ng samples + faster-whisper small on CPU — phone number
extracted exactly), TTS bake-off (Azure vs ElevenLabs, latency+cost), and
end-to-end latency smoke test speaking real AudioSocket to the live pipeline
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-11 11:27:05 +02:00
|
|
|
|
|
|
|
|
## Status (software phase complete)
|
|
|
|
|
|
|
|
|
|
| Milestone | State |
|
|
|
|
|
|---|---|
|
|
|
|
|
| M0 PoC scripts (STT/TTS/latency) | ✅ written + dry-run; real numbers need founder recordings + API keys |
|
|
|
|
|
| M1 backend core + proposal engine | ✅ |
|
|
|
|
|
| M2 agent in text mode | ✅ (Appendix-A acceptance tests run when an Anthropic key is set) |
|
|
|
|
|
| M3 widget + dashboard + super-admin | ✅ verified live in browser |
|
|
|
|
|
| M4 voice pipeline (softphone path) | ✅ incl. real-Asterisk config validation |
|
|
|
|
|
| M5 hardware layer (GSM/SMS/forwarding) | ✅ written + mock-tested; live runbook in `docs/HARDWARE_TESTING.md` |
|
|
|
|
|
| M6 hardening + deploy | ✅ `docs/DEPLOY.md` |
|
|
|
|
|
|
|
|
|
|
The §16 Definition of Done is an automated test: `tests/test_definition_of_done.py`.
|
|
|
|
|
|
|
|
|
|
Still needed from the founder: Anthropic API key, TTS key (Azure/ElevenLabs
|
|
|
|
|
bake-off via `scripts/poc/tts_bakeoff.py`), speech samples for
|
|
|
|
|
`scripts/poc/stt_test.py`, GSM gateway hardware + SIMs, Google OAuth client
|
|
|
|
|
(for Calendar tenants), SMTP account.
|