diff --git a/example/app/AgentDemos.hpp b/example/app/AgentDemos.hpp new file mode 100644 index 0000000..552c00e --- /dev/null +++ b/example/app/AgentDemos.hpp @@ -0,0 +1,30 @@ +#pragma once + +// Agent Platform demos. One register function per module, each in its own +// file under example/app/agent/. Every route lives under /agent/ and +// is excluded from locust (paid Google APIs). Rules for a demo: +// - GET pages and status routes answer 2xx without credentials (the matrix +// test crawls them); anything that calls Google is a POST and answers 503 +// google_not_configured without a credential. +// - State lives in objects created inside the register function and +// captured by the handlers; do not edit Services. +// - The Google client is services.google (null: GoogleClient::from_env()). + +#include "App.hpp" + +namespace molo::example::app { + +void register_agent_models_demo(fw::Router& router, Services& services); +void register_agent_runtime_demo(fw::Router& router, Services& services); +void register_agent_sessions_demo(fw::Router& router, Services& services); +void register_agent_sandbox_demo(fw::Router& router, Services& services); +void register_agent_registry_demo(fw::Router& router, Services& services); +void register_agent_armor_demo(fw::Router& router, Services& services); +void register_agent_optimize_demo(fw::Router& router, Services& services); +void register_agent_adk_demo(fw::Router& router, Services& services); +void register_agent_live_demo(fw::Router& router, Services& services); + +// Mounts every module's router at "" (called once from build_application). +void register_agent_demos(std::shared_ptr app, Services& services); + +} // namespace molo::example::app diff --git a/example/app/App.cpp b/example/app/App.cpp index 44c4bc8..e03a3f0 100644 --- a/example/app/App.cpp +++ b/example/app/App.cpp @@ -1,4 +1,5 @@ #include "App.hpp" +#include "AgentDemos.hpp" namespace molo::example::app { @@ -71,6 +72,8 @@ std::shared_ptr build_application(Services& services) { register_voice_demo(voice, services); app->include_router("", voice); + register_agent_demos(app, services); + register_chain_demo(app, services); return app; } diff --git a/example/app/agent/AdkDemo.cpp b/example/app/agent/AdkDemo.cpp new file mode 100644 index 0000000..4188f28 --- /dev/null +++ b/example/app/agent/AdkDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: adk. Stub: the module agent fills this in. +void register_agent_adk_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/AgentDemos.cpp b/example/app/agent/AgentDemos.cpp new file mode 100644 index 0000000..025073f --- /dev/null +++ b/example/app/agent/AgentDemos.cpp @@ -0,0 +1,55 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +void register_agent_demos(std::shared_ptr app, Services& services) { + { + fw::Router r; + register_agent_models_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_runtime_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_sessions_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_sandbox_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_registry_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_armor_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_optimize_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_adk_demo(r, services); + app->include_router("", r); + } + { + fw::Router r; + register_agent_live_demo(r, services); + app->include_router("", r); + } +} + +} // namespace molo::example::app diff --git a/example/app/agent/ArmorDemo.cpp b/example/app/agent/ArmorDemo.cpp new file mode 100644 index 0000000..9e1d31c --- /dev/null +++ b/example/app/agent/ArmorDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: armor. Stub: the module agent fills this in. +void register_agent_armor_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/LiveDemo.cpp b/example/app/agent/LiveDemo.cpp new file mode 100644 index 0000000..5b17e93 --- /dev/null +++ b/example/app/agent/LiveDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: live. Stub: the module agent fills this in. +void register_agent_live_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/ModelsDemo.cpp b/example/app/agent/ModelsDemo.cpp new file mode 100644 index 0000000..5fc32ea --- /dev/null +++ b/example/app/agent/ModelsDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: models. Stub: the module agent fills this in. +void register_agent_models_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/OptimizeDemo.cpp b/example/app/agent/OptimizeDemo.cpp new file mode 100644 index 0000000..b29ab19 --- /dev/null +++ b/example/app/agent/OptimizeDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: optimize. Stub: the module agent fills this in. +void register_agent_optimize_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/RegistryDemo.cpp b/example/app/agent/RegistryDemo.cpp new file mode 100644 index 0000000..0ee5fc4 --- /dev/null +++ b/example/app/agent/RegistryDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: registry. Stub: the module agent fills this in. +void register_agent_registry_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/RuntimeDemo.cpp b/example/app/agent/RuntimeDemo.cpp new file mode 100644 index 0000000..112d57c --- /dev/null +++ b/example/app/agent/RuntimeDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: runtime. Stub: the module agent fills this in. +void register_agent_runtime_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/SandboxDemo.cpp b/example/app/agent/SandboxDemo.cpp new file mode 100644 index 0000000..8a7b4a8 --- /dev/null +++ b/example/app/agent/SandboxDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: sandbox. Stub: the module agent fills this in. +void register_agent_sandbox_demo(fw::Router& router, Services& services) { + (void)router; + (void)services; +} + +} // namespace molo::example::app diff --git a/example/app/agent/SessionsDemo.cpp b/example/app/agent/SessionsDemo.cpp new file mode 100644 index 0000000..a2b7505 --- /dev/null +++ b/example/app/agent/SessionsDemo.cpp @@ -0,0 +1,13 @@ +#include "../AgentDemos.hpp" + +#include "../../fw/Router.hpp" + +namespace molo::example::app { + +// Agent Platform: sessions. Stub: the module agent fills this in. +void register_agent_sessions_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 a7fa96e..3dbfc3e 100644 --- a/example/check_locust_coverage.py +++ b/example/check_locust_coverage.py @@ -15,6 +15,14 @@ LOCUST = HERE / "locustfile.py" # Routes that call paid Google APIs: never load tested. The check fails if # locust references one, and does not require them to be covered. 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", "/embedded/voice.js", + "/embedded/agent_") + + +def is_excluded(route: str) -> bool: + return route in EXCLUDED or route.startswith(EXCLUDED_PREFIXES) FILLS = {"name": "locust", "id": "1", "status": "404", "tenant": "acme"} @@ -59,7 +67,7 @@ def main() -> int: routes = collect_routes() urls, methods = collect_locust_urls() missing: list[str] = [] - for r in sorted(routes - EXCLUDED): + for r in sorted(r for r in routes if not is_excluded(r)): c = fill(r) ok = ( c in urls @@ -72,7 +80,7 @@ def main() -> int: ) if not ok: missing.append(f"{r} -> {c}") - leaked = sorted(EXCLUDED & urls) + leaked = sorted(u for u in urls if is_excluded(u)) for r in leaked: print("FORBIDDEN (costs money):", r) required_methods = {"get", "post", "put", "options"} @@ -88,7 +96,8 @@ def main() -> int: if missing or missing_methods: print(f"FAIL: {len(missing)} missing routes, {len(missing_methods)} missing methods") return 1 - print(f"OK: {len(routes) - len(EXCLUDED)} routes covered, {len(EXCLUDED)} paid Google routes excluded, methods {sorted(methods)}") + excluded = sum(1 for r in routes if is_excluded(r)) + print(f"OK: {len(routes) - excluded} routes covered, {excluded} paid Google routes excluded, methods {sorted(methods)}") return 0 diff --git a/example/example.mk b/example/example.mk index 781db29..cff54dc 100644 --- a/example/example.mk +++ b/example/example.mk @@ -53,7 +53,8 @@ EXAMPLE_SRCS = \ $(EXAMPLE_DIR)/app/PlatformDemo.cpp \ $(EXAMPLE_DIR)/app/EnterpriseDemo.cpp \ $(EXAMPLE_DIR)/app/ResilienceDemo.cpp \ - $(EXAMPLE_DIR)/app/VoiceDemo.cpp + $(EXAMPLE_DIR)/app/VoiceDemo.cpp \ + $(sort $(wildcard $(EXAMPLE_DIR)/app/agent/*.cpp)) # Tests are discovered: every tests/example/**/*_test.cpp is one route test. EXAMPLE_TEST_JOBS ?= 8 @@ -65,12 +66,8 @@ EXAMPLE_EMBED_SRCS = \ src/cli/embed/gzip_stored.cpp \ src/cli/embed/mime.cpp \ src/cli/embed/sha256.cpp -EXAMPLE_ASSETS = \ - $(EXAMPLE_DIR)/assets/app.css \ - $(EXAMPLE_DIR)/assets/chart.umd.min.js \ - $(EXAMPLE_DIR)/assets/hello.txt \ - $(EXAMPLE_DIR)/assets/stats.js \ - $(EXAMPLE_DIR)/assets/voice.js +# Every file in example/assets is embedded (agent modules add agent_.js). +EXAMPLE_ASSETS = $(sort $(wildcard $(EXAMPLE_DIR)/assets/*)) EXAMPLE_INC = -I$(EXAMPLE_DIR) -I$(EXAMPLE_BUILD) -Isrc # Real framework parts the example links: Google Cloud (src/google) over the # HTTP client (src/clients, wolfSSL TLS) and the operability breaker. diff --git a/example/locustfile.py b/example/locustfile.py index 463a439..7d361c7 100644 --- a/example/locustfile.py +++ b/example/locustfile.py @@ -39,7 +39,6 @@ GETS = [ "/csp/page", "/csp/report", "/di/services", "/di/resolve/locust", "/embedded/chart.umd.min.js", "/embedded/hello.txt", "/embedded/stats.js", - "/embedded/voice.js", "/google/status", "/voice", "/events/fire", "/expose/record", "/expose/stats", "/files/", "/files/welcome.txt", "/flash", "/flash/set", @@ -88,8 +87,8 @@ GETS = [ "/webdav/files/test.txt", ] -# NOT load tested on purpose: /voice/say, /voice/hear, /voice/turn and -# /voice/reset call paid Google APIs (check_locust_coverage.py enforces this). +# NOT load tested on purpose: everything under /voice, /google and /agent +# calls or fronts paid Google APIs (check_locust_coverage.py enforces this). POSTS = [ ("/audit/log", {"event": "locust"}), ("/audit/retention/hold", {"hold": True}), diff --git a/plans/16-agent-platform.md b/plans/16-agent-platform.md new file mode 100644 index 0000000..0514765 --- /dev/null +++ b/plans/16-agent-platform.md @@ -0,0 +1,136 @@ +# 16 Gemini Enterprise Agent Platform + +Status: plan, 2026-10-24. Source: Google's announcement "Introducing Gemini +Enterprise Agent Platform" (the evolution of Vertex AI). The announcement +names products but no REST resources; each module owner researches the real +API from Google's docs and records what could and could not be verified. + +Foundation (already in `src/google/`, read it first): `GoogleClient` +(all verbs, streaming via `stream_json`), `Service`, `GoogleError`, +`Credentials` (API key, OAuth bearer via `GOOGLE_ACCESS_TOKEN`), +`CloudContext` + `endpoints::aiplatform(location)` (`resource.h`), +`wait_operation` + `list_all` (`operation.h`), typed Gemini content and the +`LanguageModel` seam (`gemini_types.h`), `StreamDecoder`. + +## 1. Modules (one worktree each) + +| Module | Dir (src / tests / example) | Covers | +|---|---|---| +| models | `src/google/models` | Model Garden, Gemini on Vertex (generate, stream, count tokens, embeddings), partner models (Claude via rawPredict), open models (Gemma endpoints), media generation (image, music), `VertexModel : LanguageModel` | +| runtime | `src/google/runtime` | Agent Runtime (Agent Engine, `reasoningEngines`): create/get/list/update/delete, query, streamQuery, deployment spec, identity type, batch and event-driven triggers (BigQuery, Pub/Sub) where an API exists | +| sessions | `src/google/sessions` | Agent Sessions (events, custom session IDs) and Agent Memory Bank (generate, retrieve, create, list, delete, memory profiles) | +| sandbox | `src/google/sandbox` | Agent Sandbox (code execution, computer use / browser) and Workspaces (bash, files) | +| registry | `src/google/registry` | Agent Registry, Agent Gateway, Agent Identity | +| armor | `src/google/armor` | Model Armor (templates, sanitize prompt/response), Agent Anomaly Detection, Agent Threat Detection, Agent Security dashboard (Security Command Center findings), `GuardedModel` decorator | +| optimize | `src/google/optimize` | Agent Evaluation, Agent Simulation, Agent Observability (traces, logs), Agent Optimizer | +| adk | `src/google/adk` | Agent Development Kit in C++: agents, tools, runner, multi-agent graph, MCP client, A2A client, Agent Studio export/import, Agent Garden catalog, AP2 types, session/memory seams | +| live | `src/google/live` | Multimodal streaming: Live API over WebSocket (bidirectional audio, video, text), RFC 6455 client | + +## 2. Rules for every module + +1. Read `AGENTS.md`, `src/google/SPEC.md`, the foundation headers, one + finished service (`generative.*`, `voice*.*`) and its tests. +2. Research first. Use WebFetch/WebSearch on Google's official docs + (`docs.cloud.google.com/gemini-enterprise-agent-platform`, Vertex AI + REST references, `cloud.google.com/*/docs`). Record exact resource + paths, HTTP methods, request and response fields. +3. The module SPEC (`src/google//SPEC.md`) has: scope, module map + (one class per concern), static caps table, contracts, `## Sources` + (URLs read), `## Unverified` (every shape or path inferred rather than + read from docs), `## Gaps`. Never invent an endpoint silently. If a + product has no public API, say so and implement only what exists, with + any local abstraction named as local. +4. Object oriented, one concern per file, namespace + `molo::google::`, services derive from `Service`. Hard caps for + every count, size, interval and wait; validate all input and every id + (`valid_segment`) before any network traffic; list calls cap pages. + Destructive calls (delete, purge) are explicit methods, never defaults. +5. Tests: `tests/src/google//test_*.cpp` with `MockTransport` + scripted from the documented shapes: request shape, happy path, error + mapping, validation, caps, pagination and long-running paths. Use the + existing harness (`TEST(suite, name)`, `framework.h`). +6. Example: fill `example/app/agent/Demo.cpp`. Routes live under + `/agent/`. Contract: GET page and status routes answer 2xx with + no credential (the matrix crawler hits them); every route that would + call Google is a POST (or DELETE) and answers 503 + `google_not_configured` without a credential, 422 on bad input. Pages + are mobile-first (360px), one template registered inside the register + function plus an optional script `example/assets/agent_.js`. + Register matrix rows with `services.add_feature(name, "/agent/")` + for the GET page only. State is created inside the register function; + do not edit `Services`. +7. Example tests: `tests/example/agent//*_test.cpp` (Arrange / Act / + Assert as in `tests/README.md`) using `support/GoogleRig.hpp`: happy + path, no credential, validation, 405, one limit case. Set + `GOOGLE_CLOUD_PROJECT` with `setenv` inside the test. +8. All of `/agent/*`, `/google/*`, `/voice/*` are excluded from locust + (`example/check_locust_coverage.py`). Do not add them to + `example/locustfile.py`. +9. Do not edit shared files: `Makefile`, `src/google/google.mk`, + `example/example.mk`, `example/app/App.*`, `example/app/AgentDemos.hpp`, + `example/app/agent/AgentDemos.cpp`, `example/app/Templates.cpp`, + `example/locustfile.py`, `example/check_locust_coverage.py`, + `tests/example/support/*`, any README or `example/SPEC.md`, other + modules' files, or `src/google/*.{h,cpp}` foundation files. If a + foundation gap blocks you, work around it inside your module and list it + in your report. Build globs pick up new files automatically. +10. No live network, no keys. The suite is scripted. Never print or commit + a credential. No em dashes anywhere (code, docs, comments, commits). +11. Build and test: `make google-test` (framework tests) and + `make -f example/example.mk example-test` (example suite). Do not run + `make lint` or a full-repo build. +12. Commit on your worktree branch when green: `feat(clients): : + `, ending with the Co-Authored-By line from your system + reminder. Final report (under 250 words): files added, routes, test + counts, the Unverified list, foundation gaps. + +## 3. Module notes + +- models: express-mode keys use `https://aiplatform.googleapis.com/v1/ + publishers/google/models/{m}:generateContent` (verified live); project + scoped calls use `projects/{p}/locations/{l}/publishers/{pub}/models/{m}`. + Support both. `VertexModel` implements `LanguageModel` (streaming via + `?alt=sse` and `stream_json`). Existing `Generative` and the voice code + must keep working untouched. +- runtime: long-running create/delete use `wait_operation`; deployment + spec fields (package, container, env, scaling, service account / agent + identity) typed, unknown fields kept as raw Json. +- sessions: both resources hang off a runtime resource name; accept the + full name as a string, validated, so this module does not depend on + runtime. +- sandbox: execution results (stdout, stderr, files, exit status) typed; + output sizes capped. +- registry: governance data is read and written by humans too, so list and + get come before mutate; approvals are explicit methods. +- armor: `GuardedModel` wraps any `LanguageModel`, sanitizes the prompt + before and the response after, and throws a typed block error with the + matched filters. Findings are read-only. +- optimize: local scoring logic (multi-turn autorater prompts, failure + clustering, instruction suggestions) codes against `LanguageModel` and is + tested with a fake; API surfaces (evaluateInstances, traces, logs) are + scripted. +- adk: codes against `LanguageModel` only; ships a private + `DirectModel` adapter over `GoogleClient` so it needs no other module. + The runner has a hard step cap, tool-call cap and wall-clock cap. Tests + use a fake model. MCP over HTTP (JSON-RPC `tools/list`, `tools/call`), + A2A agent cards and task send, and ADK's agent-config format are + researched, not guessed. +- live: if `src/realtime` has no usable WebSocket client, implement an + RFC 6455 client in the module (masking, fragmentation, ping/pong, close, + frame and message caps) over plain TCP and over the existing wolfSSL + `ITlsSession` (`clients/transports/tls_wolfssl.h`). Tests run against a + loopback WebSocket server written in the test. The example relays over + HTTP (the example server has no WebSocket): create session, send, poll + events by cursor, close. + +## 4. Integration (after the worktrees finish) + +The owner merges each branch, then writes the READMEs, `example/SPEC.md` +rows, and the per-module row in this file. Gaps found by module owners are +collected below. + +## 5. Gaps + +- Live behavior is unverified for every module except generateContent on an + express key: no OAuth project credential is available in the build + environment. Each module's SPEC lists what is only scripted. diff --git a/src/google/SPEC.md b/src/google/SPEC.md index 6f2f4bd..de9ee32 100644 --- a/src/google/SPEC.md +++ b/src/google/SPEC.md @@ -50,7 +50,9 @@ client, credentials, errors, or caps. 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`. + 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). - No key: `configured()` is false and every call throws `NotConfiguredError` (HTTP 503, status `NOT_CONFIGURED`) before any network traffic. Loud, not silent. diff --git a/src/google/client.cpp b/src/google/client.cpp index 1a341f5..fc364a7 100644 --- a/src/google/client.cpp +++ b/src/google/client.cpp @@ -2,6 +2,7 @@ #include "clients/transports/http_transport.h" #include "google/credentials.h" +#include "google/stream_decoder.h" namespace molo::google { @@ -25,13 +26,16 @@ std::shared_ptr GoogleClient::from_env() { Credentials::from_env()); } -clients::body::Json GoogleClient::post_json(const ServiceEndpoint& service, - const std::string& path, - const clients::body::Json& body) { +clients::body::Json GoogleClient::request(clients::Method method, + const ServiceEndpoint& service, + const std::string& path, + const clients::body::Json* body) { if (!configured_) throw NotConfiguredError(service.name); try { - return finish(service, client_.post_json_blocking( - service.base_url + path, body)); + clients::ClientRequest req(method, + clients::Url::parse(service.base_url + path)); + if (body) req.json(*body); + return finish(service, client_.send_blocking(std::move(req))); } catch (const GoogleError&) { throw; } catch (const std::exception& e) { @@ -39,11 +43,42 @@ clients::body::Json GoogleClient::post_json(const ServiceEndpoint& service, } } +clients::body::Json GoogleClient::post_json(const ServiceEndpoint& service, + const std::string& path, + const clients::body::Json& body) { + return request(clients::Method::kPost, service, path, &body); +} + +clients::body::Json GoogleClient::patch_json(const ServiceEndpoint& service, + const std::string& path, + const clients::body::Json& body) { + return request(clients::Method::kPatch, service, path, &body); +} + clients::body::Json GoogleClient::get_json(const ServiceEndpoint& service, const std::string& path) { + return request(clients::Method::kGet, service, path, nullptr); +} + +clients::body::Json GoogleClient::delete_json(const ServiceEndpoint& service, + const std::string& path) { + return request(clients::Method::kDelete, service, path, nullptr); +} + +void GoogleClient::stream_json(const ServiceEndpoint& service, + const std::string& path, + const clients::body::Json& body, + const EventSink& sink) { if (!configured_) throw NotConfiguredError(service.name); + StreamDecoder decoder(service.name, sink); try { - return finish(service, client_.get_blocking(service.base_url + path)); + clients::ClientRequest req( + clients::Method::kPost, clients::Url::parse(service.base_url + path)); + req.json(body); + client_.send_stream_blocking( + std::move(req), + [&](const std::string& chunk) { return decoder.feed(chunk); }); + decoder.finish(); } catch (const GoogleError&) { throw; } catch (const std::exception& e) { diff --git a/src/google/client.h b/src/google/client.h index c6f68b6..27570c7 100644 --- a/src/google/client.h +++ b/src/google/client.h @@ -4,6 +4,7 @@ // sends JSON, maps failures to GoogleError. Runs over any clients::Transport // (HttpTransport in production, MockTransport in tests). +#include #include #include @@ -26,11 +27,29 @@ class GoogleClient { bool configured() const { return configured_; } + // One entry point for every verb; the helpers below delegate to it. + // body may be null (GET, DELETE). + clients::body::Json request(clients::Method method, + const ServiceEndpoint& service, + const std::string& path, + const clients::body::Json* body = nullptr); clients::body::Json post_json(const ServiceEndpoint& service, const std::string& path, const clients::body::Json& body); + clients::body::Json patch_json(const ServiceEndpoint& service, + const std::string& path, + const clients::body::Json& body); clients::body::Json get_json(const ServiceEndpoint& service, const std::string& path); + clients::body::Json delete_json(const ServiceEndpoint& service, + const std::string& path); + + // Streaming POST. Decodes SSE ("?alt=sse") and plain JSON bodies into + // events; sink returns false to stop early. An error body (Google's + // {"error":...}) throws GoogleError. Total streamed bytes are capped. + using EventSink = std::function; + void stream_json(const ServiceEndpoint& service, const std::string& path, + const clients::body::Json& body, const EventSink& sink); clients::ClientStatsSnapshot stats() const { return client_.stats(); } diff --git a/src/google/credentials.cpp b/src/google/credentials.cpp index 2490c4e..a2335cf 100644 --- a/src/google/credentials.cpp +++ b/src/google/credentials.cpp @@ -47,6 +47,10 @@ std::string Credentials::env(const char* name) { } std::shared_ptr Credentials::from_env(const char* name) { + // An OAuth access token (GOOGLE_ACCESS_TOKEN, e.g. from + // `gcloud auth print-access-token`) wins: Agent Platform APIs need it. + std::string token = env("GOOGLE_ACCESS_TOKEN"); + if (!token.empty()) return bearer(std::move(token)); std::string key = env(name); if (key.empty()) return nullptr; return api_key(std::move(key)); diff --git a/src/google/gemini_types.cpp b/src/google/gemini_types.cpp new file mode 100644 index 0000000..eafcb8c --- /dev/null +++ b/src/google/gemini_types.cpp @@ -0,0 +1,284 @@ +#include "google/gemini_types.h" + +#include "security/crypto/Base64.h" + +namespace molo::google { + +using clients::body::Json; +using security::crypto::Base64; + +namespace { +std::string str_of(const Json& doc, const char* key) { + const Json* v = doc.is_object() ? doc.find(key) : nullptr; + return v && v->is_string() ? v->as_string() : ""; +} +int int_of(const Json& doc, const char* key) { + const Json* v = doc.is_object() ? doc.find(key) : nullptr; + return v && v->is_number() ? static_cast(v->as_int()) : 0; +} +} // namespace + +Part Part::of_text(std::string text) { + Part p; + p.text = std::move(text); + return p; +} +Part Part::of_inline(std::string mime, std::string bytes) { + Part p; + p.inline_data = InlineData{std::move(mime), std::move(bytes)}; + return p; +} +Part Part::of_file(std::string mime, std::string uri) { + Part p; + p.file_data = FileData{std::move(mime), std::move(uri)}; + return p; +} +Part Part::of_call(FunctionCall call) { + Part p; + p.function_call = std::move(call); + return p; +} +Part Part::of_response(FunctionResponse response) { + Part p; + p.function_response = std::move(response); + return p; +} + +Json Part::to_json() const { + Json out = Json::object(); + if (inline_data) { + Json d = Json::object(); + d.set("mimeType", Json(inline_data->mime)); + d.set("data", Json(Base64::encode(inline_data->data))); + out.set("inlineData", d); + } else if (file_data) { + Json d = Json::object(); + d.set("mimeType", Json(file_data->mime)); + d.set("fileUri", Json(file_data->uri)); + out.set("fileData", d); + } else if (function_call) { + Json d = Json::object(); + d.set("name", Json(function_call->name)); + d.set("args", function_call->args); + if (!function_call->id.empty()) d.set("id", Json(function_call->id)); + out.set("functionCall", d); + } else if (function_response) { + Json d = Json::object(); + d.set("name", Json(function_response->name)); + d.set("response", function_response->response); + if (!function_response->id.empty()) d.set("id", Json(function_response->id)); + out.set("functionResponse", d); + } else { + out.set("text", Json(text)); + } + if (thought) out.set("thought", Json(true)); + return out; +} + +Part Part::from_json(const Json& doc) { + Part p; + p.text = str_of(doc, "text"); + if (const Json* t = doc.find("thought"); t && t->is_bool()) p.thought = t->as_bool(); + if (const Json* d = doc.find("inlineData"); d && d->is_object()) { + std::string raw; + Base64::decode(str_of(*d, "data"), raw); + p.inline_data = InlineData{str_of(*d, "mimeType"), std::move(raw)}; + } + if (const Json* d = doc.find("fileData"); d && d->is_object()) + p.file_data = FileData{str_of(*d, "mimeType"), str_of(*d, "fileUri")}; + if (const Json* d = doc.find("functionCall"); d && d->is_object()) { + FunctionCall c; + c.name = str_of(*d, "name"); + c.id = str_of(*d, "id"); + if (const Json* a = d->find("args"); a && a->is_object()) c.args = *a; + p.function_call = std::move(c); + } + if (const Json* d = doc.find("functionResponse"); d && d->is_object()) { + FunctionResponse r; + r.name = str_of(*d, "name"); + r.id = str_of(*d, "id"); + if (const Json* a = d->find("response"); a && a->is_object()) r.response = *a; + p.function_response = std::move(r); + } + return p; +} + +Content Content::user(std::string text) { + Content c; + c.role = "user"; + c.parts.push_back(Part::of_text(std::move(text))); + return c; +} +Content Content::model(std::string text) { + Content c; + c.role = "model"; + c.parts.push_back(Part::of_text(std::move(text))); + return c; +} +std::string Content::text() const { + std::string out; + for (const Part& p : parts) + if (!p.thought && !p.inline_data && !p.file_data && !p.function_call && + !p.function_response) + out += p.text; + return out; +} + +Json Content::to_json() const { + Json out = Json::object(); + if (!role.empty()) out.set("role", Json(role)); + Json arr = Json::array(); + for (const Part& p : parts) arr.push(p.to_json()); + out.set("parts", arr); + return out; +} + +Content Content::from_json(const Json& doc) { + Content c; + c.role = str_of(doc, "role"); + if (const Json* parts = doc.find("parts"); parts && parts->is_array()) + for (const Json& p : parts->as_array()) c.parts.push_back(Part::from_json(p)); + return c; +} + +Json FunctionDeclaration::to_json() const { + Json out = Json::object(); + out.set("name", Json(name)); + out.set("description", Json(description)); + if (!parameters.is_null()) out.set("parameters", parameters); + return out; +} + +Json Tool::to_json() const { + Json out = Json::object(); + if (!functions.empty()) { + Json arr = Json::array(); + for (const auto& f : functions) arr.push(f.to_json()); + out.set("functionDeclarations", arr); + } + if (google_search) out.set("googleSearch", Json::object()); + if (code_execution) out.set("codeExecution", Json::object()); + if (extra.is_object()) + for (const auto& [k, v] : extra.as_object()) out.set(k, v); + return out; +} + +Json GenerateConfig::to_json() const { + Json out = Json::object(); + if (temperature) out.set("temperature", Json(*temperature)); + if (top_p) out.set("topP", Json(*top_p)); + if (top_k) out.set("topK", Json(*top_k)); + if (max_output_tokens) out.set("maxOutputTokens", Json(*max_output_tokens)); + if (candidate_count) out.set("candidateCount", Json(*candidate_count)); + if (thinking_budget) { + Json t = Json::object(); + t.set("thinkingBudget", Json(*thinking_budget)); + out.set("thinkingConfig", t); + } + if (!stop_sequences.empty()) { + Json a = Json::array(); + for (const auto& s : stop_sequences) a.push(Json(s)); + out.set("stopSequences", a); + } + if (!response_modalities.empty()) { + Json a = Json::array(); + for (const auto& s : response_modalities) a.push(Json(s)); + out.set("responseModalities", a); + } + if (!response_mime_type.empty()) out.set("responseMimeType", Json(response_mime_type)); + if (!response_schema.is_null()) out.set("responseSchema", response_schema); + if (!voice_name.empty()) { + Json prebuilt = Json::object(); + prebuilt.set("voiceName", Json(voice_name)); + Json vc = Json::object(); + vc.set("prebuiltVoiceConfig", prebuilt); + Json sc = Json::object(); + sc.set("voiceConfig", vc); + out.set("speechConfig", sc); + } + return out; +} + +Json GenerateRequest::to_json() const { + Json out = Json::object(); + Json arr = Json::array(); + for (const Content& c : contents) arr.push(c.to_json()); + out.set("contents", arr); + if (system) { + Content s = *system; + s.role.clear(); + out.set("systemInstruction", s.to_json()); + } + if (!tools.empty()) { + Json t = Json::array(); + for (const Tool& tool : tools) t.push(tool.to_json()); + out.set("tools", t); + } + if (!tool_mode.empty()) { + Json fcc = Json::object(); + fcc.set("mode", Json(tool_mode)); + if (!allowed_functions.empty()) { + Json names = Json::array(); + for (const auto& n : allowed_functions) names.push(Json(n)); + fcc.set("allowedFunctionNames", names); + } + Json tc = Json::object(); + tc.set("functionCallingConfig", fcc); + out.set("toolConfig", tc); + } + Json gc = config.to_json(); + if (!gc.as_object().empty()) out.set("generationConfig", gc); + if (!safety.empty()) { + Json s = Json::array(); + for (const auto& x : safety) { + Json one = Json::object(); + one.set("category", Json(x.category)); + one.set("threshold", Json(x.threshold)); + s.push(one); + } + out.set("safetySettings", s); + } + return out; +} + +UsageMetadata UsageMetadata::from_json(const Json& doc) { + UsageMetadata u; + u.prompt_tokens = int_of(doc, "promptTokenCount"); + u.candidates_tokens = int_of(doc, "candidatesTokenCount"); + u.total_tokens = int_of(doc, "totalTokenCount"); + u.thoughts_tokens = int_of(doc, "thoughtsTokenCount"); + return u; +} + +std::string GenerateResponse::text() const { + return candidates.empty() ? "" : candidates.front().content.text(); +} + +std::vector GenerateResponse::function_calls() const { + std::vector out; + if (!candidates.empty()) + for (const Part& p : candidates.front().content.parts) + if (p.function_call) out.push_back(*p.function_call); + return out; +} + +GenerateResponse GenerateResponse::from_json(const Json& doc) { + GenerateResponse r; + if (const Json* cs = doc.find("candidates"); cs && cs->is_array()) + for (const Json& c : cs->as_array()) { + Candidate cand; + if (const Json* content = c.find("content"); content && content->is_object()) + cand.content = Content::from_json(*content); + cand.finish_reason = str_of(c, "finishReason"); + if (const Json* g = c.find("groundingMetadata")) cand.grounding_metadata = *g; + if (const Json* g = c.find("safetyRatings")) cand.safety_ratings = *g; + r.candidates.push_back(std::move(cand)); + } + if (const Json* u = doc.find("usageMetadata"); u && u->is_object()) + r.usage = UsageMetadata::from_json(*u); + r.model_version = str_of(doc, "modelVersion"); + if (const Json* f = doc.find("promptFeedback")) r.prompt_feedback = *f; + return r; +} + +} // namespace molo::google diff --git a/src/google/gemini_types.h b/src/google/gemini_types.h new file mode 100644 index 0000000..a4c3671 --- /dev/null +++ b/src/google/gemini_types.h @@ -0,0 +1,152 @@ +#pragma once + +// Typed Gemini content model shared by every agent-platform module: Part, +// Content, tools, GenerateRequest/Response, and the LanguageModel seam that +// agents (ADK), the Live API, evaluation and sessions code against. Wire +// names follow the Vertex AI / Gemini REST schema (camelCase). + +#include +#include +#include +#include + +#include "clients/body/json.h" + +namespace molo::google { + +struct InlineData { + std::string mime; + std::string data; // Raw bytes (base64 only on the wire). +}; + +struct FileData { + std::string mime; + std::string uri; // gs:// or https:// +}; + +struct FunctionCall { + std::string name; + clients::body::Json args = clients::body::Json::object(); + std::string id; +}; + +struct FunctionResponse { + std::string name; + clients::body::Json response = clients::body::Json::object(); + std::string id; +}; + +struct Part { + std::string text; + bool thought = false; + std::optional inline_data; + std::optional file_data; + std::optional function_call; + std::optional function_response; + + static Part of_text(std::string text); + static Part of_inline(std::string mime, std::string bytes); + static Part of_file(std::string mime, std::string uri); + static Part of_call(FunctionCall call); + static Part of_response(FunctionResponse response); + + clients::body::Json to_json() const; + static Part from_json(const clients::body::Json& doc); +}; + +struct Content { + std::string role; // "user" | "model" | "" (system instruction) + std::vector parts; + + static Content user(std::string text); + static Content model(std::string text); + std::string text() const; // Concatenated non-thought text parts. + + clients::body::Json to_json() const; + static Content from_json(const clients::body::Json& doc); +}; + +struct FunctionDeclaration { + std::string name; + std::string description; + clients::body::Json parameters; // OpenAPI-subset schema; null: no params. + clients::body::Json to_json() const; +}; + +struct Tool { + std::vector functions; + bool google_search = false; + bool code_execution = false; + clients::body::Json extra; // Raw extra tool fields (retrieval, urlContext...). + clients::body::Json to_json() const; +}; + +struct SafetySetting { + std::string category; // HARM_CATEGORY_* + std::string threshold; // BLOCK_* +}; + +struct GenerateConfig { + std::optional temperature; + std::optional top_p; + std::optional top_k; + std::optional max_output_tokens; + std::optional candidate_count; + std::optional thinking_budget; // 0: no thinking. + std::vector stop_sequences; + std::vector response_modalities; // "TEXT", "AUDIO", "IMAGE" + std::string response_mime_type; // e.g. application/json + clients::body::Json response_schema; // null: none + std::string voice_name; // speechConfig prebuilt voice + clients::body::Json to_json() const; +}; + +struct GenerateRequest { + std::string model; // Path component, not part of the body. + std::optional system; + std::vector contents; + std::vector tools; + std::string tool_mode; // "", "AUTO", "ANY", "NONE" + std::vector allowed_functions; + GenerateConfig config; + std::vector safety; + clients::body::Json to_json() const; // Body for :generateContent. +}; + +struct UsageMetadata { + int prompt_tokens = 0; + int candidates_tokens = 0; + int total_tokens = 0; + int thoughts_tokens = 0; + static UsageMetadata from_json(const clients::body::Json& doc); +}; + +struct Candidate { + Content content; + std::string finish_reason; + clients::body::Json grounding_metadata; + clients::body::Json safety_ratings; +}; + +struct GenerateResponse { + std::vector candidates; + UsageMetadata usage; + std::string model_version; + clients::body::Json prompt_feedback; + + std::string text() const; // First candidate's text. + std::vector function_calls() const; // First candidate's calls. + static GenerateResponse from_json(const clients::body::Json& doc); +}; + +// The seam agents code against. Vertex/Gemini implement it; tests fake it. +class LanguageModel { + public: + virtual ~LanguageModel() = default; + virtual GenerateResponse generate(const GenerateRequest& request) = 0; + // Calls on_chunk per streamed response; return false to stop. + virtual void stream(const GenerateRequest& request, + const std::function& on_chunk) = 0; +}; + +} // namespace molo::google diff --git a/src/google/google.mk b/src/google/google.mk index 4323b88..aaddf8a 100644 --- a/src/google/google.mk +++ b/src/google/google.mk @@ -11,9 +11,11 @@ CLIENTS_LIB ?= $(ROOT)/build/clients/libclients.a OPERABILITY_LIB ?= build/liboperability.a GOOGLE_INCS := -I$(ROOT)/src -I$(ROOT)/tests/src/clients -GOOGLE_SRCS := $(sort $(wildcard $(ROOT)/src/google/*.cpp)) \ +# Recursive: every module under src/google// builds without editing +# this file. +GOOGLE_SRCS := $(sort $(shell find $(ROOT)/src/google -name "*.cpp")) \ $(ROOT)/src/security/crypto/Base64.cpp -GOOGLE_TEST_SRCS := $(sort $(wildcard $(ROOT)/tests/src/google/*.cpp)) +GOOGLE_TEST_SRCS := $(sort $(shell find $(ROOT)/tests/src/google -name "*.cpp")) GOOGLE_BUILD := $(ROOT)/build/google GOOGLE_OBJDIR := $(GOOGLE_BUILD)/objs diff --git a/src/google/operation.cpp b/src/google/operation.cpp new file mode 100644 index 0000000..7ad42af --- /dev/null +++ b/src/google/operation.cpp @@ -0,0 +1,71 @@ +#include "google/operation.h" + +#include + +#include "google/errors.h" + +namespace molo::google { + +using clients::body::Json; + +Operation Operation::from_json(const Json& doc) { + Operation op; + if (const Json* v = doc.find("name"); v && v->is_string()) op.name = v->as_string(); + if (const Json* v = doc.find("done"); v && v->is_bool()) op.done = v->as_bool(); + if (const Json* v = doc.find("response")) op.response = *v; + if (const Json* v = doc.find("metadata")) op.metadata = *v; + if (const Json* e = doc.find("error"); e && e->is_object()) { + const Json* c = e->find("code"); + op.error_code = c && c->is_number() ? static_cast(c->as_int()) : 2; + if (op.error_code == 0) op.error_code = 2; + const Json* m = e->find("message"); + op.error_message = m && m->is_string() ? m->as_string() : "operation failed"; + } + return op; +} + +Operation wait_operation(GoogleClient& client, const ServiceEndpoint& endpoint, + const std::string& operation_name, const Sleeper& sleeper) { + if (operation_name.empty() || operation_name.find("..") != std::string::npos) + throw GoogleError::invalid("bad operation name"); + Sleeper sleep = sleeper ? sleeper : [](std::chrono::milliseconds d) { + std::this_thread::sleep_for(d); + }; + std::chrono::milliseconds waited{0}; + for (std::size_t i = 0; i < OperationCaps::kMaxPolls; ++i) { + Operation op = Operation::from_json(client.get_json(endpoint, "/" + operation_name)); + if (op.done) { + if (op.failed()) + throw GoogleError(502, "OPERATION_FAILED", op.error_message, endpoint.name); + return op; + } + if (waited >= OperationCaps::kMaxWait) break; + sleep(OperationCaps::kInterval); + waited += OperationCaps::kInterval; + } + throw GoogleError(504, "DEADLINE_EXCEEDED", + "operation still running at the wait cap: " + operation_name, + endpoint.name); +} + +Json list_all(GoogleClient& client, const ServiceEndpoint& endpoint, + const std::string& path, const std::string& items_key, + std::size_t max_pages) { + Json items = Json::array(); + std::string token; + for (std::size_t page = 0; page < max_pages; ++page) { + std::string url = path; + if (!token.empty()) + url += (path.find('?') == std::string::npos ? "?" : "&") + + std::string("pageToken=") + clients::Url::encode_component(token); + Json reply = client.get_json(endpoint, url); + if (const Json* arr = reply.find(items_key); arr && arr->is_array()) + for (const Json& item : arr->as_array()) items.push(item); + const Json* next = reply.find("nextPageToken"); + if (!next || !next->is_string() || next->as_string().empty()) break; + token = next->as_string(); + } + return items; +} + +} // namespace molo::google diff --git a/src/google/operation.h b/src/google/operation.h new file mode 100644 index 0000000..d5616a4 --- /dev/null +++ b/src/google/operation.h @@ -0,0 +1,48 @@ +#pragma once + +// Long-running operations (google.longrunning) and pagination, shared by +// every module that creates, deletes or lists Cloud resources. + +#include +#include +#include +#include + +#include "google/client.h" + +namespace molo::google { + +struct Operation { + std::string name; // projects/.../operations/{id} + bool done = false; + clients::body::Json response; // Set when done and successful. + clients::body::Json metadata; + int error_code = 0; // google.rpc.Status, 0: no error + std::string error_message; + + bool failed() const { return error_code != 0; } + static Operation from_json(const clients::body::Json& doc); +}; + +struct OperationCaps { + static constexpr std::chrono::seconds kMaxWait{600}; + static constexpr std::chrono::milliseconds kInterval{2000}; + static constexpr std::size_t kMaxPolls = 400; +}; + +using Sleeper = std::function; + +// Polls GET {name} on the given endpoint until done. Throws GoogleError +// (status DEADLINE_EXCEEDED) at the cap and (status from the operation, or +// UNKNOWN) when the operation failed. `sleeper` is injectable for tests. +Operation wait_operation(GoogleClient& client, const ServiceEndpoint& endpoint, + const std::string& operation_name, + const Sleeper& sleeper = nullptr); + +// Follows nextPageToken. `path` may already hold a query string. Collects +// `items_key` arrays into one Json array; stops at max_pages (default 100). +clients::body::Json list_all(GoogleClient& client, const ServiceEndpoint& endpoint, + const std::string& path, const std::string& items_key, + std::size_t max_pages = 100); + +} // namespace molo::google diff --git a/src/google/resource.cpp b/src/google/resource.cpp new file mode 100644 index 0000000..d8c0a90 --- /dev/null +++ b/src/google/resource.cpp @@ -0,0 +1,83 @@ +#include "google/resource.h" + +#include "google/credentials.h" +#include "google/errors.h" + +namespace molo::google { + +namespace { +bool valid_project(const std::string& p) { + if (p.empty() || p.size() > 128) return false; + for (char c : p) + if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || + c == '.' || c == ':')) + return false; + return true; +} +bool valid_location(const std::string& l) { + if (l.empty() || l.size() > 64) return false; + for (char c : l) + if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-')) return false; + return true; +} +} // namespace + +bool valid_segment(const std::string& id) { + if (id.empty() || id.size() > 128) return false; + for (char c : id) + if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || + (c >= '0' && c <= '9') || c == '-' || c == '_' || c == '.')) + return false; + return id != "." && id != ".."; +} + +CloudContext CloudContext::from_env() { + CloudContext c; + c.project = Credentials::env("GOOGLE_CLOUD_PROJECT"); + std::string loc = Credentials::env("GOOGLE_CLOUD_LOCATION"); + if (!loc.empty()) c.location = loc; + return c; +} + +bool CloudContext::valid() const { + return valid_project(project) && valid_location(location); +} + +std::string CloudContext::parent() const { + if (!valid_project(project)) + throw GoogleError::invalid("GOOGLE_CLOUD_PROJECT is missing or malformed"); + if (!valid_location(location)) + throw GoogleError::invalid("GOOGLE_CLOUD_LOCATION is malformed"); + return "projects/" + project + "/locations/" + location; +} + +std::string CloudContext::child(const std::string& collection, + const std::string& id) const { + if (!valid_segment(collection) || !valid_segment(id)) + throw GoogleError::invalid("bad resource id"); + return parent() + "/" + collection + "/" + id; +} + +namespace endpoints { + +ServiceEndpoint aiplatform(const std::string& location) { + if (location == "global" || location.empty()) + return {"aiplatform", "https://aiplatform.googleapis.com/v1"}; + if (!valid_location(location)) throw GoogleError::invalid("bad location"); + return {"aiplatform", "https://" + location + "-aiplatform.googleapis.com/v1"}; +} + +ServiceEndpoint aiplatform_beta(const std::string& location) { + ServiceEndpoint e = aiplatform(location); + e.name = "aiplatform-beta"; + e.base_url.replace(e.base_url.size() - 2, 2, "v1beta1"); + return e; +} + +ServiceEndpoint custom(std::string name, std::string base_url) { + return {std::move(name), std::move(base_url)}; +} + +} // namespace endpoints + +} // namespace molo::google diff --git a/src/google/resource.h b/src/google/resource.h new file mode 100644 index 0000000..7f862d4 --- /dev/null +++ b/src/google/resource.h @@ -0,0 +1,37 @@ +#pragma once + +// Cloud resource naming shared by every Vertex AI / Agent Platform module. +// Env: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION (default us-central1). + +#include + +#include "google/endpoints.h" + +namespace molo::google { + +struct CloudContext { + std::string project; + std::string location = "us-central1"; + + static CloudContext from_env(); + bool valid() const; // project set and both parts well formed + // "projects/{project}/locations/{location}"; throws GoogleError (invalid) + // when the project is empty or contains characters outside [a-z0-9.:-]. + std::string parent() const; + // parent() + "/" + collection + "/" + id, id validated like a path segment. + std::string child(const std::string& collection, const std::string& id) const; +}; + +// True for a single URL path segment: 1..128 of [A-Za-z0-9._-]. +bool valid_segment(const std::string& id); + +namespace endpoints { +// https://{location}-aiplatform.googleapis.com/v1 ("global": no prefix). +ServiceEndpoint aiplatform(const std::string& location); +// Same host family, beta surface. +ServiceEndpoint aiplatform_beta(const std::string& location); +// Any other Google API host, e.g. custom("modelarmor", "https://modelarmor.us.rep.googleapis.com/v1"). +ServiceEndpoint custom(std::string name, std::string base_url); +} // namespace endpoints + +} // namespace molo::google diff --git a/src/google/service.cpp b/src/google/service.cpp index 0839248..7b233b4 100644 --- a/src/google/service.cpp +++ b/src/google/service.cpp @@ -14,6 +14,20 @@ clients::body::Json Service::fetch(const std::string& path) const { return client_->get_json(endpoint_, path); } +clients::body::Json Service::patch(const std::string& path, + const clients::body::Json& body) const { + return client_->patch_json(endpoint_, path, body); +} + +clients::body::Json Service::remove(const std::string& path) const { + return client_->delete_json(endpoint_, path); +} + +void Service::stream(const std::string& path, const clients::body::Json& body, + const GoogleClient::EventSink& sink) const { + client_->stream_json(endpoint_, path, body, sink); +} + std::string Service::string_at(const clients::body::Json& doc, const std::string& key, const std::string& fallback) { diff --git a/src/google/service.h b/src/google/service.h index 6b51424..2015db4 100644 --- a/src/google/service.h +++ b/src/google/service.h @@ -23,6 +23,11 @@ class Service { clients::body::Json call(const std::string& path, const clients::body::Json& body) const; clients::body::Json fetch(const std::string& path) const; + clients::body::Json patch(const std::string& path, + const clients::body::Json& body) const; + clients::body::Json remove(const std::string& path) const; + void stream(const std::string& path, const clients::body::Json& body, + const GoogleClient::EventSink& sink) const; // Tolerant readers for response documents. static std::string string_at(const clients::body::Json& doc, diff --git a/src/google/stream_decoder.cpp b/src/google/stream_decoder.cpp new file mode 100644 index 0000000..03f99a8 --- /dev/null +++ b/src/google/stream_decoder.cpp @@ -0,0 +1,109 @@ +#include "google/stream_decoder.h" + +#include "google/errors.h" + +namespace molo::google { + +using clients::body::Json; + +StreamDecoder::StreamDecoder(std::string service, Sink sink) + : service_(std::move(service)), sink_(std::move(sink)) {} + +bool StreamDecoder::emit(const Json& event) { + if (!sink_(event)) stopped_ = true; + return !stopped_; +} + +bool StreamDecoder::dispatch_sse_block(const std::string& block) { + std::string data; + std::size_t pos = 0; + while (pos <= block.size()) { + std::size_t eol = block.find('\n', pos); + std::string line = block.substr(pos, eol == std::string::npos ? eol : eol - pos); + if (!line.empty() && line.back() == '\r') line.pop_back(); + if (line.rfind("data:", 0) == 0) { + std::string v = line.substr(5); + if (!v.empty() && v.front() == ' ') v.erase(0, 1); + if (!data.empty()) data += "\n"; + data += v; + } + if (eol == std::string::npos) break; + pos = eol + 1; + } + if (data.empty() || data == "[DONE]") return true; + Json event; + try { + event = Json::parse(data); + } catch (const std::exception& e) { + throw GoogleError(502, "BAD_RESPONSE", std::string("bad stream event: ") + e.what(), service_); + } + if (const Json* err = event.is_object() ? event.find("error") : nullptr; err) + throw GoogleError(502, "STREAM_ERROR", err->dump(), service_); + return emit(event); +} + +bool StreamDecoder::feed(const std::string& chunk) { + if (stopped_) return false; + total_ += chunk.size(); + if (total_ > kMaxBytes) + throw GoogleError(502, "BAD_RESPONSE", "stream over the byte cap", service_); + buffer_ += chunk; + if (!decided_) { + std::size_t first = buffer_.find_first_not_of(" \t\r\n"); + if (first == std::string::npos) return true; + sse_ = buffer_[first] != '{' && buffer_[first] != '['; + decided_ = true; + } + if (!sse_) return true; // Plain JSON: parsed whole at finish(). + for (;;) { + std::size_t end = buffer_.find("\n\n"); + std::size_t sep = 2; + std::size_t crlf = buffer_.find("\r\n\r\n"); + if (crlf != std::string::npos && (end == std::string::npos || crlf < end)) { + end = crlf; + sep = 4; + } + if (end == std::string::npos) break; + std::string block = buffer_.substr(0, end); + buffer_.erase(0, end + sep); + if (!dispatch_sse_block(block)) return false; + } + return true; +} + +void StreamDecoder::finish() { + if (stopped_ || !decided_) return; + if (sse_) { + if (buffer_.find_first_not_of(" \t\r\n") != std::string::npos) + dispatch_sse_block(buffer_); + return; + } + Json doc; + try { + doc = Json::parse(buffer_); + } catch (const std::exception& e) { + throw GoogleError(502, "BAD_RESPONSE", e.what(), service_); + } + if (doc.is_object()) { + if (const Json* err = doc.find("error")) + throw GoogleError(err->is_object() && err->find("code") && err->find("code")->is_number() + ? static_cast(err->find("code")->as_int()) + : 502, + err->is_object() && err->find("status") && err->find("status")->is_string() + ? err->find("status")->as_string() + : "UNKNOWN", + err->is_object() && err->find("message") && err->find("message")->is_string() + ? err->find("message")->as_string() + : err->dump(), + service_); + emit(doc); + } else if (doc.is_array()) { + for (const Json& item : doc.as_array()) { + if (item.is_object() && item.find("error")) + throw GoogleError(502, "STREAM_ERROR", item.find("error")->dump(), service_); + if (!emit(item)) break; + } + } +} + +} // namespace molo::google diff --git a/src/google/stream_decoder.h b/src/google/stream_decoder.h new file mode 100644 index 0000000..435518a --- /dev/null +++ b/src/google/stream_decoder.h @@ -0,0 +1,40 @@ +#pragma once + +// Turns a streamed response body into JSON events. Understands SSE +// ("data: {...}" blocks, from ?alt=sse) and plain JSON bodies (an object is +// one event, an array is one event per element). A body that is Google's +// {"error":{...}} document throws GoogleError at finish(). + +#include +#include + +#include "clients/body/json.h" + +namespace molo::google { + +class StreamDecoder { + public: + static constexpr std::size_t kMaxBytes = 16u * 1024u * 1024u; + using Sink = std::function; + + StreamDecoder(std::string service, Sink sink); + + // Returns false when the sink asked to stop (or the cap was hit): the + // caller should stop reading. + bool feed(const std::string& chunk); + void finish(); + + private: + bool emit(const clients::body::Json& event); + bool dispatch_sse_block(const std::string& data); + + std::string service_; + Sink sink_; + std::string buffer_; + std::size_t total_ = 0; + bool decided_ = false; + bool sse_ = false; + bool stopped_ = false; +}; + +} // namespace molo::google diff --git a/tests/src/google/test_foundation.cpp b/tests/src/google/test_foundation.cpp new file mode 100644 index 0000000..2e15047 --- /dev/null +++ b/tests/src/google/test_foundation.cpp @@ -0,0 +1,263 @@ +// Foundation shared by every agent-platform module: all-verb client, +// streaming decoder, typed Gemini content, resource names, operations, +// pagination. +#include + +#include "framework.h" +#include "clients/transports/mock_transport.h" +#include "google/client.h" +#include "google/credentials.h" +#include "google/gemini_types.h" +#include "google/operation.h" +#include "google/resource.h" +#include "google/stream_decoder.h" + +using namespace molo::google; +using molo::clients::ClientResponse; +using molo::clients::HeaderMap; +using molo::clients::Method; +using molo::clients::body::Json; +using molo::clients::transports::MockTransport; + +namespace { +ClientResponse ok(const std::string& body, int status = 200) { + HeaderMap h; + h.set("Content-Type", "application/json"); + return ClientResponse(status, h, body); +} +struct Rig { + MockTransport* mock; + std::shared_ptr client; + Rig() { + auto t = std::make_unique(); + mock = t.get(); + client = std::make_shared(std::move(t), Credentials::bearer("tok")); + } +}; +const ServiceEndpoint kEp = endpoints::custom("t", "https://example.googleapis.com/v1"); +} // namespace + +TEST(foundation, all_verbs_and_bearer) { + Rig r; + r.mock->expect_response(Method::kGet, "/v1/a", ok("{\"v\":1}")); + r.mock->expect_response(Method::kPatch, "/v1/a", ok("{\"v\":2}")); + r.mock->expect_response(Method::kDelete, "/v1/a", ok("{}")); + ASSERT_EQ(r.client->get_json(kEp, "/a").find("v")->as_int(), 1); + Json body = Json::object(); + body.set("x", Json(1)); + ASSERT_EQ(r.client->patch_json(kEp, "/a", body).find("v")->as_int(), 2); + r.client->delete_json(kEp, "/a"); + auto seen = r.mock->seen(); + ASSERT_EQ(seen.size(), 3u); + ASSERT_EQ(seen[0].headers.get_or("Authorization", ""), "Bearer tok"); + ASSERT_EQ(seen[1].body, "{\"x\":1}"); + r.mock->verify(); +} + +TEST(foundation, stream_sse_chunked_and_early_stop) { + std::vector got; + StreamDecoder d("t", [&](const Json& e) { + got.push_back(e.dump()); + return got.size() < 2; + }); + ASSERT_TRUE(d.feed("data: {\"a\":1}\n")); + ASSERT_TRUE(d.feed("\ndata: {\"a\":")); + ASSERT_FALSE(d.feed("2}\r\n\r\ndata: {\"a\":3}\n\n")); // sink stops after the 2nd + d.finish(); + ASSERT_EQ(got.size(), 2u); + ASSERT_EQ(got[1], "{\"a\":2}"); +} + +TEST(foundation, stream_plain_json_forms) { + std::vector got; + StreamDecoder obj("t", [&](const Json& e) { got.push_back(e.dump()); return true; }); + obj.feed("{\"k\":"); + obj.feed("1}"); + obj.finish(); + ASSERT_EQ(got.size(), 1u); + got.clear(); + StreamDecoder arr("t", [&](const Json& e) { got.push_back(e.dump()); return true; }); + arr.feed("[{\"a\":1},{\"a\":2}]"); + arr.finish(); + ASSERT_EQ(got.size(), 2u); +} + +TEST(foundation, stream_errors) { + StreamDecoder bad("t", [](const Json&) { return true; }); + bad.feed("{\"error\":{\"code\":403,\"message\":\"no\",\"status\":\"PERMISSION_DENIED\"}}"); + try { + bad.finish(); + FAIL("expected GoogleError"); + } catch (const GoogleError& e) { + ASSERT_EQ(e.status(), "PERMISSION_DENIED"); + ASSERT_EQ(e.http_status(), 403); + } + StreamDecoder sse("t", [](const Json&) { return true; }); + ASSERT_THROW(sse.feed("data: {\"error\":{\"message\":\"x\"}}\n\n"), GoogleError); + StreamDecoder cap("t", [](const Json&) { return true; }); + cap.feed("{"); + ASSERT_THROW(cap.feed(std::string(StreamDecoder::kMaxBytes, 'x')), GoogleError); +} + +TEST(foundation, stream_json_through_client) { + Rig r; + r.mock->expect_response( + Method::kPost, "/v1/m:streamGenerateContent", + ok("data: {\"candidates\":[{\"content\":{\"parts\":[{\"text\":\"a\"}]}}]}\n\n" + "data: {\"candidates\":[{\"content\":{\"parts\":[{\"text\":\"b\"}]}}]}\n\n")); + std::string text; + r.client->stream_json(kEp, "/m:streamGenerateContent?alt=sse", Json::object(), + [&](const Json& e) { + text += GenerateResponse::from_json(e).text(); + return true; + }); + ASSERT_EQ(text, "ab"); +} + +TEST(foundation, gemini_types_roundtrip) { + GenerateRequest req; + req.system = Content::user("be brief"); + req.contents.push_back(Content::user("hi")); + Content call; + call.role = "model"; + FunctionCall fc; + fc.name = "get_weather"; + fc.args.set("city", Json("Utrecht")); + call.parts.push_back(Part::of_call(fc)); + req.contents.push_back(call); + Content resp; + resp.role = "user"; + FunctionResponse fr; + fr.name = "get_weather"; + fr.response.set("temp", Json(12)); + resp.parts.push_back(Part::of_response(fr)); + req.contents.push_back(resp); + Tool tool; + FunctionDeclaration decl; + decl.name = "get_weather"; + decl.description = "weather"; + tool.functions.push_back(decl); + req.tools.push_back(tool); + req.tool_mode = "ANY"; + req.config.thinking_budget = 0; + req.config.temperature = 0.5; + req.config.voice_name = "Kore"; + Json j = req.to_json(); + ASSERT_EQ(j.find("systemInstruction")->find("role"), nullptr); + ASSERT_EQ(j.find("contents")->as_array().size(), 3u); + ASSERT_EQ(j.find("tools")->as_array()[0].find("functionDeclarations")->as_array()[0] + .find("name")->as_string(), "get_weather"); + ASSERT_EQ(j.find("toolConfig")->find("functionCallingConfig")->find("mode")->as_string(), "ANY"); + ASSERT_EQ(j.find("generationConfig")->find("thinkingConfig")->find("thinkingBudget")->as_int(), 0); + ASSERT_EQ(j.find("generationConfig")->find("speechConfig")->find("voiceConfig") + ->find("prebuiltVoiceConfig")->find("voiceName")->as_string(), "Kore"); + // Round trip a part with binary data. + Part blob = Part::of_inline("audio/wav", std::string("\x00\x01\xff", 3)); + Part back = Part::from_json(Json::parse(blob.to_json().dump())); + ASSERT_TRUE(back.inline_data.has_value()); + ASSERT_EQ(back.inline_data->data, std::string("\x00\x01\xff", 3)); +} + +TEST(foundation, generate_response_parse) { + Json doc = Json::parse( + "{\"candidates\":[{\"content\":{\"role\":\"model\",\"parts\":[{\"text\":\"hi\"}," + "{\"functionCall\":{\"name\":\"f\",\"args\":{\"a\":1}}}]},\"finishReason\":\"STOP\"}]," + "\"usageMetadata\":{\"promptTokenCount\":3,\"candidatesTokenCount\":4," + "\"totalTokenCount\":7,\"thoughtsTokenCount\":2},\"modelVersion\":\"v\"}"); + GenerateResponse r = GenerateResponse::from_json(doc); + ASSERT_EQ(r.text(), "hi"); + ASSERT_EQ(r.function_calls().size(), 1u); + ASSERT_EQ(r.function_calls()[0].name, "f"); + ASSERT_EQ(r.usage.total_tokens, 7); + ASSERT_EQ(r.candidates[0].finish_reason, "STOP"); +} + +TEST(foundation, cloud_context_names) { + CloudContext c; + c.project = "my-proj"; + c.location = "europe-west4"; + ASSERT_EQ(c.parent(), "projects/my-proj/locations/europe-west4"); + ASSERT_EQ(c.child("reasoningEngines", "e1"), + "projects/my-proj/locations/europe-west4/reasoningEngines/e1"); + ASSERT_THROW(c.child("reasoningEngines", "../x"), GoogleError); + ASSERT_THROW(c.child("reasoningEngines", ""), GoogleError); + CloudContext bad; + ASSERT_THROW(bad.parent(), GoogleError); + bad.project = "UPPER/case"; + ASSERT_THROW(bad.parent(), GoogleError); + ASSERT_EQ(endpoints::aiplatform("europe-west4").base_url, + "https://europe-west4-aiplatform.googleapis.com/v1"); + ASSERT_EQ(endpoints::aiplatform("global").base_url, + "https://aiplatform.googleapis.com/v1"); + ASSERT_EQ(endpoints::aiplatform_beta("us-central1").base_url, + "https://us-central1-aiplatform.googleapis.com/v1beta1"); + ASSERT_THROW(endpoints::aiplatform("evil.com/x"), GoogleError); +} + +TEST(foundation, wait_operation_polls_and_fails) { + Rig r; + r.mock->expect_response(Method::kGet, "/v1/projects/p/operations/1", + ok("{\"name\":\"projects/p/operations/1\",\"done\":false}")); + r.mock->expect_response(Method::kGet, "/v1/projects/p/operations/1", + ok("{\"name\":\"projects/p/operations/1\",\"done\":true," + "\"response\":{\"id\":\"e1\"}}")); + int sleeps = 0; + Operation op = wait_operation(*r.client, kEp, "projects/p/operations/1", + [&](std::chrono::milliseconds) { ++sleeps; }); + ASSERT_TRUE(op.done); + ASSERT_EQ(sleeps, 1); + ASSERT_EQ(op.response.find("id")->as_string(), "e1"); + + Rig f; + f.mock->expect_response(Method::kGet, "/v1/projects/p/operations/2", + ok("{\"done\":true,\"error\":{\"code\":3,\"message\":\"bad\"}}")); + try { + wait_operation(*f.client, kEp, "projects/p/operations/2", [](auto) {}); + FAIL("expected GoogleError"); + } catch (const GoogleError& e) { + ASSERT_EQ(e.status(), "OPERATION_FAILED"); + } + ASSERT_THROW(wait_operation(*f.client, kEp, "../etc", [](auto) {}), GoogleError); +} + +TEST(foundation, wait_operation_caps) { + Rig r; + r.mock->expect( + [] { + molo::clients::transports::MockExpectation e; + e.method = Method::kGet; + e.path = "/v1/projects/p/operations/9"; + e.response = ok("{\"done\":false}"); + e.times = 1000; + return e; + }()); + int sleeps = 0; + try { + wait_operation(*r.client, kEp, "projects/p/operations/9", + [&](std::chrono::milliseconds) { ++sleeps; }); + FAIL("expected DEADLINE_EXCEEDED"); + } catch (const GoogleError& e) { + ASSERT_EQ(e.status(), "DEADLINE_EXCEEDED"); + } + ASSERT_TRUE(sleeps > 100 && sleeps <= 400); +} + +TEST(foundation, list_all_follows_pages) { + Rig r; + r.mock->expect_response(Method::kGet, "/v1/things", + ok("{\"things\":[1,2],\"nextPageToken\":\"t2\"}")); + r.mock->expect_response(Method::kGet, "/v1/things", + ok("{\"things\":[3]}")); + Json all = list_all(*r.client, kEp, "/things", "things"); + ASSERT_EQ(all.as_array().size(), 3u); + ASSERT_TRUE(r.mock->seen()[1].target.find("pageToken=t2") != std::string::npos); +} + +TEST(foundation, access_token_beats_key) { + setenv("GOOGLE_ACCESS_TOKEN", "ya29.token", 1); + setenv("GOOGLE_API_KEY", "AQ.key", 1); + ASSERT_EQ(std::string(Credentials::from_env()->scheme()), "bearer"); + unsetenv("GOOGLE_ACCESS_TOKEN"); + ASSERT_EQ(std::string(Credentials::from_env()->scheme()), "apikey"); + unsetenv("GOOGLE_API_KEY"); +}