2026-10-24 04:05:41 +02:00
|
|
|
# Google Cloud APIs - Specification
|
|
|
|
|
|
|
|
|
|
Owned directory: `src/google/`. Namespace `molo::google`. Depends on
|
|
|
|
|
`molo::clients` (HTTP client, JSON DOM, transports) and the Base64 codec in
|
|
|
|
|
`src/security/crypto`. No other part is included.
|
|
|
|
|
|
|
|
|
|
Purpose: one generic way to call any Google Cloud REST API, plus concrete
|
|
|
|
|
services built on it. Voice (text-to-speech, speech-to-text, Gemini reply and audio,
|
|
|
|
|
conversation pipeline) is the first set. Adding a service means one
|
|
|
|
|
`ServiceEndpoint` constant and one `Service` subclass; no change to the
|
|
|
|
|
client, credentials, errors, or caps.
|
|
|
|
|
|
|
|
|
|
## 1. Module map (one class or concern per file)
|
|
|
|
|
|
|
|
|
|
| File | Concern |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `caps.h` | Static ceilings, never autotuned |
|
|
|
|
|
| `errors.h/.cpp` | `GoogleError` (http status, Google status, message), `NotConfiguredError`, parser for Google's `{"error":{...}}` body |
|
|
|
|
|
| `credentials.h/.cpp` | `Credentials`: API key and OAuth bearer providers, env loader |
|
2026-10-24 04:29:48 +02:00
|
|
|
| `service_account.h/.cpp` | `ServiceAccountKey`, `JwtSigner` (RS256), `ServiceAccountAuth` (self-refreshing bearer) |
|
2026-10-24 04:05:41 +02:00
|
|
|
| `endpoints.h/.cpp` | `ServiceEndpoint` plus the catalog of known services |
|
|
|
|
|
| `client.h/.cpp` | `GoogleClient`: auth, JSON in/out, error mapping, over any `clients::Transport` |
|
|
|
|
|
| `service.h/.cpp` | `Service` base class: holds client plus endpoint, one `call()` |
|
|
|
|
|
| `text_to_speech.h/.cpp` | `TextToSpeech::synthesize`, `voices` |
|
|
|
|
|
| `speech_to_text.h/.cpp` | `SpeechToText::recognize` |
|
|
|
|
|
| `generative.h/.cpp` | `Generative::generate` (Gemini `generateContent`) |
|
|
|
|
|
| `voice_io.h/.cpp` | `Recognizer`, `Synthesizer` seams plus request and audio types |
|
|
|
|
|
| `gemini_voice.h/.cpp` | Gemini-based `Recognizer` and `Synthesizer` |
|
|
|
|
|
| `voice_backend.h/.cpp` | `cloud` / `gemini` / `vertex` selection and wiring |
|
|
|
|
|
| `wav.h/.cpp` | PCM16 to WAV |
|
|
|
|
|
| `voice.h/.cpp` | `Responder`, `GenerativeResponder`, `VoiceSessions`, `VoicePipeline` |
|
|
|
|
|
|
|
|
|
|
## 2. Static caps (see caps.h)
|
|
|
|
|
|
|
|
|
|
| Knob | Value |
|
|
|
|
|
|---|---|
|
|
|
|
|
| TTS text characters per request | 5000 |
|
|
|
|
|
| STT audio bytes per request | 10 MiB (Google sync limit) |
|
|
|
|
|
| Generation output tokens | 300 default, 1024 max |
|
|
|
|
|
| Conversation history | 20 turns per conversation |
|
|
|
|
|
| Conversations held in memory | 1000, oldest evicted |
|
|
|
|
|
| Conversation id | `[A-Za-z0-9_-]`, 1 to 64 chars |
|
|
|
|
|
| Message text per history entry | 4000 characters |
|
|
|
|
|
| Request timeout (total) | 60 s (client default) |
|
|
|
|
|
|
|
|
|
|
## 3. Contracts
|
|
|
|
|
|
2026-10-24 04:29:48 +02:00
|
|
|
- Two credentials per client: an API key and an OAuth credential (bearer
|
|
|
|
|
token or service account via `GOOGLE_APPLICATION_CREDENTIALS`). OAuth is
|
|
|
|
|
used for every endpoint except express ones (`ServiceEndpoint::prefer_key`,
|
|
|
|
|
the Vertex express voice path), which only accept the key.
|
2026-10-24 04:05:41 +02:00
|
|
|
- Credentials: `GOOGLE_API_KEY` is read once by `GoogleClient::from_env()`
|
|
|
|
|
from the process environment, else `.env.json.local` (git-ignored, put
|
|
|
|
|
secrets here), else `.env.json`, in the working directory. All env knobs
|
|
|
|
|
below follow the same order.
|
|
|
|
|
The key travels in the `x-goog-api-key` header, never in the URL, so it
|
|
|
|
|
never reaches a span, log line, or proxy URL. Bearer tokens (OAuth, for
|
2026-10-24 04:12:52 +02:00
|
|
|
APIs that refuse keys) use the same seam: `Credentials::bearer`; a
|
|
|
|
|
`GOOGLE_ACCESS_TOKEN` (same lookup order) takes precedence over a key.
|
|
|
|
|
Tokens expire after about an hour; refresh is the caller's job (gap).
|
2026-10-24 04:46:35 +02:00
|
|
|
- Test runs set `MOLO_ENV_FILES=off`: config files are ignored so a developer's
|
|
|
|
|
`.env.json.local` cannot change test outcomes. `MOLO_LIVE_NET=1` re-enables
|
2026-10-25 07:27:24 +01:00
|
|
|
them for the opt-in live checks. `make google-live` is the entry point: it
|
|
|
|
|
mints a service-account token (`build/google/sa-token`), exports it as
|
|
|
|
|
`GOOGLE_ACCESS_TOKEN`, and runs the full suite with `MOLO_LIVE_NET=1`.
|
2026-10-24 04:05:41 +02:00
|
|
|
- No key: `configured()` is false and every call throws `NotConfiguredError`
|
|
|
|
|
(HTTP 503, status `NOT_CONFIGURED`) before any network traffic. Loud, not
|
|
|
|
|
silent.
|
|
|
|
|
- Upstream failure: any non-2xx becomes `GoogleError` carrying the HTTP
|
|
|
|
|
status, Google's `status` string (`PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`,
|
|
|
|
|
...) and message. Transport failures become `GoogleError` with status
|
|
|
|
|
`UNAVAILABLE`. The key is never part of an error message.
|
|
|
|
|
- Invalid input (empty text, text over cap, empty or oversized audio, bad
|
|
|
|
|
conversation id) throws `GoogleError` 400 `INVALID_ARGUMENT` before any
|
|
|
|
|
network traffic.
|
|
|
|
|
- Transports are swappable: production uses `HttpTransport` (HTTPS via
|
|
|
|
|
wolfSSL), tests use `MockTransport`. Calling code does not change.
|
|
|
|
|
- Voice replies disable model thinking (`thinkingBudget` 0): reasoning tokens
|
|
|
|
|
count against the output cap and truncated spoken replies in practice.
|
|
|
|
|
- Backends (`voice_backend.h`): `cloud` (classic TTS/STT), `gemini`
|
|
|
|
|
(generativelanguage audio in/out), `vertex` (aiplatform, express keys
|
|
|
|
|
starting `AQ.`). `GOOGLE_API_BACKEND` overrides the key-prefix guess.
|
|
|
|
|
Gemini TTS returns raw PCM; the server wraps it as WAV.
|
|
|
|
|
- Env knobs: `GOOGLE_API_KEY`, `GOOGLE_VOICE_LANG` (default `nl-NL`),
|
|
|
|
|
`GOOGLE_VOICE_NAME` (default empty: Google picks the language default),
|
|
|
|
|
`GOOGLE_GENAI_MODEL` (default `gemini-3.5-flash`).
|
|
|
|
|
- `VoicePipeline::turn` = recognize, respond, synthesize. Silence (empty
|
|
|
|
|
transcript) returns an empty result with no reply and no synthesis, so a
|
|
|
|
|
quiet room costs one STT call and nothing else.
|
|
|
|
|
- History is bounded per conversation and conversations are bounded in
|
|
|
|
|
count; both evict oldest first.
|
|
|
|
|
|
|
|
|
|
## 4. Gaps
|
|
|
|
|
|
|
|
|
|
- Streaming recognition (gRPC/WebSocket) and the Gemini Live API are not
|
|
|
|
|
implemented; turns are request/response over REST.
|
2026-10-24 04:29:48 +02:00
|
|
|
- Service-account OAuth is implemented (`service_account.h`: RS256 JWT via
|
|
|
|
|
wolfCrypt, token exchange, refresh 60 s before expiry) and its signing is
|
|
|
|
|
tested with real RSA keys. The token exchange against Google itself is
|
|
|
|
|
unverified until a key file is configured (`GOOGLE_APPLICATION_CREDENTIALS`).
|
2026-10-24 04:05:41 +02:00
|
|
|
- Free-tier quota accounting is Google's; `RESOURCE_EXHAUSTED` is surfaced,
|
|
|
|
|
not tracked.
|
|
|
|
|
- Live behavior against Google needs a real `GOOGLE_API_KEY`; the suite
|
|
|
|
|
proves request shape and error mapping with scripted responses only.
|