diff --git a/example/app/AiDemos.hpp b/example/app/AiDemos.hpp index 3135713..a6a9724 100644 --- a/example/app/AiDemos.hpp +++ b/example/app/AiDemos.hpp @@ -28,6 +28,16 @@ void register_ai_openai_demo(fw::Router& router, Services& services); void register_ai_openaiplatform_demo(fw::Router& router, Services& services); void register_ai_openaiadmin_demo(fw::Router& router, Services& services); void register_ai_openrouter_demo(fw::Router& router, Services& services); +void register_ai_compat_demo(fw::Router& router, Services& services); +void register_ai_mistral_demo(fw::Router& router, Services& services); +void register_ai_cohere_demo(fw::Router& router, Services& services); +void register_ai_perplexity_demo(fw::Router& router, Services& services); +void register_ai_bedrock_demo(fw::Router& router, Services& services); +void register_ai_azure_demo(fw::Router& router, Services& services); +void register_ai_huggingface_demo(fw::Router& router, Services& services); +void register_ai_audio_demo(fw::Router& router, Services& services); +void register_ai_media_demo(fw::Router& router, Services& services); +void register_ai_retrieval_demo(fw::Router& router, Services& services); // Mounts every vendor router at "" (called once from build_application). void register_ai_demos(std::shared_ptr app, Services& services); diff --git a/example/app/App.cpp b/example/app/App.cpp index 5689bdd..51651eb 100644 --- a/example/app/App.cpp +++ b/example/app/App.cpp @@ -1,6 +1,7 @@ #include "App.hpp" #include "AgentDemos.hpp" #include "AiDemos.hpp" +#include "GoogleDemos.hpp" namespace molo::example::app { @@ -75,6 +76,7 @@ std::shared_ptr build_application(Services& services) { register_agent_demos(app, services); register_ai_demos(app, services); + register_google_demos(app, services); register_chain_demo(app, services); return app; diff --git a/example/app/GoogleDemos.hpp b/example/app/GoogleDemos.hpp new file mode 100644 index 0000000..83f1ab5 --- /dev/null +++ b/example/app/GoogleDemos.hpp @@ -0,0 +1,28 @@ +#pragma once + +// Google Cloud API demos beyond the Agent Platform. One register function per +// package, each in its own file under example/app/google/. Every route lives +// under /google/ and is excluded from locust (paid or private +// APIs). Same rules as AgentDemos.hpp: GET pages and status routes answer 2xx +// without a credential; a route that would call Google is a POST (or DELETE) +// and answers 503 google_not_configured without a credential, 422 on bad +// input; costly or destructive routes are dry runs unless the body has +// "confirm":true. State lives inside the register function; do not edit +// Services. The client is services.google (null: GoogleClient::from_env()). + +#include "App.hpp" + +namespace molo::example::app { + +void register_google_discovery_demo(fw::Router& router, Services& services); +void register_google_cloudai_demo(fw::Router& router, Services& services); +void register_google_enterprise_demo(fw::Router& router, Services& services); +void register_google_data_demo(fw::Router& router, Services& services); +void register_google_maps_demo(fw::Router& router, Services& services); +void register_google_workspace_demo(fw::Router& router, Services& services); +void register_google_ops_demo(fw::Router& router, Services& services); + +// Mounts every package's router at "" (called once from build_application). +void register_google_demos(std::shared_ptr app, Services& services); + +} // namespace molo::example::app diff --git a/example/app/ai/AiDemos.cpp b/example/app/ai/AiDemos.cpp index 7901da5..fbb8511 100644 --- a/example/app/ai/AiDemos.cpp +++ b/example/app/ai/AiDemos.cpp @@ -55,6 +55,56 @@ void register_ai_demos(std::shared_ptr app, Services& services) register_ai_openrouter_demo(r, services); app->include_router("", r); } + { + fw::Router r; + register_ai_compat_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_mistral_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_cohere_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_perplexity_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_bedrock_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_azure_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_huggingface_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_audio_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_media_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_ai_retrieval_demo(r, services); + app->include_router("", r); + } } } // namespace molo::example::app diff --git a/example/app/ai/AudioDemo.cpp b/example/app/ai/AudioDemo.cpp new file mode 100644 index 0000000..2edea9c --- /dev/null +++ b/example/app/ai/AudioDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// audio. Stub: the package agent fills this in. +void register_ai_audio_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/AzureDemo.cpp b/example/app/ai/AzureDemo.cpp new file mode 100644 index 0000000..e33aef9 --- /dev/null +++ b/example/app/ai/AzureDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// azure. Stub: the package agent fills this in. +void register_ai_azure_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/BedrockDemo.cpp b/example/app/ai/BedrockDemo.cpp new file mode 100644 index 0000000..7be3bc9 --- /dev/null +++ b/example/app/ai/BedrockDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// bedrock. Stub: the package agent fills this in. +void register_ai_bedrock_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/CohereDemo.cpp b/example/app/ai/CohereDemo.cpp new file mode 100644 index 0000000..333f0ca --- /dev/null +++ b/example/app/ai/CohereDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// cohere. Stub: the package agent fills this in. +void register_ai_cohere_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/CompatDemo.cpp b/example/app/ai/CompatDemo.cpp new file mode 100644 index 0000000..9d41d1f --- /dev/null +++ b/example/app/ai/CompatDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// compat. Stub: the package agent fills this in. +void register_ai_compat_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/HuggingfaceDemo.cpp b/example/app/ai/HuggingfaceDemo.cpp new file mode 100644 index 0000000..2110b89 --- /dev/null +++ b/example/app/ai/HuggingfaceDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// huggingface. Stub: the package agent fills this in. +void register_ai_huggingface_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/MediaDemo.cpp b/example/app/ai/MediaDemo.cpp new file mode 100644 index 0000000..398386b --- /dev/null +++ b/example/app/ai/MediaDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// media. Stub: the package agent fills this in. +void register_ai_media_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/MistralDemo.cpp b/example/app/ai/MistralDemo.cpp new file mode 100644 index 0000000..5250adf --- /dev/null +++ b/example/app/ai/MistralDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// mistral. Stub: the package agent fills this in. +void register_ai_mistral_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/PerplexityDemo.cpp b/example/app/ai/PerplexityDemo.cpp new file mode 100644 index 0000000..a1e4ef2 --- /dev/null +++ b/example/app/ai/PerplexityDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// perplexity. Stub: the package agent fills this in. +void register_ai_perplexity_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/ai/RetrievalDemo.cpp b/example/app/ai/RetrievalDemo.cpp new file mode 100644 index 0000000..fe9ca0c --- /dev/null +++ b/example/app/ai/RetrievalDemo.cpp @@ -0,0 +1,13 @@ +#include "../AiDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// retrieval. Stub: the package agent fills this in. +void register_ai_retrieval_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/google/CloudaiDemo.cpp b/example/app/google/CloudaiDemo.cpp new file mode 100644 index 0000000..4a33623 --- /dev/null +++ b/example/app/google/CloudaiDemo.cpp @@ -0,0 +1,13 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Translation, Vision, Natural Language, Video Intelligence, Document AI. Stub: the package agent fills this in. +void register_google_cloudai_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/google/DataDemo.cpp b/example/app/google/DataDemo.cpp new file mode 100644 index 0000000..a48f2a8 --- /dev/null +++ b/example/app/google/DataDemo.cpp @@ -0,0 +1,13 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// BigQuery, Cloud Storage, Pub/Sub, Firestore, Spanner, Bigtable, Secret Manager, Dataplex, DLP, KMS. Stub: the package agent fills this in. +void register_google_data_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/google/DiscoveryDemo.cpp b/example/app/google/DiscoveryDemo.cpp new file mode 100644 index 0000000..64a6bbc --- /dev/null +++ b/example/app/google/DiscoveryDemo.cpp @@ -0,0 +1,13 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// every Google API generically (all 316 Discovery documents). Stub: the package agent fills this in. +void register_google_discovery_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/google/EnterpriseDemo.cpp b/example/app/google/EnterpriseDemo.cpp new file mode 100644 index 0000000..15cab45 --- /dev/null +++ b/example/app/google/EnterpriseDemo.cpp @@ -0,0 +1,13 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Discovery Engine (Gemini Enterprise search and agents), Dialogflow, Retail, Contact Center Insights. Stub: the package agent fills this in. +void register_google_enterprise_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/google/GoogleDemos.cpp b/example/app/google/GoogleDemos.cpp new file mode 100644 index 0000000..aca10e0 --- /dev/null +++ b/example/app/google/GoogleDemos.cpp @@ -0,0 +1,45 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +void register_google_demos(std::shared_ptr app, Services& services) { + { + fw::Router r; + register_google_discovery_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_google_cloudai_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_google_enterprise_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_google_data_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_google_maps_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_google_workspace_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_google_ops_demo(r, services); + app->include_router("", r); + } +} + +} // namespace molo::example::app diff --git a/example/app/google/MapsDemo.cpp b/example/app/google/MapsDemo.cpp new file mode 100644 index 0000000..c8298ec --- /dev/null +++ b/example/app/google/MapsDemo.cpp @@ -0,0 +1,13 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Places, Address Validation, Solar, Pollen, Air Quality, Area Insights, Routes, Geocoding. Stub: the package agent fills this in. +void register_google_maps_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/google/OpsDemo.cpp b/example/app/google/OpsDemo.cpp new file mode 100644 index 0000000..c11eaa0 --- /dev/null +++ b/example/app/google/OpsDemo.cpp @@ -0,0 +1,13 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Compute, Cloud Run, Functions, GKE, IAM, Resource Manager, Service Usage, Logging, Monitoring, Build, Artifact Registry. Stub: the package agent fills this in. +void register_google_ops_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/google/WorkspaceDemo.cpp b/example/app/google/WorkspaceDemo.cpp new file mode 100644 index 0000000..00c4a0b --- /dev/null +++ b/example/app/google/WorkspaceDemo.cpp @@ -0,0 +1,13 @@ +#include "../GoogleDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Gmail, Drive, Calendar, Sheets, Docs, Slides, Forms, Tasks, Chat, Meet, People, YouTube. Stub: the package agent fills this in. +void register_google_workspace_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/check_locust_coverage.py b/example/check_locust_coverage.py index 85907a2..31cfa37 100644 --- a/example/check_locust_coverage.py +++ b/example/check_locust_coverage.py @@ -18,7 +18,7 @@ EXCLUDED = {"/voice/say", "/voice/hear", "/voice/turn", "/voice/reset"} # Whole areas that talk to (or front) paid Google APIs. Routes under these # prefixes are never load tested and never required to be covered. EXCLUDED_PREFIXES = ("/voice", "/google", "/agent", "/ai", "/embedded/voice.js", - "/embedded/agent_", "/embedded/ai_") + "/embedded/agent_", "/embedded/ai_", "/embedded/google_") def is_excluded(route: str) -> bool: diff --git a/example/example.mk b/example/example.mk index 0772722..5348494 100644 --- a/example/example.mk +++ b/example/example.mk @@ -55,7 +55,8 @@ EXAMPLE_SRCS = \ $(EXAMPLE_DIR)/app/ResilienceDemo.cpp \ $(EXAMPLE_DIR)/app/VoiceDemo.cpp \ $(sort $(wildcard $(EXAMPLE_DIR)/app/agent/*.cpp)) \ - $(sort $(wildcard $(EXAMPLE_DIR)/app/ai/*.cpp)) + $(sort $(wildcard $(EXAMPLE_DIR)/app/ai/*.cpp)) \ + $(sort $(wildcard $(EXAMPLE_DIR)/app/google/*.cpp)) # Tests are discovered: every tests/example/**/*_test.cpp is one route test. EXAMPLE_TEST_JOBS ?= 8 diff --git a/plans/18-breadth.md b/plans/18-breadth.md new file mode 100644 index 0000000..45bfd82 --- /dev/null +++ b/plans/18-breadth.md @@ -0,0 +1,121 @@ +# 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//`, tests `tests/src/google//`, namespace +`molo::google::`, demo `example/app/google/Demo.cpp`, routes +`/google/`, assets `example/assets/google_.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//`, tests `tests/src/vendors//`, namespace +`molo::`, demo `example/app/ai/Demo.cpp`, routes `/ai/`, assets +`example/assets/ai_.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//*_test.cpp` or + `tests/example/ai//*_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): : `, 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) diff --git a/src/ai.mk b/src/ai.mk index 62882c7..e16608b 100644 --- a/src/ai.mk +++ b/src/ai.mk @@ -1,6 +1,6 @@ # Per-part fragment for the LLM vendor platforms (owned dirs: src/llm shared # layer, src/xai, src/anthropic, src/meta, src/deepseek, src/openai, -# src/openrouter). Included by the root +# src/openrouter, src/vendors/). Included by the root # Makefile, or run standalone: # make -f src/ai.mk [ai|ai-test|ai-clean] # Root wiring: `all` depends on `ai`, `test` on `ai-test`, `clean` on `ai-clean`. @@ -18,14 +18,16 @@ GOOGLE_LIB ?= $(ROOT)/build/google/libgoogle.a # Recursive: every vendor module builds without editing this file. AI_SRCS := $(sort $(shell find $(ROOT)/src/llm $(ROOT)/src/xai $(ROOT)/src/anthropic \ - $(ROOT)/src/meta $(ROOT)/src/deepseek $(ROOT)/src/openai $(ROOT)/src/openrouter -name "*.cpp")) \ + $(ROOT)/src/meta $(ROOT)/src/deepseek $(ROOT)/src/openai $(ROOT)/src/openrouter \ + $(ROOT)/src/vendors -name "*.cpp")) \ $(ROOT)/src/security/crypto/Base64.cpp \ $(ROOT)/src/security/crypto/Sha256.cpp \ $(ROOT)/src/security/crypto/Hmac.cpp \ $(ROOT)/src/security/crypto/SecureRandom.cpp AI_TEST_SRCS := $(sort $(shell find $(ROOT)/tests/src/llm $(ROOT)/tests/src/xai \ $(ROOT)/tests/src/anthropic $(ROOT)/tests/src/meta \ - $(ROOT)/tests/src/deepseek $(ROOT)/tests/src/openai $(ROOT)/tests/src/openrouter -name "*.cpp")) + $(ROOT)/tests/src/deepseek $(ROOT)/tests/src/openai $(ROOT)/tests/src/openrouter \ + $(ROOT)/tests/src/vendors -name "*.cpp")) AI_BUILD := $(ROOT)/build/ai AI_OBJDIR := $(AI_BUILD)/objs