Merge branch 'worktree-agent-a6c7d57da30a90b4f'
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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())
|
||||
Reference in New Issue
Block a user