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

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