# 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 | | `service_account.h/.cpp` | `ServiceAccountKey`, `JwtSigner` (RS256), `ServiceAccountAuth` (self-refreshing bearer) | | `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 - 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. - 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 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). - 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 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`. - 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. - 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`). - 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.