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