Files
moloapp/plans/18-breadth.md
T

9.6 KiB

18 Breadth: the rest of Google Cloud and every other AI vendor

Status: planned 2026-10-25. Goal: offer as many provider APIs as possible through the framework, each built the way plans 16 (Google) and 17 (LLM vendors) were built. Read both first: the method, the rules and the caps there apply unchanged unless this file says otherwise.

Foundation already in place: src/google (GoogleClient, Service, CloudContext, wait_operation, list_all, api_catalog.h), src/llm (ApiClient, Service, SseDecoder, ChatModel, Config::get), the WebSocket client in src/google/live, Sha256 / Hmac / Base64 / SecureRandom in src/security/crypto.

Google's Discovery directory lists 316 preferred APIs (https://discovery.googleapis.com/discovery/v1/apis, 2026-10-25). Package discovery reaches all of them generically; the other Google packages give the most useful ones typed classes.

1. Google packages (one worktree each)

Dir src/google/<pkg>/, tests tests/src/google/<pkg>/, namespace molo::google::<pkg>, demo example/app/google/<Pkg>Demo.cpp, routes /google/<pkg>, assets example/assets/google_<pkg>.js.

Package Covers
discovery One generic engine for all 316 preferred Discovery APIs: fetch and cache a Discovery document (hard caps on size, count, age), list the APIs, list the methods of an API, and call any method by id (bigquery.jobs.query) with path / query parameter validation, request body as Json, pagination (list_all), long-running operations, media-free methods first. Resolves the base URL, regional endpoints and prefer_key. A committed tools/check_discovery_directory.py fetches the directory and reports APIs the engine cannot handle (and why). Every other Google package may use it but must not depend on it
cloudai Cloud Translation v3 (text, glossaries, batch, adaptive MT, documents), Cloud Vision (annotate, files, product search), Natural Language, Video Intelligence, Document AI (processors, process, batch), Speech v2 / Chirp if Discovery has it, Text-to-Speech long audio, Media Translation if public
enterprise Discovery Engine (Gemini Enterprise search, answer, assistants, agents, data stores, engines, documents, conversations, sessions, user events), Dialogflow ES and CX, Retail, Contact Center Insights, CES, Recommendations
data BigQuery (jobs, queries, datasets, tables, routines, models, streaming insert), Cloud Storage (JSON API: buckets, objects, simple and resumable upload, compose, signed URLs), Pub/Sub, Firestore, Spanner, Bigtable admin, Secret Manager, Dataplex, DLP, Cloud KMS, Datastore
maps Places (new), Address Validation, Solar, Pollen, Air Quality, Area Insights, Routes, Geocoding, Time Zone, Elevation, Street View Publish, Maps Platform key rules
workspace Gmail, Drive, Calendar, Sheets, Docs, Slides, Forms, Tasks, Chat, Meet, People, Keep, Classroom, YouTube Data / Analytics / Reporting, Admin SDK Directory and Reports, Groups settings, Vault. OAuth user tokens and domain-wide delegation (service-account sub claim)
ops Compute, Cloud Run, Cloud Functions, GKE (container), Cloud Build, Artifact Registry, IAM (roles, service accounts, keys), Resource Manager, Service Usage (enable / disable / list), Logging, Monitoring, Cloud Scheduler, Cloud Tasks, Workflows, Eventarc, Billing, Cloud Asset, Org Policy

Google rules in addition to plan 16:

  • Live checks use the service account on project lisa-448004 (make google-live, token from build/google/sa-token). Read-only only: no create, update, delete, no sends (no mail, no chat message), no writes to buckets, tables or topics. Live tests report a disabled API loudly (API NOT ENABLED). Costly APIs (Vision, Translation, Document AI, Video Intelligence, Maps) are touched with at most one smallest request and only with MOLO_LIVE_PAID=1.
  • Each package SPEC has a ## Required APIs section in the form used by the other module SPECs (service names, activation URL with the placeholder project example-214512124). Do not edit api_catalog.* or APIS.md; list the services in your report and the owner adds them.
  • A package that needs a service-account scope other than cloud-platform (Workspace) says which scope in its SPEC and how the credential supplies it.

2. Vendor packages (one worktree each)

Dir src/vendors/<v>/, tests tests/src/vendors/<v>/, namespace molo::<v>, demo example/app/ai/<V>Demo.cpp, routes /ai/<v>, assets example/assets/ai_<v>.js. Rules of plan 17 apply (call table, check_spec.py, SPEC sections, llm::Service, ChatModel implementation where the vendor has chat, env key names via llm::Config::get).

Package Covers
compat A registry of OpenAI-compatible providers, each a table row (name, base URL, env key, auth header, model-list path, quirks): Groq, Together, Fireworks, Cerebras, SambaNova, DeepInfra, Hyperbolic, Novita, Nvidia NIM, Cloudflare Workers AI, GitHub Models, Moonshot (Kimi), Alibaba DashScope (Qwen), Zhipu (GLM), MiniMax, Baidu Qianfan, Volcengine Ark, SiliconFlow, Lepton, Nebius, Lambda, Ollama, LM Studio, vLLM, llama.cpp server, LocalAI, and any others you find with a public OpenAI-compatible endpoint. One CompatChatModel : ChatModel, chat, embeddings, models, images and audio where the row says the provider has them. Each row cites its documentation URL
mistral La Plateforme: chat, FIM, agents, conversations, embeddings, moderation, OCR, audio transcription, files, fine-tuning, batch, libraries, models, classifiers; MistralChatModel
cohere Chat v2, embed, rerank, classify, summarize if present, datasets, embed jobs, connectors, fine-tuning, models, tokenize; CohereChatModel
perplexity Sonar chat completions (search options, citations, reasoning), Search API, async chat, embeddings if present; PerplexityChatModel
bedrock Amazon Bedrock: AWS Signature V4 signing (own class, wolfCrypt HMAC / SHA-256), Converse and ConverseStream (event-stream framing), InvokeModel, model list, guardrails, agents runtime, knowledge bases retrieve, batch inference; BedrockChatModel
azure Azure OpenAI / AI Foundry: deployments, api-version, key and Entra-token auth, chat, responses, embeddings, images, audio, assistants, batch, fine-tuning; Foundry model catalog inference
huggingface Inference Providers router, Inference Endpoints management API, Hub API (models, datasets, spaces, repos read), Text Generation Inference, Inference API tasks
audio ElevenLabs (TTS, STT, voices, dubbing, agents / conversational AI, sound effects), AssemblyAI, Deepgram, Cartesia, Speechmatics, PlayHT / Hume if public
media Stability AI, Black Forest Labs (FLUX), Runway, Luma, Replicate, fal, Ideogram, Recraft, Leonardo, Kling / Pika / Hailuo if public APIs exist
retrieval Voyage AI, Jina AI (embeddings, rerank, reader, search), Pinecone, Qdrant, Weaviate, Mixedbread, Tavily, Exa, Brave Search API

Vendor rules in addition to plan 17: no key is present for any of them, so live tests are the opt-in kind with a loud SKIP. A product with no public API is said so in the SPEC and not invented. When a vendor publishes an OpenAPI document, check_spec.py must check against it.

3. Rules for everyone

  1. Read AGENTS.md, plans 16 and 17, src/llm/SPEC.md, src/google/SPEC.md and one finished package of the same family with its tests and demo.
  2. Do not edit shared files: Makefile, src/ai.mk, src/google/google.mk, src/google/*.{h,cpp} foundation files (including api_catalog.*), src/llm/*, example/example.mk, example/app/App.*, example/app/AiDemos.hpp, example/app/GoogleDemos.hpp, example/app/ai/AiDemos.cpp, example/app/google/GoogleDemos.cpp, example/app/Templates.cpp, example/locustfile.py, example/check_locust_coverage.py, tests/example/support/*, any README, example/SPEC.md, src/google/APIS.md, other packages' files. Build globs pick up new files. If a foundation gap blocks you, work around it inside your package and report it.
  3. Demo routes: GET page and /status answer 2xx with no credential; every route that calls the provider is POST or DELETE and answers 503 not_configured (google_not_configured for Google) without a credential, 422 on bad input; paid, sending or destructive routes are dry runs unless the body has "confirm":true. Mobile-first at 360px. One template registered inside the register function, optional asset script. Matrix rows with services.add_feature(name, page) for the GET page only.
  4. Example tests: tests/example/google/<pkg>/*_test.cpp or tests/example/ai/<v>/*_test.cpp. Never script a provider reply.
  5. Everything under /google and /ai is excluded from locust. Do not touch example/locustfile.py.
  6. Build and test: make google-test or make ai-test, and make -f example/example.mk example-test. Do not run make lint. Never print, log or commit a credential; do not read .env.json.local or .secrets/. No em dashes anywhere. Commit subjects at most 100 chars, feat(clients): <package>: <summary>, ending with the Co-Authored-By line from your system reminder.
  7. Hard caps on every count, size, interval, wait and page walk. Destructive calls are explicit methods without defaults.
  8. Final report under 250 words: files, routes, test counts, what was verified how, the Unverified list, foundation gaps, Google services used.

4. Integration (after the worktrees finish)

Merge each branch, add the services to api_catalog.* and APIS.md, add the credential rows to src/llm/SPEC.md section 5, update the READMEs and example/SPEC.md, run the whole suite, make google-live, lint, then release.

5. Gaps

(filled in at integration)