Merge branch 'worktree-agent-a6c7d57da30a90b4f'

This commit is contained in:
2026-10-25 15:24:28 +01:00
35 changed files with 4698 additions and 3 deletions
+177
View File
@@ -0,0 +1,177 @@
# Enterprise APIs - Specification
Owned directory: `src/google/enterprise/`. Namespace `molo::google::enterprise`.
Depends on the `src/google` foundation (`GoogleClient`, `Service`,
`operation.h`). Plans: `plans/16-agent-platform.md`, `plans/18-breadth.md`.
## 1. Scope
Six Google API families, all REST, every call derived from Discovery
documents:
| Family (`Api`) | Host | Discovery document | Rows |
|---|---|---|---|
| Discovery Engine (Gemini Enterprise): search, answer, streamAnswer, converse, assistants (streamAssist), agents, data stores, engines, documents, conversations, sessions, user events, serving configs, ranking (`rank`), grounding (`check`), recommend, schemas, site search, controls, licenses | `discoveryengine.googleapis.com` | `v1`, plus `v1alpha` for `assistants.agents` only | 278 + agents |
| Dialogflow ES (`kDialogflowEs`) | `dialogflow.googleapis.com` | `v2` | 284 |
| Dialogflow CX (`kDialogflowCx`) | `dialogflow.googleapis.com` | `v3` | 158 |
| Retail (`kRetail`): catalogs, products, search, predict, serving configs, user events, models, controls | `retail.googleapis.com` | `v2` | 71 |
| Contact Center Insights (`kInsights`) | `contactcenterinsights.googleapis.com` | `v1` | 188 |
| Customer Engagement Suite (`kCes`) | `ces.googleapis.com` | `v1` | 73 |
| Recommendations AI (`kRecommendations`): the original `recommendationengine` product (predict, catalog items, user events, prediction API key registrations) | `recommendationengine.googleapis.com` | `v1beta1` | 22 |
Total: see `calls_table.inc` (1080 rows on 2026-10-25). "Recommendations AI" is
served by two APIs: Retail's `predict` (the successor) and the legacy
`recommendationengine` API. Both are covered. The IAM Recommender API
(`recommender.googleapis.com`) is a different product and is not here.
Not here: gRPC-only methods (Dialogflow `streamingDetectIntent`, bidi
streams), media upload methods, Discovery Engine v1beta/v1alpha resources other
than `assistants.agents` (alpha-only products such as notebooks, evaluations,
sample queries), Dialogflow ES `v2beta1` and CX `v3beta1`, Retail
`v2alpha`/`v2beta`, CES `v1beta`. They are reachable by adding a row source in
`tools/check_discovery.py` and regenerating.
## 2. Module map
| File | Concern |
|---|---|
| `caps.h` | Static ceilings (`EnterpriseCaps`) |
| `apis.h/.cpp` | `Api`, `ApiInfo`, `endpoint_for` (global and regional hosts), `activation_url` |
| `calls_table.inc` | GENERATED table of every call (one row per line) |
| `calls.h/.cpp` | `CallSpec` (path parameters with Discovery patterns, query, body fields, flags), lookup by `(Api, rpc id)` |
| `caller.h/.cpp` | `Caller`: `prepare` (pure validation + URL), `invoke`, `invoke_destructive`, `invoke_stream`, `list`, `wait`, `operation`; `valid_resource_name` |
| `discovery_engine.h/.cpp` | `DiscoveryEngine`, `DeNames`, `SearchQuery`, `AnswerQuery` |
| `dialogflow.h/.cpp` | `DialogflowEs`, `DialogflowCx`, `text_query_input` |
| `retail.h/.cpp` | `Retail`, `RetailNames`, `RetailSearch`, `Recommendations` |
| `contact_center.h/.cpp` | `Insights`, `Ces` |
| `tools/check_discovery.py` | Regenerates the table from Discovery and fails on any difference |
The typed facades cover the documented core paths. Every other row of the
table is reachable with `Caller::invoke(Invocation{rpc, path, query, body})`;
the demo route `/google/enterprise/call` does exactly that.
## 3. Static caps
| Knob | Value |
|---|---|
| request body (serialized) | 1 MiB |
| resource name / one segment | 512 / 200 chars |
| query value / query parameters | 2048 chars / 20 |
| list: page size / pages / items | 50 / 10 / 500 (truncation reported, never silent) |
| stream events delivered | 2000 (demo route: 100) |
| query or utterance text | 8000 chars (Dialogflow detectIntent text: 256, Google's limit) |
| rank records, grounding facts | 100 each |
| search page size / offset | 1..100 / 0..10000 |
| wait for an operation | 600 s / 400 polls (`operation.h`) |
## 4. Contracts
- Every URL comes from the table. A path parameter must match the regex
Discovery declares for it (when it declares one) and every `+` parameter
must be a valid resource name (segments of `[A-Za-z0-9._~-]`, no empty, `.`
or `..` segment). Unknown path, query or top-level body fields are rejected.
Required query parameters must be present. All of this runs in
`Caller::prepare` before any network traffic: `GoogleError` 400
`INVALID_ARGUMENT`. No credential: `NotConfiguredError` (503).
- Destructive rows (HTTP DELETE, or a method named delete/purge/remove/cancel/
reset/clear/batchDelete, flag `D`) are refused by `invoke`; they run only via
`invoke_destructive(inv, confirm)` and `confirm` has no default and must be
true. Streaming rows (flag `S`) only via `invoke_stream`.
- Location picks the host: from the first `locations/{x}` in a path parameter,
else the caller's default. Discovery Engine: `global`, `us`, `eu`
(`us-discoveryengine.googleapis.com`); Dialogflow: any region
(`{region}-dialogflow.googleapis.com`); CES: `us`, `eu`
(`ces.{loc}.rep.googleapis.com`, from Discovery `endpoints`); Retail,
Insights, Recommendations: the global host serves every location in the path.
- Long-running rows (flag `L`) return the operation; `Caller::wait` polls it
with the capped `wait_operation`.
- The demo (`/google/enterprise`): GET page, `/status`, `/calls`; every route
that calls Google is a POST: `/call`, `/search`, `/answer`, `/rank`,
`/ground`, `/detect`, `/predict`, `/ces/run`. Order: validate (422), require
credential (503 `google_not_configured`), then HTTP GET rows run at once and
every other call is a dry run unless `"confirm":true`. Oversize body: 413.
## 5. Required APIs
Enable these on the project (placeholder project `example-214512124`; one-line `gcloud` command in `src/google/APIS.md` once the owner adds them). A disabled API answers 403 `SERVICE_DISABLED`.
- `discoveryengine.googleapis.com`: https://console.developers.google.com/apis/api/discoveryengine.googleapis.com/overview?project=example-214512124
- `dialogflow.googleapis.com`: https://console.developers.google.com/apis/api/dialogflow.googleapis.com/overview?project=example-214512124
- `retail.googleapis.com`: https://console.developers.google.com/apis/api/retail.googleapis.com/overview?project=example-214512124
- `contactcenterinsights.googleapis.com`: https://console.developers.google.com/apis/api/contactcenterinsights.googleapis.com/overview?project=example-214512124
- `ces.googleapis.com`: https://console.developers.google.com/apis/api/ces.googleapis.com/overview?project=example-214512124
- `recommendationengine.googleapis.com`: https://console.developers.google.com/apis/api/recommendationengine.googleapis.com/overview?project=example-214512124
OAuth scope: `cloud-platform` (every document lists it). Discovery Engine also
accepts narrower scopes (`discoveryengine.readwrite`, ...); not used.
## 6. Sources
- Discovery documents, fetched 2026-10-25: `https://{service}.googleapis.com/$discovery/rest?version={v}` for
discoveryengine v1 (revision 20261022) and v1alpha, dialogflow v2 and v3
(20261018), retail v2 (20261018), contactcenterinsights v1 (20261015), ces v1
(20261023), recommendationengine v1beta1 (20261019).
- Discovery directory `https://discovery.googleapis.com/discovery/v1/apis`
(which versions exist, which are preferred).
- Regional hosts: the Discovery `endpoints` array (CES, Discovery Engine `us`);
Discovery Engine multi-region hosts `us-discoveryengine.googleapis.com` and
`eu-discoveryengine.googleapis.com` and Dialogflow `{region}-dialogflow...`
are from the product location documentation, not from Discovery.
## 7. Verified against discovery
`python3 -I src/google/enterprise/tools/check_discovery.py` (network) or with
`--cache DIR` (files `<service>-<version>.json`). Run 2026-10-25: the
committed `calls_table.inc` equals the table regenerated from Discovery (1080
rows), every rpc id written in the C++ facades is in the table, every document
exposes the `cloud-platform` scope and the expected `rootUrl`, CES regional
endpoints match. Per-document method counts are printed by the script (v1alpha
of Discovery Engine contributes only the `assistants.agents` rows not already in
v1).
## 8. Verified live
Project `lisa-448004`, service-account token, 2026-10-25,
`test_enterprise_live.cpp` (read-only lists and gets): **all six APIs answered
403 "API has not been used / is disabled"**, reported by the test as
`API NOT ENABLED`: discoveryengine (dataStores.list, engines.list),
dialogflow (ES `projects.getAgent`, CX `agents.list`), retail
(`catalogs.list`), recommendationengine (`catalogs.list`),
contactcenterinsights (`conversations.list`), ces (`apps.list`). That proves
the host, path and token were accepted by Google's front end and nothing more:
no success body from any of these APIs has been seen. A human must enable the
APIs (section 5) and rerun `make google-live`.
## 9. Unverified
- Every request and response shape beyond Discovery field names: no success
response from any enterprise API has been seen (APIs not enabled).
- Facade details not in Discovery: the `queryInput.text` shape of
detectIntent, `query.text` of answer, `inputs[].text` of CES `runSession`
follow the schemas' field names but their semantic validity was not
exercised.
- The default resource ids (`default_collection`, `default_search`,
`default_assistant`, `default_ranking_config`, `default_grounding_config`,
`default_catalog`, `default_branch`) come from product documentation.
- `us-` / `eu-` Discovery Engine hosts and regional Dialogflow hosts: from
documentation, not probed.
- Streaming rows (`streamAnswer`, `streamAssist`) go through the foundation's
`stream_json`, which decodes SSE and plain JSON; the actual wire format of
these two was not seen.
- Path parameter patterns are applied with `std::regex` (ECMAScript); a pattern
it cannot compile is skipped (left to Google). None failed to compile in the
test run.
## 10. Gaps
- No success path was ever observed (see 8); enabling the six APIs on the
project closes it.
- Typed facades exist for the core flows only; other rows use the generic
`Caller`. Media upload and gRPC-only methods are out of scope (section 1).
- `Caller::list` caps at 10 pages / 500 items and says so; larger sets need the
`pageToken` loop in the caller's hands.
- Foundation: `GoogleClient` sends no `X-Goog-User-Project` header, so a
service account is billed and quota-checked against its own project.
- Foundation: `stream_json` supports POST only; the A2A `subscribe` GET row
(`assistants.agents.a2a.v1.tasks.subscribe`) therefore answers one JSON
document or fails.
+84
View File
@@ -0,0 +1,84 @@
#include "google/enterprise/apis.h"
#include "google/errors.h"
namespace molo::google::enterprise {
namespace {
// Hosts: discoveryengine.googleapis.com dialogflow.googleapis.com
// retail.googleapis.com contactcenterinsights.googleapis.com
// ces.googleapis.com recommendationengine.googleapis.com
// CES regional (Discovery "endpoints"): ces.us.rep.googleapis.com, ces.eu.rep.googleapis.com
const ApiInfo kApis[] = {
{Api::kDiscoveryEngine, "discoveryengine", "Discovery Engine (Gemini Enterprise)",
"discoveryengine.googleapis.com", "prefix"},
{Api::kDialogflowEs, "dialogflow-es", "Dialogflow ES", "dialogflow.googleapis.com", "prefix"},
{Api::kDialogflowCx, "dialogflow-cx", "Dialogflow CX", "dialogflow.googleapis.com", "prefix"},
{Api::kRetail, "retail", "Retail", "retail.googleapis.com", "none"},
{Api::kInsights, "insights", "Contact Center Insights", "contactcenterinsights.googleapis.com",
"none"},
{Api::kCes, "ces", "Customer Engagement Suite", "ces.googleapis.com", "rep"},
{Api::kRecommendations, "recommendations", "Recommendations AI",
"recommendationengine.googleapis.com", "none"},
};
bool valid_loc(const std::string& l) {
if (l.empty() || l.size() > 32) return false;
for (char c : l)
if (!((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-')) return false;
return true;
}
} // namespace
const ApiInfo& api_info(Api api) {
for (const ApiInfo& i : kApis)
if (i.api == api) return i;
throw GoogleError::invalid("unknown api");
}
const std::vector<Api>& all_apis() {
static const std::vector<Api> v = {Api::kDiscoveryEngine, Api::kDialogflowEs, Api::kDialogflowCx,
Api::kRetail, Api::kInsights, Api::kCes,
Api::kRecommendations};
return v;
}
Api api_from_slug(const std::string& slug) {
for (const ApiInfo& i : kApis)
if (slug == i.slug) return i.api;
throw GoogleError::invalid("unknown api slug");
}
ServiceEndpoint endpoint_for(Api api, const std::string& version, const std::string& location) {
const ApiInfo& i = api_info(api);
if (version.empty() || version.size() > 12) throw GoogleError::invalid("bad version");
std::string host = i.service;
const std::string style = i.regional;
bool global = location.empty() || location == "global";
if (!global) {
if (!valid_loc(location)) throw GoogleError::invalid("bad location");
if (style == "prefix") {
// Discovery Engine serves multi-regions us and eu (us-discoveryengine...);
// Dialogflow serves every region as {region}-dialogflow...
if (api == Api::kDiscoveryEngine && location != "us" && location != "eu")
throw GoogleError::invalid("discoveryengine location must be global, us or eu");
host = location + "-" + host;
} else if (style == "rep") {
if (location != "us" && location != "eu")
throw GoogleError::invalid("ces location must be global, us or eu");
host = std::string("ces.") + location + ".rep.googleapis.com";
}
// style "none": the global host serves every location named in the path.
}
ServiceEndpoint e;
e.name = i.slug;
e.base_url = "https://" + host + "/" + version;
return e;
}
std::string activation_url(Api api, const std::string& project) {
return std::string("https://console.developers.google.com/apis/api/") + api_info(api).service +
"/overview?project=" + project;
}
} // namespace molo::google::enterprise
+42
View File
@@ -0,0 +1,42 @@
#pragma once
// The seven API families of the enterprise package and where each lives.
#include <string>
#include <vector>
#include "google/endpoints.h"
namespace molo::google::enterprise {
enum class Api {
kDiscoveryEngine, // Gemini Enterprise search, answer, assistants, agents
kDialogflowEs, // dialogflow v2
kDialogflowCx, // dialogflow v3
kRetail, // retail v2
kInsights, // Contact Center Insights v1
kCes, // Customer Engagement Suite v1
kRecommendations, // Recommendations AI (recommendationengine v1beta1)
};
struct ApiInfo {
Api api;
const char* slug; // "discoveryengine"
const char* title; // "Discovery Engine (Gemini Enterprise)"
const char* service; // "discoveryengine.googleapis.com"
const char* regional; // "none", "prefix" ("us-host"), "rep" ("svc.us.rep.host")
};
const ApiInfo& api_info(Api api);
const std::vector<Api>& all_apis();
// Throws GoogleError(invalid) for an unknown slug.
Api api_from_slug(const std::string& slug);
// Base URL for a version and a location. "global" (or empty) is the global
// host. Multi-region/region names are validated; an unsupported one throws.
ServiceEndpoint endpoint_for(Api api, const std::string& version, const std::string& location);
// The activation page for the API on a project.
std::string activation_url(Api api, const std::string& project);
} // namespace molo::google::enterprise
+215
View File
@@ -0,0 +1,215 @@
#include "google/enterprise/caller.h"
#include <regex>
#include "clients/url.h"
#include "google/enterprise/caps.h"
#include "google/errors.h"
namespace molo::google::enterprise {
using clients::body::Json;
namespace {
bool seg_char(char c) {
return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '.' ||
c == '_' || c == '~' || c == '-';
}
bool valid_segment_text(const std::string& s) {
if (s.empty() || s.size() > EnterpriseCaps::kMaxSegmentChars) return false;
if (s == "." || s == "..") return false;
for (char c : s)
if (!seg_char(c)) return false;
return true;
}
[[noreturn]] void bad(const std::string& m) { throw GoogleError::invalid(m); }
std::string enc(const std::string& s) { return clients::Url::encode_component(s); }
} // namespace
bool valid_resource_name(const std::string& name) {
if (name.empty() || name.size() > EnterpriseCaps::kMaxResourceChars) return false;
std::size_t start = 0;
while (true) {
std::size_t slash = name.find('/', start);
std::string seg = name.substr(start, slash == std::string::npos ? std::string::npos : slash - start);
if (!valid_segment_text(seg)) return false;
if (slash == std::string::npos) return true;
start = slash + 1;
}
}
Caller::Caller(std::shared_ptr<GoogleClient> client, Api api, std::string default_location,
Sleeper sleeper)
: Service(std::move(client), endpoint_for(api, "v1", "global")),
api_(api),
location_(std::move(default_location)),
sleeper_(std::move(sleeper)) {}
std::string Caller::location_of(const Invocation& inv) const {
for (const auto& kv : inv.path) {
std::size_t p = kv.second.find("locations/");
if (p == std::string::npos || (p != 0 && kv.second[p - 1] != '/')) continue;
std::size_t s = p + 10;
std::size_t e = kv.second.find('/', s);
return kv.second.substr(s, e == std::string::npos ? std::string::npos : e - s);
}
return location_;
}
Prepared Caller::prepare(const Invocation& inv) const {
const CallSpec& spec = find_call(api_, inv.rpc);
Prepared out;
out.spec = &spec;
// Path.
std::string path = spec.path;
std::size_t slash = path.find('/');
path = path.substr(slash); // drop the version prefix
std::size_t used = 0;
for (const auto& p : spec.path_params()) {
auto it = inv.path.find(p.name);
if (it == inv.path.end()) bad("missing path parameter " + p.name);
++used;
const std::string& v = it->second;
if (p.plus) {
if (!valid_resource_name(v)) bad("bad resource name for " + p.name);
} else if (!valid_segment_text(v)) {
bad("bad id for " + p.name);
}
if (!p.pattern.empty()) {
bool ok = false;
try {
ok = std::regex_match(v, std::regex(p.pattern.substr(p.pattern.front() == '^' ? 1 : 0,
p.pattern.size() -
(p.pattern.front() == '^' ? 1 : 0) -
(p.pattern.back() == '$' ? 1 : 0))));
} catch (const std::regex_error&) {
ok = true; // a pattern std::regex cannot compile is left to Google
}
if (!ok) bad(p.name + " does not match " + p.pattern);
}
std::string token = std::string("{") + (p.plus ? "+" : "") + p.name + "}";
std::size_t at = path.find(token);
path.replace(at, token.size(), v); // segments are already URL safe
}
if (used != inv.path.size()) bad("unexpected path parameter");
// Query.
std::vector<std::string> allowed = spec.query_params();
if (inv.query.size() > EnterpriseCaps::kMaxQueryParams) bad("too many query parameters");
std::string qs;
for (const auto& kv : inv.query) {
bool known = false;
for (const auto& a : allowed) known = known || a == kv.first;
if (!known) bad("unknown query parameter " + kv.first);
if (kv.second.size() > EnterpriseCaps::kMaxQueryValueChars) bad("query value too long");
for (unsigned char c : kv.second)
if (c < 0x20) bad("control character in query value");
qs += (qs.empty() ? "?" : "&") + kv.first + "=" + enc(kv.second);
}
for (const auto& r : spec.required_query())
if (!inv.query.count(r)) bad("missing query parameter " + r);
out.path = path + qs;
// Body.
if (std::string(spec.request).empty()) {
if (!inv.body.is_null()) bad("this call takes no body");
} else {
out.has_body = true;
out.body = inv.body.is_null() ? Json::object() : inv.body;
if (!out.body.is_object()) bad("body must be a JSON object");
std::vector<std::string> fields = spec.body_field_list();
for (const auto& kv : out.body.as_object()) {
bool known = false;
for (const auto& f : fields) known = known || f == kv.first;
if (!known) bad("unknown body field " + kv.first);
}
if (out.body.dump().size() > EnterpriseCaps::kMaxBodyBytes) bad("body too large");
}
out.endpoint = endpoint_for(api_, spec.version, location_of(inv));
return out;
}
Json Caller::invoke(const Invocation& inv) const {
Prepared p = prepare(inv);
if (p.spec->destructive()) bad("destructive call: use invoke_destructive");
if (p.spec->streaming()) bad("streaming call: use invoke_stream");
return client_->request(p.spec->method(), p.endpoint, p.path, p.has_body ? &p.body : nullptr);
}
Json Caller::invoke_destructive(const Invocation& inv, bool confirm) const {
Prepared p = prepare(inv);
if (!p.spec->destructive()) bad("not a destructive call: use invoke");
if (!confirm) bad("destructive call needs confirm=true");
return client_->request(p.spec->method(), p.endpoint, p.path, p.has_body ? &p.body : nullptr);
}
std::size_t Caller::invoke_stream(const Invocation& inv, const GoogleClient::EventSink& sink) const {
Prepared p = prepare(inv);
if (!p.spec->streaming()) bad("not a streaming call");
std::size_t n = 0;
client_->stream_json(p.endpoint, p.path, p.has_body ? p.body : Json::object(),
[&](const Json& ev) {
++n;
return sink(ev) && n < EnterpriseCaps::kMaxStreamEvents;
});
return n;
}
ListResult Caller::list(const Invocation& inv) const {
const CallSpec& spec = find_call(api_, inv.rpc);
if (!spec.paginated()) bad("not a paginated call");
ListResult out;
Invocation page = inv;
bool sized = false;
for (const auto& q : spec.query_params()) sized = sized || q == "pageSize";
if (sized && !page.query.count("pageSize"))
page.query["pageSize"] = std::to_string(EnterpriseCaps::kPageSize);
for (int i = 0; i < EnterpriseCaps::kMaxListPages; ++i) {
Prepared p = prepare(page);
Json doc = client_->request(p.spec->method(), p.endpoint, p.path, p.has_body ? &p.body : nullptr);
++out.pages;
out.next_page_token.clear();
if (doc.is_object()) {
if (const Json* arr = doc.find(spec.items_key); arr && arr->is_array())
for (const Json& item : arr->as_array()) {
if (out.size() >= EnterpriseCaps::kMaxListItems) {
out.truncated = true;
return out;
}
out.items.push(item);
}
if (const Json* t = doc.find("nextPageToken"); t && t->is_string())
out.next_page_token = t->as_string();
}
if (out.next_page_token.empty()) return out;
page.query["pageToken"] = out.next_page_token;
}
out.truncated = !out.next_page_token.empty();
return out;
}
void Caller::check_operation_name(const std::string& name) {
if (name.rfind("projects/", 0) != 0 || !valid_resource_name(name) ||
name.find("/operations/") == std::string::npos)
bad("bad operation name");
}
Operation Caller::operation(const std::string& name, const std::string& version,
const std::string& location) const {
check_operation_name(name);
return Operation::from_json(
client_->get_json(endpoint_for(api_, version, location.empty() ? location_ : location), "/" + name));
}
Operation Caller::wait(const std::string& name, const std::string& version,
const std::string& location) const {
check_operation_name(name);
return wait_operation(*client_, endpoint_for(api_, version, location.empty() ? location_ : location),
name, sleeper_);
}
} // namespace molo::google::enterprise
+82
View File
@@ -0,0 +1,82 @@
#pragma once
// Caller: validates and sends any call of the table for one API family.
// Every typed facade (discovery_engine.h, dialogflow.h, ...) is a thin layer
// over it. Validation runs before any network traffic and fails with
// GoogleError 400 INVALID_ARGUMENT; no credential: NotConfiguredError.
#include <functional>
#include <map>
#include <memory>
#include <string>
#include "clients/body/json.h"
#include "google/enterprise/calls.h"
#include "google/operation.h"
#include "google/service.h"
namespace molo::google::enterprise {
struct Invocation {
std::string rpc; // Discovery method id from the table
std::map<std::string, std::string> path; // placeholder name -> value
std::map<std::string, std::string> query; // query parameter -> value
clients::body::Json body; // null: no body
};
struct Prepared {
const CallSpec* spec = nullptr;
ServiceEndpoint endpoint;
std::string path; // after the version, with the query string
clients::body::Json body;
bool has_body = false;
std::string url() const { return endpoint.base_url + path; }
};
struct ListResult {
clients::body::Json items = clients::body::Json::array();
int pages = 0;
bool truncated = false; // more existed past the page or item cap
std::string next_page_token;
std::size_t size() const { return items.as_array().size(); }
};
class Caller : public Service {
public:
Caller(std::shared_ptr<GoogleClient> client, Api api, std::string default_location = "global",
Sleeper sleeper = nullptr);
Api api() const { return api_; }
const std::string& default_location() const { return location_; }
// Pure: validates and builds the request, no network, no credential needed.
Prepared prepare(const Invocation& inv) const;
// Not for destructive rows (those throw invalid; use invoke_destructive).
clients::body::Json invoke(const Invocation& inv) const;
// Destructive rows only; confirm has no default and must be true.
clients::body::Json invoke_destructive(const Invocation& inv, bool confirm) const;
// Rows flagged S. Returns the events delivered (capped).
std::size_t invoke_stream(const Invocation& inv, const GoogleClient::EventSink& sink) const;
// Rows flagged P: follows nextPageToken up to the caps, reports truncation.
ListResult list(const Invocation& inv) const;
// Polls an operation name returned by a row flagged L (capped wait).
Operation wait(const std::string& operation_name, const std::string& version,
const std::string& location = "") const;
// One poll of an operation.
Operation operation(const std::string& operation_name, const std::string& version,
const std::string& location = "") const;
private:
std::string location_of(const Invocation& inv) const;
static void check_operation_name(const std::string& name);
Api api_;
std::string location_;
Sleeper sleeper_;
};
// A resource name check shared by every facade: 1..512 chars, segments of
// [A-Za-z0-9._~-], no empty segment, no "." or ".." segment.
bool valid_resource_name(const std::string& name);
} // namespace molo::google::enterprise
+134
View File
@@ -0,0 +1,134 @@
#include "google/enterprise/calls.h"
#include <map>
#include <string>
#include "google/errors.h"
namespace molo::google::enterprise {
namespace {
const CallSpec kCalls[] = {
#include "google/enterprise/calls_table.inc"
};
std::vector<std::string> split(const std::string& s, char sep) {
std::vector<std::string> out;
std::string cur;
for (char c : s) {
if (c == sep) {
if (!cur.empty()) out.push_back(cur);
cur.clear();
} else {
cur += c;
}
}
if (!cur.empty()) out.push_back(cur);
return out;
}
bool has_flag(const CallSpec& c, char f) {
for (const char* p = c.flags; *p; ++p)
if (*p == f) return true;
return false;
}
using Index = std::map<std::pair<int, std::string>, const CallSpec*>;
const Index& index() {
static const Index idx = [] {
Index m;
for (const CallSpec& c : kCalls) m[{static_cast<int>(c.api), c.rpc_id}] = &c;
return m;
}();
return idx;
}
} // namespace
bool CallSpec::destructive() const { return has_flag(*this, 'D'); }
bool CallSpec::long_running() const { return has_flag(*this, 'L'); }
bool CallSpec::streaming() const { return has_flag(*this, 'S'); }
bool CallSpec::paginated() const { return has_flag(*this, 'P'); }
bool CallSpec::read_only() const { return std::string(http_method) == "GET"; }
clients::Method CallSpec::method() const {
std::string m = http_method;
if (m == "GET") return clients::Method::kGet;
if (m == "POST") return clients::Method::kPost;
if (m == "PATCH") return clients::Method::kPatch;
if (m == "DELETE") return clients::Method::kDelete;
throw GoogleError::invalid("unsupported http method " + m);
}
std::vector<CallSpec::Param> CallSpec::path_params() const {
std::map<std::string, std::string> patterns;
for (const std::string& item : split(params, ' ')) {
auto eq = item.find('=');
patterns[item.substr(0, eq)] = eq == std::string::npos ? "" : item.substr(eq + 1);
}
std::vector<Param> out;
std::string p = path;
for (std::size_t i = 0; i < p.size(); ++i) {
if (p[i] != '{') continue;
std::size_t end = p.find('}', i);
if (end == std::string::npos) break;
std::string name = p.substr(i + 1, end - i - 1);
bool plus = !name.empty() && name[0] == '+';
if (plus) name.erase(0, 1);
out.push_back({name, patterns[name], plus});
i = end;
}
return out;
}
std::vector<std::string> CallSpec::query_params() const {
std::vector<std::string> out;
for (std::string q : split(query, ',')) {
if (!q.empty() && q.back() == '!') q.pop_back();
out.push_back(q);
}
return out;
}
std::vector<std::string> CallSpec::required_query() const {
std::vector<std::string> out;
for (const std::string& q : split(query, ','))
if (!q.empty() && q.back() == '!') out.push_back(q.substr(0, q.size() - 1));
return out;
}
std::vector<std::string> CallSpec::body_field_list() const { return split(body_fields, ','); }
std::size_t call_count() { return sizeof(kCalls) / sizeof(kCalls[0]); }
const CallSpec& call_at(std::size_t i) { return kCalls[i]; }
const CallSpec* try_find_call(Api api, const std::string& rpc_id) {
auto it = index().find({static_cast<int>(api), rpc_id});
return it == index().end() ? nullptr : it->second;
}
const CallSpec& find_call(Api api, const std::string& rpc_id) {
const CallSpec* c = try_find_call(api, rpc_id);
if (!c) throw GoogleError::invalid("unknown rpc id for " + std::string(api_info(api).slug));
return *c;
}
std::vector<const CallSpec*> calls_of(Api api) {
std::vector<const CallSpec*> out;
for (const CallSpec& c : kCalls)
if (c.api == api) out.push_back(&c);
return out;
}
std::vector<const CallSpec*> search_calls(Api api, const std::string& needle, std::size_t limit) {
std::vector<const CallSpec*> out;
for (const CallSpec& c : kCalls) {
if (c.api != api) continue;
if (needle.empty() || std::string(c.rpc_id).find(needle) != std::string::npos) {
out.push_back(&c);
if (out.size() >= limit) break;
}
}
return out;
}
} // namespace molo::google::enterprise
+56
View File
@@ -0,0 +1,56 @@
#pragma once
// The ONE table of REST calls of the enterprise package, generated from
// Google's Discovery documents (calls_table.inc, checked by
// tools/check_discovery.py). Code never builds a URL from a literal.
#include <cstddef>
#include <string>
#include <vector>
#include "clients/request.h"
#include "google/enterprise/apis.h"
namespace molo::google::enterprise {
struct CallSpec {
Api api;
const char* version; // "v1", "v1alpha", "v2", "v3", "v2", "v1beta1"
const char* rpc_id; // Discovery method id
const char* http_method; // GET POST PATCH DELETE
const char* path; // Discovery path, e.g. "v1/{+name}:purge"
const char* params; // "name=pattern" items separated by one space
const char* query; // comma list, "!" suffix = required
const char* body_fields; // comma list of top-level request fields
const char* request; // request schema name ("" = no body)
const char* flags; // D destructive, L long-running, S stream, P paginated
const char* items_key; // list response array property (P only)
bool destructive() const;
bool long_running() const;
bool streaming() const;
bool paginated() const;
bool read_only() const; // GET
clients::Method method() const;
// Name of a placeholder -> its regex pattern, in path order.
struct Param {
std::string name;
std::string pattern;
bool plus; // {+name}: may contain slashes
};
std::vector<Param> path_params() const;
std::vector<std::string> query_params() const; // names, without "!"
std::vector<std::string> required_query() const;
std::vector<std::string> body_field_list() const;
};
std::size_t call_count();
const CallSpec& call_at(std::size_t index);
// Throws GoogleError(invalid) for an rpc id the table does not hold.
const CallSpec& find_call(Api api, const std::string& rpc_id);
const CallSpec* try_find_call(Api api, const std::string& rpc_id);
std::vector<const CallSpec*> calls_of(Api api);
// Calls whose rpc id contains `needle` (case sensitive), capped at `limit`.
std::vector<const CallSpec*> search_calls(Api api, const std::string& needle, std::size_t limit);
} // namespace molo::google::enterprise
File diff suppressed because it is too large Load Diff
+23
View File
@@ -0,0 +1,23 @@
#pragma once
// Static ceilings for the enterprise package. Never autotuned.
#include <cstddef>
namespace molo::google::enterprise {
struct EnterpriseCaps {
static constexpr std::size_t kMaxBodyBytes = 1024 * 1024; // serialized request body
static constexpr std::size_t kMaxResourceChars = 512; // a resource name
static constexpr std::size_t kMaxSegmentChars = 200; // one name segment
static constexpr std::size_t kMaxQueryValueChars = 2048; // one query value
static constexpr std::size_t kMaxQueryParams = 20;
static constexpr int kPageSize = 50;
static constexpr int kMaxListPages = 10; // 500 items per list
static constexpr std::size_t kMaxListItems = 500;
static constexpr std::size_t kMaxStreamEvents = 2000;
static constexpr std::size_t kMaxTextChars = 8000; // query / utterance text
static constexpr std::size_t kMaxDocuments = 100; // rank records, grounding facts
};
} // namespace molo::google::enterprise
+115
View File
@@ -0,0 +1,115 @@
#include "google/enterprise/contact_center.h"
#include "google/enterprise/caps.h"
#include "google/errors.h"
namespace molo::google::enterprise {
using clients::body::Json;
namespace {
[[noreturn]] void bad(const std::string& m) { throw GoogleError::invalid(m); }
Invocation make(const char* rpc, const char* key, const std::string& name) {
Invocation i;
i.rpc = rpc;
i.path[key] = name;
return i;
}
void check_id(const std::string& id, const char* what) {
if (!valid_resource_name(id) || id.find('/') != std::string::npos) bad(std::string("bad ") + what);
}
} // namespace
Insights::Insights(std::shared_ptr<GoogleClient> client, std::string location, Sleeper sleeper)
: caller_(std::move(client), Api::kInsights, std::move(location), std::move(sleeper)) {}
std::string Insights::location_name(const std::string& project, const std::string& location) {
check_id(project, "project");
check_id(location, "location");
return "projects/" + project + "/locations/" + location;
}
ListResult Insights::list_conversations(const std::string& p, const std::string& filter) const {
Invocation i = make("contactcenterinsights.projects.locations.conversations.list", "parent", p);
if (!filter.empty()) i.query["filter"] = filter;
return caller_.list(i);
}
Json Insights::get_conversation(const std::string& n) const {
return caller_.invoke(make("contactcenterinsights.projects.locations.conversations.get", "name", n));
}
Json Insights::calculate_stats(const std::string& p, const std::string& filter) const {
Invocation i = make("contactcenterinsights.projects.locations.conversations.calculateStats", "location", p);
if (!filter.empty()) i.query["filter"] = filter;
return caller_.invoke(i);
}
Json Insights::list_issue_models(const std::string& p) const {
return caller_.invoke(make("contactcenterinsights.projects.locations.issueModels.list", "parent", p));
}
ListResult Insights::list_phrase_matchers(const std::string& p) const {
return caller_.list(make("contactcenterinsights.projects.locations.phraseMatchers.list", "parent", p));
}
ListResult Insights::list_analysis_rules(const std::string& p) const {
return caller_.list(make("contactcenterinsights.projects.locations.analysisRules.list", "parent", p));
}
ListResult Insights::list_views(const std::string& p) const {
return caller_.list(make("contactcenterinsights.projects.locations.views.list", "parent", p));
}
Json Insights::analyze(const std::string& conversation) const {
return caller_.invoke(make("contactcenterinsights.projects.locations.conversations.analyses.create", "parent",
conversation));
}
Ces::Ces(std::shared_ptr<GoogleClient> client, std::string location, Sleeper sleeper)
: caller_(std::move(client), Api::kCes, std::move(location), std::move(sleeper)) {}
std::string Ces::session_name(const std::string& project, const std::string& location,
const std::string& app, const std::string& id) {
check_id(project, "project");
check_id(location, "location");
check_id(app, "app id");
check_id(id, "session id");
return "projects/" + project + "/locations/" + location + "/apps/" + app + "/sessions/" + id;
}
Invocation Ces::run_session_invocation(const std::string& session, const std::string& text) {
if (text.empty() || text.size() > EnterpriseCaps::kMaxTextChars) bad("text is empty or too long");
Invocation i = make("ces.projects.locations.apps.sessions.runSession", "session", session);
Json t = Json::object();
t.set("text", Json(text));
Json input = Json::object();
input.set("text", Json(text));
Json inputs = Json::array();
inputs.push(input);
Json b = Json::object();
b.set("inputs", inputs);
i.body = b;
return i;
}
ListResult Ces::list_apps(const std::string& p) const {
return caller_.list(make("ces.projects.locations.apps.list", "parent", p));
}
Json Ces::get_app(const std::string& n) const {
return caller_.invoke(make("ces.projects.locations.apps.get", "name", n));
}
ListResult Ces::list_agents(const std::string& a) const {
return caller_.list(make("ces.projects.locations.apps.agents.list", "parent", a));
}
ListResult Ces::list_tools(const std::string& a) const {
return caller_.list(make("ces.projects.locations.apps.tools.list", "parent", a));
}
ListResult Ces::list_examples(const std::string& a) const {
return caller_.list(make("ces.projects.locations.apps.examples.list", "parent", a));
}
ListResult Ces::list_guardrails(const std::string& a) const {
return caller_.list(make("ces.projects.locations.apps.guardrails.list", "parent", a));
}
ListResult Ces::list_conversations(const std::string& a) const {
return caller_.list(make("ces.projects.locations.apps.conversations.list", "parent", a));
}
Json Ces::run_session(const std::string& s, const std::string& t) const {
return caller_.invoke(run_session_invocation(s, t));
}
} // namespace molo::google::enterprise
+60
View File
@@ -0,0 +1,60 @@
#pragma once
// Contact Center Insights (v1) and Customer Engagement Suite (CES, v1).
#include <memory>
#include <string>
#include "google/enterprise/caller.h"
namespace molo::google::enterprise {
class Insights {
public:
Insights(std::shared_ptr<GoogleClient> client, std::string location = "us-central1",
Sleeper sleeper = nullptr);
Caller& caller() { return caller_; }
const Caller& caller() const { return caller_; }
static std::string location_name(const std::string& project, const std::string& location);
ListResult list_conversations(const std::string& location_parent, const std::string& filter = "") const;
clients::body::Json get_conversation(const std::string& name) const;
clients::body::Json calculate_stats(const std::string& location_parent, const std::string& filter = "") const;
// issueModels.list has no paging in Discovery: one document.
clients::body::Json list_issue_models(const std::string& location_parent) const;
ListResult list_phrase_matchers(const std::string& location_parent) const;
ListResult list_analysis_rules(const std::string& location_parent) const;
ListResult list_views(const std::string& location_parent) const;
// Starts an analysis (long-running, billed). Not read-only.
clients::body::Json analyze(const std::string& conversation) const;
private:
Caller caller_;
};
class Ces {
public:
Ces(std::shared_ptr<GoogleClient> client, std::string location = "global", Sleeper sleeper = nullptr);
Caller& caller() { return caller_; }
const Caller& caller() const { return caller_; }
static std::string session_name(const std::string& project, const std::string& location,
const std::string& app, const std::string& session_id);
static Invocation run_session_invocation(const std::string& session, const std::string& text);
ListResult list_apps(const std::string& location_parent) const;
clients::body::Json get_app(const std::string& name) const;
ListResult list_agents(const std::string& app) const;
ListResult list_tools(const std::string& app) const;
ListResult list_examples(const std::string& app) const;
ListResult list_guardrails(const std::string& app) const;
ListResult list_conversations(const std::string& app) const;
// Sends one text turn to the app.
clients::body::Json run_session(const std::string& session, const std::string& text) const;
private:
Caller caller_;
};
} // namespace molo::google::enterprise
+165
View File
@@ -0,0 +1,165 @@
#include "google/enterprise/dialogflow.h"
#include "google/enterprise/caps.h"
#include "google/errors.h"
namespace molo::google::enterprise {
using clients::body::Json;
namespace {
[[noreturn]] void bad(const std::string& m) { throw GoogleError::invalid(m); }
Invocation make(const char* rpc, const char* key, const std::string& name) {
Invocation i;
i.rpc = rpc;
i.path[key] = name;
return i;
}
void check_id(const std::string& id, const char* what) {
if (!valid_resource_name(id) || id.find('/') != std::string::npos) bad(std::string("bad ") + what);
}
bool is_regional(const std::string& name) { return name.find("/locations/") != std::string::npos; }
Json detect_body(const std::string& text, const std::string& language) {
Json b = Json::object();
b.set("queryInput", text_query_input(text, language));
return b;
}
} // namespace
Json text_query_input(const std::string& text, const std::string& language) {
if (text.empty() || text.size() > 256) // Dialogflow rejects text over 256 characters
bad("text must be 1..256 characters");
check_id(language, "language code");
Json t = Json::object();
t.set("text", Json(text));
Json q = Json::object();
q.set("text", t);
q.set("languageCode", Json(language));
return q;
}
// ---- ES ---------------------------------------------------------------
DialogflowEs::DialogflowEs(std::shared_ptr<GoogleClient> client, std::string location)
: caller_(std::move(client), Api::kDialogflowEs, std::move(location)) {}
bool DialogflowEs::regional(const std::string& name) const { return is_regional(name); }
std::string DialogflowEs::session_name(const std::string& project, const std::string& location,
const std::string& id) {
check_id(project, "project");
check_id(id, "session id");
if (location.empty() || location == "global") return "projects/" + project + "/agent/sessions/" + id;
check_id(location, "location");
return "projects/" + project + "/locations/" + location + "/agent/sessions/" + id;
}
Invocation DialogflowEs::detect_intent_invocation(const std::string& session, const std::string& text,
const std::string& language) {
Invocation i = make(is_regional(session) ? "dialogflow.projects.locations.agent.sessions.detectIntent"
: "dialogflow.projects.agent.sessions.detectIntent",
"session", session);
i.body = detect_body(text, language);
return i;
}
Json DialogflowEs::detect_intent(const std::string& s, const std::string& t, const std::string& l) const {
return caller_.invoke(detect_intent_invocation(s, t, l));
}
Json DialogflowEs::get_agent(const std::string& project) const {
// The ES agent get row hangs off `projects/{p}` (or a location).
return caller_.invoke(make(regional(project) ? "dialogflow.projects.locations.getAgent"
: "dialogflow.projects.getAgent",
"parent", project));
}
ListResult DialogflowEs::list_intents(const std::string& p) const {
return caller_.list(make(regional(p) ? "dialogflow.projects.locations.agent.intents.list"
: "dialogflow.projects.agent.intents.list",
"parent", p));
}
ListResult DialogflowEs::list_entity_types(const std::string& p) const {
return caller_.list(make(regional(p) ? "dialogflow.projects.locations.agent.entityTypes.list"
: "dialogflow.projects.agent.entityTypes.list",
"parent", p));
}
ListResult DialogflowEs::list_environments(const std::string& p) const {
return caller_.list(make(regional(p) ? "dialogflow.projects.locations.agent.environments.list"
: "dialogflow.projects.agent.environments.list",
"parent", p));
}
ListResult DialogflowEs::list_contexts(const std::string& s) const {
return caller_.list(make(regional(s) ? "dialogflow.projects.locations.agent.sessions.contexts.list"
: "dialogflow.projects.agent.sessions.contexts.list",
"parent", s));
}
Json DialogflowEs::train_agent(const std::string& p) const {
return caller_.invoke(make(regional(p) ? "dialogflow.projects.locations.agent.train"
: "dialogflow.projects.agent.train",
"parent", p));
}
Json DialogflowEs::delete_contexts(const std::string& s, bool confirm) const {
return caller_.invoke_destructive(
make(regional(s) ? "dialogflow.projects.locations.agent.sessions.deleteContexts"
: "dialogflow.projects.agent.sessions.deleteContexts",
"parent", s),
confirm);
}
// ---- CX ---------------------------------------------------------------
DialogflowCx::DialogflowCx(std::shared_ptr<GoogleClient> client, std::string location)
: caller_(std::move(client), Api::kDialogflowCx, std::move(location)) {}
std::string DialogflowCx::session_name(const std::string& project, const std::string& location,
const std::string& agent, const std::string& id) {
check_id(project, "project");
check_id(location, "location");
check_id(agent, "agent id");
check_id(id, "session id");
return "projects/" + project + "/locations/" + location + "/agents/" + agent + "/sessions/" + id;
}
Invocation DialogflowCx::detect_intent_invocation(const std::string& session, const std::string& text,
const std::string& language) {
Invocation i = make("dialogflow.projects.locations.agents.sessions.detectIntent", "session", session);
i.body = detect_body(text, language);
return i;
}
Json DialogflowCx::detect_intent(const std::string& s, const std::string& t, const std::string& l) const {
return caller_.invoke(detect_intent_invocation(s, t, l));
}
Json DialogflowCx::match_intent(const std::string& s, const std::string& t, const std::string& l) const {
Invocation i = make("dialogflow.projects.locations.agents.sessions.matchIntent", "session", s);
i.body = detect_body(t, l);
return caller_.invoke(i);
}
ListResult DialogflowCx::list_agents(const std::string& p) const {
return caller_.list(make("dialogflow.projects.locations.agents.list", "parent", p));
}
Json DialogflowCx::get_agent(const std::string& n) const {
return caller_.invoke(make("dialogflow.projects.locations.agents.get", "name", n));
}
ListResult DialogflowCx::list_flows(const std::string& a) const {
return caller_.list(make("dialogflow.projects.locations.agents.flows.list", "parent", a));
}
ListResult DialogflowCx::list_pages(const std::string& f) const {
return caller_.list(make("dialogflow.projects.locations.agents.flows.pages.list", "parent", f));
}
ListResult DialogflowCx::list_intents(const std::string& a) const {
return caller_.list(make("dialogflow.projects.locations.agents.intents.list", "parent", a));
}
Json DialogflowCx::validate_agent(const std::string& a) const {
return caller_.invoke(make("dialogflow.projects.locations.agents.validate", "name", a));
}
Json DialogflowCx::delete_agent(const std::string& n, bool confirm) const {
return caller_.invoke_destructive(make("dialogflow.projects.locations.agents.delete", "name", n), confirm);
}
} // namespace molo::google::enterprise
+72
View File
@@ -0,0 +1,72 @@
#pragma once
// Dialogflow ES (v2) and CX (v3): detect intent, match intent, agents,
// intents, flows, pages, sessions. Other rows through caller().
#include <memory>
#include <string>
#include "google/enterprise/caller.h"
namespace molo::google::enterprise {
// queryInput for detectIntent: text with a language code.
clients::body::Json text_query_input(const std::string& text, const std::string& language);
class DialogflowEs {
public:
// location "global" uses the legacy `projects/{p}/agent` names; any other
// uses `projects/{p}/locations/{l}/agent` on the regional host.
DialogflowEs(std::shared_ptr<GoogleClient> client, std::string location = "global");
Caller& caller() { return caller_; }
const Caller& caller() const { return caller_; }
static std::string session_name(const std::string& project, const std::string& location,
const std::string& session_id);
static Invocation detect_intent_invocation(const std::string& session, const std::string& text,
const std::string& language);
clients::body::Json detect_intent(const std::string& session, const std::string& text,
const std::string& language) const;
clients::body::Json get_agent(const std::string& project) const; // projects/{p}/agent
ListResult list_intents(const std::string& agent_parent) const;
ListResult list_entity_types(const std::string& agent_parent) const;
ListResult list_environments(const std::string& agent_parent) const;
ListResult list_contexts(const std::string& session) const;
// Starts training: a long-running operation. Not read-only.
clients::body::Json train_agent(const std::string& project_parent) const; // projects/{p}[/locations/{l}]
clients::body::Json delete_contexts(const std::string& session, bool confirm) const;
private:
bool regional(const std::string& name) const;
Caller caller_;
};
class DialogflowCx {
public:
DialogflowCx(std::shared_ptr<GoogleClient> client, std::string location = "global");
Caller& caller() { return caller_; }
const Caller& caller() const { return caller_; }
static std::string session_name(const std::string& project, const std::string& location,
const std::string& agent, const std::string& session_id);
static Invocation detect_intent_invocation(const std::string& session, const std::string& text,
const std::string& language);
clients::body::Json detect_intent(const std::string& session, const std::string& text,
const std::string& language) const;
clients::body::Json match_intent(const std::string& session, const std::string& text,
const std::string& language) const;
ListResult list_agents(const std::string& location_parent) const;
clients::body::Json get_agent(const std::string& name) const;
ListResult list_flows(const std::string& agent) const;
ListResult list_pages(const std::string& flow) const;
ListResult list_intents(const std::string& agent) const;
clients::body::Json validate_agent(const std::string& agent) const; // starts validation
clients::body::Json delete_agent(const std::string& name, bool confirm) const;
private:
Caller caller_;
};
} // namespace molo::google::enterprise
+315
View File
@@ -0,0 +1,315 @@
#include "google/enterprise/discovery_engine.h"
#include "google/enterprise/caps.h"
#include "google/errors.h"
namespace molo::google::enterprise {
using clients::body::Json;
namespace {
[[noreturn]] void bad(const std::string& m) { throw GoogleError::invalid(m); }
void check_text(const std::string& t, const char* what) {
if (t.empty() || t.size() > EnterpriseCaps::kMaxTextChars) bad(std::string(what) + " is empty or too long");
}
void check_id(const std::string& id, const char* what) {
if (!valid_resource_name(id) || id.find('/') != std::string::npos) bad(std::string("bad ") + what);
}
Invocation make(const char* rpc, const char* key, const std::string& name) {
Invocation i;
i.rpc = rpc;
i.path[key] = name;
return i;
}
void check_count(const Json& arr, const char* what) {
if (!arr.is_array() || arr.as_array().empty() ||
arr.as_array().size() > EnterpriseCaps::kMaxDocuments)
bad(std::string(what) + " must be an array of 1.." +
std::to_string(EnterpriseCaps::kMaxDocuments) + " items");
}
} // namespace
std::string DeNames::parent() const {
check_id(project, "project");
check_id(location, "location");
return "projects/" + project + "/locations/" + location;
}
std::string DeNames::data_store(const std::string& id) const {
check_id(collection, "collection");
check_id(id, "data store id");
return parent() + "/collections/" + collection + "/dataStores/" + id;
}
std::string DeNames::engine(const std::string& id) const {
check_id(collection, "collection");
check_id(id, "engine id");
return parent() + "/collections/" + collection + "/engines/" + id;
}
std::string DeNames::serving_config(DeKind kind, const std::string& id, const std::string& config) const {
check_id(config, "serving config id");
return (kind == DeKind::kDataStore ? data_store(id) : engine(id)) + "/servingConfigs/" + config;
}
std::string DeNames::assistant(const std::string& engine_id, const std::string& id) const {
check_id(id, "assistant id");
return engine(engine_id) + "/assistants/" + id;
}
std::string DeNames::branch(const std::string& ds, const std::string& b) const {
check_id(b, "branch id");
return data_store(ds) + "/branches/" + b;
}
std::string DeNames::ranking_config(const std::string& id) const {
check_id(id, "ranking config id");
return parent() + "/rankingConfigs/" + id;
}
std::string DeNames::grounding_config(const std::string& id) const {
check_id(id, "grounding config id");
return parent() + "/groundingConfigs/" + id;
}
Json SearchQuery::to_body() const {
if (query.size() > EnterpriseCaps::kMaxTextChars) bad("query too long");
if (page_size < 1 || page_size > 100) bad("pageSize must be 1..100");
if (offset < 0 || offset > 10000) bad("offset must be 0..10000");
Json b = extra.is_object() ? extra : Json::object();
b.set("query", Json(query));
b.set("pageSize", Json(page_size));
if (offset) b.set("offset", Json(offset));
if (!filter.empty()) b.set("filter", Json(filter));
if (!order_by.empty()) b.set("orderBy", Json(order_by));
if (!user_pseudo_id.empty()) b.set("userPseudoId", Json(user_pseudo_id));
return b;
}
Json AnswerQuery::to_body() const {
check_text(query_text, "query text");
Json b = extra.is_object() ? extra : Json::object();
Json q = Json::object();
q.set("text", Json(query_text));
b.set("query", q);
if (!session.empty()) b.set("session", Json(session));
if (!user_pseudo_id.empty()) b.set("userPseudoId", Json(user_pseudo_id));
return b;
}
DiscoveryEngine::DiscoveryEngine(std::shared_ptr<GoogleClient> client, std::string location,
Sleeper sleeper)
: caller_(std::move(client), Api::kDiscoveryEngine, std::move(location), std::move(sleeper)) {}
bool DiscoveryEngine::under_engine(const std::string& name) {
return name.find("/engines/") != std::string::npos;
}
Invocation DiscoveryEngine::search_invocation(const SearchQuery& q) {
const bool eng = under_engine(q.serving_config);
Invocation i = make(eng ? "discoveryengine.projects.locations.collections.engines.servingConfigs.search"
: "discoveryengine.projects.locations.collections.dataStores.servingConfigs.search",
"servingConfig", q.serving_config);
i.body = q.to_body();
return i;
}
Invocation DiscoveryEngine::answer_invocation(const AnswerQuery& q, bool stream) {
const bool eng = under_engine(q.serving_config);
const char* rpc =
stream ? (eng ? "discoveryengine.projects.locations.collections.engines.servingConfigs.streamAnswer"
: "discoveryengine.projects.locations.collections.dataStores.servingConfigs.streamAnswer")
: (eng ? "discoveryengine.projects.locations.collections.engines.servingConfigs.answer"
: "discoveryengine.projects.locations.collections.dataStores.servingConfigs.answer");
Invocation i = make(rpc, "servingConfig", q.serving_config);
i.body = q.to_body();
return i;
}
Json DiscoveryEngine::search(const SearchQuery& q) const {
return caller_.invoke(search_invocation(q));
}
Json DiscoveryEngine::answer(const AnswerQuery& q) const {
return caller_.invoke(answer_invocation(q, false));
}
std::size_t DiscoveryEngine::stream_answer(const AnswerQuery& q,
const GoogleClient::EventSink& sink) const {
return caller_.invoke_stream(answer_invocation(q, true), sink);
}
Json DiscoveryEngine::converse(const std::string& conversation, const std::string& text,
const std::string& serving_config) const {
check_text(text, "text");
Invocation i = make(under_engine(conversation)
? "discoveryengine.projects.locations.collections.engines.conversations.converse"
: "discoveryengine.projects.locations.collections.dataStores.conversations.converse",
"name", conversation);
Json b = Json::object();
Json q = Json::object();
q.set("input", Json(text));
b.set("query", q);
if (!serving_config.empty()) b.set("servingConfig", Json(serving_config));
i.body = b;
return caller_.invoke(i);
}
std::size_t DiscoveryEngine::stream_assist(const std::string& assistant, const std::string& text,
const std::string& session,
const GoogleClient::EventSink& sink) const {
check_text(text, "text");
Invocation i = make("discoveryengine.projects.locations.collections.engines.assistants.streamAssist",
"name", assistant);
Json b = Json::object();
Json q = Json::object();
q.set("text", Json(text));
b.set("query", q);
if (!session.empty()) b.set("session", Json(session));
i.body = b;
return caller_.invoke_stream(i, sink);
}
Json DiscoveryEngine::recommend(const std::string& serving_config, const Json& user_event,
int page_size) const {
if (!user_event.is_object()) bad("userEvent must be an object");
if (page_size < 1 || page_size > 100) bad("pageSize must be 1..100");
Invocation i = make(under_engine(serving_config)
? "discoveryengine.projects.locations.collections.engines.servingConfigs.recommend"
: "discoveryengine.projects.locations.collections.dataStores.servingConfigs.recommend",
"servingConfig", serving_config);
Json b = Json::object();
b.set("userEvent", user_event);
b.set("pageSize", Json(page_size));
i.body = b;
return caller_.invoke(i);
}
Invocation DiscoveryEngine::rank_invocation(const std::string& ranking_config, const std::string& query,
const Json& records, int top_n) {
check_text(query, "query");
check_count(records, "records");
if (top_n < 0 || top_n > 100) bad("topN must be 0..100");
Invocation i = make("discoveryengine.projects.locations.rankingConfigs.rank", "rankingConfig",
ranking_config);
Json b = Json::object();
b.set("query", Json(query));
b.set("records", records);
if (top_n) b.set("topN", Json(top_n));
i.body = b;
return i;
}
Invocation DiscoveryEngine::grounding_invocation(const std::string& grounding_config,
const std::string& answer_candidate, const Json& facts) {
check_text(answer_candidate, "answer candidate");
check_count(facts, "facts");
Invocation i = make("discoveryengine.projects.locations.groundingConfigs.check", "groundingConfig",
grounding_config);
Json b = Json::object();
b.set("answerCandidate", Json(answer_candidate));
b.set("facts", facts);
i.body = b;
return i;
}
Json DiscoveryEngine::rank(const std::string& ranking_config, const std::string& query,
const Json& records, int top_n) const {
return caller_.invoke(rank_invocation(ranking_config, query, records, top_n));
}
Json DiscoveryEngine::check_grounding(const std::string& grounding_config,
const std::string& answer_candidate, const Json& facts) const {
return caller_.invoke(grounding_invocation(grounding_config, answer_candidate, facts));
}
Json DiscoveryEngine::write_user_event(const std::string& ds, const Json& event) const {
if (!event.is_object()) bad("event must be an object");
Invocation i = make("discoveryengine.projects.locations.collections.dataStores.userEvents.write",
"parent", ds);
i.body = event;
return caller_.invoke(i);
}
ListResult DiscoveryEngine::list_data_stores(const std::string& p) const {
return caller_.list(make("discoveryengine.projects.locations.collections.dataStores.list", "parent", p));
}
Json DiscoveryEngine::get_data_store(const std::string& n) const {
return caller_.invoke(make("discoveryengine.projects.locations.collections.dataStores.get", "name", n));
}
ListResult DiscoveryEngine::list_engines(const std::string& p) const {
return caller_.list(make("discoveryengine.projects.locations.collections.engines.list", "parent", p));
}
Json DiscoveryEngine::get_engine(const std::string& n) const {
return caller_.invoke(make("discoveryengine.projects.locations.collections.engines.get", "name", n));
}
ListResult DiscoveryEngine::list_documents(const std::string& b) const {
return caller_.list(
make("discoveryengine.projects.locations.collections.dataStores.branches.documents.list", "parent", b));
}
Json DiscoveryEngine::get_document(const std::string& n) const {
return caller_.invoke(
make("discoveryengine.projects.locations.collections.dataStores.branches.documents.get", "name", n));
}
ListResult DiscoveryEngine::list_sessions(const std::string& p) const {
return caller_.list(make(under_engine(p) ? "discoveryengine.projects.locations.collections.engines.sessions.list"
: "discoveryengine.projects.locations.collections.dataStores.sessions.list",
"parent", p));
}
Json DiscoveryEngine::get_session(const std::string& n) const {
return caller_.invoke(make(under_engine(n) ? "discoveryengine.projects.locations.collections.engines.sessions.get"
: "discoveryengine.projects.locations.collections.dataStores.sessions.get",
"name", n));
}
ListResult DiscoveryEngine::list_conversations(const std::string& p) const {
return caller_.list(make(under_engine(p) ? "discoveryengine.projects.locations.collections.engines.conversations.list"
: "discoveryengine.projects.locations.collections.dataStores.conversations.list",
"parent", p));
}
Json DiscoveryEngine::get_conversation(const std::string& n) const {
return caller_.invoke(make(under_engine(n) ? "discoveryengine.projects.locations.collections.engines.conversations.get"
: "discoveryengine.projects.locations.collections.dataStores.conversations.get",
"name", n));
}
ListResult DiscoveryEngine::list_assistants(const std::string& e) const {
return caller_.list(make("discoveryengine.projects.locations.collections.engines.assistants.list", "parent", e));
}
ListResult DiscoveryEngine::list_agents(const std::string& a) const {
return caller_.list(make("discoveryengine.projects.locations.collections.engines.assistants.agents.list", "parent", a));
}
Json DiscoveryEngine::get_agent(const std::string& n) const {
return caller_.invoke(make("discoveryengine.projects.locations.collections.engines.assistants.agents.get", "name", n));
}
ListResult DiscoveryEngine::list_serving_configs(const std::string& p) const {
return caller_.list(make(under_engine(p) ? "discoveryengine.projects.locations.collections.engines.servingConfigs.list"
: "discoveryengine.projects.locations.collections.dataStores.servingConfigs.list",
"parent", p));
}
Json DiscoveryEngine::create_session(const std::string& parent, const std::string& user) const {
Invocation i = make(under_engine(parent) ? "discoveryengine.projects.locations.collections.engines.sessions.create"
: "discoveryengine.projects.locations.collections.dataStores.sessions.create",
"parent", parent);
Json b = Json::object();
if (!user.empty()) b.set("userPseudoId", Json(user));
i.body = b;
return caller_.invoke(i);
}
Json DiscoveryEngine::delete_session(const std::string& n, bool confirm) const {
return caller_.invoke_destructive(
make(under_engine(n) ? "discoveryengine.projects.locations.collections.engines.sessions.delete"
: "discoveryengine.projects.locations.collections.dataStores.sessions.delete",
"name", n),
confirm);
}
Json DiscoveryEngine::delete_conversation(const std::string& n, bool confirm) const {
return caller_.invoke_destructive(
make(under_engine(n) ? "discoveryengine.projects.locations.collections.engines.conversations.delete"
: "discoveryengine.projects.locations.collections.dataStores.conversations.delete",
"name", n),
confirm);
}
Json DiscoveryEngine::delete_document(const std::string& n, bool confirm) const {
return caller_.invoke_destructive(
make("discoveryengine.projects.locations.collections.dataStores.branches.documents.delete", "name", n),
confirm);
}
Json DiscoveryEngine::delete_agent(const std::string& n, bool confirm) const {
return caller_.invoke_destructive(
make("discoveryengine.projects.locations.collections.engines.assistants.agents.delete", "name", n),
confirm);
}
} // namespace molo::google::enterprise
+120
View File
@@ -0,0 +1,120 @@
#pragma once
// Discovery Engine (Gemini Enterprise): search, answer, assistants, agents,
// data stores, engines, documents, conversations, sessions, user events,
// ranking and grounding check. Typed entry points over Caller; any other row
// of the table is reachable through caller().
#include <memory>
#include <string>
#include "google/enterprise/caller.h"
namespace molo::google::enterprise {
// Where a serving config, conversation or session hangs: under a data store
// or under an engine.
enum class DeKind { kDataStore, kEngine };
struct DeNames {
std::string project;
std::string location = "global";
std::string collection = "default_collection";
std::string parent() const; // projects/{p}/locations/{l}
std::string data_store(const std::string& id) const;
std::string engine(const std::string& id) const;
std::string serving_config(DeKind kind, const std::string& id,
const std::string& config = "default_search") const;
std::string assistant(const std::string& engine_id, const std::string& id = "default_assistant") const;
std::string branch(const std::string& data_store_id, const std::string& branch = "default_branch") const;
std::string ranking_config(const std::string& id = "default_ranking_config") const;
std::string grounding_config(const std::string& id = "default_grounding_config") const;
};
struct SearchQuery {
std::string serving_config;
std::string query;
std::string user_pseudo_id;
std::string filter;
std::string order_by;
int page_size = 10;
int offset = 0;
clients::body::Json extra = clients::body::Json::object(); // other SearchRequest fields
clients::body::Json to_body() const;
};
struct AnswerQuery {
std::string serving_config;
std::string query_text;
std::string session; // optional session resource name
std::string user_pseudo_id;
clients::body::Json extra = clients::body::Json::object(); // AnswerQueryRequest fields
clients::body::Json to_body() const;
};
class DiscoveryEngine {
public:
DiscoveryEngine(std::shared_ptr<GoogleClient> client, std::string location = "global",
Sleeper sleeper = nullptr);
Caller& caller() { return caller_; }
const Caller& caller() const { return caller_; }
static Invocation search_invocation(const SearchQuery& q);
static Invocation answer_invocation(const AnswerQuery& q, bool stream);
static Invocation rank_invocation(const std::string& ranking_config, const std::string& query,
const clients::body::Json& records, int top_n);
static Invocation grounding_invocation(const std::string& grounding_config,
const std::string& answer_candidate,
const clients::body::Json& facts);
clients::body::Json search(const SearchQuery& q) const;
clients::body::Json answer(const AnswerQuery& q) const;
std::size_t stream_answer(const AnswerQuery& q, const GoogleClient::EventSink& sink) const;
// Multi-turn conversation: `conversation` is the full name of an existing one.
clients::body::Json converse(const std::string& conversation, const std::string& text,
const std::string& serving_config = "") const;
// Gemini Enterprise assistant: streamed events.
std::size_t stream_assist(const std::string& assistant, const std::string& text,
const std::string& session, const GoogleClient::EventSink& sink) const;
clients::body::Json recommend(const std::string& serving_config,
const clients::body::Json& user_event, int page_size = 10) const;
// records: array of {id, title?, content?, score?}.
clients::body::Json rank(const std::string& ranking_config, const std::string& query,
const clients::body::Json& records, int top_n = 0) const;
// facts: array of {factText, attributes?}.
clients::body::Json check_grounding(const std::string& grounding_config,
const std::string& answer_candidate,
const clients::body::Json& facts) const;
clients::body::Json write_user_event(const std::string& data_store_name,
const clients::body::Json& event) const;
// Reads. `parent` / `name` are full resource names.
ListResult list_data_stores(const std::string& collection_parent) const;
clients::body::Json get_data_store(const std::string& name) const;
ListResult list_engines(const std::string& collection_parent) const;
clients::body::Json get_engine(const std::string& name) const;
ListResult list_documents(const std::string& branch) const;
clients::body::Json get_document(const std::string& name) const;
ListResult list_sessions(const std::string& parent) const;
clients::body::Json get_session(const std::string& name) const;
ListResult list_conversations(const std::string& parent) const;
clients::body::Json get_conversation(const std::string& name) const;
ListResult list_assistants(const std::string& engine) const;
ListResult list_agents(const std::string& assistant) const; // v1alpha
clients::body::Json get_agent(const std::string& name) const;
ListResult list_serving_configs(const std::string& parent) const;
// Writes that need a name: explicit methods, delete has no default confirm.
clients::body::Json create_session(const std::string& parent, const std::string& user_pseudo_id) const;
clients::body::Json delete_session(const std::string& name, bool confirm) const;
clients::body::Json delete_conversation(const std::string& name, bool confirm) const;
clients::body::Json delete_document(const std::string& name, bool confirm) const;
clients::body::Json delete_agent(const std::string& name, bool confirm) const;
private:
static bool under_engine(const std::string& name);
Caller caller_;
};
} // namespace molo::google::enterprise
+165
View File
@@ -0,0 +1,165 @@
#include "google/enterprise/retail.h"
#include "google/enterprise/caps.h"
#include "google/errors.h"
namespace molo::google::enterprise {
using clients::body::Json;
namespace {
[[noreturn]] void bad(const std::string& m) { throw GoogleError::invalid(m); }
Invocation make(const char* rpc, const char* key, const std::string& name) {
Invocation i;
i.rpc = rpc;
i.path[key] = name;
return i;
}
void check_id(const std::string& id, const char* what) {
if (!valid_resource_name(id) || id.find('/') != std::string::npos) bad(std::string("bad ") + what);
}
void check_page(int n) {
if (n < 1 || n > 100) bad("pageSize must be 1..100");
}
} // namespace
std::string RetailNames::catalog_name() const {
check_id(project, "project");
check_id(location, "location");
check_id(catalog, "catalog");
return "projects/" + project + "/locations/" + location + "/catalogs/" + catalog;
}
std::string RetailNames::placement(const std::string& id) const {
check_id(id, "placement id");
return catalog_name() + "/placements/" + id;
}
std::string RetailNames::serving_config(const std::string& id) const {
check_id(id, "serving config id");
return catalog_name() + "/servingConfigs/" + id;
}
std::string RetailNames::branch(const std::string& id) const {
check_id(id, "branch id");
return catalog_name() + "/branches/" + id;
}
Json RetailSearch::to_body() const {
if (query.size() > EnterpriseCaps::kMaxTextChars) bad("query too long");
if (visitor_id.empty() || visitor_id.size() > 128) bad("visitorId is required (1..128 chars)");
check_page(page_size);
if (offset < 0 || offset > 10000) bad("offset must be 0..10000");
Json b = extra.is_object() ? extra : Json::object();
b.set("query", Json(query));
b.set("visitorId", Json(visitor_id));
b.set("pageSize", Json(page_size));
if (offset) b.set("offset", Json(offset));
if (!filter.empty()) b.set("filter", Json(filter));
if (!branch.empty()) b.set("branch", Json(branch));
return b;
}
Retail::Retail(std::shared_ptr<GoogleClient> client, Sleeper sleeper)
: caller_(std::move(client), Api::kRetail, "global", std::move(sleeper)) {}
Invocation Retail::search_invocation(const RetailSearch& s) {
const bool sc = s.placement.find("/servingConfigs/") != std::string::npos;
Invocation i = make(sc ? "retail.projects.locations.catalogs.servingConfigs.search"
: "retail.projects.locations.catalogs.placements.search",
sc ? "placement" : "placement", s.placement);
i.body = s.to_body();
return i;
}
Invocation Retail::predict_invocation(const std::string& placement, const Json& user_event, int page_size,
bool validate_only) {
if (!user_event.is_object()) bad("userEvent must be an object");
check_page(page_size);
const bool sc = placement.find("/servingConfigs/") != std::string::npos;
Invocation i = make(sc ? "retail.projects.locations.catalogs.servingConfigs.predict"
: "retail.projects.locations.catalogs.placements.predict",
"placement", placement);
Json b = Json::object();
b.set("userEvent", user_event);
b.set("pageSize", Json(page_size));
if (validate_only) b.set("validateOnly", Json(true));
i.body = b;
return i;
}
Json Retail::search(const RetailSearch& s) const { return caller_.invoke(search_invocation(s)); }
Json Retail::predict(const std::string& p, const Json& e, int n, bool v) const {
return caller_.invoke(predict_invocation(p, e, n, v));
}
Json Retail::write_user_event(const std::string& catalog, const Json& event) const {
if (!event.is_object()) bad("event must be an object");
Invocation i = make("retail.projects.locations.catalogs.userEvents.write", "parent", catalog);
i.body = event;
return caller_.invoke(i);
}
ListResult Retail::list_catalogs(const std::string& p) const {
return caller_.list(make("retail.projects.locations.catalogs.list", "parent", p));
}
ListResult Retail::list_products(const std::string& b) const {
return caller_.list(make("retail.projects.locations.catalogs.branches.products.list", "parent", b));
}
Json Retail::get_product(const std::string& n) const {
return caller_.invoke(make("retail.projects.locations.catalogs.branches.products.get", "name", n));
}
ListResult Retail::list_serving_configs(const std::string& c) const {
return caller_.list(make("retail.projects.locations.catalogs.servingConfigs.list", "parent", c));
}
Json Retail::delete_product(const std::string& n, bool confirm) const {
return caller_.invoke_destructive(make("retail.projects.locations.catalogs.branches.products.delete", "name", n),
confirm);
}
// ---- Recommendations AI -------------------------------------------------
Recommendations::Recommendations(std::shared_ptr<GoogleClient> client)
: caller_(std::move(client), Api::kRecommendations, "global") {}
std::string Recommendations::placement(const std::string& project, const std::string& location,
const std::string& catalog, const std::string& store,
const std::string& id) {
check_id(project, "project");
check_id(location, "location");
check_id(catalog, "catalog");
check_id(store, "event store");
check_id(id, "placement id");
return "projects/" + project + "/locations/" + location + "/catalogs/" + catalog + "/eventStores/" +
store + "/placements/" + id;
}
Invocation Recommendations::predict_invocation(const std::string& p, const Json& e, int n, bool dry) {
if (!e.is_object()) bad("userEvent must be an object");
check_page(n);
Invocation i = make("recommendationengine.projects.locations.catalogs.eventStores.placements.predict",
"name", p);
Json b = Json::object();
b.set("userEvent", e);
b.set("pageSize", Json(n));
if (dry) b.set("dryRun", Json(true));
i.body = b;
return i;
}
Json Recommendations::predict(const std::string& p, const Json& e, int n, bool dry) const {
return caller_.invoke(predict_invocation(p, e, n, dry));
}
ListResult Recommendations::list_catalogs(const std::string& p) const {
return caller_.list(make("recommendationengine.projects.locations.catalogs.list", "parent", p));
}
ListResult Recommendations::list_catalog_items(const std::string& c) const {
return caller_.list(make("recommendationengine.projects.locations.catalogs.catalogItems.list", "parent", c));
}
ListResult Recommendations::list_user_events(const std::string& s) const {
return caller_.list(make("recommendationengine.projects.locations.catalogs.eventStores.userEvents.list", "parent", s));
}
Json Recommendations::write_user_event(const std::string& s, const Json& event) const {
if (!event.is_object()) bad("event must be an object");
Invocation i = make("recommendationengine.projects.locations.catalogs.eventStores.userEvents.write", "parent", s);
i.body = event;
return caller_.invoke(i);
}
} // namespace molo::google::enterprise
+85
View File
@@ -0,0 +1,85 @@
#pragma once
// Retail API (v2) and Recommendations AI (recommendationengine v1beta1, the
// original product; Retail's predict is its successor). Predict, search,
// products, catalogs, user events. Other rows through caller().
#include <memory>
#include <string>
#include "google/enterprise/caller.h"
namespace molo::google::enterprise {
struct RetailNames {
std::string project;
std::string location = "global";
std::string catalog = "default_catalog";
std::string catalog_name() const; // projects/p/locations/l/catalogs/c
std::string placement(const std::string& id) const; // .../placements/{id}
std::string serving_config(const std::string& id) const;
std::string branch(const std::string& id = "0") const; // .../branches/{id}
};
struct RetailSearch {
std::string placement; // placement or serving config full name
std::string query;
std::string visitor_id; // required by Retail
std::string filter;
std::string branch;
int page_size = 10;
int offset = 0;
clients::body::Json extra = clients::body::Json::object();
clients::body::Json to_body() const;
};
class Retail {
public:
Retail(std::shared_ptr<GoogleClient> client, Sleeper sleeper = nullptr);
Caller& caller() { return caller_; }
const Caller& caller() const { return caller_; }
static Invocation search_invocation(const RetailSearch& s);
static Invocation predict_invocation(const std::string& placement, const clients::body::Json& user_event,
int page_size, bool validate_only);
clients::body::Json search(const RetailSearch& s) const;
// user_event: {eventType, visitorId, productDetails?...}; Retail requires it.
clients::body::Json predict(const std::string& placement, const clients::body::Json& user_event,
int page_size = 10, bool validate_only = false) const;
clients::body::Json write_user_event(const std::string& catalog, const clients::body::Json& event) const;
ListResult list_catalogs(const std::string& location_parent) const;
ListResult list_products(const std::string& branch) const;
clients::body::Json get_product(const std::string& name) const;
ListResult list_serving_configs(const std::string& catalog) const;
clients::body::Json delete_product(const std::string& name, bool confirm) const;
private:
Caller caller_;
};
// Recommendations AI (legacy surface).
class Recommendations {
public:
explicit Recommendations(std::shared_ptr<GoogleClient> client);
Caller& caller() { return caller_; }
const Caller& caller() const { return caller_; }
static std::string placement(const std::string& project, const std::string& location,
const std::string& catalog, const std::string& event_store,
const std::string& placement_id);
static Invocation predict_invocation(const std::string& placement, const clients::body::Json& user_event,
int page_size, bool dry_run);
clients::body::Json predict(const std::string& placement, const clients::body::Json& user_event,
int page_size = 10, bool dry_run = false) const;
ListResult list_catalogs(const std::string& location_parent) const;
ListResult list_catalog_items(const std::string& catalog) const;
ListResult list_user_events(const std::string& event_store) const;
clients::body::Json write_user_event(const std::string& event_store, const clients::body::Json& event) const;
private:
Caller caller_;
};
} // namespace molo::google::enterprise
@@ -0,0 +1,212 @@
#!/usr/bin/env python3
"""Discovery conformance for src/google/enterprise (python3 stdlib only).
The call table `src/google/enterprise/calls_table.inc` is derived from Google's
Discovery documents. This script has two modes:
check_discovery.py fetch Discovery, regenerate the table in memory,
fail on any difference with the committed file,
then run the structural checks below
check_discovery.py --write regenerate calls_table.inc from Discovery
--cache DIR read <service>-<version>.json from DIR instead of
the network (offline runs, same checks)
Structural checks (all fail the run):
- table == Discovery: every row field (method, path, path parameter patterns,
query parameters, request body fields, flags, list items key) is exactly what
Discovery says; a changed Discovery document shows up as a difference
- coverage: every Discovery method of a covered document is a table row or is
on an explicit exclusion rule (EXCLUDE below, counted and printed)
- rpc ids written in the C++ facades exist in the table
- ApiInfo (apis.cpp): host, regional endpoints and the default scope agree
with the Discovery documents
"""
import json
import os
import re
import sys
import urllib.request
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
TABLE = os.path.join(ROOT, "calls_table.inc")
# (Api enum name, discovery service, version, include-only regex or None)
# v1alpha of Discovery Engine is read only for assistants.agents: Gemini
# Enterprise agents exist nowhere else in Discovery (v1 and v1beta have none).
SOURCES = [
("kDiscoveryEngine", "discoveryengine", "v1", None),
("kDiscoveryEngine", "discoveryengine", "v1alpha", r"\.assistants\.agents\."),
("kDialogflowEs", "dialogflow", "v2", None),
("kDialogflowCx", "dialogflow", "v3", None),
("kRetail", "retail", "v2", None),
("kInsights", "contactcenterinsights", "v1", None),
("kCes", "ces", "v1", None),
("kRecommendations", "recommendationengine", "v1beta1", None),
]
EXCLUDE = {
"discoveryengine v1alpha": "every method except assistants.agents (alpha-only products)",
}
DESTRUCTIVE = re.compile(r"^(delete|purge|remove|cancel|reset|clear|batchDelete)")
def fetch(service, version, cache):
if cache:
with open(os.path.join(cache, "%s-%s.json" % (service, version))) as f:
return json.load(f)
url = "https://%s.googleapis.com/$discovery/rest?version=%s" % (service, version)
with urllib.request.urlopen(url, timeout=60) as r:
return json.load(r)
def walk(res, out):
for m in res.get("methods", {}).values():
out.append(m)
for sub in res.get("resources", {}).values():
walk(sub, out)
def resolve(doc, ref):
return doc["schemas"].get(ref, {})
def row_for(api, doc, method):
version = doc["version"]
params = method.get("parameters", {})
path = method["path"]
placeholders = re.findall(r"\{\+?([A-Za-z0-9_]+)\}", path)
pparts = []
for name in placeholders:
p = params[name]
pat = p.get("pattern", "")
assert " " not in pat, (method["id"], name)
pparts.append("%s=%s" % (name, pat))
qparts = []
for name in sorted(params):
p = params[name]
if p.get("location") == "query":
qparts.append(name + ("!" if p.get("required") else ""))
req = method.get("request", {}).get("$ref", "")
body = ",".join(sorted(resolve(doc, req).get("properties", {}))) if req else ""
resp = method.get("response", {}).get("$ref", "")
last = method["id"].split(".")[-1]
flags = ""
if method["httpMethod"] == "DELETE" or DESTRUCTIVE.match(last):
flags += "D"
if resp.endswith("Operation"):
flags += "L"
if last.startswith("stream"):
flags += "S"
items_key = ""
if "pageToken" in params and "nextPageToken" in resolve(doc, resp).get("properties", {}):
flags += "P"
for k, v in resolve(doc, resp).get("properties", {}).items():
if v.get("type") == "array" and k != "unreachable":
items_key = k
break
return [api, version, method["id"], method["httpMethod"], path, " ".join(pparts),
",".join(qparts), body, req, flags, items_key]
def generate(cache):
lines, counts, covered = [], {}, {}
docs = {}
emitted = set()
for api, service, version, only in SOURCES:
doc = fetch(service, version, cache)
docs[(service, version)] = doc
methods = []
walk(doc, methods)
n = 0
for m in sorted(methods, key=lambda m: m["id"]):
if only and not re.search(only, m["id"]):
continue
if (api, m["id"]) in emitted: # an earlier version already has this id
continue
emitted.add((api, m["id"]))
row = row_for(api, doc, m)
fields = ", ".join(json.dumps(x) for x in row[1:])
lines.append("{Api::%s, %s}," % (api, fields))
n += 1
counts["%s %s" % (service, version)] = (n, len(methods), doc["revision"])
return lines, counts, docs
HEADER = (
"// GENERATED by tools/check_discovery.py --write from Google's Discovery\n"
"// documents. Do not edit by hand: the checker fails on any difference.\n"
"// Fields: api, version, rpc id, http method, path, path params (name=pattern),\n"
"// query params (! = required), request body fields, request schema, flags\n"
"// (D destructive, L long-running, S stream, P paginated), list items key.\n"
)
def read_table():
if not os.path.exists(TABLE):
return []
return [l.rstrip("\n") for l in open(TABLE) if l.startswith("{Api::")]
def cpp_rpc_ids():
ids = set()
for name in os.listdir(ROOT):
if name.endswith((".cpp", ".h")):
text = open(os.path.join(ROOT, name)).read()
ids.update(i for i in re.findall(r'"((?:discoveryengine|dialogflow|retail|contactcenterinsights|ces|recommendationengine)\.[A-Za-z0-9_.]+)"', text) if not i.endswith("googleapis.com"))
return ids
def main():
cache = None
if "--cache" in sys.argv:
cache = sys.argv[sys.argv.index("--cache") + 1]
lines, counts, docs = generate(cache)
if "--write" in sys.argv:
with open(TABLE, "w") as f:
f.write(HEADER)
f.write("\n".join(lines) + "\n")
print("wrote %d rows" % len(lines))
return 0
failures = []
committed = read_table()
if committed != lines:
a, b = set(committed), set(lines)
for l in sorted(a - b)[:5]:
failures.append("committed row not in Discovery: " + l[:160])
for l in sorted(b - a)[:5]:
failures.append("Discovery row missing from table: " + l[:160])
failures.append("table differs from Discovery (%d committed, %d expected)" % (len(committed), len(lines)))
# Rows keyed by (api, rpc) must be unique.
keys = [(l.split(",")[0], json.loads("[" + l[l.index(",") + 1:-2] + "]")[1]) for l in lines]
if len(set(keys)) != len(keys):
failures.append("duplicate (api, rpc) rows")
table_ids = {k[1] for k in keys}
for rpc in sorted(cpp_rpc_ids() - table_ids):
failures.append("facade uses an rpc id absent from the table: " + rpc)
# ApiInfo checks.
apis_src = open(os.path.join(ROOT, "apis.cpp")).read()
for (service, version), doc in docs.items():
host = "%s.googleapis.com" % service
if host not in apis_src:
failures.append("apis.cpp lacks host " + host)
if doc["rootUrl"] != "https://%s/" % host:
failures.append("rootUrl differs for " + service)
scopes = doc.get("auth", {}).get("oauth2", {}).get("scopes", {})
if "https://www.googleapis.com/auth/cloud-platform" not in scopes:
failures.append("cloud-platform scope missing for %s %s" % (service, version))
ces = docs[("ces", "v1")]
for e in ces.get("endpoints", []):
if "ces.%s.rep.googleapis.com" % e["location"] not in apis_src:
failures.append("apis.cpp lacks CES regional endpoint " + e["location"])
for k, (n, total, rev) in sorted(counts.items()):
note = "" if n == total else " (excluded: %s)" % EXCLUDE.get(k, "?")
print("%-28s %4d of %4d methods, revision %s%s" % (k, n, total, rev, note))
if failures:
for f in failures:
print("FAIL " + f)
return 1
print("discovery ok: %d calls, %d facade rpc ids checked" % (len(lines), len(cpp_rpc_ids())))
return 0
if __name__ == "__main__":
sys.exit(main())