Merge models and runtime gaps

This commit is contained in:
2026-10-24 05:47:50 +02:00
38 changed files with 4437 additions and 72 deletions
+145 -23
View File
@@ -30,7 +30,10 @@ Two addressing modes, one class (`VertexTarget`):
| `vertex_service.h/.cpp` | `VertexService : Service`: runs planned calls |
| `json_read.h` | tolerant response readers |
| `gemini.h/.cpp` | `Gemini`: generate, stream (`?alt=sse`), count/compute tokens, embedContent, predict embeddings |
| `vertex_model.h/.cpp` | `VertexModel : LanguageModel` |
| `vertex_model.h/.cpp` | `VertexModel : LanguageModel`, `TurnBuilder` (replayable model turn with every `thoughtSignature`) |
| `admin_checks.h` | Input rules shared by the admin classes (object, size, mask, confirm) |
| `endpoint_admin.h/.cpp` | `EndpointAdmin`: endpoint lifecycle, remaining inference surfaces, endpoint operations, v1beta1 IAM and list |
| `publisher_admin.h/.cpp` | `PublisherAdmin`: publisher `v1/responses`, serverStreamingPredict, export, config, enableModel, IAM, v1beta1 forms |
| `model_garden.h/.cpp` | `ModelGarden`: list, get, fetch config, EULA check/accept, deploy |
| `claude_models.h/.cpp` | `ClaudeModels`: rawPredict, streamRawPredict, `text_delta` |
| `open_models.h/.cpp` | `OpenModels`: endpoints list/get, predict, rawPredict, streamRawPredict, serverStreamingPredict, generate/stream/count on endpoints, predictLongRunning, fetchPredictOperation, publisher invoke |
@@ -49,7 +52,9 @@ dimensions; list page size 1..100, 20 pages, 2000 models returned; Claude
200 messages, 1,000,000 chars, max_tokens 1..32768; endpoint instances 16,
100,000 chars, Gemma max_tokens 8192; media prompt 4000 chars, images 4,
music samples 4, video samples 4, video 8 seconds, 32 MiB and 8 items per
result, operation name 512 chars; video polls 120 at 5 s (10 minutes).
result, operation name 512 chars; video polls 120 at 5 s (10 minutes). Admin surface: request body 262144
chars serialized, updateMask 512 chars, operations.wait 1..600 s, operation
list pages 1..5, 64 permissions, 5000 streamed events.
## 4. Contracts
@@ -68,11 +73,36 @@ result, operation name 512 chars; video polls 120 at 5 s (10 minutes).
(fetchPredictOperation, a POST), `wait_video` bounded by the caps.
`wait_operation` (GET) is not used: Discovery has no GET on these
operations for publisher models.
- Admin bodies are Json whose top-level keys must be declared in the call
table: `CallPlanner::plan` rejects a stray key (`INVALID_ARGUMENT`) before
any traffic; rows with `-` (raw HTTP bodies) take any object.
- `EndpointAdmin(beta=true)` sends the v1beta1 twin of every `endpoint.` row
(`CallPlanner::plan(..., beta=true)`); `tools/check_discovery.py` verifies
each twin (same method, path, rpc id, fields). `endpoint.beta_*` rows exist
in v1beta1 only (list with `gdcZone`, IAM).
- Gated admin calls refuse without `confirm=true`: endpoint delete, deployModel,
undeployModel, mutateDeployedModel, IAM set, stored response delete,
operation record delete, publisher export, setPublisherModelConfig,
enableModel. The example routes answer a dry run instead.
- `VertexModel::TurnBuilder` builds the model turn to replay from stream
chunks: text parts merge only while they carry no `thoughtSignature`, a
signature that arrives on an empty part attaches to the part before it,
calls and data parts are kept as received. `VertexModel::model_turn` and
`replay` do the same for a whole reply. `Gemini::validate` accepts a
signature-only part (it is not "empty").
- Example (`/agent/models`): GET page, `/status`, `/calls` need no
credential; every Google call is a POST that answers 503
`google_not_configured` without a credential (checked first), 422 on bad
input. Routes: generate, count, embed, claude, list, endpoint, image,
music, video, video/status.
music, video, video/status, and the admin routes `endpoints` (create,
patch, update, delete, deploy, undeploy, mutate, list_beta, get_iam,
set_iam, test_iam), `endpoint/call` (compute_tokens, direct_predict,
direct_raw_predict, explain, invoke, deployed_invoke, chat, openapi,
science, response_get, response_delete), `endpoint/operations` (get, list,
cancel, wait, delete), `publisher` (stream_predict, responses_*, export,
set_config, enable, iam, beta_get, beta_generate, beta_count, beta_post,
beta_invoke). The video default model is `veo-3.1-generate-001`
(`veo-3.0-generate-001` answers 404 for the project).
## 5. Verified against discovery
@@ -80,7 +110,18 @@ result, operation name 512 chars; video polls 120 at 5 s (10 minutes).
`https://aiplatform.googleapis.com/$discovery/rest?version=v1` and `v1beta1`
and fails when any row of `calls.h` has a missing method or path, a wrong
rpc id, an absent request body field (dotted names follow the schema) or an
absent query parameter. Result on 2026-10-24: `29 calls checked, 0 problems`.
absent query parameter. Result on 2026-10-24: `84 calls checked, 132 owned
discovery methods covered, 0 problems`.
Coverage is part of the check: every Discovery method whose rpc id starts with
`aiplatform.publishers.models.`, `aiplatform.projects.locations.publishers.`,
`aiplatform.projects.publishers.models.`, `aiplatform.projects.locations.endpoints.`,
`aiplatform.projects.modelGardenEula.` or `aiplatform.projects.locations.deployPublisherModel`
(v1 and v1beta1, 132 methods) must be a row, the express form of a row, or the
v1beta1 twin of an `endpoint.` row (verified field by field); the check fails
on any other method until it is wrapped or excluded on purpose (`EXCLUDED`,
empty today). So a Discovery change that adds a method to these resources is
loud.
The same pass shows what Discovery says about express forms:
generateContent, streamGenerateContent, countTokens, computeTokens, predict,
predictLongRunning, fetchPredictOperation exist without a project;
@@ -89,8 +130,9 @@ embedContent, rawPredict, streamRawPredict, publisher invoke do not
only in v1beta1; `publishers.models.get` in v1 and v1beta1.
Request construction is compared to the table in
`tests/src/google/models/test_models.cpp` (every body key must be a declared
field).
`tests/src/google/models/test_models.cpp` and `test_models_admin.cpp` (every
body key must be a declared field; the planner also rejects a stray key at
run time; every row plans to a concrete URL, express and project scoped).
## 6. Verified live
@@ -124,9 +166,68 @@ With the service account OAuth token (project `lisa-448004`):
- Generation calls may answer 429 on the shared project; the live test notes
that instead of failing.
Not live-verified (mutating or billable): deploy, EULA accept, image, music
and video generation, endpoint predict family (no endpoint exists), Gemma
shapes. These are verified by Discovery only.
Run 2026-10-24 (closing the gaps), service account token, project
`lisa-448004`, through the new classes (`models_live_admin.*`) or direct
requests:
- `EndpointAdmin` read-only: v1beta1 endpoints list (`us-central1`): 200 `{}`
(an empty list has no `endpoints` key); v1 and v1beta1 operations list of a
missing endpoint: 200 `{}`; v1beta1 `getIamPolicy`, `operations.get` on a
missing endpoint: 404 NOT_FOUND; stored responses
(`endpoints/{id}/responses/{id}` get): 501 UNIMPLEMENTED for the project.
- `PublisherAdmin`: v1beta1 `publishers/google/models/gemini-2.5-flash` get: 200;
project scoped v1beta1 `getIamPolicy` on a publisher model: 400
INVALID_ARGUMENT (nothing to read there).
- Thought signatures: `gemini-3.5-flash` at `global` with a function
declaration, streamed: the `functionCall` part carries a `thoughtSignature`
(`TurnBuilder` keeps 1 signed part). The stream ends with an empty text
part, which `TurnBuilder` drops. The turn replayed with a `functionResponse`
via `VertexModel::replay` is accepted (200, "The weather in Paris is 18°C.").
Whether Google rejects a replay that lacks the signature was not tested.
- Veo: `veo-3.1-generate-001` exists for the project (us-central1 and
`global`); `veo-3.0-generate-001`, `veo-3.0-fast-generate-001`,
`veo-2.0-generate-001` and every Imagen model tried
(`imagen-3.0-generate-001/002`, `imagen-3.0-fast-generate-001`,
`imagen-4.0-generate-001`, `imagen-4.0-fast-generate-001`,
`imagen-4.0-ultra-generate-001`) answer 404 "not found or your project
does not have access". `predictLongRunning` accepts `instances[{prompt}]`
(an instance with `text` instead: 400 "No inputs provided") and answers
`{"name": "projects/.../publishers/google/models/veo-3.1-generate-001/operations/<uuid>"}`.
Parameters are validated inside the operation, which finishes
`done:true` with `error{code:3,message}` on `fetchPredictOperation`:
`sampleCount` 99 -> "Invalid sample count 99. The sample count should be in
the range of [1, 4]" (name and range match our cap 1..4); `durationSeconds`
99 -> "Unsupported output video duration 99 seconds, supported durations are
[8,4,6] for feature text_to_video" (name confirmed; the model accepts only
4, 6, 8, our cap 1..8 is wider); `storageUri` "bogus" -> "Unsupported output
storage uri: bogus" (name confirmed); `aspectRatio` "bogus" is rejected
synchronously with 400 "Invalid aspect ratio: bogus".
- A finished Veo operation, read with `fetchPredictOperation`: `done:true`,
`response` = `{"@type":"type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
"raiMediaFilteredCount":0, "videos":[{"bytesBase64Encoded":"...","mimeType":"video/mp4"}]}`
(one 8 s clip, about 13.8 MB decoded, under the 32 MiB cap). This is the
real shape of the operation `response` Any for video and is what
`wait_video` reads.
- Lyria: `lyria-002` `predict` (project scoped, us-central1 and `global`):
`instances[{prompt}]` -> 200 `{"predictions":[{"bytesBase64Encoded":"UklGR..."}]}`
with no `mimeType`; the bytes are a RIFF/WAVE file, so `items_from` names
`audio/wav` when the mime is missing. An empty prompt or an instance
without `prompt` -> 400 "Request contains an invalid argument".
- Claude `rawPredict` and `streamRawPredict` at `global`: still 429
RESOURCE_EXHAUSTED on quota `global_online_prediction_requests_per_base_model`
(`anthropic-claude-sonnet-4-6`). The streaming call reports the error as a JSON
array `[{"error":{...}}]`, not as one object.
Cost note: the Veo and Lyria probes were meant to be rejected requests. Google
accepted several, so the run started 5 Veo operations (4 failed validation
inside the operation and cost nothing, one `generateAudio:"str"` probe rendered
one 8 s clip) and generated 3 Lyria clips. The probe scripts are not part of
the repo; the live tests in the repo never call a generation method.
Not live-verified (mutating or billable): deploy, EULA accept, image
generation (no Imagen model is visible to the project), endpoint create, patch,
update, delete, deployModel, undeployModel, mutateDeployedModel, IAM set,
publisher export, config and enableModel, the endpoint inference family (no
endpoint exists). These are verified by Discovery and by local request tests.
## 7. Sources
@@ -136,28 +237,49 @@ shapes. These are verified by Discovery only.
## 8. Unverified (neither Discovery nor docs read, nor live)
Settled on 2026-10-24 and moved to section 6: Veo `prompt`, `sampleCount`,
`durationSeconds`, `aspectRatio`, `storageUri` and the finished operation
`response`; Lyria `prompt` and the `predictions[].bytesBase64Encoded` WAV
response; the empty endpoint list shape; thought signatures on function calls.
- Imagen `predict` instance/parameter names (`prompt`; `sampleCount`,
`aspectRatio`, `negativePrompt`) and the `predictions[].bytesBase64Encoded`
/ `mimeType` response: Discovery types them as free-form `Value`; the doc
pages could not be read.
- Lyria shape (`prompt`, `negative_prompt`, `seed`; `sample_count`).
- Veo shape (`sampleCount`, `durationSeconds`, `aspectRatio`, `storageUri`;
final `response.videos[]` with `gcsUri` / `bytesBase64Encoded` / `mimeType`).
`fetchPredictOperation` itself is Discovery-verified and reachable live.
/ `mimeType` response: no Imagen model is visible to project `lisa-448004`
(404 for every id tried), so even a rejected request is not informative.
- Lyria `negative_prompt`, `seed` and `sample_count`: a live call accepted
them, but it also accepted junk values (`seed:"abc"`, `sample_count:99`), so
acceptance does not prove the names. Whether a clip count above 1 is
honored was not checked.
- Veo `generateAudio` and the `gcsUri` result form with a real `storageUri`
bucket (no bucket was used). A missing `mimeType` on Veo output was not seen.
- Gemma/vLLM instance shape in `gemma_instance` (`prompt`, `max_tokens`,
`temperature`): the serving container's, not Google's API.
`temperature`): the serving container's, not Google's API; no endpoint
exists to ask.
- Anthropic streaming event names (`content_block_delta` / `text_delta`)
come from Anthropic's format; Claude completions were not obtained live.
- Embedding predict response `embeddings.values` / `statistics.token_count`
was observed live for text-embedding-005, not documented-read.
come from Anthropic's format; Claude completions were not obtained live
(429 quota on every attempt).
- `deployPublisherModel` field semantics beyond the schema names.
- Response shapes of the admin methods that need a real endpoint or a
mutation: deployModel, directPredict, directRawPredict, explain, chat
completions, openapi, invoke, stored responses (501 for this project),
export, setPublisherModelConfig, enableModel. They are returned as raw Json
(no field is read), so a different shape cannot break the client.
- Whether Google rejects a Gemini 3 replay that omits the `thoughtSignature`
(the accepted replay with it is verified).
## 9. Gaps
- Discovery methods deliberately not wrapped (owner: this module): publisher
`export`, `setPublisherModelConfig`, `enableModel`, IAM policy, `v1/responses`
on publishers, publisher-level `serverStreamingPredict` and v1beta1
`publishers.models.*` project-less duplicates.
- Every Discovery method of the owned resources is in the call table (see
section 5); the only intentional difference is that project-less v1 forms
are the `express` forms of rows and the v1beta1 forms of endpoint rows are
twins selected with `EndpointAdmin(beta=true)`.
- The admin request bodies are validated by top-level key against the call
table and by caps; nested fields (a `DeployedModel`, a `PublisherModelConfig`)
are Json the caller owns. Typed structs exist where the module reads fields
(`EndpointInfo`, `Operation`, `PublisherModel`).
- Endpoint `generateContent` family is wired but only Discovery-verified.
- `VertexModel` has no retry; quota 429 surfaces as `GoogleError`.
- A streaming error body shaped as a JSON array (`[{"error":...}]`, seen on
Claude `streamRawPredict`) goes through the foundation `StreamDecoder`, which
is outside this module; not verified that it maps to `GoogleError`.
- Token refresh is the caller's job (foundation gap).
+49
View File
@@ -0,0 +1,49 @@
#pragma once
// Input rules shared by the admin classes (EndpointAdmin, PublisherAdmin).
// Everything throws GoogleError::invalid before any network traffic.
#include <string>
#include "clients/body/json.h"
#include "google/errors.h"
#include "google/models/caps.h"
namespace molo::google::models {
struct AdminChecks {
// A JSON object no larger than ModelsCaps::kMaxAdminBodyChars serialized.
static const clients::body::Json& object(const clients::body::Json& body,
const char* what) {
if (!body.is_object())
throw GoogleError::invalid(std::string(what) + " must be a JSON object");
size(body, what);
return body;
}
static void size(const clients::body::Json& body, const char* what) {
if (body.dump().size() > ModelsCaps::kMaxAdminBodyChars)
throw GoogleError::invalid(std::string(what) + " over " +
std::to_string(ModelsCaps::kMaxAdminBodyChars) +
" characters");
}
// FieldMask: comma separated dotted camelCase paths, 1..kMaxMaskChars.
static void mask(const std::string& m) {
if (m.empty() || m.size() > ModelsCaps::kMaxMaskChars)
throw GoogleError::invalid("updateMask must be 1.." +
std::to_string(ModelsCaps::kMaxMaskChars) + " characters");
for (char c : m)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '_' || c == '.' || c == ','))
throw GoogleError::invalid("updateMask has invalid characters");
}
// Destructive, billable or access-changing calls refuse without confirm.
static void confirm(bool confirmed, const char* what) {
if (!confirmed)
throw GoogleError::invalid(std::string(what) + " needs confirm=true");
}
};
} // namespace molo::google::models
+56
View File
@@ -67,6 +67,62 @@ inline constexpr CallSpec kCalls[] = {
{"endpoint.count_tokens", "POST", "v1", "L", "/endpoints/{endpoint}:countTokens", false, "aiplatform.projects.locations.endpoints.countTokens", "contents systemInstruction tools generationConfig"},
{"endpoint.predict_long_running", "POST", "v1", "L", "/endpoints/{endpoint}:predictLongRunning", false, "aiplatform.projects.locations.endpoints.predictLongRunning", "instances parameters"},
{"endpoint.fetch_predict_operation", "POST", "v1", "L", "/endpoints/{endpoint}:fetchPredictOperation", false, "aiplatform.projects.locations.endpoints.fetchPredictOperation", "operationName"},
{"endpoint.create", "POST", "v1", "L", "/endpoints", false, "aiplatform.projects.locations.endpoints.create", "?endpointId displayName description labels network trafficSplit etag encryptionSpec dedicatedEndpointEnabled enablePrivateServiceConnect privateServiceConnectConfig predictRequestResponseLoggingConfig clientConnectionConfig genAiAdvancedFeaturesConfig gdcConfig"},
{"endpoint.patch", "PATCH", "v1", "L", "/endpoints/{endpoint}", false, "aiplatform.projects.locations.endpoints.patch", "?updateMask displayName description labels network trafficSplit etag encryptionSpec dedicatedEndpointEnabled enablePrivateServiceConnect privateServiceConnectConfig predictRequestResponseLoggingConfig clientConnectionConfig genAiAdvancedFeaturesConfig gdcConfig"},
{"endpoint.update", "POST", "v1", "L", "/endpoints/{endpoint}:update", false, "aiplatform.projects.locations.endpoints.update", "endpoint"},
{"endpoint.delete", "DELETE", "v1", "L", "/endpoints/{endpoint}", false, "aiplatform.projects.locations.endpoints.delete", "-"},
{"endpoint.deploy_model", "POST", "v1", "L", "/endpoints/{endpoint}:deployModel", false, "aiplatform.projects.locations.endpoints.deployModel", "deployedModel trafficSplit"},
{"endpoint.undeploy_model", "POST", "v1", "L", "/endpoints/{endpoint}:undeployModel", false, "aiplatform.projects.locations.endpoints.undeployModel", "deployedModelId trafficSplit"},
{"endpoint.mutate_deployed_model", "POST", "v1", "L", "/endpoints/{endpoint}:mutateDeployedModel", false, "aiplatform.projects.locations.endpoints.mutateDeployedModel", "deployedModel updateMask"},
{"endpoint.compute_tokens", "POST", "v1", "L", "/endpoints/{endpoint}:computeTokens", false, "aiplatform.projects.locations.endpoints.computeTokens", "instances contents model"},
{"endpoint.direct_predict", "POST", "v1", "L", "/endpoints/{endpoint}:directPredict", false, "aiplatform.projects.locations.endpoints.directPredict", "inputs parameters"},
{"endpoint.direct_raw_predict", "POST", "v1", "L", "/endpoints/{endpoint}:directRawPredict", false, "aiplatform.projects.locations.endpoints.directRawPredict", "methodName input"},
{"endpoint.explain", "POST", "v1", "L", "/endpoints/{endpoint}:explain", false, "aiplatform.projects.locations.endpoints.explain", "instances parameters deployedModelId explanationSpecOverride"},
{"endpoint.invoke", "POST", "v1", "L", "/endpoints/{endpoint}/invoke/{invoke}", false, "aiplatform.projects.locations.endpoints.invoke.invoke", "-"},
{"endpoint.deployed_model_invoke", "POST", "v1", "L", "/endpoints/{endpoint}/deployedModels/{deployed}/invoke/{invoke}", false, "aiplatform.projects.locations.endpoints.deployedModels.invoke.invoke", "-"},
{"endpoint.chat_completions", "POST", "v1", "L", "/endpoints/{endpoint}/chat/completions", false, "aiplatform.projects.locations.endpoints.chat.completions", "-"},
{"endpoint.openapi_completions", "POST", "v1", "L", "/endpoints/openapi/completions", false, "aiplatform.projects.locations.endpoints.openapi.completions", "-"},
{"endpoint.openapi_embeddings", "POST", "v1", "L", "/endpoints/openapi/embeddings", false, "aiplatform.projects.locations.endpoints.openapi.embeddings", "-"},
{"endpoint.openapi_responses", "POST", "v1", "L", "/endpoints/openapi/responses", false, "aiplatform.projects.locations.endpoints.openapi.responses", "-"},
{"endpoint.science_inference", "POST", "v1", "L", "/endpoints/google/science/inference", false, "aiplatform.projects.locations.endpoints.google.science.inference", "-"},
{"endpoint.response_get", "GET", "v1", "L", "/endpoints/{endpoint}/responses/{response}", false, "aiplatform.projects.locations.endpoints.responses.get", "-"},
{"endpoint.response_delete", "DELETE", "v1", "L", "/endpoints/{endpoint}/responses/{response}", false, "aiplatform.projects.locations.endpoints.responses.delete", "-"},
{"endpoint.operation_get", "GET", "v1", "L", "/endpoints/{endpoint}/operations/{operation}", false, "aiplatform.projects.locations.endpoints.operations.get", "-"},
{"endpoint.operation_list", "GET", "v1", "L", "/endpoints/{endpoint}/operations", false, "aiplatform.projects.locations.endpoints.operations.list", "?pageSize ?returnPartialSuccess ?filter ?pageToken"},
{"endpoint.operation_cancel", "POST", "v1", "L", "/endpoints/{endpoint}/operations/{operation}:cancel", false, "aiplatform.projects.locations.endpoints.operations.cancel", "-"},
{"endpoint.operation_wait", "POST", "v1", "L", "/endpoints/{endpoint}/operations/{operation}:wait", false, "aiplatform.projects.locations.endpoints.operations.wait", "?timeout"},
{"endpoint.operation_delete", "DELETE", "v1", "L", "/endpoints/{endpoint}/operations/{operation}", false, "aiplatform.projects.locations.endpoints.operations.delete", "-"},
{"publisher.server_streaming_predict", "POST", "v1", "L", "/publishers/{publisher}/models/{model}:serverStreamingPredict", false, "aiplatform.projects.locations.publishers.models.serverStreamingPredict", "inputs parameters"},
{"publisher.responses_create", "POST", "v1", "L", "/publishers/{publisher}/v1/responses", false, "aiplatform.projects.locations.publishers.v1.responses", "-"},
{"publisher.responses_compact", "POST", "v1", "L", "/publishers/{publisher}/v1/responses/compact", false, "aiplatform.projects.locations.publishers.v1.responses.compact", "-"},
{"publisher.responses_get", "GET", "v1", "L", "/publishers/{publisher}/v1/responses/{response}", false, "aiplatform.projects.locations.publishers.v1.responses.get", "-"},
{"publisher.responses_delete", "DELETE", "v1", "L", "/publishers/{publisher}/v1/responses/{response}", false, "aiplatform.projects.locations.publishers.v1.responses.delete", "-"},
{"beta.generate", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:generateContent", true, "aiplatform.projects.locations.publishers.models.generateContent", "contents systemInstruction tools toolConfig safetySettings generationConfig"},
{"beta.stream", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:streamGenerateContent", true, "aiplatform.projects.locations.publishers.models.streamGenerateContent", "contents systemInstruction tools toolConfig safetySettings generationConfig"},
{"beta.count_tokens", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:countTokens", true, "aiplatform.projects.locations.publishers.models.countTokens", "contents systemInstruction tools generationConfig"},
{"beta.compute_tokens", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:computeTokens", true, "aiplatform.projects.locations.publishers.models.computeTokens", "contents"},
{"beta.embed_content", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:embedContent", false, "aiplatform.projects.locations.publishers.models.embedContent", "content embedContentConfig"},
{"beta.predict", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:predict", true, "aiplatform.projects.locations.publishers.models.predict", "instances parameters"},
{"beta.predict_long_running", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:predictLongRunning", true, "aiplatform.projects.locations.publishers.models.predictLongRunning", "instances parameters"},
{"beta.fetch_predict_operation", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:fetchPredictOperation", true, "aiplatform.projects.locations.publishers.models.fetchPredictOperation", "operationName"},
{"beta.raw_predict", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:rawPredict", false, "aiplatform.projects.locations.publishers.models.rawPredict", "-"},
{"beta.stream_raw_predict", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:streamRawPredict", false, "aiplatform.projects.locations.publishers.models.streamRawPredict", "-"},
{"beta.server_streaming_predict", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:serverStreamingPredict", false, "aiplatform.projects.locations.publishers.models.serverStreamingPredict", "inputs parameters"},
{"beta.invoke", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}/invoke/{invoke}", false, "aiplatform.projects.locations.publishers.models.invoke.invoke", "-"},
{"beta.get_iam_policy", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:getIamPolicy", false, "aiplatform.projects.locations.publishers.models.getIamPolicy", "?options.requestedPolicyVersion"},
{"beta.set_config", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:setPublisherModelConfig", false, "aiplatform.projects.locations.publishers.models.setPublisherModelConfig", "updateMask publisherModelConfig"},
{"beta.export", "POST", "v1beta1", "L", "/publishers/{publisher}/models/{model}:export", false, "aiplatform.projects.locations.publishers.models.export", "destination"},
{"beta.enable_model", "POST", "v1beta1", "R", "/publishers/{publisher}/models/{model}:enableModel", false, "aiplatform.projects.publishers.models.enableModel", "service"},
{"beta.get", "GET", "v1beta1", "", "/publishers/{publisher}/models/{model}", false, "aiplatform.publishers.models.get", "?view ?languageCode"},
{"beta.responses_create", "POST", "v1beta1", "L", "/publishers/{publisher}/v1/responses", false, "aiplatform.projects.locations.publishers.v1.responses", "-"},
{"beta.responses_compact", "POST", "v1beta1", "L", "/publishers/{publisher}/v1/responses/compact", false, "aiplatform.projects.locations.publishers.v1.responses.compact", "-"},
{"beta.responses_get", "GET", "v1beta1", "L", "/publishers/{publisher}/v1/responses/{response}", false, "aiplatform.projects.locations.publishers.v1.responses.get", "-"},
{"beta.responses_delete", "DELETE", "v1beta1", "L", "/publishers/{publisher}/v1/responses/{response}", false, "aiplatform.projects.locations.publishers.v1.responses.delete", "-"},
// v1beta1-only endpoint methods (the rest of the endpoint rows also exist in v1beta1: planner beta flag)
{"endpoint.beta_list", "GET", "v1beta1", "L", "/endpoints", false, "aiplatform.projects.locations.endpoints.list", "?pageSize ?pageToken ?filter ?readMask ?gdcZone"},
{"endpoint.beta_get_iam_policy", "POST", "v1beta1", "L", "/endpoints/{endpoint}:getIamPolicy", false, "aiplatform.projects.locations.endpoints.getIamPolicy", "?options.requestedPolicyVersion"},
{"endpoint.beta_set_iam_policy", "POST", "v1beta1", "L", "/endpoints/{endpoint}:setIamPolicy", false, "aiplatform.projects.locations.endpoints.setIamPolicy", "policy"},
{"endpoint.beta_test_iam_permissions", "POST", "v1beta1", "L", "/endpoints/{endpoint}:testIamPermissions", false, "aiplatform.projects.locations.endpoints.testIamPermissions", "?permissions"},
};
// clang-format on
+7
View File
@@ -29,6 +29,13 @@ struct ModelsCaps {
static constexpr std::size_t kMaxInstances = 16;
static constexpr std::size_t kMaxInstanceChars = 100000;
static constexpr int kMaxGemmaTokens = 8192;
// Admin surface: endpoint lifecycle, publisher extras, operations
static constexpr std::size_t kMaxAdminBodyChars = 262144; // serialized request body
static constexpr std::size_t kMaxMaskChars = 512; // updateMask
static constexpr int kMaxOperationTimeoutSeconds = 600; // operations.wait
static constexpr std::size_t kMaxOperationPages = 5;
static constexpr std::size_t kMaxPermissions = 64;
static constexpr std::size_t kMaxStreamEvents = 5000;
// Media
static constexpr std::size_t kMaxPromptChars = 4000;
static constexpr int kMaxImages = 4;
+331
View File
@@ -0,0 +1,331 @@
#include "google/models/endpoint_admin.h"
#include <cstring>
#include "clients/url.h"
#include "google/models/admin_checks.h"
#include "google/models/open_models.h"
namespace molo::google::models {
using clients::body::Json;
namespace {
bool base64_chars(const std::string& s) {
for (char c : s)
if (!((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') ||
c == '+' || c == '/' || c == '=' || c == '-' || c == '_'))
return false;
return true;
}
Json with(const char* key, const Json& value, Json body = Json::object()) {
body.set(key, value);
return body;
}
std::string q_int(const char* key, int value) {
return std::string(key) + "=" + std::to_string(value);
}
} // namespace
EndpointAdmin::EndpointAdmin(std::shared_ptr<GoogleClient> client, VertexTarget target,
bool beta)
: VertexService(std::move(client), std::move(target), "aiplatform"), beta_(beta) {}
PlannedCall EndpointAdmin::plan_call(const std::string& call_id,
const std::string& endpoint_id, const Json* body,
const std::string& query,
const CallPlanner::Args& extra) const {
CallPlanner::Args args = extra;
if (!endpoint_id.empty()) args["endpoint"] = endpoint_id;
const bool twin = beta_ && std::strcmp(CallPlanner::spec(call_id).version, "v1") == 0;
return planner_.plan(call_id, args, body, query, twin);
}
Operation EndpointAdmin::run_operation(const PlannedCall& call) const {
return Operation::from_json(run(call));
}
// --- lifecycle ---------------------------------------------------------------
Operation EndpointAdmin::create(const Json& endpoint, const std::string& endpoint_id) const {
AdminChecks::object(endpoint, "endpoint");
std::string q;
if (!endpoint_id.empty()) {
VertexTarget::require_segment(endpoint_id, "endpointId");
q = "endpointId=" + clients::Url::encode_component(endpoint_id);
}
return run_operation(plan_call("endpoint.create", "", &endpoint, q));
}
Json EndpointAdmin::patch(const std::string& endpoint_id, const Json& endpoint,
const std::string& update_mask) const {
AdminChecks::object(endpoint, "endpoint");
AdminChecks::mask(update_mask);
return run(plan_call("endpoint.patch", endpoint_id, &endpoint,
"updateMask=" + clients::Url::encode_component(update_mask)));
}
Operation EndpointAdmin::update(const std::string& endpoint_id, const Json& endpoint) const {
AdminChecks::object(endpoint, "endpoint");
Json body = with("endpoint", endpoint);
return run_operation(plan_call("endpoint.update", endpoint_id, &body));
}
Operation EndpointAdmin::destroy(const std::string& endpoint_id, bool confirm) const {
AdminChecks::confirm(confirm, "deleting an endpoint");
return run_operation(plan_call("endpoint.delete", endpoint_id));
}
Operation EndpointAdmin::deploy_model(const std::string& endpoint_id, const Json& deployed_model,
const Json& traffic_split, bool confirm) const {
AdminChecks::confirm(confirm, "deploying a model (billable)");
AdminChecks::object(deployed_model, "deployedModel");
Json body = with("deployedModel", deployed_model);
if (traffic_split.is_object()) body.set("trafficSplit", AdminChecks::object(traffic_split, "trafficSplit"));
return run_operation(plan_call("endpoint.deploy_model", endpoint_id, &body));
}
Operation EndpointAdmin::undeploy_model(const std::string& endpoint_id,
const std::string& deployed_model_id,
const Json& traffic_split, bool confirm) const {
AdminChecks::confirm(confirm, "undeploying a model");
VertexTarget::require_segment(deployed_model_id, "deployedModelId");
Json body = with("deployedModelId", Json(deployed_model_id));
if (traffic_split.is_object()) body.set("trafficSplit", AdminChecks::object(traffic_split, "trafficSplit"));
return run_operation(plan_call("endpoint.undeploy_model", endpoint_id, &body));
}
Operation EndpointAdmin::mutate_deployed_model(const std::string& endpoint_id,
const Json& deployed_model,
const std::string& update_mask,
bool confirm) const {
AdminChecks::confirm(confirm, "mutating a deployed model");
AdminChecks::object(deployed_model, "deployedModel");
AdminChecks::mask(update_mask);
Json body = with("deployedModel", deployed_model);
body.set("updateMask", Json(update_mask));
return run_operation(plan_call("endpoint.mutate_deployed_model", endpoint_id, &body));
}
// --- inference ---------------------------------------------------------------
Json EndpointAdmin::compute_tokens(const std::string& endpoint_id, const Json& contents,
const std::string& model) const {
if (!contents.is_array() || contents.as_array().empty() ||
contents.as_array().size() > ModelsCaps::kMaxContents)
throw GoogleError::invalid("contents must be an array of 1.." +
std::to_string(ModelsCaps::kMaxContents) + " items");
AdminChecks::size(contents, "contents");
Json body = with("contents", contents);
if (!model.empty()) {
VertexTarget::require_segment(model, "model");
body.set("model", Json(model));
}
return run(plan_call("endpoint.compute_tokens", endpoint_id, &body));
}
Json EndpointAdmin::direct_predict(const std::string& endpoint_id, const Json& inputs,
const Json& parameters) const {
if (!inputs.is_array() || inputs.as_array().empty() ||
inputs.as_array().size() > ModelsCaps::kMaxInstances)
throw GoogleError::invalid("inputs must be an array of 1.." +
std::to_string(ModelsCaps::kMaxInstances) + " items");
AdminChecks::size(inputs, "inputs");
Json body = with("inputs", inputs);
if (parameters.is_object()) body.set("parameters", parameters);
return run(plan_call("endpoint.direct_predict", endpoint_id, &body));
}
Json EndpointAdmin::direct_raw_predict(const std::string& endpoint_id,
const std::string& method_name,
const std::string& input_base64) const {
if (method_name.empty() || method_name.size() > 256)
throw GoogleError::invalid("methodName must be 1..256 characters");
for (char c : method_name)
if (!((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') ||
c == '/' || c == '.' || c == '_' || c == '-'))
throw GoogleError::invalid("methodName has invalid characters");
if (input_base64.size() > ModelsCaps::kMaxAdminBodyChars || !base64_chars(input_base64))
throw GoogleError::invalid("input must be base64 within " +
std::to_string(ModelsCaps::kMaxAdminBodyChars) + " characters");
Json body = with("methodName", Json(method_name));
body.set("input", Json(input_base64));
return run(plan_call("endpoint.direct_raw_predict", endpoint_id, &body));
}
Json EndpointAdmin::explain(const std::string& endpoint_id, const Json& instances,
const Json& parameters, const std::string& deployed_model_id) const {
if (!instances.is_array() || instances.as_array().empty() ||
instances.as_array().size() > ModelsCaps::kMaxInstances)
throw GoogleError::invalid("instances must be an array of 1.." +
std::to_string(ModelsCaps::kMaxInstances) + " items");
AdminChecks::size(instances, "instances");
Json body = with("instances", instances);
if (parameters.is_object()) body.set("parameters", parameters);
if (!deployed_model_id.empty()) {
VertexTarget::require_segment(deployed_model_id, "deployedModelId");
body.set("deployedModelId", Json(deployed_model_id));
}
return run(plan_call("endpoint.explain", endpoint_id, &body));
}
Json EndpointAdmin::invoke(const std::string& endpoint_id, const std::string& invoke_id,
const Json& body) const {
AdminChecks::object(body, "body");
return run(plan_call("endpoint.invoke", endpoint_id, &body, "", {{"invoke", invoke_id}}));
}
Json EndpointAdmin::invoke_deployed_model(const std::string& endpoint_id,
const std::string& deployed_model_id,
const std::string& invoke_id, const Json& body) const {
AdminChecks::object(body, "body");
return run(plan_call("endpoint.deployed_model_invoke", endpoint_id, &body, "",
{{"deployed", deployed_model_id}, {"invoke", invoke_id}}));
}
Json EndpointAdmin::chat_completions(const std::string& endpoint_id, const Json& body) const {
AdminChecks::object(body, "body");
return run(plan_call("endpoint.chat_completions", endpoint_id, &body));
}
Json EndpointAdmin::openapi(const std::string& kind, const Json& body) const {
AdminChecks::object(body, "body");
if (kind != "completions" && kind != "embeddings" && kind != "responses")
throw GoogleError::invalid("kind must be completions, embeddings or responses");
return run(plan_call("endpoint.openapi_" + kind, "", &body));
}
Json EndpointAdmin::science_inference(const Json& body) const {
AdminChecks::object(body, "body");
return run(plan_call("endpoint.science_inference", "", &body));
}
Json EndpointAdmin::get_response(const std::string& endpoint_id,
const std::string& response_id) const {
return run(plan_call("endpoint.response_get", endpoint_id, nullptr, "",
{{"response", response_id}}));
}
Json EndpointAdmin::delete_response(const std::string& endpoint_id,
const std::string& response_id, bool confirm) const {
AdminChecks::confirm(confirm, "deleting a stored response");
return run(plan_call("endpoint.response_delete", endpoint_id, nullptr, "",
{{"response", response_id}}));
}
// --- operations --------------------------------------------------------------
Operation EndpointAdmin::operation(const std::string& endpoint_id,
const std::string& operation_id) const {
return run_operation(plan_call("endpoint.operation_get", endpoint_id, nullptr, "",
{{"operation", operation_id}}));
}
std::vector<Operation> EndpointAdmin::list_operations(const std::string& endpoint_id,
std::size_t max_pages,
const std::string& filter) const {
if (max_pages < 1 || max_pages > ModelsCaps::kMaxOperationPages)
throw GoogleError::invalid("max_pages outside 1.." +
std::to_string(ModelsCaps::kMaxOperationPages));
if (filter.size() > 256) throw GoogleError::invalid("filter over 256 characters");
std::vector<Operation> out;
std::string token;
for (std::size_t page = 0; page < max_pages; ++page) {
std::string q = "pageSize=" + std::to_string(ModelsCaps::kMaxPageSize);
if (!filter.empty()) q += "&filter=" + clients::Url::encode_component(filter);
if (!token.empty()) q += "&pageToken=" + clients::Url::encode_component(token);
Json reply = run(plan_call("endpoint.operation_list", endpoint_id, nullptr, q));
if (const Json* items = reply.find("operations"); items && items->is_array())
for (const Json& item : items->as_array()) {
if (out.size() >= ModelsCaps::kMaxModelsReturned) return out;
out.push_back(Operation::from_json(item));
}
token = json_str(reply, "nextPageToken");
if (token.empty()) break;
}
return out;
}
void EndpointAdmin::cancel_operation(const std::string& endpoint_id,
const std::string& operation_id) const {
run(plan_call("endpoint.operation_cancel", endpoint_id, nullptr, "",
{{"operation", operation_id}}));
}
Operation EndpointAdmin::wait_operation(const std::string& endpoint_id,
const std::string& operation_id,
int timeout_seconds) const {
if (timeout_seconds < 1 || timeout_seconds > ModelsCaps::kMaxOperationTimeoutSeconds)
throw GoogleError::invalid("timeout outside 1.." +
std::to_string(ModelsCaps::kMaxOperationTimeoutSeconds) +
" seconds");
return run_operation(plan_call("endpoint.operation_wait", endpoint_id, nullptr,
"timeout=" + std::to_string(timeout_seconds) + "s",
{{"operation", operation_id}}));
}
void EndpointAdmin::delete_operation(const std::string& endpoint_id,
const std::string& operation_id, bool confirm) const {
AdminChecks::confirm(confirm, "deleting an operation record");
run(plan_call("endpoint.operation_delete", endpoint_id, nullptr, "",
{{"operation", operation_id}}));
}
// --- v1beta1 only ------------------------------------------------------------
Json EndpointAdmin::list_beta(const std::string& read_mask, const std::string& gdc_zone) const {
std::string q = "pageSize=" + std::to_string(ModelsCaps::kMaxPageSize);
if (!read_mask.empty()) {
AdminChecks::mask(read_mask);
q += "&readMask=" + clients::Url::encode_component(read_mask);
}
if (!gdc_zone.empty()) {
VertexTarget::require_segment(gdc_zone, "gdcZone");
q += "&gdcZone=" + clients::Url::encode_component(gdc_zone);
}
return run(plan_call("endpoint.beta_list", "", nullptr, q));
}
Json EndpointAdmin::get_iam_policy(const std::string& endpoint_id, int policy_version) const {
if (policy_version < 0 || policy_version > 3)
throw GoogleError::invalid("policy version outside 0..3");
return run(plan_call("endpoint.beta_get_iam_policy", endpoint_id, nullptr,
policy_version ? q_int("options.requestedPolicyVersion", policy_version)
: ""));
}
Json EndpointAdmin::set_iam_policy(const std::string& endpoint_id, const Json& policy,
bool confirm) const {
AdminChecks::confirm(confirm, "replacing an IAM policy");
AdminChecks::object(policy, "policy");
Json body = with("policy", policy);
return run(plan_call("endpoint.beta_set_iam_policy", endpoint_id, &body));
}
std::vector<std::string> EndpointAdmin::test_iam_permissions(
const std::string& endpoint_id, const std::vector<std::string>& permissions) const {
if (permissions.empty() || permissions.size() > ModelsCaps::kMaxPermissions)
throw GoogleError::invalid("1.." + std::to_string(ModelsCaps::kMaxPermissions) +
" permissions");
std::string q;
for (const std::string& p : permissions) {
if (p.empty() || p.size() > 128) throw GoogleError::invalid("bad permission");
for (char c : p)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '.' || c == '_'))
throw GoogleError::invalid("bad permission");
q += (q.empty() ? "permissions=" : "&permissions=") + clients::Url::encode_component(p);
}
Json reply = run(plan_call("endpoint.beta_test_iam_permissions", endpoint_id, nullptr, q));
std::vector<std::string> out;
if (const Json* a = reply.find("permissions"); a && a->is_array())
for (const Json& p : a->as_array())
if (p.is_string()) out.push_back(p.as_string());
return out;
}
} // namespace molo::google::models
+123
View File
@@ -0,0 +1,123 @@
#pragma once
// EndpointAdmin: every Discovery method of projects.locations.endpoints that
// OpenModels does not wrap: lifecycle (create, patch, update, delete,
// deployModel, undeployModel, mutateDeployedModel), the remaining inference
// surfaces (computeTokens, directPredict, directRawPredict, explain, invoke,
// deployed model invoke, OpenAI style chat/completions/embeddings/responses,
// science inference), stored responses, the endpoint's operations, and the
// v1beta1-only methods (list with gdcZone, IAM). Project scoped, OAuth.
//
// Request bodies are Json whose top-level keys must be declared in the call
// table (calls.h); a stray key is rejected before any network traffic.
// Destructive, billable and access-changing calls need confirm=true.
// `beta` sends the v1beta1 twin of every "endpoint." row.
#include <functional>
#include <string>
#include <vector>
#include "google/models/vertex_service.h"
#include "google/operation.h"
namespace molo::google::models {
class EndpointAdmin : public VertexService {
public:
EndpointAdmin(std::shared_ptr<GoogleClient> client, VertexTarget target,
bool beta = false);
bool beta() const { return beta_; }
// --- lifecycle (long-running: they return the Operation) -------------
Operation create(const clients::body::Json& endpoint,
const std::string& endpoint_id = "") const;
// PATCH: returns the updated endpoint document.
clients::body::Json patch(const std::string& endpoint_id,
const clients::body::Json& endpoint,
const std::string& update_mask) const;
// POST :update (long-running form of patch).
Operation update(const std::string& endpoint_id,
const clients::body::Json& endpoint) const;
Operation destroy(const std::string& endpoint_id, bool confirm) const;
// deployedModel is the DeployedModel object (model, displayName, machine
// and scaling fields); billable, hence confirm.
Operation deploy_model(const std::string& endpoint_id,
const clients::body::Json& deployed_model,
const clients::body::Json& traffic_split, bool confirm) const;
Operation undeploy_model(const std::string& endpoint_id,
const std::string& deployed_model_id,
const clients::body::Json& traffic_split, bool confirm) const;
Operation mutate_deployed_model(const std::string& endpoint_id,
const clients::body::Json& deployed_model,
const std::string& update_mask, bool confirm) const;
// --- inference surfaces ----------------------------------------------
clients::body::Json compute_tokens(const std::string& endpoint_id,
const clients::body::Json& contents,
const std::string& model = "") const;
clients::body::Json direct_predict(const std::string& endpoint_id,
const clients::body::Json& inputs,
const clients::body::Json& parameters = {}) const;
// input is bytes, sent base64 as Discovery types it (`bytes` field).
clients::body::Json direct_raw_predict(const std::string& endpoint_id,
const std::string& method_name,
const std::string& input_base64) const;
clients::body::Json explain(const std::string& endpoint_id,
const clients::body::Json& instances,
const clients::body::Json& parameters = {},
const std::string& deployed_model_id = "") const;
clients::body::Json invoke(const std::string& endpoint_id, const std::string& invoke_id,
const clients::body::Json& body) const;
clients::body::Json invoke_deployed_model(const std::string& endpoint_id,
const std::string& deployed_model_id,
const std::string& invoke_id,
const clients::body::Json& body) const;
// OpenAI compatible: /endpoints/{id}/chat/completions
clients::body::Json chat_completions(const std::string& endpoint_id,
const clients::body::Json& body) const;
// kind: "completions", "embeddings" or "responses" (/endpoints/openapi/...)
clients::body::Json openapi(const std::string& kind, const clients::body::Json& body) const;
clients::body::Json science_inference(const clients::body::Json& body) const;
clients::body::Json get_response(const std::string& endpoint_id,
const std::string& response_id) const;
clients::body::Json delete_response(const std::string& endpoint_id,
const std::string& response_id, bool confirm) const;
// --- the endpoint's operations -----------------------------------------
Operation operation(const std::string& endpoint_id, const std::string& operation_id) const;
std::vector<Operation> list_operations(const std::string& endpoint_id,
std::size_t max_pages = 1,
const std::string& filter = "") const;
void cancel_operation(const std::string& endpoint_id, const std::string& operation_id) const;
// POST :wait with a server side timeout (1..kMaxOperationTimeoutSeconds).
Operation wait_operation(const std::string& endpoint_id, const std::string& operation_id,
int timeout_seconds) const;
void delete_operation(const std::string& endpoint_id, const std::string& operation_id,
bool confirm) const;
// --- v1beta1 only ---------------------------------------------------
// Lists endpoints through the v1beta1 form (readMask, gdcZone available).
clients::body::Json list_beta(const std::string& read_mask = "",
const std::string& gdc_zone = "") const;
clients::body::Json get_iam_policy(const std::string& endpoint_id,
int policy_version = 0) const;
clients::body::Json set_iam_policy(const std::string& endpoint_id,
const clients::body::Json& policy, bool confirm) const;
std::vector<std::string> test_iam_permissions(
const std::string& endpoint_id, const std::vector<std::string>& permissions) const;
// Plans without sending (tests and the call-table conformance check).
// `extra` carries additional path arguments (operation, response, deployed,
// invoke); `query` is the already encoded query string.
PlannedCall plan_call(const std::string& call_id, const std::string& endpoint_id,
const clients::body::Json* body = nullptr,
const std::string& query = "",
const CallPlanner::Args& extra = {}) const;
private:
Operation run_operation(const PlannedCall& call) const;
bool beta_;
};
} // namespace molo::google::models
+1 -1
View File
@@ -49,7 +49,7 @@ void Gemini::validate(const GenerateRequest& request) {
if (c.parts.empty()) throw GoogleError::invalid("a content has no parts");
for (const Part& p : c.parts) {
chars += p.text.size();
if (p.text.empty() && !p.inline_data && !p.file_data && !p.function_call &&
if (p.text.empty() && p.thought_signature.empty() && !p.inline_data && !p.file_data && !p.function_call &&
!p.function_response)
throw GoogleError::invalid("a part is empty");
}
+5
View File
@@ -50,6 +50,11 @@ std::vector<MediaItem> MediaGenerator::items_from(const Json& list) {
throw GoogleError(502, "BAD_RESPONSE", "media item is not valid base64");
}
if (item.bytes.empty() && item.uri.empty()) continue;
// lyria-002 answered 200 with bytesBase64Encoded only (observed live
// 2026-10-24); the bytes are a RIFF/WAVE file. Name the mime from them.
if (item.mime.empty() && item.bytes.size() >= 12 && item.bytes.compare(0, 4, "RIFF") == 0 &&
item.bytes.compare(8, 4, "WAVE") == 0)
item.mime = "audio/wav";
out.push_back(std::move(item));
}
return out;
+20 -2
View File
@@ -41,14 +41,32 @@ std::string fill(const std::string& tpl, const CallPlanner::Args& args) {
}
} // namespace
namespace {
void check_body_keys(const CallSpec& s, const clients::body::Json& body) {
const std::string fields = std::string(" ") + s.fields + " ";
if (fields == " - ") return;
if (!body.is_object())
throw GoogleError::invalid(std::string(s.id) + ": body must be an object");
for (const auto& [key, value] : body.as_object()) {
(void)value;
if (fields.find(" " + key + " ") == std::string::npos)
throw GoogleError::invalid(std::string(s.id) + ": unknown body field " + key);
}
}
} // namespace
PlannedCall CallPlanner::plan(const std::string& call_id, const Args& args,
const clients::body::Json* body,
const std::string& query) const {
const std::string& query, bool want_beta) const {
const CallSpec& s = spec(call_id);
PlannedCall p;
p.spec = &s;
p.method = method_of(s.http);
const bool beta = std::strcmp(s.version, "v1beta1") == 0;
if (want_beta &&
(std::strcmp(s.version, "v1") != 0 || std::strncmp(s.id, "endpoint.", 9) != 0))
throw GoogleError::invalid(call_id + " has no v1beta1 twin");
const bool beta = want_beta || std::strcmp(s.version, "v1beta1") == 0;
if (body) check_body_keys(s, *body);
const std::string prefix = s.prefix;
std::string path;
if (prefix == "L") {
+6 -2
View File
@@ -35,10 +35,14 @@ class CallPlanner {
// Throws std::logic_error for an id missing from the table (a bug), and
// GoogleError::invalid for a bad id value or a project-only call in
// express mode. `query` is appended after "?" when non-empty.
// express mode. `query` is appended after "?" when non-empty. `beta`
// selects the v1beta1 twin of an "endpoint." row (tools/check_discovery.py
// verifies the twin); it is invalid for any other row. A body key that the
// row's field list does not declare is GoogleError::invalid (rows with "-"
// take any body: raw HTTP bodies).
PlannedCall plan(const std::string& call_id, const Args& args,
const clients::body::Json* body = nullptr,
const std::string& query = "") const;
const std::string& query = "", bool beta = false) const;
static const CallSpec& spec(const std::string& call_id);
+213
View File
@@ -0,0 +1,213 @@
#include "google/models/publisher_admin.h"
#include "clients/url.h"
#include "google/models/admin_checks.h"
namespace molo::google::models {
using clients::body::Json;
namespace {
const char* responses_id(const char* name, bool beta) {
static const char* kV1[] = {"publisher.responses_create", "publisher.responses_compact",
"publisher.responses_get", "publisher.responses_delete"};
static const char* kBeta[] = {"beta.responses_create", "beta.responses_compact",
"beta.responses_get", "beta.responses_delete"};
int i = name[0] == 'c' ? (name[1] == 'r' ? 0 : 1) : (name[0] == 'g' ? 2 : 3);
return beta ? kBeta[i] : kV1[i];
}
Json take(const Json& contents, const char* what) {
if (!contents.is_array() || contents.as_array().empty() ||
contents.as_array().size() > ModelsCaps::kMaxContents)
throw GoogleError::invalid(std::string(what) + " must be an array of 1.." +
std::to_string(ModelsCaps::kMaxContents) + " items");
AdminChecks::size(contents, what);
return contents;
}
} // namespace
PublisherAdmin::PublisherAdmin(std::shared_ptr<GoogleClient> client, VertexTarget target)
: VertexService(std::move(client), std::move(target), "aiplatform") {}
PlannedCall PublisherAdmin::plan_call(const std::string& call_id, const CallPlanner::Args& args,
const Json* body, const std::string& query) const {
return planner_.plan(call_id, args, body, query);
}
// --- v1 ----------------------------------------------------------------------
void PublisherAdmin::server_streaming_predict(const std::string& publisher,
const std::string& model, const Json& inputs,
const Json& parameters, const Sink& sink) const {
if (!inputs.is_array() || inputs.as_array().empty() ||
inputs.as_array().size() > ModelsCaps::kMaxInstances)
throw GoogleError::invalid("inputs must be an array of 1.." +
std::to_string(ModelsCaps::kMaxInstances) + " items");
AdminChecks::size(inputs, "inputs");
Json body = Json::object();
body.set("inputs", inputs);
if (parameters.is_object()) body.set("parameters", parameters);
PlannedCall call =
plan_call("publisher.server_streaming_predict", model_args(publisher, model), &body);
std::size_t seen = 0;
run_stream(call, [&](const Json& event) {
return sink(event) && ++seen < ModelsCaps::kMaxStreamEvents;
});
}
Json PublisherAdmin::responses_create(const std::string& publisher, const Json& body,
bool beta) const {
AdminChecks::object(body, "body");
return run(plan_call(responses_id("create", beta), {{"publisher", publisher}}, &body));
}
Json PublisherAdmin::responses_compact(const std::string& publisher, const Json& body,
bool beta) const {
AdminChecks::object(body, "body");
return run(plan_call(responses_id("compact", beta), {{"publisher", publisher}}, &body));
}
Json PublisherAdmin::responses_get(const std::string& publisher, const std::string& response_id,
bool beta) const {
return run(plan_call(responses_id("get", beta),
{{"publisher", publisher}, {"response", response_id}}));
}
Json PublisherAdmin::responses_delete(const std::string& publisher,
const std::string& response_id, bool confirm,
bool beta) const {
AdminChecks::confirm(confirm, "deleting a stored response");
return run(plan_call(responses_id("delete", beta),
{{"publisher", publisher}, {"response", response_id}}));
}
// --- v1beta1 -----------------------------------------------------------------
Operation PublisherAdmin::export_model(const std::string& publisher, const std::string& model,
const std::string& gcs_output_uri_prefix,
bool confirm) const {
AdminChecks::confirm(confirm, "exporting a publisher model (copies weights to your bucket)");
if (gcs_output_uri_prefix.rfind("gs://", 0) != 0 || gcs_output_uri_prefix.size() <= 5 ||
gcs_output_uri_prefix.size() > 512)
throw GoogleError::invalid("destination must be a gs:// prefix");
for (char c : gcs_output_uri_prefix)
if (static_cast<unsigned char>(c) <= 0x20) throw GoogleError::invalid("bad gs:// prefix");
Json dest = Json::object();
dest.set("outputUriPrefix", Json(gcs_output_uri_prefix));
Json body = Json::object();
body.set("destination", dest);
return Operation::from_json(run(plan_call("beta.export", model_args(publisher, model), &body)));
}
Operation PublisherAdmin::set_config(const std::string& publisher, const std::string& model,
const Json& publisher_model_config,
const std::string& update_mask, bool confirm) const {
AdminChecks::confirm(confirm, "changing a publisher model config");
AdminChecks::object(publisher_model_config, "publisherModelConfig");
AdminChecks::mask(update_mask);
Json body = Json::object();
body.set("publisherModelConfig", publisher_model_config);
body.set("updateMask", Json(update_mask));
return Operation::from_json(
run(plan_call("beta.set_config", model_args(publisher, model), &body)));
}
Json PublisherAdmin::enable_model(const std::string& publisher, const std::string& model,
const std::string& service, bool confirm) const {
AdminChecks::confirm(confirm, "enabling a model for the project");
if (service.size() > 256) throw GoogleError::invalid("service over 256 characters");
for (char c : service)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '.' || c == '-' || c == '_'))
throw GoogleError::invalid("service has invalid characters");
Json body = Json::object();
if (!service.empty()) body.set("service", Json(service));
return run(plan_call("beta.enable_model", model_args(publisher, model), &body));
}
Json PublisherAdmin::get_iam_policy(const std::string& publisher, const std::string& model,
int policy_version) const {
if (policy_version < 0 || policy_version > 3)
throw GoogleError::invalid("policy version outside 0..3");
return run(plan_call("beta.get_iam_policy", model_args(publisher, model), nullptr,
policy_version ? "options.requestedPolicyVersion=" +
std::to_string(policy_version)
: ""));
}
GenerateResponse PublisherAdmin::beta_generate(const std::string& publisher,
const std::string& model,
const GenerateRequest& request) const {
Gemini::validate(request);
Json body = request.to_json();
return GenerateResponse::from_json(
run(plan_call("beta.generate", model_args(publisher, model), &body)));
}
void PublisherAdmin::beta_stream(
const std::string& publisher, const std::string& model, const GenerateRequest& request,
const std::function<bool(const GenerateResponse&)>& on_chunk) const {
Gemini::validate(request);
Json body = request.to_json();
run_stream(plan_call("beta.stream", model_args(publisher, model), &body, "alt=sse"),
[&](const Json& e) { return on_chunk(GenerateResponse::from_json(e)); });
}
CountTokensResult PublisherAdmin::beta_count_tokens(const std::string& publisher,
const std::string& model,
const GenerateRequest& request) const {
Gemini::validate(request);
Json full = request.to_json();
Json body = Json::object();
for (const char* key : {"contents", "systemInstruction", "tools", "generationConfig"})
if (const Json* v = full.find(key)) body.set(key, *v);
Json reply = run(plan_call("beta.count_tokens", model_args(publisher, model), &body));
CountTokensResult out;
out.total_tokens = static_cast<int>(json_num(reply, "totalTokens"));
out.billable_characters = static_cast<int>(json_num(reply, "totalBillableCharacters"));
out.raw = reply;
return out;
}
Json PublisherAdmin::beta_compute_tokens(const std::string& publisher, const std::string& model,
const Json& contents) const {
Json body = Json::object();
body.set("contents", take(contents, "contents"));
return run(plan_call("beta.compute_tokens", model_args(publisher, model), &body));
}
Json PublisherAdmin::beta_get(const std::string& publisher, const std::string& model,
bool full_view) const {
return run(plan_call("beta.get", model_args(publisher, model), nullptr,
full_view ? "view=PUBLISHER_MODEL_VIEW_FULL" : ""));
}
Json PublisherAdmin::beta_post(const std::string& call_id, const std::string& publisher,
const std::string& model, const Json& body) const {
static const char* kAllowed[] = {"beta.embed_content", "beta.predict", "beta.predict_long_running",
"beta.fetch_predict_operation", "beta.raw_predict",
"beta.server_streaming_predict"};
bool ok = false;
for (const char* a : kAllowed) ok = ok || call_id == a;
if (!ok) throw GoogleError::invalid("call " + call_id + " is not a v1beta1 POST form");
AdminChecks::object(body, "body");
return run(plan_call(call_id, model_args(publisher, model), &body));
}
void PublisherAdmin::beta_stream_raw_predict(const std::string& publisher,
const std::string& model, const Json& body,
const Sink& sink) const {
AdminChecks::object(body, "body");
run_stream(plan_call("beta.stream_raw_predict", model_args(publisher, model), &body), sink);
}
Json PublisherAdmin::beta_invoke(const std::string& publisher, const std::string& model,
const std::string& invoke_id, const Json& body) const {
AdminChecks::object(body, "body");
CallPlanner::Args args = model_args(publisher, model);
args["invoke"] = invoke_id;
return run(plan_call("beta.invoke", args, &body));
}
} // namespace molo::google::models
+84
View File
@@ -0,0 +1,84 @@
#pragma once
// PublisherAdmin: the publisher model methods Discovery lists that the other
// services in this module do not wrap:
// - v1: serverStreamingPredict, the `v1/responses` family (create, compact,
// get, delete) of a publisher;
// - v1beta1: export, setPublisherModelConfig, enableModel, getIamPolicy,
// the `v1/responses` family, and the v1beta1 form of every publisher
// model method (generate, stream, tokens, predict, long running, raw
// predict, invoke, embedContent, get).
// Request bodies are checked against the call table (see EndpointAdmin).
// Export, config changes and enableModel change the project: confirm=true.
#include <functional>
#include <string>
#include "google/gemini_types.h"
#include "google/models/gemini.h"
#include "google/models/vertex_service.h"
#include "google/operation.h"
namespace molo::google::models {
class PublisherAdmin : public VertexService {
public:
using Sink = std::function<bool(const clients::body::Json&)>;
PublisherAdmin(std::shared_ptr<GoogleClient> client, VertexTarget target);
// --- v1 --------------------------------------------------------------
void server_streaming_predict(const std::string& publisher, const std::string& model,
const clients::body::Json& inputs,
const clients::body::Json& parameters,
const Sink& sink) const;
// `v1/responses` of a publisher; version selects v1 or v1beta1.
clients::body::Json responses_create(const std::string& publisher,
const clients::body::Json& body, bool beta = false) const;
clients::body::Json responses_compact(const std::string& publisher,
const clients::body::Json& body, bool beta = false) const;
clients::body::Json responses_get(const std::string& publisher, const std::string& response_id,
bool beta = false) const;
clients::body::Json responses_delete(const std::string& publisher,
const std::string& response_id, bool confirm,
bool beta = false) const;
// --- v1beta1 ---------------------------------------------------------
Operation export_model(const std::string& publisher, const std::string& model,
const std::string& gcs_output_uri_prefix, bool confirm) const;
Operation set_config(const std::string& publisher, const std::string& model,
const clients::body::Json& publisher_model_config,
const std::string& update_mask, bool confirm) const;
clients::body::Json enable_model(const std::string& publisher, const std::string& model,
const std::string& service, bool confirm) const;
clients::body::Json get_iam_policy(const std::string& publisher, const std::string& model,
int policy_version = 0) const;
GenerateResponse beta_generate(const std::string& publisher, const std::string& model,
const GenerateRequest& request) const;
void beta_stream(const std::string& publisher, const std::string& model,
const GenerateRequest& request,
const std::function<bool(const GenerateResponse&)>& on_chunk) const;
CountTokensResult beta_count_tokens(const std::string& publisher, const std::string& model,
const GenerateRequest& request) const;
clients::body::Json beta_compute_tokens(const std::string& publisher, const std::string& model,
const clients::body::Json& contents) const;
clients::body::Json beta_get(const std::string& publisher, const std::string& model,
bool full_view = false) const;
// The remaining v1beta1 POST forms take their Discovery body as is:
// call_id is one of beta.embed_content, beta.predict, beta.predict_long_running,
// beta.fetch_predict_operation, beta.raw_predict, beta.server_streaming_predict.
clients::body::Json beta_post(const std::string& call_id, const std::string& publisher,
const std::string& model, const clients::body::Json& body) const;
void beta_stream_raw_predict(const std::string& publisher, const std::string& model,
const clients::body::Json& body, const Sink& sink) const;
clients::body::Json beta_invoke(const std::string& publisher, const std::string& model,
const std::string& invoke_id,
const clients::body::Json& body) const;
// Plans without sending (tests, call-table conformance).
PlannedCall plan_call(const std::string& call_id, const CallPlanner::Args& args,
const clients::body::Json* body = nullptr,
const std::string& query = "") const;
};
} // namespace molo::google::models
+42 -3
View File
@@ -8,6 +8,10 @@ For every row it requires: the HTTP method and path exist in Discovery (the
prefixed form, and the unprefixed express form when the row says express),
the rpc id matches, every body field name exists in the request schema
(dotted names follow $ref), and every "?name" is a query parameter.
Coverage: every Discovery method whose rpc id starts with one of OWNED (the
resources this module owns) must be a row of the table, the express form of a
row, or listed in EXCLUDED with a reason. A new Discovery method therefore
fails the check until it is wrapped or excluded on purpose.
Exit 0: all rows verified. Exit 1: at least one mismatch (printed).
"""
import json
@@ -21,6 +25,18 @@ TABLE = os.path.join(HERE, "..", "calls.h")
ROW = re.compile(
r'^\s*\{"([^"]+)",\s*"([A-Z]+)",\s*"([^"]+)",\s*"([^"]*)",\s*"([^"]+)",\s*'
r'(true|false),\s*"([^"]+)",\s*"([^"]*)"\},?\s*$')
OWNED = (
"aiplatform.publishers.models.",
"aiplatform.projects.locations.publishers.",
"aiplatform.projects.publishers.models.",
"aiplatform.projects.locations.endpoints.",
"aiplatform.projects.modelGardenEula.",
"aiplatform.projects.locations.deployPublisherModel",
)
# rpc id -> reason it is deliberately not wrapped (none today).
EXCLUDED = {}
BETA_TWIN = ("endpoint.",)
BETA_TWIN_SKIP = ("endpoint.list",) # beta list has other query parameters: own row
PREFIX = {"L": "/projects/{}/locations/{}", "R": "/projects/{}", "": ""}
@@ -84,22 +100,29 @@ def main():
docs = {}
index = {}
bad = []
for call_id, http, ver, prefix, suffix, express, rpc, fields in rows:
covered = set()
def load(ver):
if ver not in docs:
docs[ver] = fetch(ver, cache)
index[ver] = methods(docs[ver])
def check(call_id, http, ver, prefix, suffix, express, rpc, fields):
load(ver)
doc, idx = docs[ver], index[ver]
full = "/" + ver + PREFIX[prefix] + suffix
meth = idx.get((http, norm(full)))
if meth is None:
bad.append("%s: %s %s not in discovery %s" % (call_id, http, full, ver))
continue
return
covered.add((ver, meth["id"]))
if meth["id"] != rpc:
bad.append("%s: rpc id %s, table says %s" % (call_id, meth["id"], rpc))
if express == "true":
ex = idx.get((http, norm("/" + ver + suffix)))
if ex is None:
bad.append("%s: express form %s not in discovery" % (call_id, suffix))
else:
covered.add((ver, ex["id"]))
req = meth.get("request", {}).get("$ref")
params = meth.get("parameters", {})
for f in fields.split():
@@ -110,9 +133,25 @@ def main():
bad.append("%s: query parameter %s absent" % (call_id, f[1:]))
elif req is None or not schema_has(doc, req, f):
bad.append("%s: request field %s absent in %s" % (call_id, f, req))
for call_id, http, ver, prefix, suffix, express, rpc, fields in rows:
check(call_id, http, ver, prefix, suffix, express, rpc, fields)
# Every v1 endpoint row also exists in v1beta1 (selected with the
# planner's beta flag): same method, path, rpc id and fields.
if call_id.startswith(BETA_TWIN) and ver == "v1" and call_id not in BETA_TWIN_SKIP:
check(call_id + " [v1beta1 twin]", http, "v1beta1", prefix, suffix,
"false", rpc, fields)
owned = 0
for ver in docs:
for (http, path), meth in index[ver].items():
if meth["id"].startswith(OWNED):
owned += 1
if (ver, meth["id"]) not in covered and meth["id"] not in EXCLUDED:
bad.append("unwrapped discovery method %s %s (%s)" % (ver, meth["id"], path))
for b in bad:
print("FAIL " + b)
print("%d calls checked, %d problems" % (len(rows), len(bad)))
print("%d calls checked, %d owned discovery methods covered, %d problems"
% (len(rows), owned, len(bad)))
return 1 if bad else 0
+51
View File
@@ -1,9 +1,60 @@
#include "google/models/vertex_model.h"
#include "google/errors.h"
#include "google/models/caps.h"
namespace molo::google::models {
namespace {
bool plain_text(const Part& p) {
return !p.inline_data && !p.file_data && !p.function_call && !p.function_response;
}
} // namespace
void VertexModel::TurnBuilder::add(const GenerateResponse& chunk) {
if (chunk.candidates.empty()) return;
for (const Part& p : chunk.candidates[0].content.parts) {
if (turn_.parts.size() >= ModelsCaps::kMaxContents * 10)
throw GoogleError(502, "BAD_RESPONSE", "model turn over the part cap");
// An empty text part without a signature carries nothing to replay (the
// live stream ends with one) and Gemini::validate rejects it.
if (plain_text(p) && p.text.empty() && p.thought_signature.empty()) continue;
Part* last = turn_.parts.empty() ? nullptr : &turn_.parts.back();
if (!plain_text(p) || !last) {
turn_.parts.push_back(p);
} else if (plain_text(*last) && p.text.empty() && !p.thought_signature.empty() &&
last->thought_signature.empty()) {
last->thought_signature = p.thought_signature;
} else if (plain_text(*last) && last->thought == p.thought &&
last->thought_signature.empty() && !p.text.empty()) {
last->text += p.text;
last->thought_signature = p.thought_signature;
} else {
turn_.parts.push_back(p);
}
}
}
std::size_t VertexModel::TurnBuilder::signatures() const {
std::size_t n = 0;
for (const Part& p : turn_.parts)
if (!p.thought_signature.empty()) ++n;
return n;
}
Content VertexModel::model_turn(const GenerateResponse& reply) {
if (reply.candidates.empty() || reply.candidates[0].content.parts.empty())
throw GoogleError(502, "EMPTY_RESPONSE", "model returned no content");
Content turn = reply.candidates[0].content;
turn.role = "model";
return turn;
}
void VertexModel::replay(GenerateRequest& request, const Content& model_turn, Content next) {
request.contents.push_back(model_turn);
request.contents.push_back(std::move(next));
}
VertexModel::VertexModel(std::shared_ptr<Gemini> gemini, std::string default_model)
: gemini_(std::move(gemini)), default_model_(std::move(default_model)) {
VertexTarget::require_segment(default_model_, "model");
+23
View File
@@ -13,6 +13,29 @@ namespace molo::google::models {
class VertexModel : public LanguageModel {
public:
// Builds the model turn to replay from a stream of chunks. Gemini 3 rejects
// a replayed functionCall part without the thoughtSignature it was given,
// so every signature is kept: text parts of one kind are merged while they
// carry no signature, a part that has one is never merged into, and a
// signature that arrives on an empty text part is attached to the part
// before it. Non-text parts (calls, data) are kept as received.
class TurnBuilder {
public:
void add(const GenerateResponse& chunk); // first candidate only
const Content& content() const { return turn_; }
bool empty() const { return turn_.parts.empty(); }
std::size_t signatures() const; // parts that carry a thoughtSignature
private:
Content turn_{"model", {}};
};
// The first candidate of a reply as a replayable model turn (signatures
// intact). Throws GoogleError (EMPTY_RESPONSE) when there is none.
static Content model_turn(const GenerateResponse& reply);
// Appends a model turn and the next user content to a request.
static void replay(GenerateRequest& request, const Content& model_turn, Content next);
VertexModel(std::shared_ptr<Gemini> gemini, std::string default_model);
const std::string& default_model() const { return default_model_; }
+99 -18
View File
@@ -14,9 +14,18 @@ spec (package, container, source, env, secret env, scaling, resource limits,
service account or agent identity, build spec, KMS key). Unknown fields stay
raw Json and are sent back unchanged.
Not here: sessions, memories, sandboxes (other modules), A2A endpoints
(`a2a`, `a2aTasks`, owner: adk), `examples` and `feedbackEntries` (v1beta1,
not implemented, see Gaps).
Also (v1beta1, added to close the gap list): the A2A gateway of an engine and
of a runtime revision (agent card, extended card, tasks, push notification
configs, cancel, subscribe, message send and stream, plain and `v1` routes),
`a2aTasks` (create, get, list, delete, appendEvents, events), the A2A task
store (`taskStores/.../a2aTaskRecords` and the store's operations),
`feedbackEntries` (list, get, create, patch, delete, feedback context) and
the operations of runtime revisions, examples, feedback entries and task
stores. Every v1 row also exists in v1beta1 (`AgentRuntime(beta=true)`).
Not here: sessions, memories, sandboxes (other modules). `examples` has no
method of its own in Discovery, only `operations` (get, cancel, wait,
delete), wrapped here.
## 2. Module map
@@ -26,7 +35,10 @@ not implemented, see Gaps).
| `calls.h/.cpp` | The ONE table of REST calls (`kCalls`) and used schema fields (`kSchemas`); `render`, `method_of`, `endpoint_of` |
| `deployment_spec.h/.cpp` | `EngineSpec`, `DeploymentSpec`, `PackageSpec`, `ContainerSpec`, `SourceCodeSpec`, `IdentityType` (validate, to/from Json, updateMask parts) |
| `engine.h/.cpp` | `Engine` (response), `EngineDraft` (create), `EngineUpdate` (patch with derived `updateMask`) |
| `agent_runtime.h/.cpp` | `AgentRuntime : Service`, `Revision` |
| `agent_runtime.h/.cpp` | `AgentRuntime : Service`, `Revision`; `beta` flag selects the v1beta1 twin of every v1 row |
| `operation_calls.h/.cpp` | `OperationCalls`: get, list, cancel, wait (server side), delete for the operations of an engine, revision, example, feedback entry or task store; the name must belong to the scope |
| `feedback.h/.cpp` | `FeedbackEntry`, `RuntimeFeedback`: `feedbackEntries` and the feedback context |
| `a2a.h/.cpp` | `RuntimeA2a`: A2A gateway (`A2aRequest`: target, protocol, op), `a2aTasks`, `a2aTaskRecords`; `A2aTaskInfo` |
| `tools/check_discovery.py` | Fails when any row of the call table or schema table is absent from Google's Discovery documents |
## 3. Static caps
@@ -42,7 +54,11 @@ not implemented, see Gaps).
| query input / execute inputs / policy | 1 MiB serialized |
| classMethod | 1..64 of `[A-Za-z0-9_]` |
| list filter | 512 chars; page size 50, 20 pages max |
| stream events delivered | 5000 (example route: 100) |
| stream events delivered | 5000 (example route: 100); A2A stream 5000 |
| operations: server side wait / list pages | 1..600 s / 5 |
| feedback: text / labels / label chars / context | 4000 / 20 / 64 / 256 KiB |
| A2A: body / historyLength / task id | 1 MiB / 0..1000 / 1..63 of `[a-z0-9-]` on create |
| A2A list pages / items returned | 20 / 2000 |
| updateMask | 512 chars |
| wait for an operation | 600 s / 400 polls (`operation.h`), multi-day work uses `*_start` plus `operation()` |
| ids | `valid_segment`; operation names must start `projects/`, no `..` or `?` |
@@ -67,12 +83,32 @@ not implemented, see Gaps).
`reasoningEngines.query` through a Cloud Run or Workflows target. Nothing
is implemented for it; this is not an API of this part.
- A2A gateway tails are never free text: `(target, protocol, op)` selects the
Discovery rpc and builds the `a2aEndpoint` tail (`card`, `tasks/{id}`,
`v1/message`, ...). `tools/check_discovery.py` compares each tail shape with
the `a2aEndpoint` pattern Discovery declares for that rpc.
- `GET ...:subscribe` answers server-sent events; the foundation only streams
POSTs, so `subscribe()` returns one JSON document or raises `BAD_RESPONSE`.
- Deleting a feedback entry, task, task record or operation record needs
`confirm=true` (library) and is a dry run in the example.
- The project-less forms `aiplatform.reasoningEngines.*` (`/v1/reasoningEngines`
with a `parent` query parameter) are only other URLs of the same RPCs; the
checker requires the same HTTP method and request schema as the covered
`projects.locations` row and counts them as covered.
## 5. Example routes (`/agent/runtime`)
GET `/agent/runtime` (page), `/status`, `/calls` (the call table). POST
`/list`, `/get`, `/create` (starts, answers 202 and the operation name),
`/operation`, `/query`, `/stream`, `/async`, `/delete`. No credential: 503
`google_not_configured`; bad input: 422; oversize body: 413.
`/operation`, `/query`, `/stream`, `/async`, `/delete`, and the extended
routes `/operations` (get, list, cancel, wait, delete for every scope),
`/revisions` (get, list, delete, query, stream), `/update`, `/iam` (get, test,
set), `/code`, `/async/cancel`, `/feedback` (list, get, create, patch, delete,
context, context_update), `/a2a` (gateway: target, protocol, op), `/a2a/tasks`
and `/a2a/records` (create, get, list, delete, append, events). Input is
validated first (422), then a credential is required (503
`google_not_configured`); destructive actions are dry runs unless
`"confirm":true`; oversize body: 413.
## Sources
@@ -89,9 +125,19 @@ GET `/agent/runtime` (page), `/status`, `/calls` (the call table). POST
## Verified against discovery
`python3 -I src/google/runtime/tools/check_discovery.py`, run 2026-10-24:
`discovery ok: 22 calls, 20 schemas, revisions v1 20261012, v1beta1 20261012`.
`discovery ok: 103 calls, 30 schemas, 214 owned discovery methods covered,
revisions v1 20261012, v1beta1 20261012`.
Checks HTTP method, path, rpc id, query parameters, request body fields and
every schema field the code reads or writes. Findings it caught or confirmed:
every schema field the code reads or writes, and three more things:
- twin: every v1 row exists in v1beta1 with the same method, path, rpc id,
query parameters and body fields (`AgentRuntime(beta=true)`);
- a2aEndpoint: the tail the code builds for each of the 40 A2A gateway rows
equals the `a2aEndpoint` pattern Discovery declares for that rpc
(`^card$`, `^v1/tasks/[^/]+$`, `^message$`, ...);
- coverage: every method under `reasoningEngines` and `taskStores` (v1 and
v1beta1) is a row, a twin, a project-less alias of a row (same method and
request schema), or belongs to `sessions`, `memories` or `sandboxEnvironment*`
(other modules, `OTHER_MODULES`). A new Discovery method fails the check. Findings it caught or confirmed:
revision list items key is `reasoningEngineRuntimeRevisions` (not
`runtimeRevisions`), v1 `setIamPolicy` takes only `policy`, secret env uses
`secretRef{secret,version}`.
@@ -109,28 +155,63 @@ read-only (`MOLO_LIVE_NET=1`, test `runtime_live.read_only_calls`):
| `POST .../reasoningEngines/1234567890123:query` | 404 NOT_FOUND |
| `GET .../reasoningEngines/molo-does-not-exist` | 400 INVALID_ARGUMENT (ids are numeric) |
2026-10-24, service account OAuth token (project `lisa-448004`), read-only,
tests `runtime_live_extra.*` through the new classes:
| Call | Result |
|---|---|
| v1 and v1beta1 `reasoningEngines` list (`us-central1`) | 200 `{}` (no `reasoningEngines` key when empty) |
| `GET .../reasoningEngines/{missing}/operations` | 200 `{}` |
| `GET .../operations/1` under a missing engine | 404 "Operation ... not found" |
| `POST ...:getIamPolicy` on a missing engine | 404 "ReasoningEngine ... not found" |
| v1beta1 `runtimeRevisions`, `feedbackEntries`, `a2aTasks` list of a missing engine | 404 "Reasoning Engine [project number: ..., reasoning engine id: ...] is not found" |
| v1beta1 `.../a2a/card` and `.../a2a/v1/card` of a missing engine | 404 "The reasoning engine resource [...] is not found" (both routes exist) |
| v1beta1 `taskStores/{id}/a2aTaskRecords` list | 501 UNIMPLEMENTED "Operation is not implemented, or supported, or enabled." (the task store service is not enabled for the project) |
Everything else (create, patch, delete, streamQuery, asyncQuery, executeCode,
IAM, operations, revisions) is verified by discovery only: no OAuth token is
available and no resource may be created. Rerun:
`MOLO_LIVE_NET=1 GOOGLE_CLOUD_PROJECT=... GOOGLE_API_KEY=... make google-test`.
IAM set, feedback and task writes, revisions delete, operations cancel, wait
and delete, A2A calls that reach a live engine) is verified by discovery only:
no Agent Engine exists in the project and no resource may be created. Rerun:
`MOLO_LIVE_NET=1 GOOGLE_CLOUD_PROJECT=... GOOGLE_ACCESS_TOKEN=... make google-test`.
## Unverified
Settled on 2026-10-24: the v1beta1 `feedbackEntries`, `a2aTasks`, `a2a/...` and
revision routes exist and map a missing engine to 404 (table above); an OAuth
token works for the reads (the express key was only proven for list/get/query).
- Whether the create/patch operation `response` is a `ReasoningEngine` with
`name` (discovery types it as `Any`; `create` fails loudly with 502
`BAD_RESPONSE` if no name is present).
`BAD_RESPONSE` if no name is present). Needs a create; none is allowed. The
Veo operation `response` was seen live (`@type` plus payload fields, see the
models SPEC), so the `Any` convention is real, but the engine one is not seen.
- The streamQuery wire format (discovery: `HttpBody`; decoded as plain JSON
or SSE by the foundation decoder).
or SSE by the foundation decoder). Needs a deployed engine.
- Nested `updateMask` names such as `spec.deploymentSpec` (FieldMask dotted
syntax per docs; not exercised, no write credential).
- That an express key can call any mutating method (list/get/query do work).
- `executeCode` chunk shape (`Chunk`) is passed through as raw Json.
- The A2A gateway answers (agent card, task, message) are the agent's own A2A
JSON and stay raw; none was seen because no engine exists. `message:stream`
is read as SSE/JSON events like `streamQuery`.
- `GET ...:subscribe` is a server-sent-event stream on a GET; the foundation
streams POSTs only, so `subscribe()` was not exercised against a stream.
- `feedbackEntries`/`a2aTasks` create semantics beyond the schema: required
fields, the id Google assigns, ttl format, `generation` handling in
`appendEvents`, and the `view` values of `a2aTasks.get`. Writes are not run.
- The task store (`taskStores/.../a2aTaskRecords`): the service answers 501 in
this project, so nothing about it is seen beyond Discovery.
- The feedback context path `.../feedbackEntries/{id}/feedbackContext` is
taken from the Discovery `name` pattern, not from a live response.
## Gaps
- v1beta1 `examples`, `feedbackEntries` and `a2a*` resources are not typed
here (A2A belongs to adk).
- `trafficConfig`, `revisionGarbageCollectionStrategy` (v1beta1 engine
fields) travel as raw `extra` only on the v1beta1 revision path; the v1
`Engine` does not carry them.
fields) are readable from `Engine::raw` with `AgentRuntime(beta=true)` but
`EngineDraft`/`EngineUpdate` do not write them (owner: `engine.cpp`).
- Responses of the A2A gateway are raw Json (the agent defines them), not
typed structs.
- `:subscribe` (GET server-sent events) needs a streaming GET in the
foundation `GoogleClient` (foundation gap); `RuntimeA2a::subscribe` returns
one JSON document or `BAD_RESPONSE`.
- No OAuth refresh (foundation gap).
+343
View File
@@ -0,0 +1,343 @@
#include "google/runtime/a2a.h"
#include "clients/url.h"
#include "google/errors.h"
#include "google/operation.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
std::string str(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_string() ? v->as_string() : std::string();
}
void check_size(const Json& j, const char* what) {
if (j.dump().size() > A2aCaps::kMaxBodyBytes)
throw GoogleError::invalid(std::string(what) + " over " +
std::to_string(A2aCaps::kMaxBodyBytes) + " bytes");
}
void check_filter(const std::string& filter, const std::string& order_by) {
if (filter.size() > 512) throw GoogleError::invalid("filter over 512 characters");
if (order_by.size() > 128) throw GoogleError::invalid("orderBy over 128 characters");
}
void check_segment(const std::string& id, const char* what) {
if (!valid_segment(id)) throw GoogleError::invalid(std::string("bad ") + what);
}
std::string enc(const std::string& s) { return clients::Url::encode_component(s); }
void set_if(Json& o, const char* key, const std::string& v) {
if (!v.empty()) o.set(key, Json(v));
}
} // namespace
bool A2aRequest::is_get() const {
return op != A2aOp::kTaskCancel && op != A2aOp::kMessageSend && op != A2aOp::kMessageStream;
}
void A2aTaskInfo::validate() const {
if (context_id.size() > 256 || app_id.size() > 256 || user_id.size() > 256 ||
ttl.size() > 32 || expire_time.size() > 64)
throw GoogleError::invalid("task field too long");
if (!metadata.is_null()) {
if (!metadata.is_object()) throw GoogleError::invalid("metadata must be an object");
check_size(metadata, "metadata");
}
}
Json A2aTaskInfo::to_json() const {
validate();
Json o = Json::object();
set_if(o, "contextId", context_id);
set_if(o, "appId", app_id);
set_if(o, "userId", user_id);
set_if(o, "ttl", ttl);
set_if(o, "expireTime", expire_time);
if (metadata.is_object()) o.set("metadata", metadata);
return o;
}
A2aTaskInfo A2aTaskInfo::from_json(const Json& doc) {
A2aTaskInfo t;
t.raw = doc;
t.name = str(doc, "name");
t.context_id = str(doc, "contextId");
t.app_id = str(doc, "appId");
t.user_id = str(doc, "userId");
t.ttl = str(doc, "ttl");
t.expire_time = str(doc, "expireTime");
t.create_time = str(doc, "createTime");
t.update_time = str(doc, "updateTime");
t.generation = str(doc, "generation");
if (const Json* s = doc.is_object() ? doc.find("state") : nullptr; s && s->is_string())
t.state = s->as_string();
else if (const Json* st = doc.is_object() ? doc.find("status") : nullptr; st && st->is_object())
t.state = str(*st, "state");
if (const Json* m = doc.is_object() ? doc.find("metadata") : nullptr; m && m->is_object())
t.metadata = *m;
return t;
}
RuntimeA2a::RuntimeA2a(std::shared_ptr<GoogleClient> client, CloudContext context)
: Service(std::move(client), endpoints::aiplatform_beta(context.location)),
context_(std::move(context)) {}
std::string RuntimeA2a::engine_name(const std::string& engine_id) const {
return context_.child("reasoningEngines", engine_id);
}
std::string RuntimeA2a::store_name(const std::string& store_id) const {
return context_.child("taskStores", store_id);
}
void RuntimeA2a::check_task_id(const std::string& id) {
if (id.empty() || id.size() > A2aCaps::kMaxTaskIdChars)
throw GoogleError::invalid("task id must be 1.." + std::to_string(A2aCaps::kMaxTaskIdChars) +
" characters");
for (std::size_t i = 0; i < id.size(); ++i) {
char c = id[i];
bool alnum = (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9');
if (!(alnum || (i > 0 && c == '-')))
throw GoogleError::invalid("task id must be lowercase letters, digits and hyphens, "
"starting with a letter or digit");
}
}
std::string RuntimeA2a::task_name(const std::string& engine_id, const std::string& task_id) const {
check_segment(task_id, "task id");
return engine_name(engine_id) + "/a2aTasks/" + task_id;
}
std::string RuntimeA2a::record_name(const std::string& store_id,
const std::string& record_id) const {
check_segment(record_id, "record id");
return store_name(store_id) + "/a2aTaskRecords/" + record_id;
}
Json RuntimeA2a::send(Call call, const std::string& target, const std::string& query,
const Json* body) const {
return client_->request(method_of(call), endpoint_of(call, context_.location, true),
render(call, target) + query, body);
}
// --- gateway -----------------------------------------------------------------
Call RuntimeA2a::call_of(A2aTarget target, A2aProtocol protocol, A2aOp op) {
int family = static_cast<int>(target) * 2 + static_cast<int>(protocol);
return static_cast<Call>(static_cast<int>(Call::kA2aEngineCard) + family * 10 +
static_cast<int>(op));
}
std::string RuntimeA2a::tail_of(const A2aRequest& r) {
std::string pre = r.protocol == A2aProtocol::kV1 ? "v1/" : "";
switch (r.op) {
case A2aOp::kCard: return pre + "card";
case A2aOp::kExtendedAgentCard: return pre + "extendedAgentCard";
case A2aOp::kTasks: return pre + "tasks";
case A2aOp::kTaskGet:
case A2aOp::kTaskCancel:
case A2aOp::kTaskSubscribe: return pre + "tasks/" + r.task_id;
case A2aOp::kPushConfigs: return pre + "tasks/" + r.task_id + "/pushNotificationConfigs";
case A2aOp::kPushConfigGet:
return pre + "tasks/" + r.task_id + "/pushNotificationConfigs/" + r.config_id;
case A2aOp::kMessageSend:
case A2aOp::kMessageStream: return pre + "message";
}
throw GoogleError::invalid("unknown A2A op");
}
std::string RuntimeA2a::path_of(const A2aRequest& r) const {
std::string target = engine_name(r.engine_id);
if (r.target == A2aTarget::kRevision) {
check_segment(r.revision_id, "revision id");
target += "/runtimeRevisions/" + r.revision_id;
} else if (!r.revision_id.empty()) {
throw GoogleError::invalid("revision id given for an engine target");
}
bool needs_task = r.op == A2aOp::kTaskGet || r.op == A2aOp::kTaskCancel ||
r.op == A2aOp::kTaskSubscribe || r.op == A2aOp::kPushConfigs ||
r.op == A2aOp::kPushConfigGet;
if (needs_task) check_segment(r.task_id, "task id");
else if (!r.task_id.empty()) throw GoogleError::invalid("task id given for an op without one");
if (r.op == A2aOp::kPushConfigGet) check_segment(r.config_id, "config id");
else if (!r.config_id.empty()) throw GoogleError::invalid("config id given for an op without one");
if (r.history_length < 0 || r.history_length > A2aCaps::kMaxHistoryLength)
throw GoogleError::invalid("historyLength outside 0.." +
std::to_string(A2aCaps::kMaxHistoryLength));
if (r.history_length > 0 && (!r.is_get() || r.op == A2aOp::kTaskSubscribe))
throw GoogleError::invalid("historyLength applies to GET ops without subscribe");
std::string path = render(call_of(r.target, r.protocol, r.op), target, tail_of(r));
if (r.history_length > 0) path += "?historyLength=" + std::to_string(r.history_length);
return path;
}
Json RuntimeA2a::call(const A2aRequest& r) const {
if (r.is_stream() || r.op == A2aOp::kTaskSubscribe)
throw GoogleError::invalid("use stream() or subscribe() for this op");
std::string path = path_of(r);
const Json* body = nullptr;
if (!r.is_get()) {
if (!r.body.is_object()) throw GoogleError::invalid("body must be an object");
check_size(r.body, "body");
body = &r.body;
}
Call c = call_of(r.target, r.protocol, r.op);
return client_->request(method_of(c), endpoint_of(c, context_.location, true), path, body);
}
std::size_t RuntimeA2a::stream(const A2aRequest& r, const GoogleClient::EventSink& sink) const {
if (!r.is_stream()) throw GoogleError::invalid("stream() takes the message stream op");
std::string path = path_of(r);
if (!r.body.is_object()) throw GoogleError::invalid("body must be an object");
check_size(r.body, "body");
Call c = call_of(r.target, r.protocol, r.op);
std::size_t n = 0;
client_->stream_json(endpoint_of(c, context_.location, true), path, r.body,
[&](const Json& e) {
++n;
return sink(e) && n < A2aCaps::kMaxStreamEvents;
});
return n;
}
Json RuntimeA2a::subscribe(const A2aRequest& r) const {
if (r.op != A2aOp::kTaskSubscribe) throw GoogleError::invalid("subscribe() takes the subscribe op");
Call c = call_of(r.target, r.protocol, r.op);
return client_->request(method_of(c), endpoint_of(c, context_.location, true), path_of(r));
}
// --- tasks and records ---------------------------------------------------------
std::vector<A2aTaskInfo> RuntimeA2a::list_items(Call call, const std::string& parent,
const std::string& key,
const std::string& filter,
const std::string& order_by) const {
check_filter(filter, order_by);
std::string path = render(call, parent) + "?pageSize=50";
if (!filter.empty()) path += "&filter=" + enc(filter);
if (!order_by.empty()) path += "&orderBy=" + enc(order_by);
Json items = list_all(*client_, endpoint_of(call, context_.location, true), path, key,
A2aCaps::kMaxListPages);
std::vector<A2aTaskInfo> out;
for (const Json& j : items.as_array()) {
if (out.size() >= A2aCaps::kMaxItemsReturned) break;
out.push_back(A2aTaskInfo::from_json(j));
}
return out;
}
A2aTaskInfo RuntimeA2a::create_task(const std::string& engine_id, const std::string& task_id,
const A2aTaskInfo& task) const {
check_task_id(task_id);
Json body = task.to_json();
return A2aTaskInfo::from_json(send(Call::kA2aTaskCreate, engine_name(engine_id),
"?a2aTaskId=" + enc(task_id), &body));
}
A2aTaskInfo RuntimeA2a::get_task(const std::string& engine_id, const std::string& task_id,
const std::string& view) const {
std::string q;
if (!view.empty()) {
if (view.size() > 64) throw GoogleError::invalid("bad view");
for (char c : view)
if (!((c >= 'A' && c <= 'Z') || c == '_')) throw GoogleError::invalid("bad view");
q = "?view=" + view;
}
return A2aTaskInfo::from_json(send(Call::kA2aTaskGet, task_name(engine_id, task_id), q));
}
std::vector<A2aTaskInfo> RuntimeA2a::list_tasks(const std::string& engine_id,
const std::string& filter,
const std::string& order_by) const {
return list_items(Call::kA2aTaskList, engine_name(engine_id), "a2aTasks", filter, order_by);
}
void RuntimeA2a::delete_task(const std::string& engine_id, const std::string& task_id,
bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting a task needs confirm=true");
send(Call::kA2aTaskDelete, task_name(engine_id, task_id));
}
namespace {
Json append_body(const Json& events, const std::string& generation) {
if (!events.is_array() || events.as_array().empty() || events.as_array().size() > 100)
throw GoogleError::invalid("events must be an array of 1..100 items");
check_size(events, "events");
if (generation.size() > 32) throw GoogleError::invalid("generation too long");
Json body = Json::object();
body.set("events", events);
if (!generation.empty()) body.set("generation", Json(generation));
return body;
}
} // namespace
Json RuntimeA2a::append_task_events(const std::string& engine_id, const std::string& task_id,
const Json& events, const std::string& generation) const {
Json body = append_body(events, generation);
return send(Call::kA2aTaskAppendEvents, task_name(engine_id, task_id), "", &body);
}
Json RuntimeA2a::list_task_events(const std::string& engine_id, const std::string& task_id,
const std::string& filter) const {
check_filter(filter, "");
return send(Call::kA2aTaskEventsList, task_name(engine_id, task_id),
"?pageSize=100" + (filter.empty() ? std::string() : "&filter=" + enc(filter)));
}
A2aTaskInfo RuntimeA2a::create_record(const std::string& store_id, const std::string& record_id,
const A2aTaskInfo& record) const {
std::string q;
if (!record_id.empty()) {
check_segment(record_id, "record id");
q = "?a2aTaskRecordId=" + enc(record_id);
}
Json body = record.to_json();
return A2aTaskInfo::from_json(send(Call::kTaskRecordCreate, store_name(store_id), q, &body));
}
A2aTaskInfo RuntimeA2a::get_record(const std::string& store_id, const std::string& record_id,
const std::string& view) const {
std::string q;
if (!view.empty()) {
if (view.size() > 64) throw GoogleError::invalid("bad view");
for (char c : view)
if (!((c >= 'A' && c <= 'Z') || c == '_')) throw GoogleError::invalid("bad view");
q = "?view=" + view;
}
return A2aTaskInfo::from_json(send(Call::kTaskRecordGet, record_name(store_id, record_id), q));
}
std::vector<A2aTaskInfo> RuntimeA2a::list_records(const std::string& store_id,
const std::string& filter,
const std::string& order_by) const {
return list_items(Call::kTaskRecordList, store_name(store_id), "a2aTaskRecords", filter,
order_by);
}
A2aTaskInfo RuntimeA2a::delete_record(const std::string& store_id, const std::string& record_id,
bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting a task record needs confirm=true");
return A2aTaskInfo::from_json(send(Call::kTaskRecordDelete, record_name(store_id, record_id)));
}
Json RuntimeA2a::append_record_events(const std::string& store_id, const std::string& record_id,
const Json& events, const std::string& generation) const {
Json body = append_body(events, generation);
return send(Call::kTaskRecordAppendEvents, record_name(store_id, record_id), "", &body);
}
Json RuntimeA2a::list_record_events(const std::string& store_id, const std::string& record_id,
const std::string& filter) const {
check_filter(filter, "");
return send(Call::kTaskRecordEventsList, record_name(store_id, record_id),
"?pageSize=100" + (filter.empty() ? std::string() : "&filter=" + enc(filter)));
}
} // namespace molo::google::runtime
+149
View File
@@ -0,0 +1,149 @@
#pragma once
// A2A on Agent Runtime (all v1beta1):
// - the A2A gateway of an engine or runtime revision: agent card, extended
// card, tasks, push notification configs, cancel, subscribe, message send
// and stream. Each (target, protocol, op) is one Discovery rpc; the
// `a2aEndpoint` tail is derived from the op (never free text), so it
// always matches the pattern Discovery declares (checked by
// tools/check_discovery.py).
// - `a2aTasks` of an engine (create, get, list, delete, appendEvents, events)
// - `a2aTaskRecords` of a task store (the same operations on a store)
// Responses of the gateway are the agent's own A2A JSON and stay raw.
#include <memory>
#include <string>
#include <vector>
#include "clients/body/json.h"
#include "google/resource.h"
#include "google/runtime/calls.h"
#include "google/runtime/operation_calls.h"
#include "google/service.h"
namespace molo::google::runtime {
struct A2aCaps {
static constexpr std::size_t kMaxBodyBytes = 1024 * 1024;
static constexpr int kMaxHistoryLength = 1000;
static constexpr std::size_t kMaxStreamEvents = 5000;
static constexpr int kMaxListPages = 20;
static constexpr std::size_t kMaxItemsReturned = 2000;
static constexpr std::size_t kMaxTaskIdChars = 63;
};
enum class A2aTarget { kEngine, kRevision };
enum class A2aProtocol { kPlain, kV1 }; // kV1: routes under .../a2a/v1/...
// Order matches the rows of calls.cpp (see Call::kA2aEngineCard).
enum class A2aOp {
kCard, kExtendedAgentCard, kTasks, kTaskGet, kPushConfigs, kPushConfigGet, kTaskCancel,
kTaskSubscribe, kMessageSend, kMessageStream,
};
struct A2aRequest {
A2aTarget target = A2aTarget::kEngine;
A2aProtocol protocol = A2aProtocol::kPlain;
A2aOp op = A2aOp::kCard;
std::string engine_id;
std::string revision_id; // required when target is kRevision
std::string task_id; // kTaskGet, kPushConfigs, kPushConfigGet, kTaskCancel, kTaskSubscribe
std::string config_id; // kPushConfigGet
int history_length = 0; // GET ops only; 0: not sent
clients::body::Json body = clients::body::Json::object(); // POST ops
bool is_get() const;
bool is_stream() const { return op == A2aOp::kMessageStream; }
};
// An A2A task of an engine (a2aTasks) or of a task store (a2aTaskRecords).
// Output only fields are read, never sent.
struct A2aTaskInfo {
std::string name;
std::string context_id;
std::string app_id;
std::string user_id;
std::string ttl;
std::string expire_time;
std::string state; // output only
std::string create_time;
std::string update_time;
std::string generation;
clients::body::Json metadata; // object or null
clients::body::Json raw;
void validate() const;
clients::body::Json to_json() const;
static A2aTaskInfo from_json(const clients::body::Json& doc);
};
class RuntimeA2a : public Service {
public:
RuntimeA2a(std::shared_ptr<GoogleClient> client, CloudContext context);
// --- gateway ----------------------------------------------------------
static Call call_of(A2aTarget target, A2aProtocol protocol, A2aOp op);
// The `a2aEndpoint` the op's rpc takes, e.g. "v1/tasks/t1".
static std::string tail_of(const A2aRequest& request);
std::string path_of(const A2aRequest& request) const; // validates everything
// Any op except stream and subscribe: one JSON answer.
clients::body::Json call(const A2aRequest& request) const;
// :stream (POST, server-sent events). Returns events delivered (capped).
std::size_t stream(const A2aRequest& request, const GoogleClient::EventSink& sink) const;
// :subscribe is a GET that answers server-sent events; the foundation only
// streams POSTs, so this returns the single JSON document of the reply and
// raises BAD_RESPONSE for an event stream (see SPEC Gaps).
clients::body::Json subscribe(const A2aRequest& request) const;
// --- a2aTasks of an engine ----------------------------------------------
A2aTaskInfo create_task(const std::string& engine_id, const std::string& task_id,
const A2aTaskInfo& task) const;
A2aTaskInfo get_task(const std::string& engine_id, const std::string& task_id,
const std::string& view = "") const;
std::vector<A2aTaskInfo> list_tasks(const std::string& engine_id,
const std::string& filter = "",
const std::string& order_by = "") const;
void delete_task(const std::string& engine_id, const std::string& task_id, bool confirm) const;
// events: array of A2aTaskEvent objects; generation guards concurrent writers.
clients::body::Json append_task_events(const std::string& engine_id, const std::string& task_id,
const clients::body::Json& events,
const std::string& generation = "") const;
clients::body::Json list_task_events(const std::string& engine_id, const std::string& task_id,
const std::string& filter = "") const;
// --- a2aTaskRecords of a task store ---------------------------------------
A2aTaskInfo create_record(const std::string& store_id, const std::string& record_id,
const A2aTaskInfo& record) const;
A2aTaskInfo get_record(const std::string& store_id, const std::string& record_id,
const std::string& view = "") const;
std::vector<A2aTaskInfo> list_records(const std::string& store_id,
const std::string& filter = "",
const std::string& order_by = "") const;
A2aTaskInfo delete_record(const std::string& store_id, const std::string& record_id,
bool confirm) const;
clients::body::Json append_record_events(const std::string& store_id,
const std::string& record_id,
const clients::body::Json& events,
const std::string& generation = "") const;
clients::body::Json list_record_events(const std::string& store_id,
const std::string& record_id,
const std::string& filter = "") const;
// Task ids Google accepts on create: 1..63 of [a-z0-9-], not starting with "-".
static void check_task_id(const std::string& id);
OperationCalls operations() const { return OperationCalls(client_, context_.location, true); }
std::string engine_name(const std::string& engine_id) const;
std::string store_name(const std::string& store_id) const;
private:
clients::body::Json send(Call call, const std::string& target, const std::string& query = "",
const clients::body::Json* body = nullptr) const;
std::vector<A2aTaskInfo> list_items(Call call, const std::string& parent,
const std::string& key, const std::string& filter,
const std::string& order_by) const;
std::string task_name(const std::string& engine_id, const std::string& task_id) const;
std::string record_name(const std::string& store_id, const std::string& record_id) const;
CloudContext context_;
};
} // namespace molo::google::runtime
+21 -9
View File
@@ -54,10 +54,16 @@ Revision Revision::from_json(const Json& doc) {
}
AgentRuntime::AgentRuntime(std::shared_ptr<GoogleClient> client, CloudContext context,
Sleeper sleeper)
: Service(std::move(client), endpoints::aiplatform(context.location)),
Sleeper sleeper, bool beta)
: Service(std::move(client), beta ? endpoints::aiplatform_beta(context.location)
: endpoints::aiplatform(context.location)),
context_(std::move(context)),
sleeper_(std::move(sleeper)) {}
sleeper_(std::move(sleeper)),
beta_(beta) {}
OperationCalls AgentRuntime::operations() const {
return OperationCalls(client_, context_.location, beta_);
}
std::string AgentRuntime::name_of(const std::string& id) const {
return context_.child("reasoningEngines", id);
@@ -78,13 +84,13 @@ std::string AgentRuntime::checked_operation(const std::string& name) {
Json AgentRuntime::send(Call call, const std::string& target, const std::string& query,
const Json* body) const {
std::string path = render(call, target) + query;
return client_->request(method_of(call), endpoint_of(call, context_.location), path, body);
return client_->request(method_of(call), endpoint_of(call, context_.location, beta_), path, body);
}
std::size_t AgentRuntime::stream_call(Call call, const std::string& target, const Json& body,
const GoogleClient::EventSink& sink) const {
std::size_t n = 0;
client_->stream_json(endpoint_of(call, context_.location), render(call, target), body,
client_->stream_json(endpoint_of(call, context_.location, beta_), render(call, target), body,
[&](const Json& event) {
++n;
bool more = sink(event);
@@ -98,7 +104,7 @@ Json AgentRuntime::list_items(Call call, const std::string& parent, const std::s
if (filter.size() > RuntimeCaps::kMaxFilterChars) throw GoogleError::invalid("filter too long");
std::string path = render(call, parent) + "?pageSize=50";
if (!filter.empty()) path += "&filter=" + enc(filter);
return list_all(*client_, endpoint_of(call, context_.location), path, key,
return list_all(*client_, endpoint_of(call, context_.location, beta_), path, key,
RuntimeCaps::kMaxListPages);
}
@@ -286,21 +292,27 @@ std::vector<Revision> AgentRuntime::list_revisions(const std::string& id) const
return out;
}
Operation AgentRuntime::destroy_revision_start(const std::string& id,
const std::string& revision) const {
return Operation::from_json(send(Call::kRevisionDelete, revision_of(id, revision)));
}
Operation AgentRuntime::destroy_revision(const std::string& id, const std::string& revision) const {
return finish(Operation::from_json(send(Call::kRevisionDelete, revision_of(id, revision))));
return finish(destroy_revision_start(id, revision));
}
Json AgentRuntime::query_revision(const std::string& id, const std::string& revision,
const Json& input, const std::string& class_method) const {
Json body = query_body(input, class_method);
return send(Call::kRevisionQuery, revision_of(id, revision), "", &body);
return send(beta_ ? Call::kRevisionQuery : Call::kRevisionQueryV1, revision_of(id, revision), "", &body);
}
std::size_t AgentRuntime::stream_query_revision(const std::string& id, const std::string& revision,
const Json& input,
const GoogleClient::EventSink& sink,
const std::string& class_method) const {
return stream_call(Call::kRevisionStreamQuery, revision_of(id, revision),
return stream_call(beta_ ? Call::kRevisionStreamQuery : Call::kRevisionStreamQueryV1,
revision_of(id, revision),
query_body(input, class_method), sink);
}
+12 -1
View File
@@ -12,6 +12,7 @@
#include <vector>
#include "google/operation.h"
#include "google/runtime/operation_calls.h"
#include "google/resource.h"
#include "google/runtime/calls.h"
#include "google/runtime/engine.h"
@@ -31,10 +32,17 @@ struct Revision {
class AgentRuntime : public Service {
public:
// beta: send the v1beta1 twin of every v1 row (same methods, checked by
// tools/check_discovery.py). v1beta1 engines also carry trafficConfig and
// revisionGarbageCollectionStrategy, which travel as raw Json.
AgentRuntime(std::shared_ptr<GoogleClient> client, CloudContext context,
Sleeper sleeper = nullptr);
Sleeper sleeper = nullptr, bool beta = false);
const CloudContext& context() const { return context_; }
bool beta() const { return beta_; }
// get/list/cancel/wait/delete for the operations of an engine, revision,
// example, feedback entry or task store.
OperationCalls operations() const;
// --- engines (v1) ---------------------------------------------------
Operation create_start(const EngineDraft& draft) const;
@@ -84,6 +92,8 @@ class AgentRuntime : public Service {
Revision get_revision(const std::string& id, const std::string& revision) const;
std::vector<Revision> list_revisions(const std::string& id) const;
Operation destroy_revision(const std::string& id, const std::string& revision) const;
// Starts the delete and returns the Operation without waiting.
Operation destroy_revision_start(const std::string& id, const std::string& revision) const;
clients::body::Json query_revision(const std::string& id, const std::string& revision,
const clients::body::Json& input,
const std::string& class_method = "query") const;
@@ -107,6 +117,7 @@ class AgentRuntime : public Service {
CloudContext context_;
Sleeper sleeper_;
bool beta_;
};
} // namespace molo::google::runtime
+113 -3
View File
@@ -31,6 +31,87 @@ static const CallSpec kCalls[] = {
{Call::kRevisionDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.delete", "", ""},
{Call::kRevisionQuery, "POST", "v1beta1/{+name}:query", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.query", "input,classMethod", ""},
{Call::kRevisionStreamQuery, "POST", "v1beta1/{+name}:streamQuery", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.streamQuery", "input,classMethod", ""},
{Call::kOperationWait, "POST", "v1/{+name}:wait", "v1", "aiplatform.projects.locations.reasoningEngines.operations.wait", "", "timeout"},
{Call::kRevisionQueryV1, "POST", "v1/{+name}:query", "v1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.query", "input,classMethod", ""},
{Call::kRevisionStreamQueryV1, "POST", "v1/{+name}:streamQuery", "v1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.streamQuery", "input,classMethod", ""},
{Call::kRevisionOperationGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.get", "", ""},
{Call::kRevisionOperationList, "GET", "v1beta1/{+name}/operations", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.list", "", "returnPartialSuccess,pageSize,pageToken,filter"},
{Call::kRevisionOperationCancel, "POST", "v1beta1/{+name}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.cancel", "", ""},
{Call::kRevisionOperationWait, "POST", "v1beta1/{+name}:wait", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.wait", "", "timeout"},
{Call::kRevisionOperationDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.operations.delete", "", ""},
{Call::kExampleOperationGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.get", "", ""},
{Call::kExampleOperationCancel, "POST", "v1beta1/{+name}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.cancel", "", ""},
{Call::kExampleOperationWait, "POST", "v1beta1/{+name}:wait", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.wait", "", "timeout"},
{Call::kExampleOperationDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.examples.operations.delete", "", ""},
{Call::kFeedbackList, "GET", "v1beta1/{+parent}/feedbackEntries", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.list", "", "filter,orderBy,pageToken,pageSize"},
{Call::kFeedbackCreate, "POST", "v1beta1/{+parent}/feedbackEntries", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.create", "eventId,source,createTime,sessionId,userId,feedbackType,feedbackText,feedbackLabels,name,updateTime,customMetadata", ""},
{Call::kFeedbackGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.get", "", ""},
{Call::kFeedbackPatch, "PATCH", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.patch", "eventId,source,createTime,sessionId,userId,feedbackType,feedbackText,feedbackLabels,name,updateTime,customMetadata", "updateMask"},
{Call::kFeedbackDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.delete", "", ""},
{Call::kFeedbackUpdateContext, "PATCH", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.updateFeedbackContext", "name,contextEvents", "updateMask"},
{Call::kFeedbackGetContext, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.getFeedbackContext", "", ""},
{Call::kFeedbackOperationGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.get", "", ""},
{Call::kFeedbackOperationList, "GET", "v1beta1/{+name}/operations", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.list", "", "pageSize,returnPartialSuccess,pageToken,filter"},
{Call::kFeedbackOperationCancel, "POST", "v1beta1/{+name}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.cancel", "", ""},
{Call::kFeedbackOperationWait, "POST", "v1beta1/{+name}:wait", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.wait", "", "timeout"},
{Call::kFeedbackOperationDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.feedbackEntries.operations.delete", "", ""},
{Call::kA2aTaskCreate, "POST", "v1beta1/{+parent}/a2aTasks", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.create", "ttl,createTime,state,metadata,updateTime,userId,artifacts,nextEventSequenceNumber,appId,statusDetails,output,contextId,history,expireTime,generation,name,status", "a2aTaskId"},
{Call::kA2aTaskAppendEvents, "POST", "v1beta1/{+name}:appendEvents", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.appendEvents", "generation,taskEvents,events", ""},
{Call::kA2aTaskDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.delete", "", ""},
{Call::kA2aTaskList, "GET", "v1beta1/{+parent}/a2aTasks", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.list", "", "pageSize,filter,orderBy,pageToken"},
{Call::kA2aTaskGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.get", "", "view"},
{Call::kA2aTaskEventsList, "GET", "v1beta1/{+parent}/events", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2aTasks.events.list", "", "pageSize,pageToken,filter,orderBy"},
{Call::kTaskRecordCreate, "POST", "v1beta1/{+parent}/a2aTaskRecords", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.create", "deleteTime,generation,expireTime,appId,userId,artifacts,ttl,name,metadata,updateTime,purgeTime,createTime,contextId,status,serviceMetadata,history", "a2aTaskRecordId"},
{Call::kTaskRecordAppendEvents, "POST", "v1beta1/{+name}:appendEvents", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.appendEvents", "events,generation", ""},
{Call::kTaskRecordDelete, "DELETE", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.delete", "", ""},
{Call::kTaskRecordList, "GET", "v1beta1/{+parent}/a2aTaskRecords", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.list", "", "orderBy,pageToken,filter,pageSize"},
{Call::kTaskRecordGet, "GET", "v1beta1/{+name}", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.get", "", "view"},
{Call::kA2aEngineCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.card", "", "historyLength"},
{Call::kA2aEngineExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.extendedAgentCard", "", "historyLength"},
{Call::kA2aEngineTasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks", "", "historyLength"},
{Call::kA2aEngineTasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineTasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aEngineTasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineTasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.cancel", "", ""},
{Call::kA2aEngineTasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.tasks.subscribe", "", ""},
{Call::kA2aEngineMessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.message.send", "", ""},
{Call::kA2aEngineMessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.message.stream", "", ""},
{Call::kA2aEngineV1Card, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.card", "", "historyLength"},
{Call::kA2aEngineV1ExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.extendedAgentCard", "", "historyLength"},
{Call::kA2aEngineV1Tasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks", "", "historyLength"},
{Call::kA2aEngineV1TasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineV1TasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aEngineV1TasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aEngineV1TasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.cancel", "", ""},
{Call::kA2aEngineV1TasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.tasks.subscribe", "", ""},
{Call::kA2aEngineV1MessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.message.send", "", ""},
{Call::kA2aEngineV1MessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.a2a.v1.message.stream", "", ""},
{Call::kA2aRevisionCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.card", "", "historyLength"},
{Call::kA2aRevisionExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.extendedAgentCard", "", "historyLength"},
{Call::kA2aRevisionTasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks", "", "historyLength"},
{Call::kA2aRevisionTasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionTasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aRevisionTasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionTasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.cancel", "", ""},
{Call::kA2aRevisionTasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.tasks.subscribe", "", ""},
{Call::kA2aRevisionMessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.message.send", "", ""},
{Call::kA2aRevisionMessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.message.stream", "", ""},
{Call::kA2aRevisionV1Card, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.card", "", "historyLength"},
{Call::kA2aRevisionV1ExtendedAgentCard, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.extendedAgentCard", "", "historyLength"},
{Call::kA2aRevisionV1Tasks, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks", "", "historyLength"},
{Call::kA2aRevisionV1TasksGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionV1TasksPushConfigs, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.pushNotificationConfigs", "", "historyLength"},
{Call::kA2aRevisionV1TasksPushConfigsGetEngine, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.pushNotificationConfigs.a2aGetReasoningEngine", "", "historyLength"},
{Call::kA2aRevisionV1TasksCancel, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:cancel", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.cancel", "", ""},
{Call::kA2aRevisionV1TasksSubscribe, "GET", "v1beta1/{+name}/a2a/{+a2aEndpoint}:subscribe", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.tasks.subscribe", "", ""},
{Call::kA2aRevisionV1MessageSend, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:send", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.message.send", "", ""},
{Call::kA2aRevisionV1MessageStream, "POST", "v1beta1/{+name}/a2a/{+a2aEndpoint}:stream", "v1beta1", "aiplatform.projects.locations.reasoningEngines.runtimeRevisions.a2a.v1.message.stream", "", ""},
{Call::kTaskStoreOperationGet, "GET", "v1/{+name}", "v1", "aiplatform.projects.locations.taskStores.operations.get", "", ""},
{Call::kTaskStoreOperationList, "GET", "v1/{+name}/operations", "v1", "aiplatform.projects.locations.taskStores.operations.list", "", "returnPartialSuccess,pageToken,filter,pageSize"},
{Call::kTaskStoreOperationCancel, "POST", "v1/{+name}:cancel", "v1", "aiplatform.projects.locations.taskStores.operations.cancel", "", ""},
{Call::kTaskStoreOperationWait, "POST", "v1/{+name}:wait", "v1", "aiplatform.projects.locations.taskStores.operations.wait", "", "timeout"},
{Call::kTaskStoreOperationDelete, "DELETE", "v1/{+name}", "v1", "aiplatform.projects.locations.taskStores.operations.delete", "", ""},
{Call::kTaskRecordEventsList, "GET", "v1beta1/{+parent}/events", "v1beta1", "aiplatform.projects.locations.taskStores.a2aTaskRecords.events.list", "", "filter,orderBy,pageSize,pageToken"},
};
// CALLS-END
@@ -56,6 +137,16 @@ static const SchemaFields kSchemas[] = {
{"ListReasoningEngineRuntimeRevisionsResponse", "v1beta1", "reasoningEngineRuntimeRevisions,nextPageToken"},
{"ReasoningEngineSpecDeploymentSpec", "v1beta1", "agentServerMode"},
{"ReasoningEngineSpec", "v1beta1", "agentCard"},
{"FeedbackEntry", "v1beta1", "name,eventId,source,createTime,updateTime,sessionId,userId,feedbackType,feedbackText,feedbackLabels,customMetadata"},
{"FeedbackContext", "v1beta1", "name,contextEvents"},
{"ListFeedbackEntriesResponse", "v1beta1", "feedbackEntries,nextPageToken"},
{"A2aTask", "v1beta1", "name,ttl,createTime,state,metadata,updateTime,userId,nextEventSequenceNumber,appId,statusDetails,output,contextId,expireTime,generation,status"},
{"ListA2aTasksResponse", "v1beta1", "a2aTasks,nextPageToken"},
{"ListA2aTaskEventsResponse", "v1beta1", "events,nextPageToken,taskEvents"},
{"AppendA2aTaskEventsResponse", "v1beta1", "generation"},
{"A2ATaskRecord", "v1beta1", "name,ttl,metadata,createTime,updateTime,userId,appId,contextId,status,serviceMetadata,generation,expireTime"},
{"ListA2ATaskRecordsResponse", "v1beta1", "a2aTaskRecords,nextPageToken"},
{"AppendA2ATaskRecordEventsResponse", "v1beta1", "generation"},
};
// SCHEMAS-END
@@ -73,19 +164,38 @@ clients::Method method_of(Call call) {
return clients::Method::kDelete;
}
ServiceEndpoint endpoint_of(Call call, const std::string& location) {
return std::strcmp(spec_of(call).version, "v1beta1") == 0
std::size_t call_count() { return sizeof(kCalls) / sizeof(kCalls[0]); }
const CallSpec& spec_at(std::size_t index) {
if (index >= call_count()) throw GoogleError::invalid("call index out of range");
return kCalls[index];
}
ServiceEndpoint endpoint_of(Call call, const std::string& location, bool beta) {
return beta || std::strcmp(spec_of(call).version, "v1beta1") == 0
? endpoints::aiplatform_beta(location)
: endpoints::aiplatform(location);
}
std::string render(Call call, const std::string& target) {
std::string render(Call call, const std::string& target, const std::string& tail) {
std::string path = spec_of(call).path;
path.erase(0, path.find('/') + 1); // drop the version prefix; the endpoint has it
for (const char* key : {"{+name}", "{+parent}", "{+resource}"}) {
auto at = path.find(key);
if (at != std::string::npos) path.replace(at, std::strlen(key), target);
}
auto at = path.find("{+a2aEndpoint}");
if (at != std::string::npos) {
if (tail.empty() || tail.size() > 256 || tail.find("..") != std::string::npos ||
tail.front() == '/' || tail.back() == '/')
throw GoogleError::invalid("a2a endpoint must be 1..256 characters, no leading or "
"trailing slash, no ..");
for (char c : tail)
if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') ||
c == '.' || c == '_' || c == '-' || c == '/' || c == ':'))
throw GoogleError::invalid("a2a endpoint has invalid characters");
path.replace(at, std::strlen("{+a2aEndpoint}"), tail);
}
return "/" + path;
}
+38 -4
View File
@@ -16,6 +16,34 @@ enum class Call {
kCancelAsyncQuery, kExecuteCode, kGetIamPolicy, kSetIamPolicy, kTestIamPermissions,
kOperationGet, kOperationList, kOperationCancel, kOperationDelete,
kRevisionGet, kRevisionList, kRevisionDelete, kRevisionQuery, kRevisionStreamQuery,
// Rows below were added from Discovery to close the gap list. Families of
// A2A gateway calls: Engine/EngineV1 hang off an engine, Revision/RevisionV1
// off a runtime revision; the V1 forms are `.../a2a/v1/...` routes.
kOperationWait, kRevisionQueryV1, kRevisionStreamQueryV1, kRevisionOperationGet,
kRevisionOperationList, kRevisionOperationCancel, kRevisionOperationWait,
kRevisionOperationDelete, kExampleOperationGet, kExampleOperationCancel,
kExampleOperationWait, kExampleOperationDelete, kFeedbackList, kFeedbackCreate, kFeedbackGet,
kFeedbackPatch, kFeedbackDelete, kFeedbackUpdateContext, kFeedbackGetContext,
kFeedbackOperationGet, kFeedbackOperationList, kFeedbackOperationCancel,
kFeedbackOperationWait, kFeedbackOperationDelete, kA2aTaskCreate, kA2aTaskAppendEvents,
kA2aTaskDelete, kA2aTaskList, kA2aTaskGet, kA2aTaskEventsList, kTaskRecordCreate,
kTaskRecordAppendEvents, kTaskRecordDelete, kTaskRecordList, kTaskRecordGet, kA2aEngineCard,
kA2aEngineExtendedAgentCard, kA2aEngineTasks, kA2aEngineTasksGetEngine,
kA2aEngineTasksPushConfigs, kA2aEngineTasksPushConfigsGetEngine, kA2aEngineTasksCancel,
kA2aEngineTasksSubscribe, kA2aEngineMessageSend, kA2aEngineMessageStream, kA2aEngineV1Card,
kA2aEngineV1ExtendedAgentCard, kA2aEngineV1Tasks, kA2aEngineV1TasksGetEngine,
kA2aEngineV1TasksPushConfigs, kA2aEngineV1TasksPushConfigsGetEngine, kA2aEngineV1TasksCancel,
kA2aEngineV1TasksSubscribe, kA2aEngineV1MessageSend, kA2aEngineV1MessageStream,
kA2aRevisionCard, kA2aRevisionExtendedAgentCard, kA2aRevisionTasks,
kA2aRevisionTasksGetEngine, kA2aRevisionTasksPushConfigs,
kA2aRevisionTasksPushConfigsGetEngine, kA2aRevisionTasksCancel, kA2aRevisionTasksSubscribe,
kA2aRevisionMessageSend, kA2aRevisionMessageStream, kA2aRevisionV1Card,
kA2aRevisionV1ExtendedAgentCard, kA2aRevisionV1Tasks, kA2aRevisionV1TasksGetEngine,
kA2aRevisionV1TasksPushConfigs, kA2aRevisionV1TasksPushConfigsGetEngine,
kA2aRevisionV1TasksCancel, kA2aRevisionV1TasksSubscribe, kA2aRevisionV1MessageSend,
kA2aRevisionV1MessageStream, kTaskStoreOperationGet, kTaskStoreOperationList,
kTaskStoreOperationCancel, kTaskStoreOperationWait, kTaskStoreOperationDelete,
kTaskRecordEventsList,
};
struct CallSpec {
@@ -36,10 +64,16 @@ struct SchemaFields {
const CallSpec& spec_of(Call call);
clients::Method method_of(Call call);
// Endpoint for the call's API version in a location.
ServiceEndpoint endpoint_of(Call call, const std::string& location);
// The table itself, for listing (demo, tests, conformance).
std::size_t call_count();
const CallSpec& spec_at(std::size_t index);
// Endpoint for the call's API version in a location. `beta` selects the
// v1beta1 twin of a v1 row (tools/check_discovery.py verifies every v1 row
// has the same method, path, rpc id and fields in v1beta1).
ServiceEndpoint endpoint_of(Call call, const std::string& location, bool beta = false);
// Path under the endpoint base: "/projects/.../reasoningEngines/x:query".
// `target` replaces the {+name}, {+parent} or {+resource} placeholder.
std::string render(Call call, const std::string& target);
// `target` replaces the {+name}, {+parent} or {+resource} placeholder; `tail`
// replaces {+a2aEndpoint} (validated: segments of [A-Za-z0-9._:-], no "..").
std::string render(Call call, const std::string& target, const std::string& tail = "");
} // namespace molo::google::runtime
+193
View File
@@ -0,0 +1,193 @@
#include "google/runtime/feedback.h"
#include "clients/url.h"
#include "google/errors.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
std::string str(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_string() ? v->as_string() : std::string();
}
void check_field(const std::string& value, const char* what, std::size_t max) {
if (value.size() > max)
throw GoogleError::invalid(std::string(what) + " over " + std::to_string(max) + " characters");
}
void set_if(Json& o, const char* key, const std::string& v) {
if (!v.empty()) o.set(key, Json(v));
}
} // namespace
void FeedbackEntry::validate() const {
check_field(event_id, "eventId", FeedbackCaps::kMaxFieldChars);
check_field(source, "source", FeedbackCaps::kMaxFieldChars);
check_field(session_id, "sessionId", FeedbackCaps::kMaxFieldChars);
check_field(user_id, "userId", FeedbackCaps::kMaxFieldChars);
check_field(feedback_type, "feedbackType", FeedbackCaps::kMaxFieldChars);
check_field(feedback_text, "feedbackText", FeedbackCaps::kMaxTextChars);
if (feedback_labels.size() > FeedbackCaps::kMaxLabels)
throw GoogleError::invalid("more than " + std::to_string(FeedbackCaps::kMaxLabels) +
" feedback labels");
for (const std::string& l : feedback_labels) {
if (l.empty()) throw GoogleError::invalid("empty feedback label");
check_field(l, "feedback label", FeedbackCaps::kMaxLabelChars);
}
if (!custom_metadata.is_null() && !custom_metadata.is_object())
throw GoogleError::invalid("customMetadata must be an object");
if (custom_metadata.is_object() &&
custom_metadata.dump().size() > FeedbackCaps::kMaxContextBytes)
throw GoogleError::invalid("customMetadata too large");
}
Json FeedbackEntry::to_json() const {
validate();
Json o = Json::object();
set_if(o, "eventId", event_id);
set_if(o, "source", source);
set_if(o, "sessionId", session_id);
set_if(o, "userId", user_id);
set_if(o, "feedbackType", feedback_type);
set_if(o, "feedbackText", feedback_text);
if (!feedback_labels.empty()) {
Json arr = Json::array();
for (const std::string& l : feedback_labels) arr.push(Json(l));
o.set("feedbackLabels", arr);
}
if (custom_metadata.is_object()) o.set("customMetadata", custom_metadata);
return o;
}
std::string FeedbackEntry::update_mask() const {
std::string mask;
auto add = [&](bool set, const char* field) {
if (!set) return;
mask += (mask.empty() ? "" : ",") + std::string(field);
};
add(!event_id.empty(), "eventId");
add(!source.empty(), "source");
add(!session_id.empty(), "sessionId");
add(!user_id.empty(), "userId");
add(!feedback_type.empty(), "feedbackType");
add(!feedback_text.empty(), "feedbackText");
add(!feedback_labels.empty(), "feedbackLabels");
add(custom_metadata.is_object(), "customMetadata");
return mask;
}
FeedbackEntry FeedbackEntry::from_json(const Json& doc) {
FeedbackEntry e;
e.name = str(doc, "name");
e.event_id = str(doc, "eventId");
e.source = str(doc, "source");
e.session_id = str(doc, "sessionId");
e.user_id = str(doc, "userId");
e.feedback_type = str(doc, "feedbackType");
e.feedback_text = str(doc, "feedbackText");
e.create_time = str(doc, "createTime");
e.update_time = str(doc, "updateTime");
if (const Json* l = doc.is_object() ? doc.find("feedbackLabels") : nullptr; l && l->is_array())
for (const Json& x : l->as_array())
if (x.is_string()) e.feedback_labels.push_back(x.as_string());
if (const Json* m = doc.is_object() ? doc.find("customMetadata") : nullptr; m && m->is_object())
e.custom_metadata = *m;
return e;
}
RuntimeFeedback::RuntimeFeedback(std::shared_ptr<GoogleClient> client, CloudContext context,
bool beta)
: Service(std::move(client), endpoints::aiplatform_beta(context.location)),
context_(std::move(context)) {
(void)beta; // feedbackEntries exist in v1beta1 only
}
std::string RuntimeFeedback::engine_name(const std::string& engine_id) const {
return context_.child("reasoningEngines", engine_id);
}
std::string RuntimeFeedback::entry_name(const std::string& engine_id,
const std::string& entry_id) const {
if (!valid_segment(entry_id)) throw GoogleError::invalid("bad feedback entry id");
return engine_name(engine_id) + "/feedbackEntries/" + entry_id;
}
Json RuntimeFeedback::send(Call call, const std::string& target, const std::string& query,
const Json* body) const {
return client_->request(method_of(call), endpoint_, render(call, target) + query, body);
}
std::vector<FeedbackEntry> RuntimeFeedback::list(const std::string& engine_id,
const std::string& filter,
const std::string& order_by) const {
if (filter.size() > 512) throw GoogleError::invalid("filter over 512 characters");
if (order_by.size() > 128) throw GoogleError::invalid("orderBy over 128 characters");
std::string parent = engine_name(engine_id);
std::string q = "?pageSize=50";
if (!filter.empty()) q += "&filter=" + clients::Url::encode_component(filter);
if (!order_by.empty()) q += "&orderBy=" + clients::Url::encode_component(order_by);
Json items = list_all(*client_, endpoint_, render(Call::kFeedbackList, parent) + q,
"feedbackEntries", FeedbackCaps::kMaxListPages);
std::vector<FeedbackEntry> out;
for (const Json& j : items.as_array()) {
if (out.size() >= FeedbackCaps::kMaxEntriesReturned) break;
out.push_back(FeedbackEntry::from_json(j));
}
return out;
}
FeedbackEntry RuntimeFeedback::get(const std::string& engine_id,
const std::string& entry_id) const {
return FeedbackEntry::from_json(send(Call::kFeedbackGet, entry_name(engine_id, entry_id)));
}
Operation RuntimeFeedback::create(const std::string& engine_id, const FeedbackEntry& entry) const {
Json body = entry.to_json();
if (body.as_object().empty()) throw GoogleError::invalid("feedback entry has no fields");
return Operation::from_json(send(Call::kFeedbackCreate, engine_name(engine_id), "", &body));
}
Operation RuntimeFeedback::patch(const std::string& engine_id, const std::string& entry_id,
const FeedbackEntry& changes) const {
std::string mask = changes.update_mask();
if (mask.empty()) throw GoogleError::invalid("no feedback fields set to update");
Json body = changes.to_json();
std::string name = entry_name(engine_id, entry_id);
body.set("name", Json(name));
return Operation::from_json(send(Call::kFeedbackPatch, name,
"?updateMask=" + clients::Url::encode_component(mask), &body));
}
Operation RuntimeFeedback::destroy(const std::string& engine_id, const std::string& entry_id,
bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting feedback needs confirm=true");
return Operation::from_json(send(Call::kFeedbackDelete, entry_name(engine_id, entry_id)));
}
Json RuntimeFeedback::get_context(const std::string& engine_id,
const std::string& entry_id) const {
// The context is a child singleton of the entry: .../feedbackEntries/{id}/feedbackContext
return send(Call::kFeedbackGetContext, entry_name(engine_id, entry_id) + "/feedbackContext");
}
Operation RuntimeFeedback::update_context(const std::string& engine_id,
const std::string& entry_id,
const Json& context_events) const {
if (!context_events.is_array() || context_events.as_array().empty())
throw GoogleError::invalid("contextEvents must be a non-empty array");
if (context_events.dump().size() > FeedbackCaps::kMaxContextBytes)
throw GoogleError::invalid("contextEvents too large");
std::string name = entry_name(engine_id, entry_id) + "/feedbackContext";
Json body = Json::object();
body.set("name", Json(name));
body.set("contextEvents", context_events);
return Operation::from_json(send(Call::kFeedbackUpdateContext, name,
"?updateMask=contextEvents", &body));
}
} // namespace molo::google::runtime
+79
View File
@@ -0,0 +1,79 @@
#pragma once
// Feedback on an agent's conversations: the v1beta1 `feedbackEntries`
// resource of an engine and its feedback context. Create, patch, delete and
// context updates are long-running calls: they return the Operation.
#include <memory>
#include <string>
#include <vector>
#include "clients/body/json.h"
#include "google/operation.h"
#include "google/resource.h"
#include "google/runtime/operation_calls.h"
#include "google/service.h"
namespace molo::google::runtime {
struct FeedbackCaps {
static constexpr std::size_t kMaxTextChars = 4000;
static constexpr std::size_t kMaxLabels = 20;
static constexpr std::size_t kMaxLabelChars = 64;
static constexpr std::size_t kMaxFieldChars = 256; // ids, source, type
static constexpr std::size_t kMaxContextBytes = 256 * 1024;
static constexpr int kMaxListPages = 20;
static constexpr std::size_t kMaxEntriesReturned = 2000;
};
struct FeedbackEntry {
std::string name; // .../reasoningEngines/{e}/feedbackEntries/{id}
std::string event_id;
std::string source;
std::string session_id;
std::string user_id;
std::string feedback_type;
std::string feedback_text;
std::vector<std::string> feedback_labels;
clients::body::Json custom_metadata; // object or null
std::string create_time; // output only
std::string update_time; // output only
void validate() const;
// Writable fields only (output only fields are never sent).
clients::body::Json to_json() const;
// updateMask for the fields that are set, e.g. "feedbackText,feedbackLabels".
std::string update_mask() const;
static FeedbackEntry from_json(const clients::body::Json& doc);
};
class RuntimeFeedback : public Service {
public:
RuntimeFeedback(std::shared_ptr<GoogleClient> client, CloudContext context,
bool beta = true);
std::vector<FeedbackEntry> list(const std::string& engine_id, const std::string& filter = "",
const std::string& order_by = "") const;
FeedbackEntry get(const std::string& engine_id, const std::string& entry_id) const;
// entry_id may be empty (Google assigns one).
Operation create(const std::string& engine_id, const FeedbackEntry& entry) const;
Operation patch(const std::string& engine_id, const std::string& entry_id,
const FeedbackEntry& changes) const;
Operation destroy(const std::string& engine_id, const std::string& entry_id,
bool confirm) const;
// Context events are SessionEvent objects, kept as raw Json.
clients::body::Json get_context(const std::string& engine_id, const std::string& entry_id) const;
Operation update_context(const std::string& engine_id, const std::string& entry_id,
const clients::body::Json& context_events) const;
OperationCalls operations() const { return OperationCalls(client_, context_.location, true); }
std::string entry_name(const std::string& engine_id, const std::string& entry_id) const;
std::string engine_name(const std::string& engine_id) const;
private:
clients::body::Json send(Call call, const std::string& target, const std::string& query = "",
const clients::body::Json* body = nullptr) const;
CloudContext context_;
};
} // namespace molo::google::runtime
+139
View File
@@ -0,0 +1,139 @@
#include "google/runtime/operation_calls.h"
#include <cstring>
#include "clients/url.h"
#include "google/errors.h"
namespace molo::google::runtime {
using clients::body::Json;
namespace {
struct Set {
OperationScope scope;
const char* label;
const char* marker;
bool has_list;
Call get, list, cancel, wait, remove;
};
// list is unused for examples (Discovery has no examples.operations.list).
const Set kSets[] = {
{OperationScope::kEngine, "engine", "/reasoningEngines/", true, Call::kOperationGet,
Call::kOperationList, Call::kOperationCancel, Call::kOperationWait, Call::kOperationDelete},
{OperationScope::kRevision, "revision", "/runtimeRevisions/", true,
Call::kRevisionOperationGet, Call::kRevisionOperationList, Call::kRevisionOperationCancel,
Call::kRevisionOperationWait, Call::kRevisionOperationDelete},
{OperationScope::kExample, "example", "/examples/", false, Call::kExampleOperationGet,
Call::kExampleOperationGet, Call::kExampleOperationCancel, Call::kExampleOperationWait,
Call::kExampleOperationDelete},
{OperationScope::kFeedback, "feedback", "/feedbackEntries/", true,
Call::kFeedbackOperationGet, Call::kFeedbackOperationList, Call::kFeedbackOperationCancel,
Call::kFeedbackOperationWait, Call::kFeedbackOperationDelete},
{OperationScope::kTaskStore, "taskStore", "/taskStores/", true,
Call::kTaskStoreOperationGet, Call::kTaskStoreOperationList,
Call::kTaskStoreOperationCancel, Call::kTaskStoreOperationWait,
Call::kTaskStoreOperationDelete},
};
const Set& set_of(OperationScope scope) {
for (const Set& s : kSets)
if (s.scope == scope) return s;
throw GoogleError::invalid("unknown operation scope");
}
} // namespace
OperationCalls::OperationCalls(std::shared_ptr<GoogleClient> client, std::string location,
bool beta)
: client_(std::move(client)), location_(std::move(location)), beta_(beta) {}
OperationScope OperationCalls::scope_from(const std::string& name) {
// Most specific marker first: a revision lives under an engine.
for (OperationScope s : {OperationScope::kFeedback, OperationScope::kRevision,
OperationScope::kExample, OperationScope::kTaskStore,
OperationScope::kEngine})
if (name.find(set_of(s).marker) != std::string::npos) return s;
throw GoogleError::invalid("operation name is not under a runtime resource");
}
const char* OperationCalls::scope_name(OperationScope scope) { return set_of(scope).label; }
bool OperationCalls::has_list(OperationScope scope) { return set_of(scope).has_list; }
const std::string& OperationCalls::check(OperationScope scope, const std::string& name) {
if (name.rfind("projects/", 0) != 0 || name.size() > ScopedOperationCaps::kMaxNameChars ||
name.find("..") != std::string::npos || name.find('?') != std::string::npos ||
name.find('#') != std::string::npos)
throw GoogleError::invalid("bad operation name");
if (name.find(set_of(scope).marker) == std::string::npos ||
scope_from(name) != scope)
throw GoogleError::invalid(std::string("operation name is not under ") + set_of(scope).marker);
return name;
}
Call OperationCalls::call_for(OperationScope scope, const char* verb) {
const Set& s = set_of(scope);
if (!std::strcmp(verb, "get")) return s.get;
if (!std::strcmp(verb, "list")) return s.list;
if (!std::strcmp(verb, "cancel")) return s.cancel;
if (!std::strcmp(verb, "wait")) return s.wait;
if (!std::strcmp(verb, "delete")) return s.remove;
throw GoogleError::invalid("unknown operation verb");
}
Json OperationCalls::send(Call call, const std::string& target, const std::string& query) const {
return client_->request(method_of(call), endpoint_of(call, location_, beta_),
render(call, target) + query, nullptr);
}
Operation OperationCalls::get(OperationScope scope, const std::string& name) const {
return Operation::from_json(send(set_of(scope).get, check(scope, name)));
}
std::vector<Operation> OperationCalls::list(OperationScope scope, const std::string& parent,
const std::string& filter) const {
const Set& s = set_of(scope);
if (!s.has_list) throw GoogleError::invalid(std::string(s.label) + " operations cannot be listed");
if (parent.rfind("projects/", 0) != 0 || parent.size() > ScopedOperationCaps::kMaxNameChars ||
parent.find("..") != std::string::npos || parent.find('?') != std::string::npos ||
parent.find(s.marker) == std::string::npos)
throw GoogleError::invalid("bad parent resource name");
if (filter.size() > 256) throw GoogleError::invalid("filter over 256 characters");
std::vector<Operation> out;
std::string token;
for (int page = 0; page < ScopedOperationCaps::kMaxListPages; ++page) {
std::string q = "?pageSize=50";
if (!filter.empty()) q += "&filter=" + clients::Url::encode_component(filter);
if (!token.empty()) q += "&pageToken=" + clients::Url::encode_component(token);
Json reply = send(s.list, parent, q);
if (const Json* items = reply.find("operations"); items && items->is_array())
for (const Json& j : items->as_array()) out.push_back(Operation::from_json(j));
const Json* next = reply.find("nextPageToken");
if (!next || !next->is_string() || next->as_string().empty()) break;
token = next->as_string();
}
return out;
}
void OperationCalls::cancel(OperationScope scope, const std::string& name) const {
send(set_of(scope).cancel, check(scope, name));
}
Operation OperationCalls::wait(OperationScope scope, const std::string& name,
int timeout_seconds) const {
if (timeout_seconds < 1 || timeout_seconds > ScopedOperationCaps::kMaxWaitSeconds)
throw GoogleError::invalid("timeout outside 1.." +
std::to_string(ScopedOperationCaps::kMaxWaitSeconds) + " seconds");
return Operation::from_json(send(set_of(scope).wait, check(scope, name),
"?timeout=" + std::to_string(timeout_seconds) + "s"));
}
void OperationCalls::remove(OperationScope scope, const std::string& name, bool confirm) const {
if (!confirm) throw GoogleError::invalid("deleting an operation record needs confirm=true");
send(set_of(scope).remove, check(scope, name));
}
} // namespace molo::google::runtime
+63
View File
@@ -0,0 +1,63 @@
#pragma once
// The long-running operation methods that hang off the runtime's resources:
// get, list, cancel, wait, delete, for an engine, a runtime revision, an
// example, a feedback entry and the A2A task store. One class, one table of
// call sets (calls.h rows), one validation rule: the operation name must
// belong to the scope it is used with.
#include <memory>
#include <string>
#include <vector>
#include "google/client.h"
#include "google/operation.h"
#include "google/runtime/calls.h"
namespace molo::google::runtime {
enum class OperationScope { kEngine, kRevision, kExample, kFeedback, kTaskStore };
struct ScopedOperationCaps {
static constexpr int kMaxWaitSeconds = 600; // server side wait, per call
static constexpr int kMaxListPages = 5;
static constexpr std::size_t kMaxNameChars = 512;
};
class OperationCalls {
public:
OperationCalls(std::shared_ptr<GoogleClient> client, std::string location, bool beta);
static OperationScope scope_from(const std::string& name); // throws invalid
static const char* scope_name(OperationScope scope);
static bool has_list(OperationScope scope);
// Throws GoogleError::invalid unless `name` is "projects/..." within
// kMaxNameChars, has no "..", "?" or "#", and contains the scope's marker
// ("/runtimeRevisions/", "/feedbackEntries/", ...).
static const std::string& check(OperationScope scope, const std::string& name);
Operation get(OperationScope scope, const std::string& name) const;
// `parent` is the resource whose operations are listed (engine, revision,
// feedback entry, task store name). Examples have no list method.
std::vector<Operation> list(OperationScope scope, const std::string& parent,
const std::string& filter = "") const;
void cancel(OperationScope scope, const std::string& name) const;
// POST :wait with a server side timeout of 1..kMaxWaitSeconds seconds.
Operation wait(OperationScope scope, const std::string& name, int timeout_seconds) const;
// Removes the operation record only; needs confirm.
void remove(OperationScope scope, const std::string& name, bool confirm) const;
// The table rows used for a scope (conformance tests).
static Call call_for(OperationScope scope, const char* verb);
private:
clients::body::Json send(Call call, const std::string& target,
const std::string& query = "") const;
std::shared_ptr<GoogleClient> client_;
std::string location_;
bool beta_;
};
} // namespace molo::google::runtime
+87 -1
View File
@@ -6,6 +6,19 @@ differs, or a request body field, query parameter or schema field we use is
not in the discovery document. Python 3 stdlib only, no credentials needed.
python3 -I src/google/runtime/tools/check_discovery.py
Besides the rows it checks three more things:
twin every v1 row also exists in v1beta1 with the same HTTP method,
path (v1beta1 prefix), rpc id, query parameters and body fields
(selected in code with AgentRuntime's beta flag);
alias the project-less form `aiplatform.reasoningEngines.X` of a covered
`aiplatform.projects.locations.reasoningEngines.X` has the same
HTTP method and request schema (it is only another URL for the
same RPC, so the row covers it);
coverage every Discovery method under reasoningEngines (and taskStores,
the A2A task record store) is a row, an alias, or belongs to a
resource owned by another module (OTHER_MODULES). A new Discovery
method fails the check until it is wrapped or excluded on purpose.
"""
import json
import os
@@ -16,6 +29,12 @@ import urllib.request
HERE = os.path.dirname(os.path.abspath(__file__))
CALLS = os.path.join(HERE, "..", "calls.cpp")
URL = "https://aiplatform.googleapis.com/$discovery/rest?version=%s"
OWNED = ("aiplatform.projects.locations.reasoningEngines.",
"aiplatform.projects.locations.taskStores.",
"aiplatform.reasoningEngines.")
# sub-resources of reasoningEngines wrapped by other modules (src/google/sessions,
# src/google/sandbox); they are not this module's gaps.
OTHER_MODULES = ("sessions", "memories", "sandboxEnvironment") # incl. Snapshots, Templates
PREFIX = {"v1": "GoogleCloudAiplatformV1", "v1beta1": "GoogleCloudAiplatformV1beta1"}
ROW = re.compile(r'^\s*\{(.*)\},?\s*$')
@@ -83,13 +102,80 @@ def main():
for f in fields.split(","):
if f not in props:
bad.append("schema %s.%s absent" % (name, f))
covered = {(v, rpc) for _, _, v, rpc, _, _ in calls}
# twin: every v1 row exists in v1beta1
for http, path, version, rpc, body, query in calls:
if version != "v1":
continue
m = index["v1beta1"].get(rpc)
if not m:
bad.append("twin: %s absent in v1beta1" % rpc)
continue
covered.add(("v1beta1", rpc))
if m["httpMethod"] != http or m["path"] != path.replace("v1/", "v1beta1/", 1):
bad.append("twin: %s differs in v1beta1 (%s %s)" % (rpc, m["httpMethod"], m["path"]))
params = m.get("parameters", {})
for q in filter(None, query.split(",")):
if q not in params or params[q].get("location") != "query":
bad.append("twin: %s query param %s absent in v1beta1" % (rpc, q))
ref = m.get("request", {}).get("$ref")
props = docs["v1beta1"]["schemas"].get(ref, {}).get("properties", {})
for f in filter(None, body.split(",")):
if f not in props:
bad.append("twin: %s body field %s absent in v1beta1" % (rpc, f))
# a2aEndpoint: the tail the code builds for an op must match Discovery's pattern
shapes = {"card": "card", "extendedAgentCard": "extendedAgentCard", "tasks": "tasks",
"tasks.a2aGetReasoningEngine": "tasks/[^/]+",
"tasks.pushNotificationConfigs": "tasks/[^/]+/pushNotificationConfigs",
"tasks.pushNotificationConfigs.a2aGetReasoningEngine":
"tasks/[^/]+/pushNotificationConfigs/[^/]+",
"tasks.cancel": "tasks/[^/]+", "tasks.subscribe": "tasks/[^/]+",
"message.send": "message", "message.stream": "message"}
a2a_rows = 0
for http, path, version, rpc, body, query in calls:
if "{+a2aEndpoint}" not in path:
continue
a2a_rows += 1
rest = rpc.split("reasoningEngines.", 1)[1].replace("runtimeRevisions.", "", 1)
rest = rest[len("a2a."):]
pre = ""
if rest.startswith("v1."):
pre, rest = "v1/", rest[3:]
want = "^" + pre + shapes.get(rest, "?") + "$"
got = index[version][rpc].get("parameters", {}).get("a2aEndpoint", {}).get("pattern")
if got != want:
bad.append("a2aEndpoint pattern of %s is %s, code builds %s" % (rpc, got, want))
if a2a_rows != 40:
bad.append("expected 40 A2A gateway rows, table has %d" % a2a_rows)
# coverage and alias
owned = 0
for v in ("v1", "v1beta1"):
for rpc, m in index[v].items():
if not rpc.startswith(OWNED):
continue
tail = rpc.split("reasoningEngines.", 1)[-1] if "reasoningEngines." in rpc else rpc
if tail.startswith(OTHER_MODULES):
continue
owned += 1
if (v, rpc) in covered:
continue
if rpc.startswith("aiplatform.reasoningEngines."):
twin = "aiplatform.projects.locations.reasoningEngines." + tail
tm = index[v].get(twin)
if tm and (v, twin) in covered and tm["httpMethod"] == m["httpMethod"] \
and tm.get("request", {}).get("$ref") == m.get("request", {}).get("$ref"):
continue
bad.append("alias %s %s differs from or lacks a covered %s" % (v, rpc, twin))
continue
bad.append("unwrapped discovery method %s %s" % (v, rpc))
revs = {v: docs[v].get("revision") for v in docs}
if bad:
print("DISCOVERY CHECK FAILED (revisions %s)" % revs)
for b in bad:
print(" " + b)
return 1
print("discovery ok: %d calls, %d schemas, revisions %s" % (len(calls), len(schemas), revs))
print("discovery ok: %d calls, %d schemas, %d owned discovery methods covered, revisions %s"
% (len(calls), len(schemas), owned, revs))
return 0