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

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):

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

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

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.