Merge sessions module (Agent Sessions, Memory Bank)
This commit is contained in:
@@ -1,13 +1,360 @@
|
||||
#include "../AgentDemos.hpp"
|
||||
|
||||
#include <memory>
|
||||
|
||||
#include "../../fw/Router.hpp"
|
||||
#include "../../fw/Templates.hpp"
|
||||
#include "../../fw/Validate.hpp"
|
||||
#include "google/resource.h"
|
||||
#include "google/sessions/caps.h"
|
||||
#include "google/sessions/calls.h"
|
||||
#include "google/sessions/memory_bank.h"
|
||||
#include "google/sessions/sessions.h"
|
||||
|
||||
namespace molo::example::app {
|
||||
|
||||
// Agent Platform: sessions. Stub: the module agent fills this in.
|
||||
// Agent Platform: Agent Sessions and Agent Memory Bank over src/google/sessions.
|
||||
// Every route that would call Google is a POST (or DELETE) and answers 503
|
||||
// google_not_configured without a credential and 422 on bad input. The engine
|
||||
// is a full reasoningEngines name or a bare engine id (project from
|
||||
// GOOGLE_CLOUD_PROJECT). Live behavior needs an Agent Engine resource and a
|
||||
// credential Google accepts for it; see src/google/sessions/SPEC.md.
|
||||
|
||||
namespace {
|
||||
|
||||
namespace gs = molo::google::sessions;
|
||||
using Flat = std::map<std::string, std::string>;
|
||||
using GJson = molo::clients::body::Json;
|
||||
|
||||
const char kSessionsPage[] = R"SESSIONS({% extends "base.html" %}
|
||||
{% block content %}
|
||||
<h1>Agent sessions and memory</h1>
|
||||
<p>Sessions and Memory Bank under one Agent Engine
|
||||
(<code>projects/P/locations/L/reasoningEngines/E</code>, or a bare engine id).
|
||||
Every call below is a JSON POST (or DELETE) and answers 503
|
||||
<code>google_not_configured</code> without a credential.</p>
|
||||
<p><a href="/agent/sessions/status">Status</a></p>
|
||||
<div style="overflow-x:auto">
|
||||
<table>
|
||||
<thead><tr><th>Route</th><th>Body</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>POST /agent/sessions/create</td><td>engine, user_id, session_id?, display_name?, ttl?</td></tr>
|
||||
<tr><td>POST /agent/sessions/get</td><td>engine, session_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/list</td><td>engine, filter?</td></tr>
|
||||
<tr><td>DELETE /agent/sessions/session</td><td>query: engine, id</td></tr>
|
||||
<tr><td>POST /agent/sessions/events/append</td><td>engine, session_id, author, invocation_id, timestamp, text</td></tr>
|
||||
<tr><td>POST /agent/sessions/events/list</td><td>engine, session_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/generate</td><td>engine, scope_key, scope_value, text or session_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/retrieve</td><td>engine, scope_key, scope_value, query?, top_k?</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/create</td><td>engine, scope_key, scope_value, fact, memory_id?</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/get</td><td>engine, memory_id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/list</td><td>engine, filter?</td></tr>
|
||||
<tr><td>DELETE /agent/sessions/memories/memory</td><td>query: engine, id</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/profiles</td><td>engine, scope_key, scope_value</td></tr>
|
||||
<tr><td>POST /agent/sessions/memories/purge</td><td>engine, filter, force?, confirm? (dry run by default)</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
{% endblock %}
|
||||
)SESSIONS";
|
||||
|
||||
[[noreturn]] void rethrow(const google::GoogleError& e) {
|
||||
if (e.http_status() == 503 && e.status() == "NOT_CONFIGURED")
|
||||
throw fw::HttpError(503, "google_not_configured", e.message());
|
||||
if (e.service().empty() && e.status() == "INVALID_ARGUMENT")
|
||||
throw fw::HttpError(422, "validation_error", e.message());
|
||||
throw fw::HttpError(502, "google_error", e.status() + ": " + e.message());
|
||||
}
|
||||
|
||||
template <typename F>
|
||||
auto guarded(F&& f) -> decltype(f()) {
|
||||
try {
|
||||
return f();
|
||||
} catch (const google::GoogleError& e) {
|
||||
rethrow(e);
|
||||
}
|
||||
}
|
||||
|
||||
std::string field(const Flat& in, const std::string& key) {
|
||||
auto it = in.find(key);
|
||||
return it == in.end() ? "" : it->second;
|
||||
}
|
||||
|
||||
fw::Response answer(const GJson& body, int status = 200) {
|
||||
fw::Response res = fw::JsonResponse(body.dump(), status);
|
||||
res.headers.set("Cache-Control", "no-store");
|
||||
return res;
|
||||
}
|
||||
|
||||
// Routes for one demo: resolves the engine and runs the typed services.
|
||||
class SessionsRoutes {
|
||||
public:
|
||||
explicit SessionsRoutes(std::shared_ptr<google::GoogleClient> client)
|
||||
: client_(std::move(client)) {}
|
||||
|
||||
bool configured() const { return client_->configured(); }
|
||||
|
||||
gs::EngineName engine_of(const std::string& value) const {
|
||||
if (value.rfind("projects/", 0) == 0) return gs::EngineName(value);
|
||||
google::CloudContext ctx = google::CloudContext::from_env();
|
||||
return gs::EngineName(ctx.child("reasoningEngines", value));
|
||||
}
|
||||
gs::Sessions sessions(const std::string& engine) const {
|
||||
return gs::Sessions(client_, engine_of(engine));
|
||||
}
|
||||
gs::MemoryBank bank(const std::string& engine) const {
|
||||
return gs::MemoryBank(client_, engine_of(engine));
|
||||
}
|
||||
|
||||
static gs::StringMap scope_of(const Flat& in) {
|
||||
gs::StringMap scope;
|
||||
if (!field(in, "scope_key").empty() || !field(in, "scope_value").empty())
|
||||
scope[field(in, "scope_key")] = field(in, "scope_value");
|
||||
return scope;
|
||||
}
|
||||
|
||||
private:
|
||||
std::shared_ptr<google::GoogleClient> client_;
|
||||
};
|
||||
|
||||
GJson memory_json(const gs::Memory& m) { return m.to_json(); }
|
||||
|
||||
} // namespace
|
||||
|
||||
void register_agent_sessions_demo(fw::Router& router, Services& services) {
|
||||
(void)router;
|
||||
(void)services;
|
||||
if (!services.google) services.google = google::GoogleClient::from_env();
|
||||
auto routes = std::make_shared<SessionsRoutes>(services.google);
|
||||
fw::Environment* env = services.templates.get();
|
||||
env->add_template("agent_sessions.html", kSessionsPage);
|
||||
|
||||
services.add_feature("agent sessions", "/agent/sessions");
|
||||
|
||||
router.get("/agent/sessions", "agent-sessions-page", [env](fw::Request req) {
|
||||
(void)req;
|
||||
fw::TemplateCtx ctx;
|
||||
ctx["title"] = std::string("Agent sessions");
|
||||
return fw::Response(200, env->render("agent_sessions.html", ctx),
|
||||
"text/html; charset=utf-8");
|
||||
});
|
||||
|
||||
router.get("/agent/sessions/status", "agent-sessions-status", [routes](fw::Request req) {
|
||||
(void)req;
|
||||
GJson out = GJson::object();
|
||||
out.set("configured", GJson(routes->configured()));
|
||||
out.set("surface", GJson(std::string(gs::kDiscoveryService) + " " + gs::kDiscoveryVersion));
|
||||
out.set("calls", GJson(static_cast<int>(gs::Call::kCount)));
|
||||
GJson caps = GJson::object();
|
||||
caps.set("max_session_id_chars", GJson(static_cast<int>(gs::SessionsCaps::kMaxIdChars)));
|
||||
caps.set("max_list_items", GJson(static_cast<int>(gs::SessionsCaps::kMaxListItems)));
|
||||
caps.set("max_top_k", GJson(gs::MemoryCaps::kMaxTopK));
|
||||
caps.set("max_fact_chars", GJson(static_cast<int>(gs::MemoryCaps::kMaxFactChars)));
|
||||
out.set("caps", caps);
|
||||
return answer(out);
|
||||
});
|
||||
|
||||
// Sessions ---------------------------------------------------------------
|
||||
|
||||
router.post("/agent/sessions/create", "agent-sessions-create", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::SessionSpec spec;
|
||||
spec.session_id = field(in, "session_id");
|
||||
spec.user_id = field(in, "user_id");
|
||||
spec.display_name = field(in, "display_name");
|
||||
spec.ttl = field(in, "ttl");
|
||||
return answer(routes->sessions(field(in, "engine")).create(spec).to_json(), 201);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/get", "agent-sessions-get", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
return answer(routes->sessions(field(in, "engine")).get(field(in, "session_id")).to_json());
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/list", "agent-sessions-list", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::SessionListOptions options;
|
||||
options.filter = field(in, "filter");
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::Session& s : routes->sessions(field(in, "engine")).list(options))
|
||||
arr.push(s.to_json());
|
||||
GJson out = GJson::object();
|
||||
out.set("sessions", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.del("/agent/sessions/session", "agent-sessions-delete", [routes](fw::Request req) {
|
||||
return guarded([&] {
|
||||
routes->sessions(req.query_or("engine", "")).delete_session(req.query_or("id", ""));
|
||||
GJson out = GJson::object();
|
||||
out.set("deleted", GJson(true));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/events/append", "agent-sessions-event-append",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::SessionEvent ev;
|
||||
ev.author = field(in, "author");
|
||||
ev.invocation_id = field(in, "invocation_id");
|
||||
ev.timestamp = field(in, "timestamp");
|
||||
if (!field(in, "text").empty()) {
|
||||
std::string role = field(in, "role").empty() ? "user" : field(in, "role");
|
||||
google::Content c = role == "model" ? google::Content::model(field(in, "text"))
|
||||
: google::Content::user(field(in, "text"));
|
||||
ev.content = c;
|
||||
}
|
||||
routes->sessions(field(in, "engine")).append_event(field(in, "session_id"), ev);
|
||||
GJson out = GJson::object();
|
||||
out.set("appended", GJson(true));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/events/list", "agent-sessions-event-list",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::SessionEvent& e :
|
||||
routes->sessions(field(in, "engine")).list_events(field(in, "session_id")))
|
||||
arr.push(e.to_json());
|
||||
GJson out = GJson::object();
|
||||
out.set("events", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
// Memory Bank ------------------------------------------------------------
|
||||
|
||||
router.post("/agent/sessions/memories/generate", "agent-memories-generate",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::MemoryGenerateRequest g;
|
||||
g.scope = SessionsRoutes::scope_of(in);
|
||||
if (!field(in, "session_id").empty()) {
|
||||
g.source = gs::MemoryGenerateRequest::Source::kSession;
|
||||
g.session_id = field(in, "session_id");
|
||||
} else {
|
||||
g.source = gs::MemoryGenerateRequest::Source::kContents;
|
||||
if (!field(in, "text").empty()) g.contents.push_back(google::Content::user(field(in, "text")));
|
||||
}
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::GeneratedMemory& m : routes->bank(field(in, "engine")).generate(g)) {
|
||||
GJson item = GJson::object();
|
||||
item.set("memory", memory_json(m.memory));
|
||||
item.set("action", GJson(m.action));
|
||||
arr.push(item);
|
||||
}
|
||||
GJson out = GJson::object();
|
||||
out.set("generated", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/retrieve", "agent-memories-retrieve",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::RetrieveRequest r;
|
||||
r.scope = SessionsRoutes::scope_of(in);
|
||||
r.search_query = field(in, "query");
|
||||
if (!field(in, "top_k").empty()) r.top_k = std::atoi(field(in, "top_k").c_str());
|
||||
gs::RetrieveResult res = routes->bank(field(in, "engine")).retrieve(r);
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::RetrievedMemory& m : res.memories) {
|
||||
GJson item = GJson::object();
|
||||
item.set("memory", memory_json(m.memory));
|
||||
if (m.has_distance) item.set("distance", GJson(m.distance));
|
||||
arr.push(item);
|
||||
}
|
||||
GJson out = GJson::object();
|
||||
out.set("memories", arr);
|
||||
out.set("next_page_token", GJson(res.next_page_token));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/create", "agent-memories-create",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::MemorySpec spec;
|
||||
spec.memory_id = field(in, "memory_id");
|
||||
spec.fact = field(in, "fact");
|
||||
spec.scope = SessionsRoutes::scope_of(in);
|
||||
return answer(memory_json(routes->bank(field(in, "engine")).create(spec)), 201);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/get", "agent-memories-get", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
return answer(memory_json(routes->bank(field(in, "engine")).get(field(in, "memory_id"))));
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/list", "agent-memories-list", [routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::MemoryListOptions options;
|
||||
options.filter = field(in, "filter");
|
||||
GJson arr = GJson::array();
|
||||
for (const gs::Memory& m : routes->bank(field(in, "engine")).list(options))
|
||||
arr.push(memory_json(m));
|
||||
GJson out = GJson::object();
|
||||
out.set("memories", arr);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.del("/agent/sessions/memories/memory", "agent-memories-delete",
|
||||
[routes](fw::Request req) {
|
||||
return guarded([&] {
|
||||
routes->bank(req.query_or("engine", "")).delete_memory(req.query_or("id", ""));
|
||||
GJson out = GJson::object();
|
||||
out.set("deleted", GJson(true));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
router.post("/agent/sessions/memories/profiles", "agent-memories-profiles",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
GJson profiles = GJson::object();
|
||||
for (const auto& [id, p] :
|
||||
routes->bank(field(in, "engine")).retrieve_profiles(SessionsRoutes::scope_of(in)))
|
||||
profiles.set(id, p.fields);
|
||||
GJson out = GJson::object();
|
||||
out.set("profiles", profiles);
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
|
||||
// Irreversible when force is true: needs confirm == engine id.
|
||||
router.post("/agent/sessions/memories/purge", "agent-memories-purge",
|
||||
[routes](fw::Request req) {
|
||||
Flat in = fw::parse_json_object_flat(req.body);
|
||||
return guarded([&] {
|
||||
gs::PurgeRequest p;
|
||||
p.filter = field(in, "filter");
|
||||
p.force = field(in, "force") == "true";
|
||||
p.confirm = field(in, "confirm");
|
||||
gs::PurgeResult r = routes->bank(field(in, "engine")).purge(p);
|
||||
GJson out = GJson::object();
|
||||
out.set("forced", GJson(r.forced));
|
||||
out.set("purge_count", GJson(static_cast<int>(r.purge_count)));
|
||||
return answer(out);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
} // namespace molo::example::app
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
# Google Agent Sessions and Memory Bank - Specification
|
||||
|
||||
Owned directory: `src/google/sessions/`. Namespace `molo::google::sessions`.
|
||||
Depends on the `src/google` foundation (`GoogleClient`, `Service`, `Operation`,
|
||||
`wait_operation`, `list_all`, `gemini_types.h`). Does not depend on the runtime
|
||||
module: the Agent Engine is accepted as a validated resource-name string.
|
||||
|
||||
## 1. Scope
|
||||
|
||||
Gemini Enterprise Agent Platform, Agent Engine (`reasoningEngines`) children:
|
||||
|
||||
- Agent Sessions: create (custom session id), get, list, patch, delete,
|
||||
compact, appendEvent, list events.
|
||||
- Agent Memory Bank: generate (from a session, a conversation, or given facts),
|
||||
ingestEvents (streaming), retrieve (scope, similarity search, metadata
|
||||
filters), retrieveProfiles (Memory Profiles, low-latency structured recall),
|
||||
create, get, list, patch, delete, purge (explicit, guarded), revisions
|
||||
(list, get), rollback, topics (managed and custom), scope maps, metadata.
|
||||
- Long-running operations: every mutating call returns an Operation; the module
|
||||
waits with `wait_operation` (hard caps in `OperationCaps`). `operation()`,
|
||||
`cancel_operation()` and `wait()` expose them for one engine only.
|
||||
|
||||
Everything is against one API surface: `aiplatform` **v1beta1**. See section 6
|
||||
for why not v1.
|
||||
|
||||
## 2. Module map (one class or concern per file)
|
||||
|
||||
| File | Concern |
|
||||
|---|---|
|
||||
| `caps.h` | Static ceilings (`SessionsCaps`, `MemoryCaps`) |
|
||||
| `calls.h` | The ONE table of every REST call (verb, path, discovery method, request fields, query params) |
|
||||
| `names.h/.cpp` | `EngineName` (validated resource name), `Check` (input validators), wire helpers |
|
||||
| `session_types.h/.cpp` | `SessionSpec`, `Session`, `SessionPatch`, `CompactRequest`, `SessionEvent`, list options |
|
||||
| `memory_types.h/.cpp` | `Memory`, `MemorySpec`, `MemoryPatch`, `Topic`, `MetadataValue`, `MetadataFilter`, `MemoryGenerateRequest`, `IngestRequest`, `RetrieveRequest`, `PurgeRequest`, `MemoryRevision`, `Profile` |
|
||||
| `engine_service.h/.cpp` | `EngineService : Service`: table-driven `send`, `settle`, capped `list_items`, operation helpers |
|
||||
| `sessions.h/.cpp` | `Sessions : EngineService` |
|
||||
| `memory_bank.h/.cpp` | `MemoryBank : EngineService` |
|
||||
| `tools/check_discovery.py` | Verifies `calls.h` and the typed bodies against Google's Discovery document |
|
||||
|
||||
Tests: `tests/src/google/sessions/test_sessions.cpp`. Example:
|
||||
`example/app/agent/SessionsDemo.cpp` (routes under `/agent/sessions`), tests in
|
||||
`tests/example/agent/sessions/`.
|
||||
|
||||
## 3. Static caps (see caps.h)
|
||||
|
||||
| Knob | Value |
|
||||
|---|---|
|
||||
| Session / memory id | 1..63 chars `[a-z0-9-]`; memory id starts with a letter, ends alphanumeric |
|
||||
| Engine name | `projects/{p}/locations/{l}/reasoningEngines/{e}`, 512 chars max |
|
||||
| Session TTL | `Ns` form, 24 h minimum (Google), 3650 days maximum (ours) |
|
||||
| session_state / event | 64 KiB / 256 KiB serialized |
|
||||
| Labels | 20, key and value 64 chars |
|
||||
| List pages / items | 10 pages of 100, 1000 items; more is `RESULT_TOO_LARGE`, narrow the filter |
|
||||
| Scope | 1..10 entries, 128 chars, no `*` |
|
||||
| Fact / description / context | 4000 chars |
|
||||
| Generate sources | 100 events, 64 KiB; direct memories max 5 (Google) |
|
||||
| Retrieve | query 1000 chars, top_k 0..50 (default 5), page size 0..100 |
|
||||
| Topics / metadata / filter groups | 10 / 20 entries / 10 groups of 10 filters |
|
||||
| Operation wait | `OperationCaps`: 600 s, 2 s interval, 400 polls |
|
||||
|
||||
## 4. Contracts
|
||||
|
||||
- All input and every id is validated before any network traffic and throws
|
||||
`GoogleError::invalid` (HTTP 400 `INVALID_ARGUMENT`, empty service name).
|
||||
- No credential: every call throws `NotConfiguredError` (503) before traffic.
|
||||
- Destructive calls are explicit methods: `delete_session`, `delete_memory`,
|
||||
`purge`. `purge` is a server-side dry run unless `force` is set, and a forced
|
||||
purge additionally needs `confirm` equal to the engine id (local guard).
|
||||
Compaction rewrites history and is its own method.
|
||||
- Request bodies are built only from fields named in the `calls.h` row of the
|
||||
call (tested), and those fields are checked against the discovery schema.
|
||||
- Unknown response parts stay raw `Json` (event `actions`, `eventMetadata`,
|
||||
`rawEvent`, `sessionState`, memory `metadata`, `structuredContent`, profile
|
||||
fields).
|
||||
- Example routes: GET pages answer 2xx without a credential; every route that
|
||||
calls Google is POST or DELETE and answers 503 `google_not_configured`
|
||||
without a credential and 422 on bad input.
|
||||
|
||||
## 5. Verified against discovery
|
||||
|
||||
`python3 -I src/google/sessions/tools/check_discovery.py` fetches
|
||||
`https://aiplatform.googleapis.com/$discovery/rest?version=v1beta1` (no
|
||||
credential) and fails if a declared call, verb, path, request field, query
|
||||
parameter, enum value, response key or nested request field is absent.
|
||||
|
||||
Result 2026-10-24: `OK 2026-10-24: 23 calls, 7 enums, 25 response keys, 18
|
||||
nested schemas match aiplatform v1beta1 discovery`. A deliberately misspelled
|
||||
field made it exit 1 (checked). Rerun it after any change to `calls.h` or the
|
||||
typed bodies.
|
||||
|
||||
From discovery (v1beta1, `projects.locations.reasoningEngines`):
|
||||
sessions create (POST, `sessionId` query, returns Operation), get, list
|
||||
(`filter orderBy pageSize pageToken`), patch (`updateMask`), delete (returns
|
||||
Operation), appendEvent (POST `:appendEvent`, body `SessionEvent`), compact
|
||||
(POST `:compact`, returns Operation), events.list (`sessionEvents`);
|
||||
memories generate / retrieve / retrieveProfiles / create (`memoryId`) / get /
|
||||
list / patch (`updateMask`) / delete / purge / rollback / ingestEvents,
|
||||
memories.revisions list / get; operations get / cancel. Discovery also lists
|
||||
`wait`, `list`, `delete` on operations, which this module does not wrap
|
||||
(`wait_operation` polls with GET).
|
||||
|
||||
## 6. Verified live
|
||||
|
||||
Read-only, 2026-10-24, project read from `GOOGLE_CLOUD_PROJECT`, no resource
|
||||
created, changed or deleted. Two credentials:
|
||||
|
||||
Express API key (`AQ.`):
|
||||
|
||||
| Call | Result |
|
||||
|---|---|
|
||||
| GET `v1/.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc}` | 401 `UNAUTHENTICATED`: "API keys are not supported by this API" |
|
||||
| GET `v1beta1/.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc, memories/abc/revisions}` | 404 `NOT_FOUND` "The ReasoningEngine does not exist." (key accepted, path routed) |
|
||||
| GET `v1beta1/.../reasoningEngines/1/operations/1` | 404 `NOT_FOUND` "Operation ... not found." |
|
||||
|
||||
Service-account OAuth bearer token (token exchange, never stored):
|
||||
|
||||
| Call | Result |
|
||||
|---|---|
|
||||
| GET `v1` and `v1beta1` `.../reasoningEngines` | 200 `{}` (no engine exists) |
|
||||
| GET `v1` and `v1beta1` `.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc, memories/abc/revisions}` | 404 `NOT_FOUND` "The ReasoningEngine does not exist." |
|
||||
| GET `v1` and `v1beta1` `.../reasoningEngines/1/operations/1` | 404 `NOT_FOUND` "Operation ... not found." |
|
||||
|
||||
The module uses v1beta1 only because it is the one surface that accepts both
|
||||
an express key and a token; v1 refuses keys. The opt-in test `sessions_live`
|
||||
(`MOLO_LIVE_NET=1`, `GOOGLE_API_KEY` or `GOOGLE_ACCESS_TOKEN`,
|
||||
`GOOGLE_CLOUD_PROJECT`; loud SKIP otherwise) repeats six of the reads through
|
||||
the real client (sessions list / get / events, memories list / get /
|
||||
revisions) and passed with the key and with the token on 2026-10-24.
|
||||
|
||||
No Agent Engine exists in the project, so **no happy path was verified
|
||||
live**: create, patch, delete, append, compact, generate, ingest, retrieve,
|
||||
retrieveProfiles, purge, rollback are verified by discovery only. Nothing that
|
||||
costs money was called.
|
||||
|
||||
## 7. Unverified
|
||||
|
||||
Neither discovery nor the docs pages read state these; they are inferred:
|
||||
|
||||
- Operation `response` bodies (discovery types them as `Any`): that generate
|
||||
answers `{"generatedMemories":[{"memory":{...},"action":"..."}]}`, that purge
|
||||
answers `{"purgeCount":N}`, that create and patch answer the resource
|
||||
(`name`, ...). Parsers are tolerant: missing keys give empty results, and
|
||||
create/patch fall back to a GET when the id is known.
|
||||
- `GeneratedMemory.action` values (not enumerated anywhere read).
|
||||
- That `delete` Operations are returned `done` or pollable at `operations/{id}`
|
||||
under the engine (the path shape follows discovery's `operations.get`).
|
||||
- Filter grammar (AIP-160) beyond the field names the docs list: `topics`,
|
||||
`scope` as a JSON string with equality, `timestamp` ranges for events,
|
||||
`displayName` / `userId` / `labels.k` for sessions.
|
||||
- Similarity search needs the engine's Memory Bank configured with a similarity
|
||||
search model (docs); the error body when it is not is unread.
|
||||
- Memory Profiles need schema configs on the engine (`MemoryBankConfig` in the
|
||||
runtime module); the shape of `profile` is free-form and kept raw.
|
||||
- Managed topic names beyond the four in discovery, and `thought`/`audio` parts
|
||||
inside event `content` (typed by `gemini_types.h`, unknown parts dropped).
|
||||
|
||||
## 8. Gaps
|
||||
|
||||
- `servingProfiles` (location-level create/get/list/patch for Gemini Live,
|
||||
Interactions and Response APIs) is listed by discovery next to this product
|
||||
but is not engine-scoped; not implemented here. Owner: the `live` or
|
||||
`models` module.
|
||||
- Engine-level Memory Bank configuration (`contextSpec.memoryBankConfig`,
|
||||
customization, TTL config) is part of the Agent Engine resource: runtime
|
||||
module.
|
||||
- Operations `list`, `delete`, `wait` (server-side) are not wrapped.
|
||||
- Session and memory `labels` / `metadata` filters beyond a passthrough string.
|
||||
- Token refresh is the caller's job (foundation gap).
|
||||
@@ -0,0 +1,99 @@
|
||||
#pragma once
|
||||
|
||||
// The ONE table of every REST call this module makes. Each row is checked
|
||||
// against Google's Discovery document by tools/check_discovery.py (method id,
|
||||
// HTTP verb, path, request schema fields, query parameters), and every
|
||||
// request builder in this module takes its verb and path from here.
|
||||
//
|
||||
// Surface: aiplatform v1beta1. Probed live (2026-10-24): v1 answers 401
|
||||
// "API keys are not supported" for sessions and memories, v1beta1 accepts an
|
||||
// express API key (404 for a missing engine). See SPEC.md.
|
||||
//
|
||||
// Row: {Call, verb, path template, discovery method (under
|
||||
// aiplatform.projects.locations.reasoningEngines.), request schema suffix
|
||||
// (after GoogleCloudAiplatformV1beta1), request fields used, query params used}.
|
||||
|
||||
#include <string>
|
||||
|
||||
#include "clients/client.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
inline constexpr const char* kDiscoveryService = "aiplatform";
|
||||
inline constexpr const char* kDiscoveryVersion = "v1beta1";
|
||||
inline constexpr const char* kDiscoveryPrefix =
|
||||
"aiplatform.projects.locations.reasoningEngines.";
|
||||
|
||||
enum class Call {
|
||||
kSessionCreate, kSessionGet, kSessionList, kSessionPatch, kSessionDelete,
|
||||
kSessionAppendEvent, kSessionCompact, kEventList,
|
||||
kMemoryGenerate, kMemoryRetrieve, kMemoryRetrieveProfiles, kMemoryCreate,
|
||||
kMemoryGet, kMemoryList, kMemoryPatch, kMemoryDelete, kMemoryPurge,
|
||||
kMemoryRollback, kMemoryIngestEvents, kRevisionList, kRevisionGet,
|
||||
kOperationGet, kOperationCancel,
|
||||
kCount
|
||||
};
|
||||
|
||||
struct CallSpec {
|
||||
Call call;
|
||||
const char* verb;
|
||||
const char* path;
|
||||
const char* method;
|
||||
const char* request;
|
||||
const char* fields;
|
||||
const char* query;
|
||||
};
|
||||
|
||||
// clang-format off
|
||||
inline constexpr CallSpec kCalls[] = {
|
||||
{Call::kSessionCreate, "POST", "/{parent}/sessions", "sessions.create", "Session", "userId displayName labels sessionState ttl", "sessionId"},
|
||||
{Call::kSessionGet, "GET", "/{name}", "sessions.get", "", "", ""},
|
||||
{Call::kSessionList, "GET", "/{parent}/sessions", "sessions.list", "", "", "filter orderBy pageSize pageToken"},
|
||||
{Call::kSessionPatch, "PATCH", "/{name}", "sessions.patch", "Session", "displayName labels sessionState ttl", "updateMask"},
|
||||
{Call::kSessionDelete, "DELETE", "/{name}", "sessions.delete", "", "", ""},
|
||||
{Call::kSessionAppendEvent, "POST", "/{name}:appendEvent", "sessions.appendEvent", "SessionEvent", "author invocationId timestamp content actions errorCode errorMessage eventMetadata rawEvent", ""},
|
||||
{Call::kSessionCompact, "POST", "/{name}:compact", "sessions.compact", "CompactSessionRequest", "compaction", ""},
|
||||
{Call::kEventList, "GET", "/{parent}/events", "sessions.events.list", "", "", "filter orderBy pageSize pageToken"},
|
||||
{Call::kMemoryGenerate, "POST", "/{parent}/memories:generate", "memories.generate", "GenerateMemoriesRequest", "scope disableConsolidation allowedTopics vertexSessionSource directContentsSource directMemoriesSource metadata metadataMergeStrategy timeZone revisionLabels revisionTtl revisionExpireTime disableMemoryRevisions", ""},
|
||||
{Call::kMemoryRetrieve, "POST", "/{parent}/memories:retrieve", "memories.retrieve", "RetrieveMemoriesRequest", "scope filter filterGroups memoryTypes similaritySearchParams simpleRetrievalParams", ""},
|
||||
{Call::kMemoryRetrieveProfiles, "POST", "/{parent}/memories:retrieveProfiles", "memories.retrieveProfiles", "RetrieveProfilesRequest", "scope", ""},
|
||||
{Call::kMemoryCreate, "POST", "/{parent}/memories", "memories.create", "Memory", "fact scope displayName description context topics ttl metadata revisionLabels revisionTtl disableMemoryRevisions memoryType structuredContent", "memoryId"},
|
||||
{Call::kMemoryGet, "GET", "/{name}", "memories.get", "", "", ""},
|
||||
{Call::kMemoryList, "GET", "/{parent}/memories", "memories.list", "", "", "filter orderBy pageSize pageToken"},
|
||||
{Call::kMemoryPatch, "PATCH", "/{name}", "memories.patch", "Memory", "fact displayName description context topics ttl metadata revisionLabels revisionTtl disableMemoryRevisions structuredContent", "updateMask"},
|
||||
{Call::kMemoryDelete, "DELETE", "/{name}", "memories.delete", "", "", ""},
|
||||
{Call::kMemoryPurge, "POST", "/{parent}/memories:purge", "memories.purge", "PurgeMemoriesRequest", "filter filterGroups force", ""},
|
||||
{Call::kMemoryRollback, "POST", "/{name}:rollback", "memories.rollback", "RollbackMemoryRequest", "targetRevisionId", ""},
|
||||
{Call::kMemoryIngestEvents, "POST", "/{parent}/memories:ingestEvents", "memories.ingestEvents", "IngestEventsRequest", "scope streamId forceFlush directContentsSource generationTriggerConfig revisionTtl disableMemoryRevisions revisionLabels metadata metadataMergeStrategy", ""},
|
||||
{Call::kRevisionList, "GET", "/{parent}/revisions", "memories.revisions.list", "", "", "filter pageSize pageToken"},
|
||||
{Call::kRevisionGet, "GET", "/{name}", "memories.revisions.get", "", "", ""},
|
||||
{Call::kOperationGet, "GET", "/{name}", "operations.get", "", "", ""},
|
||||
{Call::kOperationCancel, "POST", "/{name}:cancel", "operations.cancel", "", "", ""},
|
||||
};
|
||||
// clang-format on
|
||||
|
||||
inline const CallSpec& spec_of(Call call) {
|
||||
for (const CallSpec& row : kCalls)
|
||||
if (row.call == call) return row;
|
||||
return kCalls[0]; // Unreachable: every enumerator has a row (tested).
|
||||
}
|
||||
|
||||
inline clients::Method verb_of(const CallSpec& spec) {
|
||||
std::string v = spec.verb;
|
||||
if (v == "POST") return clients::Method::kPost;
|
||||
if (v == "PATCH") return clients::Method::kPatch;
|
||||
if (v == "DELETE") return clients::Method::kDelete;
|
||||
return clients::Method::kGet;
|
||||
}
|
||||
|
||||
// Substitutes the single {parent} or {name} placeholder with a validated
|
||||
// resource name and appends an encoded query string.
|
||||
inline std::string expand(Call call, const std::string& resource,
|
||||
const std::string& query = "") {
|
||||
std::string path = spec_of(call).path;
|
||||
std::size_t open = path.find('{');
|
||||
std::size_t close = path.find('}');
|
||||
return path.substr(0, open) + resource + path.substr(close + 1) + query;
|
||||
}
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,50 @@
|
||||
#pragma once
|
||||
|
||||
// Static ceilings for Agent Sessions and Agent Memory Bank. Never autotuned.
|
||||
|
||||
#include <cstddef>
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
struct SessionsCaps {
|
||||
static constexpr std::size_t kMaxIdChars = 63; // Google: [a-z0-9-], 63
|
||||
static constexpr std::size_t kMaxNameChars = 512; // resource name
|
||||
static constexpr std::size_t kMaxUserIdChars = 128;
|
||||
static constexpr std::size_t kMaxDisplayChars = 128;
|
||||
static constexpr std::size_t kMaxLabels = 20;
|
||||
static constexpr std::size_t kMaxLabelChars = 64; // key and value
|
||||
static constexpr std::size_t kMaxStateBytes = 64 * 1024;
|
||||
static constexpr std::size_t kMaxEventBytes = 256 * 1024;
|
||||
static constexpr std::size_t kMaxFilterChars = 512;
|
||||
static constexpr std::size_t kMaxTimestampChars = 40;
|
||||
static constexpr int kMinTtlSeconds = 24 * 3600; // Google minimum
|
||||
static constexpr long kMaxTtlSeconds = 3650L * 24 * 3600;
|
||||
static constexpr int kPageSize = 100; // Google ceiling
|
||||
static constexpr std::size_t kMaxListPages = 10;
|
||||
static constexpr std::size_t kMaxListItems = 1000;
|
||||
};
|
||||
|
||||
struct MemoryCaps {
|
||||
static constexpr std::size_t kMaxFactChars = 4000;
|
||||
static constexpr std::size_t kMaxQueryChars = 1000;
|
||||
static constexpr std::size_t kMaxScopeEntries = 10;
|
||||
static constexpr std::size_t kMaxScopeChars = 128; // key and value
|
||||
static constexpr std::size_t kMaxTopics = 10;
|
||||
static constexpr std::size_t kMaxTopicLabelChars = 64;
|
||||
static constexpr std::size_t kMaxDirectMemories = 5; // Google
|
||||
static constexpr std::size_t kMaxSourceEvents = 100; // generate from contents
|
||||
static constexpr std::size_t kMaxSourceBytes = 64 * 1024;
|
||||
static constexpr std::size_t kMaxMetadataEntries = 20;
|
||||
static constexpr std::size_t kMaxMetadataChars = 256; // key and string value
|
||||
static constexpr std::size_t kMaxFilterGroups = 10;
|
||||
static constexpr std::size_t kMaxFiltersPerGroup = 10;
|
||||
static constexpr std::size_t kMaxMemoryTypes = 2;
|
||||
static constexpr std::size_t kMaxUpdateMaskChars = 256;
|
||||
static constexpr int kMaxTopK = 50;
|
||||
static constexpr int kDefaultTopK = 5;
|
||||
static constexpr int kPageSize = 100;
|
||||
static constexpr std::size_t kMaxListPages = 10;
|
||||
static constexpr std::size_t kMaxListItems = 1000;
|
||||
};
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,73 @@
|
||||
#include "google/sessions/engine_service.h"
|
||||
|
||||
#include "google/resource.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
using clients::body::Json;
|
||||
|
||||
EngineService::EngineService(std::shared_ptr<GoogleClient> client, EngineName engine,
|
||||
Sleeper sleeper)
|
||||
: Service(std::move(client), endpoints::aiplatform_beta(engine.location())),
|
||||
engine_name_(std::move(engine)),
|
||||
sleeper_(std::move(sleeper)) {}
|
||||
|
||||
Json EngineService::send(Call call, const std::string& resource, const Json* body,
|
||||
const std::string& query) const {
|
||||
const CallSpec& row = spec_of(call);
|
||||
return client_->request(verb_of(row), endpoint_, expand(call, resource, query), body);
|
||||
}
|
||||
|
||||
Operation EngineService::settle(const Json& reply) const {
|
||||
Operation op = Operation::from_json(reply);
|
||||
if (op.done) {
|
||||
if (op.failed())
|
||||
throw GoogleError(502, "OPERATION_FAILED", op.error_message, endpoint_.name);
|
||||
return op;
|
||||
}
|
||||
if (op.name.empty())
|
||||
throw GoogleError(502, "EMPTY_RESPONSE", "no operation returned", endpoint_.name);
|
||||
return wait(op.name);
|
||||
}
|
||||
|
||||
namespace {
|
||||
void check_operation_name(const EngineName& engine, const std::string& name) {
|
||||
const std::string prefix = engine.str() + "/";
|
||||
bool ok = name.size() > prefix.size() && name.compare(0, prefix.size(), prefix) == 0 &&
|
||||
name.find("/operations/") != std::string::npos &&
|
||||
name.find("..") == std::string::npos && name.find('?') == std::string::npos &&
|
||||
name.size() <= 512;
|
||||
if (!ok) throw GoogleError::invalid("operation name must belong to this engine");
|
||||
}
|
||||
} // namespace
|
||||
|
||||
Json EngineService::operation(const std::string& operation_name) const {
|
||||
check_operation_name(engine_name_, operation_name);
|
||||
return send(Call::kOperationGet, operation_name);
|
||||
}
|
||||
|
||||
void EngineService::cancel_operation(const std::string& operation_name) const {
|
||||
check_operation_name(engine_name_, operation_name);
|
||||
Json empty = Json::object();
|
||||
send(Call::kOperationCancel, operation_name, &empty);
|
||||
}
|
||||
|
||||
Operation EngineService::wait(const std::string& operation_name) const {
|
||||
check_operation_name(engine_name_, operation_name);
|
||||
return wait_operation(*client_, endpoint_, operation_name, sleeper_);
|
||||
}
|
||||
|
||||
Json EngineService::list_items(Call call, const std::string& resource,
|
||||
const std::string& query, const std::string& items_key,
|
||||
std::size_t max_pages, std::size_t max_items) const {
|
||||
Json items = list_all(*client_, endpoint_, expand(call, resource, query), items_key,
|
||||
max_pages);
|
||||
if (items.as_array().size() > max_items)
|
||||
throw GoogleError(502, "RESULT_TOO_LARGE",
|
||||
"more than " + std::to_string(max_items) +
|
||||
" items; narrow the filter",
|
||||
endpoint_.name);
|
||||
return items;
|
||||
}
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,48 @@
|
||||
#pragma once
|
||||
|
||||
// Base of Sessions and MemoryBank: one validated Agent Engine, the v1beta1
|
||||
// aiplatform endpoint of its location, table-driven requests (calls.h) and
|
||||
// long-running operation handling shared by both.
|
||||
|
||||
#include <memory>
|
||||
#include <string>
|
||||
|
||||
#include "google/operation.h"
|
||||
#include "google/service.h"
|
||||
#include "google/sessions/calls.h"
|
||||
#include "google/sessions/names.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
class EngineService : public Service {
|
||||
public:
|
||||
const EngineName& engine() const { return engine_name_; }
|
||||
|
||||
// Raw operation document (GET) and cancel (POST :cancel). The name must be
|
||||
// an operation of this engine; nothing else is reachable through here.
|
||||
clients::body::Json operation(const std::string& operation_name) const;
|
||||
void cancel_operation(const std::string& operation_name) const;
|
||||
// Polls until done (hard caps in OperationCaps); throws on failure.
|
||||
Operation wait(const std::string& operation_name) const;
|
||||
|
||||
protected:
|
||||
EngineService(std::shared_ptr<GoogleClient> client, EngineName engine,
|
||||
Sleeper sleeper);
|
||||
|
||||
// One table-driven request. `resource` fills the {parent} / {name} slot.
|
||||
clients::body::Json send(Call call, const std::string& resource,
|
||||
const clients::body::Json* body = nullptr,
|
||||
const std::string& query = "") const;
|
||||
// Follows an Operation reply to completion (done replies are checked).
|
||||
Operation settle(const clients::body::Json& reply) const;
|
||||
// Paged list through the table; caps pages and total items.
|
||||
clients::body::Json list_items(Call call, const std::string& resource,
|
||||
const std::string& query,
|
||||
const std::string& items_key,
|
||||
std::size_t max_pages, std::size_t max_items) const;
|
||||
|
||||
EngineName engine_name_;
|
||||
Sleeper sleeper_;
|
||||
};
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,178 @@
|
||||
#include "google/sessions/memory_bank.h"
|
||||
|
||||
#include "google/resource.h"
|
||||
#include "google/sessions/caps.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
using clients::body::Json;
|
||||
|
||||
namespace {
|
||||
|
||||
void check_revision_id(const std::string& id) {
|
||||
if (!valid_segment(id)) throw GoogleError::invalid("bad revision id");
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
MemoryBank::MemoryBank(std::shared_ptr<GoogleClient> client, EngineName engine,
|
||||
Sleeper sleeper)
|
||||
: EngineService(std::move(client), std::move(engine), std::move(sleeper)) {}
|
||||
|
||||
std::vector<GeneratedMemory> MemoryBank::generate(const MemoryGenerateRequest& request) const {
|
||||
request.validate();
|
||||
Json body = request.to_json(engine_name_.str());
|
||||
Operation op = settle(send(Call::kMemoryGenerate, engine_name_.str(), &body));
|
||||
std::vector<GeneratedMemory> out;
|
||||
const Json* list =
|
||||
op.response.is_object() ? op.response.find("generatedMemories") : nullptr;
|
||||
if (list && list->is_array())
|
||||
for (const Json& item : list->as_array()) {
|
||||
GeneratedMemory g;
|
||||
if (const Json* m = item.find("memory")) g.memory = Memory::from_json(*m);
|
||||
g.action = str_at(item, "action");
|
||||
out.push_back(std::move(g));
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
void MemoryBank::ingest_events(const IngestRequest& request) const {
|
||||
request.validate();
|
||||
Json body = request.to_json();
|
||||
settle(send(Call::kMemoryIngestEvents, engine_name_.str(), &body));
|
||||
}
|
||||
|
||||
RetrieveResult MemoryBank::retrieve(const RetrieveRequest& request) const {
|
||||
request.validate();
|
||||
Json body = request.to_json();
|
||||
Json reply = send(Call::kMemoryRetrieve, engine_name_.str(), &body);
|
||||
RetrieveResult out;
|
||||
const Json* list = reply.find("retrievedMemories");
|
||||
if (list && list->is_array()) {
|
||||
if (list->as_array().size() > MemoryCaps::kMaxListItems)
|
||||
throw GoogleError(502, "RESULT_TOO_LARGE", "retrieve returned too many memories",
|
||||
endpoint_.name);
|
||||
for (const Json& item : list->as_array()) {
|
||||
RetrievedMemory r;
|
||||
if (const Json* m = item.find("memory")) r.memory = Memory::from_json(*m);
|
||||
if (const Json* d = item.find("distance"); d && d->is_number()) {
|
||||
r.distance = d->as_number();
|
||||
r.has_distance = true;
|
||||
}
|
||||
out.memories.push_back(std::move(r));
|
||||
}
|
||||
}
|
||||
out.next_page_token = str_at(reply, "nextPageToken");
|
||||
return out;
|
||||
}
|
||||
|
||||
std::map<std::string, Profile> MemoryBank::retrieve_profiles(const StringMap& scope) const {
|
||||
Check::scope(scope);
|
||||
Json body = Json::object();
|
||||
body.set("scope", to_json(scope));
|
||||
Json reply = send(Call::kMemoryRetrieveProfiles, engine_name_.str(), &body);
|
||||
std::map<std::string, Profile> out;
|
||||
const Json* profiles = reply.find("profiles");
|
||||
if (profiles && profiles->is_object())
|
||||
for (const auto& [key, value] : profiles->as_object()) {
|
||||
if (out.size() >= MemoryCaps::kMaxListItems) break;
|
||||
Profile p;
|
||||
p.schema_id = str_at(value, "schemaId");
|
||||
if (p.schema_id.empty()) p.schema_id = key;
|
||||
if (const Json* f = value.find("profile")) p.fields = *f;
|
||||
out[key] = std::move(p);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
Memory MemoryBank::create(const MemorySpec& spec) const {
|
||||
spec.validate();
|
||||
Json body = spec.to_json();
|
||||
Operation op = settle(send(Call::kMemoryCreate, engine_name_.str(), &body,
|
||||
query_of({{"memoryId", spec.memory_id}})));
|
||||
if (op.response.is_object() && !str_at(op.response, "name").empty())
|
||||
return Memory::from_json(op.response);
|
||||
if (!spec.memory_id.empty()) return get(spec.memory_id);
|
||||
throw GoogleError(502, "EMPTY_RESPONSE", "create returned no memory", endpoint_.name);
|
||||
}
|
||||
|
||||
Memory MemoryBank::get(const std::string& memory_id) const {
|
||||
return Memory::from_json(send(Call::kMemoryGet, engine_name_.memory(memory_id)));
|
||||
}
|
||||
|
||||
std::vector<Memory> MemoryBank::list(const MemoryListOptions& options) const {
|
||||
Check::expression("filter", options.filter);
|
||||
Check::expression("order_by", options.order_by);
|
||||
Check::page_size(options.page_size, MemoryCaps::kPageSize);
|
||||
Json items = list_items(
|
||||
Call::kMemoryList, engine_name_.str(),
|
||||
query_of({{"filter", options.filter},
|
||||
{"orderBy", options.order_by},
|
||||
{"pageSize", options.page_size > 0 ? std::to_string(options.page_size) : ""}}),
|
||||
"memories", MemoryCaps::kMaxListPages, MemoryCaps::kMaxListItems);
|
||||
std::vector<Memory> out;
|
||||
for (const Json& item : items.as_array()) out.push_back(Memory::from_json(item));
|
||||
return out;
|
||||
}
|
||||
|
||||
Memory MemoryBank::patch(const MemoryPatch& patch) const {
|
||||
patch.validate();
|
||||
Json body = patch.to_json();
|
||||
Operation op = settle(send(Call::kMemoryPatch, engine_name_.memory(patch.memory_id),
|
||||
&body, query_of({{"updateMask", patch.update_mask}})));
|
||||
if (op.response.is_object() && !str_at(op.response, "name").empty())
|
||||
return Memory::from_json(op.response);
|
||||
return get(patch.memory_id);
|
||||
}
|
||||
|
||||
void MemoryBank::delete_memory(const std::string& memory_id) const {
|
||||
Json reply = send(Call::kMemoryDelete, engine_name_.memory(memory_id));
|
||||
if (reply.is_object() && !reply.as_object().empty()) settle(reply);
|
||||
}
|
||||
|
||||
PurgeResult MemoryBank::purge(const PurgeRequest& request) const {
|
||||
Check::expression("filter", request.filter);
|
||||
if (request.filter.empty()) throw GoogleError::invalid("purge needs a filter");
|
||||
check_filter_groups(request.filter_groups);
|
||||
if (request.force && request.confirm != engine_name_.engine())
|
||||
throw GoogleError::invalid("forced purge is irreversible: set confirm to the engine id");
|
||||
Json body = Json::object();
|
||||
body.set("filter", Json(request.filter));
|
||||
if (!request.filter_groups.empty())
|
||||
body.set("filterGroups", filter_groups_json(request.filter_groups));
|
||||
body.set("force", Json(request.force));
|
||||
Operation op = settle(send(Call::kMemoryPurge, engine_name_.str(), &body));
|
||||
PurgeResult out;
|
||||
out.forced = request.force;
|
||||
if (op.response.is_object())
|
||||
out.purge_count = static_cast<long>(number_at(op.response, "purgeCount", 0));
|
||||
return out;
|
||||
}
|
||||
|
||||
std::vector<MemoryRevision> MemoryBank::list_revisions(const std::string& memory_id,
|
||||
const std::string& filter) const {
|
||||
Check::expression("filter", filter);
|
||||
Json items = list_items(Call::kRevisionList, engine_name_.memory(memory_id),
|
||||
query_of({{"filter", filter}}), "memoryRevisions",
|
||||
MemoryCaps::kMaxListPages, MemoryCaps::kMaxListItems);
|
||||
std::vector<MemoryRevision> out;
|
||||
for (const Json& item : items.as_array()) out.push_back(MemoryRevision::from_json(item));
|
||||
return out;
|
||||
}
|
||||
|
||||
MemoryRevision MemoryBank::get_revision(const std::string& memory_id,
|
||||
const std::string& revision_id) const {
|
||||
check_revision_id(revision_id);
|
||||
return MemoryRevision::from_json(
|
||||
send(Call::kRevisionGet, engine_name_.memory(memory_id) + "/revisions/" + revision_id));
|
||||
}
|
||||
|
||||
void MemoryBank::rollback(const std::string& memory_id,
|
||||
const std::string& revision_id) const {
|
||||
check_revision_id(revision_id);
|
||||
Json body = Json::object();
|
||||
body.set("targetRevisionId", Json(revision_id));
|
||||
settle(send(Call::kMemoryRollback, engine_name_.memory(memory_id), &body));
|
||||
}
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,46 @@
|
||||
#pragma once
|
||||
|
||||
// Agent Memory Bank under one Agent Engine resource. Every call is a row in
|
||||
// calls.h; every Operation is waited with wait_operation.
|
||||
|
||||
#include <map>
|
||||
#include <memory>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
#include "google/sessions/engine_service.h"
|
||||
#include "google/sessions/memory_types.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
class MemoryBank : public EngineService {
|
||||
public:
|
||||
MemoryBank(std::shared_ptr<GoogleClient> client, EngineName engine,
|
||||
Sleeper sleeper = nullptr);
|
||||
|
||||
// Extract memories from a session, a conversation or given facts.
|
||||
std::vector<GeneratedMemory> generate(const MemoryGenerateRequest& request) const;
|
||||
// Streaming ingestion; generation fires by rule or force_flush.
|
||||
void ingest_events(const IngestRequest& request) const;
|
||||
RetrieveResult retrieve(const RetrieveRequest& request) const;
|
||||
// Low-latency recall of structured profiles (Memory Profiles), keyed by
|
||||
// schema id.
|
||||
std::map<std::string, Profile> retrieve_profiles(const StringMap& scope) const;
|
||||
|
||||
Memory create(const MemorySpec& spec) const;
|
||||
Memory get(const std::string& memory_id) const;
|
||||
std::vector<Memory> list(const MemoryListOptions& options = {}) const;
|
||||
Memory patch(const MemoryPatch& patch) const;
|
||||
// Destructive: explicit method, waits for the delete operation.
|
||||
void delete_memory(const std::string& memory_id) const;
|
||||
// Destructive and irreversible when request.force is true (see PurgeRequest).
|
||||
PurgeResult purge(const PurgeRequest& request) const;
|
||||
|
||||
std::vector<MemoryRevision> list_revisions(const std::string& memory_id,
|
||||
const std::string& filter = "") const;
|
||||
MemoryRevision get_revision(const std::string& memory_id,
|
||||
const std::string& revision_id) const;
|
||||
void rollback(const std::string& memory_id, const std::string& revision_id) const;
|
||||
};
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,485 @@
|
||||
#include "google/sessions/memory_types.h"
|
||||
|
||||
#include "google/errors.h"
|
||||
#include "google/sessions/caps.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
using clients::body::Json;
|
||||
|
||||
namespace {
|
||||
|
||||
[[noreturn]] void bad(const std::string& message) {
|
||||
throw GoogleError::invalid(message);
|
||||
}
|
||||
|
||||
void check_topics(const std::vector<Topic>& topics) {
|
||||
if (topics.size() > MemoryCaps::kMaxTopics)
|
||||
bad("topics over " + std::to_string(MemoryCaps::kMaxTopics));
|
||||
for (const Topic& t : topics) t.validate();
|
||||
}
|
||||
|
||||
Json topics_json(const std::vector<Topic>& topics) {
|
||||
Json arr = Json::array();
|
||||
for (const Topic& t : topics) arr.push(t.to_json());
|
||||
return arr;
|
||||
}
|
||||
|
||||
void check_metadata(const Metadata& metadata) {
|
||||
if (metadata.size() > MemoryCaps::kMaxMetadataEntries)
|
||||
bad("metadata over " + std::to_string(MemoryCaps::kMaxMetadataEntries) + " entries");
|
||||
for (const auto& [k, v] : metadata) {
|
||||
Check::text("metadata key", k, MemoryCaps::kMaxMetadataChars, true);
|
||||
v.validate();
|
||||
}
|
||||
}
|
||||
|
||||
void check_mask(const std::string& mask) {
|
||||
Check::text("update_mask", mask, MemoryCaps::kMaxUpdateMaskChars, true);
|
||||
for (char c : mask) {
|
||||
bool ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') ||
|
||||
(c >= '0' && c <= '9') || c == ',' || c == '.' || c == '_';
|
||||
if (!ok) bad("update_mask allows letters, digits, comma, dot, underscore");
|
||||
}
|
||||
}
|
||||
|
||||
void check_strategy(const std::string& s) {
|
||||
if (s.empty() || s == "OVERWRITE" || s == "MERGE" || s == "REQUIRE_EXACT_MATCH") return;
|
||||
bad("metadata_merge_strategy must be OVERWRITE, MERGE or REQUIRE_EXACT_MATCH");
|
||||
}
|
||||
|
||||
void put_structured(Json& body, const Json& structured) {
|
||||
if (structured.is_object()) body.set("structuredContent", structured);
|
||||
}
|
||||
|
||||
void check_structured(const Json& structured) {
|
||||
if (structured.is_null()) return;
|
||||
if (!structured.is_object() || !structured.has("schemaId") || !structured.has("data"))
|
||||
bad("structured_content needs schemaId and data");
|
||||
if (structured.dump().size() > MemoryCaps::kMaxFactChars * 4)
|
||||
bad("structured_content too large");
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
Topic Topic::managed(std::string name) { return Topic{Kind::kManaged, std::move(name)}; }
|
||||
Topic Topic::custom(std::string label) { return Topic{Kind::kCustom, std::move(label)}; }
|
||||
|
||||
void Topic::validate() const {
|
||||
Check::text("topic", value, MemoryCaps::kMaxTopicLabelChars, true);
|
||||
if (kind == Kind::kManaged)
|
||||
for (char c : value)
|
||||
if (!((c >= 'A' && c <= 'Z') || c == '_'))
|
||||
bad("managed topic must be an enum name like USER_PREFERENCES");
|
||||
}
|
||||
|
||||
Json Topic::to_json() const {
|
||||
Json out = Json::object();
|
||||
out.set(kind == Kind::kManaged ? "managedMemoryTopic" : "customMemoryTopicLabel",
|
||||
Json(value));
|
||||
return out;
|
||||
}
|
||||
|
||||
Topic Topic::from_json(const Json& doc) {
|
||||
std::string managed_name = str_at(doc, "managedMemoryTopic");
|
||||
if (!managed_name.empty()) return managed(managed_name);
|
||||
return custom(str_at(doc, "customMemoryTopicLabel"));
|
||||
}
|
||||
|
||||
MetadataValue MetadataValue::of_string(std::string v) {
|
||||
MetadataValue m;
|
||||
m.kind = Kind::kString;
|
||||
m.text = std::move(v);
|
||||
return m;
|
||||
}
|
||||
MetadataValue MetadataValue::of_double(double v) {
|
||||
MetadataValue m;
|
||||
m.kind = Kind::kDouble;
|
||||
m.number = v;
|
||||
return m;
|
||||
}
|
||||
MetadataValue MetadataValue::of_bool(bool v) {
|
||||
MetadataValue m;
|
||||
m.kind = Kind::kBool;
|
||||
m.flag = v;
|
||||
return m;
|
||||
}
|
||||
MetadataValue MetadataValue::of_timestamp(std::string v) {
|
||||
MetadataValue m;
|
||||
m.kind = Kind::kTimestamp;
|
||||
m.text = std::move(v);
|
||||
return m;
|
||||
}
|
||||
|
||||
void MetadataValue::validate() const {
|
||||
if (kind == Kind::kString)
|
||||
Check::text("metadata value", text, MemoryCaps::kMaxMetadataChars);
|
||||
if (kind == Kind::kTimestamp) Check::timestamp("metadata timestamp", text);
|
||||
}
|
||||
|
||||
Json MetadataValue::to_json() const {
|
||||
Json out = Json::object();
|
||||
switch (kind) {
|
||||
case Kind::kString: out.set("stringValue", Json(text)); break;
|
||||
case Kind::kDouble: out.set("doubleValue", Json(number)); break;
|
||||
case Kind::kBool: out.set("boolValue", Json(flag)); break;
|
||||
case Kind::kTimestamp: out.set("timestampValue", Json(text)); break;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
Json metadata_json(const Metadata& metadata) {
|
||||
Json out = Json::object();
|
||||
for (const auto& [k, v] : metadata) out.set(k, v.to_json());
|
||||
return out;
|
||||
}
|
||||
|
||||
void check_filter_groups(const FilterGroups& groups) {
|
||||
if (groups.size() > MemoryCaps::kMaxFilterGroups)
|
||||
bad("filter_groups over " + std::to_string(MemoryCaps::kMaxFilterGroups));
|
||||
for (const auto& group : groups) {
|
||||
if (group.empty()) bad("empty filter group");
|
||||
if (group.size() > MemoryCaps::kMaxFiltersPerGroup)
|
||||
bad("filters per group over " + std::to_string(MemoryCaps::kMaxFiltersPerGroup));
|
||||
for (const MetadataFilter& f : group) {
|
||||
Check::text("filter key", f.key, MemoryCaps::kMaxMetadataChars, true);
|
||||
f.value.validate();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Json filter_groups_json(const FilterGroups& groups) {
|
||||
Json out = Json::array();
|
||||
for (const auto& group : groups) {
|
||||
Json filters = Json::array();
|
||||
for (const MetadataFilter& f : group) {
|
||||
Json item = Json::object();
|
||||
item.set("key", Json(f.key));
|
||||
item.set("op", Json(f.op == MetadataFilter::Op::kEqual ? "EQUAL"
|
||||
: f.op == MetadataFilter::Op::kGreaterThan ? "GREATER_THAN"
|
||||
: "LESS_THAN"));
|
||||
if (f.negate) item.set("negate", Json(true));
|
||||
item.set("value", f.value.to_json());
|
||||
filters.push(item);
|
||||
}
|
||||
Json g = Json::object();
|
||||
g.set("filters", filters);
|
||||
out.push(g);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
std::string Memory::id() const {
|
||||
std::size_t slash = name.rfind('/');
|
||||
return slash == std::string::npos ? name : name.substr(slash + 1);
|
||||
}
|
||||
|
||||
Memory Memory::from_json(const Json& doc) {
|
||||
Memory m;
|
||||
m.name = str_at(doc, "name");
|
||||
m.display_name = str_at(doc, "displayName");
|
||||
m.description = str_at(doc, "description");
|
||||
m.fact = str_at(doc, "fact");
|
||||
m.context = str_at(doc, "context");
|
||||
m.scope = string_map_from(doc.find("scope"));
|
||||
if (const Json* t = doc.find("topics"); t && t->is_array())
|
||||
for (const Json& item : t->as_array()) m.topics.push_back(Topic::from_json(item));
|
||||
m.memory_type = str_at(doc, "memoryType");
|
||||
if (const Json* v = doc.find("structuredContent")) m.structured_content = *v;
|
||||
if (const Json* v = doc.find("metadata")) m.metadata = *v;
|
||||
m.create_time = str_at(doc, "createTime");
|
||||
m.update_time = str_at(doc, "updateTime");
|
||||
m.expire_time = str_at(doc, "expireTime");
|
||||
return m;
|
||||
}
|
||||
|
||||
Json Memory::to_json() const {
|
||||
Json out = Json::object();
|
||||
out.set("name", Json(name));
|
||||
out.set("displayName", Json(display_name));
|
||||
out.set("description", Json(description));
|
||||
out.set("fact", Json(fact));
|
||||
out.set("context", Json(context));
|
||||
out.set("scope", sessions::to_json(scope));
|
||||
out.set("topics", topics_json(topics));
|
||||
out.set("memoryType", Json(memory_type));
|
||||
if (structured_content.is_object()) out.set("structuredContent", structured_content);
|
||||
if (metadata.is_object()) out.set("metadata", metadata);
|
||||
out.set("createTime", Json(create_time));
|
||||
out.set("updateTime", Json(update_time));
|
||||
out.set("expireTime", Json(expire_time));
|
||||
return out;
|
||||
}
|
||||
|
||||
void RevisionOptions::validate() const {
|
||||
Check::labels(labels);
|
||||
if (!ttl.empty()) Check::ttl(ttl, 1);
|
||||
}
|
||||
|
||||
void RevisionOptions::apply(Json& body) const {
|
||||
if (!labels.empty()) body.set("revisionLabels", sessions::to_json(labels));
|
||||
if (!ttl.empty()) body.set("revisionTtl", Json(ttl));
|
||||
if (disable) body.set("disableMemoryRevisions", Json(true));
|
||||
}
|
||||
|
||||
void MemorySpec::validate() const {
|
||||
if (!memory_id.empty()) Check::memory_id(memory_id);
|
||||
Check::text("display_name", display_name, SessionsCaps::kMaxDisplayChars);
|
||||
Check::text("description", description, MemoryCaps::kMaxFactChars);
|
||||
Check::text("context", context, MemoryCaps::kMaxFactChars);
|
||||
Check::text("fact", fact, MemoryCaps::kMaxFactChars, structured_content.is_null());
|
||||
Check::scope(scope);
|
||||
check_topics(topics);
|
||||
check_metadata(metadata);
|
||||
check_structured(structured_content);
|
||||
if (!ttl.empty()) Check::ttl(ttl, 1);
|
||||
if (!memory_type.empty() && memory_type != "NATURAL_LANGUAGE_COLLECTION" &&
|
||||
memory_type != "STRUCTURED_PROFILE")
|
||||
bad("memory_type must be NATURAL_LANGUAGE_COLLECTION or STRUCTURED_PROFILE");
|
||||
revision.validate();
|
||||
}
|
||||
|
||||
Json MemorySpec::to_json() const {
|
||||
Json out = Json::object();
|
||||
if (!fact.empty()) out.set("fact", Json(fact));
|
||||
out.set("scope", sessions::to_json(scope));
|
||||
if (!display_name.empty()) out.set("displayName", Json(display_name));
|
||||
if (!description.empty()) out.set("description", Json(description));
|
||||
if (!context.empty()) out.set("context", Json(context));
|
||||
if (!topics.empty()) out.set("topics", topics_json(topics));
|
||||
if (!ttl.empty()) out.set("ttl", Json(ttl));
|
||||
if (!metadata.empty()) out.set("metadata", metadata_json(metadata));
|
||||
if (!memory_type.empty()) out.set("memoryType", Json(memory_type));
|
||||
put_structured(out, structured_content);
|
||||
revision.apply(out);
|
||||
return out;
|
||||
}
|
||||
|
||||
void MemoryPatch::validate() const {
|
||||
Check::memory_id(memory_id);
|
||||
check_mask(update_mask);
|
||||
Check::text("fact", fact, MemoryCaps::kMaxFactChars);
|
||||
Check::text("display_name", display_name, SessionsCaps::kMaxDisplayChars);
|
||||
Check::text("description", description, MemoryCaps::kMaxFactChars);
|
||||
Check::text("context", context, MemoryCaps::kMaxFactChars);
|
||||
check_topics(topics);
|
||||
check_metadata(metadata);
|
||||
check_structured(structured_content);
|
||||
if (!ttl.empty()) Check::ttl(ttl, 1);
|
||||
revision.validate();
|
||||
}
|
||||
|
||||
Json MemoryPatch::to_json() const {
|
||||
Json out = Json::object();
|
||||
if (!fact.empty()) out.set("fact", Json(fact));
|
||||
if (!display_name.empty()) out.set("displayName", Json(display_name));
|
||||
if (!description.empty()) out.set("description", Json(description));
|
||||
if (!context.empty()) out.set("context", Json(context));
|
||||
if (!topics.empty()) out.set("topics", topics_json(topics));
|
||||
if (!ttl.empty()) out.set("ttl", Json(ttl));
|
||||
if (!metadata.empty()) out.set("metadata", metadata_json(metadata));
|
||||
put_structured(out, structured_content);
|
||||
revision.apply(out);
|
||||
return out;
|
||||
}
|
||||
|
||||
void MemoryGenerateRequest::validate() const {
|
||||
Check::scope(scope);
|
||||
check_topics(allowed_topics);
|
||||
check_metadata(metadata);
|
||||
check_strategy(metadata_merge_strategy);
|
||||
Check::text("time_zone", time_zone, 64);
|
||||
revision.validate();
|
||||
switch (source) {
|
||||
case Source::kSession:
|
||||
Check::session_id(session_id);
|
||||
if (!start_time.empty()) Check::timestamp("start_time", start_time);
|
||||
if (!end_time.empty()) Check::timestamp("end_time", end_time);
|
||||
break;
|
||||
case Source::kContents: {
|
||||
if (contents.empty()) bad("contents is empty");
|
||||
if (contents.size() > MemoryCaps::kMaxSourceEvents)
|
||||
bad("contents over " + std::to_string(MemoryCaps::kMaxSourceEvents) + " events");
|
||||
std::size_t bytes = 0;
|
||||
for (const Content& c : contents) bytes += c.to_json().dump().size();
|
||||
if (bytes > MemoryCaps::kMaxSourceBytes)
|
||||
bad("contents over " + std::to_string(MemoryCaps::kMaxSourceBytes) + " bytes");
|
||||
break;
|
||||
}
|
||||
case Source::kDirectMemories:
|
||||
if (direct_memories.empty()) bad("direct_memories is empty");
|
||||
if (direct_memories.size() > MemoryCaps::kMaxDirectMemories)
|
||||
bad("direct_memories over " + std::to_string(MemoryCaps::kMaxDirectMemories));
|
||||
for (const DirectMemory& d : direct_memories) {
|
||||
Check::text("fact", d.fact, MemoryCaps::kMaxFactChars, true);
|
||||
check_topics(d.topics);
|
||||
}
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
Json MemoryGenerateRequest::to_json(const std::string& engine_name) const {
|
||||
Json out = Json::object();
|
||||
out.set("scope", sessions::to_json(scope));
|
||||
if (disable_consolidation) out.set("disableConsolidation", Json(true));
|
||||
if (!allowed_topics.empty()) out.set("allowedTopics", topics_json(allowed_topics));
|
||||
if (!metadata.empty()) out.set("metadata", metadata_json(metadata));
|
||||
if (!metadata_merge_strategy.empty())
|
||||
out.set("metadataMergeStrategy", Json(metadata_merge_strategy));
|
||||
if (!time_zone.empty()) out.set("timeZone", Json(time_zone));
|
||||
revision.apply(out);
|
||||
switch (source) {
|
||||
case Source::kSession: {
|
||||
Json src = Json::object();
|
||||
src.set("session", Json(engine_name + "/sessions/" + session_id));
|
||||
if (!start_time.empty()) src.set("startTime", Json(start_time));
|
||||
if (!end_time.empty()) src.set("endTime", Json(end_time));
|
||||
out.set("vertexSessionSource", src);
|
||||
break;
|
||||
}
|
||||
case Source::kContents: {
|
||||
Json events = Json::array();
|
||||
for (const Content& c : contents) {
|
||||
Json e = Json::object();
|
||||
e.set("content", c.to_json());
|
||||
events.push(e);
|
||||
}
|
||||
Json src = Json::object();
|
||||
src.set("events", events);
|
||||
out.set("directContentsSource", src);
|
||||
break;
|
||||
}
|
||||
case Source::kDirectMemories: {
|
||||
Json list = Json::array();
|
||||
for (const DirectMemory& d : direct_memories) {
|
||||
Json item = Json::object();
|
||||
item.set("fact", Json(d.fact));
|
||||
if (!d.topics.empty()) item.set("topics", topics_json(d.topics));
|
||||
list.push(item);
|
||||
}
|
||||
Json src = Json::object();
|
||||
src.set("directMemories", list);
|
||||
out.set("directMemoriesSource", src);
|
||||
break;
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
void IngestRequest::validate() const {
|
||||
Check::scope(scope);
|
||||
if (events.empty()) bad("events is empty");
|
||||
if (events.size() > MemoryCaps::kMaxSourceEvents)
|
||||
bad("events over " + std::to_string(MemoryCaps::kMaxSourceEvents));
|
||||
std::size_t bytes = 0;
|
||||
for (const Event& e : events) {
|
||||
Check::text("event_id", e.event_id, SessionsCaps::kMaxUserIdChars);
|
||||
if (!e.event_time.empty()) Check::timestamp("event_time", e.event_time);
|
||||
bytes += e.content.to_json().dump().size();
|
||||
}
|
||||
if (bytes > MemoryCaps::kMaxSourceBytes)
|
||||
bad("events over " + std::to_string(MemoryCaps::kMaxSourceBytes) + " bytes");
|
||||
Check::text("stream_id", stream_id, SessionsCaps::kMaxUserIdChars);
|
||||
if (trigger_event_count < 0 || trigger_event_count > 1000 ||
|
||||
trigger_overlap_event_count < 0 || trigger_overlap_event_count > 1000)
|
||||
bad("trigger counts outside 0..1000");
|
||||
if (!trigger_fixed_interval.empty()) Check::ttl(trigger_fixed_interval, 60);
|
||||
if (!trigger_idle_duration.empty()) Check::ttl(trigger_idle_duration, 1);
|
||||
check_metadata(metadata);
|
||||
check_strategy(metadata_merge_strategy);
|
||||
revision.validate();
|
||||
}
|
||||
|
||||
Json IngestRequest::to_json() const {
|
||||
Json out = Json::object();
|
||||
out.set("scope", sessions::to_json(scope));
|
||||
Json list = Json::array();
|
||||
for (const Event& e : events) {
|
||||
Json item = Json::object();
|
||||
if (!e.event_id.empty()) item.set("eventId", Json(e.event_id));
|
||||
if (!e.event_time.empty()) item.set("eventTime", Json(e.event_time));
|
||||
item.set("content", e.content.to_json());
|
||||
list.push(item);
|
||||
}
|
||||
Json src = Json::object();
|
||||
src.set("events", list);
|
||||
out.set("directContentsSource", src);
|
||||
if (!stream_id.empty()) out.set("streamId", Json(stream_id));
|
||||
if (force_flush) out.set("forceFlush", Json(true));
|
||||
Json rule = Json::object();
|
||||
if (trigger_event_count > 0) rule.set("eventCount", Json(trigger_event_count));
|
||||
if (trigger_overlap_event_count > 0)
|
||||
rule.set("overlapEventCount", Json(trigger_overlap_event_count));
|
||||
if (!trigger_fixed_interval.empty()) rule.set("fixedInterval", Json(trigger_fixed_interval));
|
||||
if (!trigger_idle_duration.empty()) rule.set("idleDuration", Json(trigger_idle_duration));
|
||||
if (!rule.as_object().empty()) {
|
||||
Json trigger = Json::object();
|
||||
trigger.set("generationRule", rule);
|
||||
out.set("generationTriggerConfig", trigger);
|
||||
}
|
||||
if (!metadata.empty()) out.set("metadata", metadata_json(metadata));
|
||||
if (!metadata_merge_strategy.empty())
|
||||
out.set("metadataMergeStrategy", Json(metadata_merge_strategy));
|
||||
revision.apply(out);
|
||||
return out;
|
||||
}
|
||||
|
||||
void RetrieveRequest::validate() const {
|
||||
Check::scope(scope);
|
||||
Check::text("search_query", search_query, MemoryCaps::kMaxQueryChars);
|
||||
Check::expression("filter", filter);
|
||||
check_filter_groups(filter_groups);
|
||||
if (memory_types.size() > MemoryCaps::kMaxMemoryTypes) bad("memory_types over 2");
|
||||
for (const std::string& t : memory_types)
|
||||
if (t != "NATURAL_LANGUAGE_COLLECTION" && t != "STRUCTURED_PROFILE")
|
||||
bad("memory_types allows NATURAL_LANGUAGE_COLLECTION, STRUCTURED_PROFILE");
|
||||
if (top_k < 0 || top_k > MemoryCaps::kMaxTopK)
|
||||
bad("top_k outside 0.." + std::to_string(MemoryCaps::kMaxTopK));
|
||||
Check::page_size(page_size, MemoryCaps::kPageSize);
|
||||
if (!search_query.empty() && (page_size > 0 || !page_token.empty()))
|
||||
bad("similarity search takes top_k, not page_size or page_token");
|
||||
if (search_query.empty() && top_k > 0) bad("top_k needs a search_query");
|
||||
Check::text("page_token", page_token, 2048);
|
||||
}
|
||||
|
||||
Json RetrieveRequest::to_json() const {
|
||||
Json out = Json::object();
|
||||
out.set("scope", sessions::to_json(scope));
|
||||
if (!filter.empty()) out.set("filter", Json(filter));
|
||||
if (!filter_groups.empty()) out.set("filterGroups", filter_groups_json(filter_groups));
|
||||
if (!memory_types.empty()) {
|
||||
Json arr = Json::array();
|
||||
for (const std::string& t : memory_types) arr.push(Json(t));
|
||||
out.set("memoryTypes", arr);
|
||||
}
|
||||
if (!search_query.empty()) {
|
||||
Json params = Json::object();
|
||||
params.set("searchQuery", Json(search_query));
|
||||
params.set("topK", Json(top_k > 0 ? top_k : MemoryCaps::kDefaultTopK));
|
||||
out.set("similaritySearchParams", params);
|
||||
} else if (page_size > 0 || !page_token.empty()) {
|
||||
Json params = Json::object();
|
||||
if (page_size > 0) params.set("pageSize", Json(page_size));
|
||||
if (!page_token.empty()) params.set("pageToken", Json(page_token));
|
||||
out.set("simpleRetrievalParams", params);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
std::string MemoryRevision::id() const {
|
||||
std::size_t slash = name.rfind('/');
|
||||
return slash == std::string::npos ? name : name.substr(slash + 1);
|
||||
}
|
||||
|
||||
MemoryRevision MemoryRevision::from_json(const Json& doc) {
|
||||
MemoryRevision r;
|
||||
r.name = str_at(doc, "name");
|
||||
r.fact = str_at(doc, "fact");
|
||||
r.context = str_at(doc, "context");
|
||||
r.labels = string_map_from(doc.find("labels"));
|
||||
r.create_time = str_at(doc, "createTime");
|
||||
r.expire_time = str_at(doc, "expireTime");
|
||||
return r;
|
||||
}
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,229 @@
|
||||
#pragma once
|
||||
|
||||
// Typed Agent Memory Bank resources and requests. Wire names are the REST
|
||||
// camelCase names of aiplatform v1beta1 (see calls.h for the call table).
|
||||
|
||||
#include <map>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
#include "clients/body/json.h"
|
||||
#include "google/gemini_types.h"
|
||||
#include "google/sessions/names.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
// Memory topic: a Google managed topic (enum name such as
|
||||
// "USER_PREFERENCES") or a custom label.
|
||||
struct Topic {
|
||||
enum class Kind { kManaged, kCustom };
|
||||
Kind kind = Kind::kManaged;
|
||||
std::string value;
|
||||
|
||||
static Topic managed(std::string name);
|
||||
static Topic custom(std::string label);
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
static Topic from_json(const clients::body::Json& doc);
|
||||
};
|
||||
|
||||
// MemoryMetadataValue: exactly one of string, double, bool, timestamp.
|
||||
struct MetadataValue {
|
||||
enum class Kind { kString, kDouble, kBool, kTimestamp };
|
||||
Kind kind = Kind::kString;
|
||||
std::string text; // string or RFC 3339 timestamp
|
||||
double number = 0;
|
||||
bool flag = false;
|
||||
|
||||
static MetadataValue of_string(std::string v);
|
||||
static MetadataValue of_double(double v);
|
||||
static MetadataValue of_bool(bool v);
|
||||
static MetadataValue of_timestamp(std::string v);
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
using Metadata = std::map<std::string, MetadataValue>;
|
||||
|
||||
// One AND-group of metadata filters; groups are OR-ed (Google semantics).
|
||||
struct MetadataFilter {
|
||||
enum class Op { kEqual, kGreaterThan, kLessThan };
|
||||
std::string key;
|
||||
Op op = Op::kEqual;
|
||||
bool negate = false;
|
||||
MetadataValue value;
|
||||
};
|
||||
using FilterGroups = std::vector<std::vector<MetadataFilter>>;
|
||||
|
||||
struct Memory {
|
||||
std::string name;
|
||||
std::string display_name, description, fact, context;
|
||||
StringMap scope;
|
||||
std::vector<Topic> topics;
|
||||
std::string memory_type; // NATURAL_LANGUAGE_COLLECTION, STRUCTURED_PROFILE
|
||||
clients::body::Json structured_content; // {schemaId, data}, raw
|
||||
clients::body::Json metadata; // map of MemoryMetadataValue, raw
|
||||
std::string create_time, update_time, expire_time;
|
||||
|
||||
std::string id() const;
|
||||
static Memory from_json(const clients::body::Json& doc);
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
struct RevisionOptions { // Shared by create, patch, generate, ingest.
|
||||
StringMap labels;
|
||||
std::string ttl; // "86400s"
|
||||
bool disable = false;
|
||||
void validate() const;
|
||||
void apply(clients::body::Json& body) const; // adds the three wire fields
|
||||
};
|
||||
|
||||
struct MemorySpec { // Input to create (a memory written directly).
|
||||
std::string memory_id; // Optional custom id.
|
||||
std::string display_name, description, context;
|
||||
std::string fact; // Required unless structured_content is set.
|
||||
StringMap scope; // Required, immutable.
|
||||
std::vector<Topic> topics;
|
||||
std::string ttl; // "3600s", empty: never expires.
|
||||
Metadata metadata;
|
||||
std::string memory_type;
|
||||
clients::body::Json structured_content;
|
||||
RevisionOptions revision;
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
// PATCH of one memory. scope and metadata keys cannot be changed by Google
|
||||
// (scope is immutable). update_mask is a comma list of the fields to write.
|
||||
struct MemoryPatch {
|
||||
std::string memory_id;
|
||||
std::string fact, display_name, description, context, ttl;
|
||||
std::vector<Topic> topics;
|
||||
Metadata metadata;
|
||||
clients::body::Json structured_content;
|
||||
RevisionOptions revision;
|
||||
std::string update_mask; // Required, e.g. "fact,displayName".
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
// What generate reads. Exactly one source is used.
|
||||
struct MemoryGenerateRequest {
|
||||
enum class Source { kSession, kContents, kDirectMemories };
|
||||
Source source = Source::kContents;
|
||||
|
||||
std::string session_id; // kSession: an Agent Sessions id under this engine
|
||||
std::string start_time; // kSession, optional RFC 3339
|
||||
std::string end_time; // kSession, optional RFC 3339
|
||||
std::vector<Content> contents; // kContents: the conversation
|
||||
struct DirectMemory {
|
||||
std::string fact;
|
||||
std::vector<Topic> topics;
|
||||
};
|
||||
std::vector<DirectMemory> direct_memories; // kDirectMemories, max 5
|
||||
|
||||
StringMap scope; // Required.
|
||||
bool disable_consolidation = false;
|
||||
std::vector<Topic> allowed_topics;
|
||||
Metadata metadata;
|
||||
std::string metadata_merge_strategy; // OVERWRITE, MERGE, REQUIRE_EXACT_MATCH
|
||||
std::string time_zone; // IANA name
|
||||
RevisionOptions revision;
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json(const std::string& engine_name) const;
|
||||
};
|
||||
|
||||
struct GeneratedMemory {
|
||||
Memory memory;
|
||||
std::string action; // As reported by Google (see SPEC Unverified).
|
||||
};
|
||||
|
||||
// Streaming ingestion into a Memory Bank stream; generation is triggered by
|
||||
// the rule (event count, interval, idle) or by force_flush.
|
||||
struct IngestRequest {
|
||||
struct Event {
|
||||
std::string event_id, event_time; // optional; time is RFC 3339
|
||||
Content content;
|
||||
};
|
||||
std::vector<Event> events; // Required.
|
||||
StringMap scope; // Required.
|
||||
std::string stream_id;
|
||||
bool force_flush = false;
|
||||
int trigger_event_count = 0; // 0: unset
|
||||
int trigger_overlap_event_count = 0;
|
||||
std::string trigger_fixed_interval; // "3600s"
|
||||
std::string trigger_idle_duration; // "600s"
|
||||
Metadata metadata;
|
||||
std::string metadata_merge_strategy;
|
||||
RevisionOptions revision;
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
struct RetrieveRequest {
|
||||
StringMap scope; // Required.
|
||||
std::string search_query; // Set: similarity search. Empty: simple retrieval.
|
||||
int top_k = 0; // Similarity only; 0: kDefaultTopK.
|
||||
int page_size = 0; // Simple only; 0: Google default.
|
||||
std::string page_token; // Simple only.
|
||||
std::string filter; // fact, createTime, updateTime, topics
|
||||
FilterGroups filter_groups;
|
||||
std::vector<std::string> memory_types;
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
struct RetrievedMemory {
|
||||
Memory memory;
|
||||
double distance = 0.0; // Similarity only; smaller is closer.
|
||||
bool has_distance = false;
|
||||
};
|
||||
|
||||
struct RetrieveResult {
|
||||
std::vector<RetrievedMemory> memories;
|
||||
std::string next_page_token; // Simple retrieval only.
|
||||
};
|
||||
|
||||
struct MemoryListOptions {
|
||||
std::string filter; // scope (JSON equality) and topics
|
||||
std::string order_by; // createTime / updateTime, "desc"
|
||||
int page_size = 0;
|
||||
};
|
||||
|
||||
struct MemoryRevision {
|
||||
std::string name, fact, context;
|
||||
StringMap labels;
|
||||
std::string create_time, expire_time;
|
||||
static MemoryRevision from_json(const clients::body::Json& doc);
|
||||
std::string id() const;
|
||||
};
|
||||
|
||||
struct Profile {
|
||||
std::string schema_id;
|
||||
clients::body::Json fields; // Free-form profile object.
|
||||
};
|
||||
|
||||
// Purge is irreversible. force=false (the default) is a server-side dry run.
|
||||
// force=true additionally needs `confirm` to equal the engine id.
|
||||
struct PurgeRequest {
|
||||
std::string filter; // Required, AIP-160.
|
||||
FilterGroups filter_groups;
|
||||
bool force = false;
|
||||
std::string confirm;
|
||||
};
|
||||
|
||||
struct PurgeResult {
|
||||
bool forced = false;
|
||||
long purge_count = 0; // Memories matched (dry run) or deleted (force).
|
||||
};
|
||||
|
||||
// Shared helpers (also used by tests).
|
||||
clients::body::Json filter_groups_json(const FilterGroups& groups);
|
||||
void check_filter_groups(const FilterGroups& groups);
|
||||
clients::body::Json metadata_json(const Metadata& metadata);
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,195 @@
|
||||
#include "google/sessions/names.h"
|
||||
|
||||
#include <cctype>
|
||||
#include <cstdlib>
|
||||
#include <vector>
|
||||
|
||||
#include "clients/url.h"
|
||||
#include "google/errors.h"
|
||||
#include "google/resource.h"
|
||||
#include "google/sessions/caps.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
using clients::body::Json;
|
||||
|
||||
namespace {
|
||||
|
||||
bool id_char(char c) {
|
||||
return (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-';
|
||||
}
|
||||
|
||||
bool project_ok(const std::string& p) {
|
||||
if (p.empty() || p.size() > 128) return false;
|
||||
for (char c : p)
|
||||
if (!id_char(c) && c != '.' && c != ':') return false;
|
||||
return true;
|
||||
}
|
||||
|
||||
[[noreturn]] void bad(const std::string& message) {
|
||||
throw GoogleError::invalid(message);
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
EngineName::EngineName(std::string full) : full_(std::move(full)) {
|
||||
if (full_.empty() || full_.size() > SessionsCaps::kMaxNameChars)
|
||||
bad("engine name missing or too long");
|
||||
std::vector<std::string> parts;
|
||||
std::string cur;
|
||||
for (char c : full_) {
|
||||
if (c == '/') {
|
||||
parts.push_back(cur);
|
||||
cur.clear();
|
||||
} else {
|
||||
cur.push_back(c);
|
||||
}
|
||||
}
|
||||
parts.push_back(cur);
|
||||
if (parts.size() != 6 || parts[0] != "projects" || parts[2] != "locations" ||
|
||||
parts[4] != "reasoningEngines")
|
||||
bad("engine must look like projects/{p}/locations/{l}/reasoningEngines/{e}");
|
||||
project_ = parts[1];
|
||||
location_ = parts[3];
|
||||
engine_ = parts[5];
|
||||
if (!project_ok(project_)) bad("engine name: bad project");
|
||||
if (location_.empty() || location_.size() > 64) bad("engine name: bad location");
|
||||
for (char c : location_)
|
||||
if (!id_char(c)) bad("engine name: bad location");
|
||||
if (!valid_segment(engine_)) bad("engine name: bad engine id");
|
||||
}
|
||||
|
||||
std::string EngineName::session(const std::string& session_id) const {
|
||||
Check::session_id(session_id);
|
||||
return full_ + "/sessions/" + session_id;
|
||||
}
|
||||
|
||||
std::string EngineName::memory(const std::string& memory_id) const {
|
||||
Check::memory_id(memory_id);
|
||||
return full_ + "/memories/" + memory_id;
|
||||
}
|
||||
|
||||
void Check::session_id(const std::string& id) {
|
||||
if (id.empty() || id.size() > SessionsCaps::kMaxIdChars)
|
||||
bad("session id must be 1.." + std::to_string(SessionsCaps::kMaxIdChars) +
|
||||
" characters");
|
||||
for (char c : id)
|
||||
if (!id_char(c)) bad("session id allows only a-z 0-9 -");
|
||||
}
|
||||
|
||||
void Check::memory_id(const std::string& id) {
|
||||
if (id.empty() || id.size() > SessionsCaps::kMaxIdChars)
|
||||
bad("memory id must be 1.." + std::to_string(SessionsCaps::kMaxIdChars) +
|
||||
" characters");
|
||||
for (char c : id)
|
||||
if (!id_char(c)) bad("memory id allows only a-z 0-9 -");
|
||||
if (!(id.front() >= 'a' && id.front() <= 'z')) bad("memory id must start with a letter");
|
||||
if (id.back() == '-') bad("memory id must end with a letter or number");
|
||||
}
|
||||
|
||||
void Check::text(const std::string& field, const std::string& value,
|
||||
std::size_t max, bool required) {
|
||||
if (required && value.empty()) bad(field + " is required");
|
||||
if (value.size() > max)
|
||||
bad(field + " over " + std::to_string(max) + " characters");
|
||||
}
|
||||
|
||||
void Check::expression(const std::string& field, const std::string& value) {
|
||||
text(field, value, SessionsCaps::kMaxFilterChars);
|
||||
for (char c : value)
|
||||
if (static_cast<unsigned char>(c) < 0x20 || c == 0x7f)
|
||||
bad(field + " has control characters");
|
||||
}
|
||||
|
||||
void Check::scope(const StringMap& scope, bool required) {
|
||||
if (scope.empty()) {
|
||||
if (required) bad("scope is required");
|
||||
return;
|
||||
}
|
||||
if (scope.size() > MemoryCaps::kMaxScopeEntries)
|
||||
bad("scope over " + std::to_string(MemoryCaps::kMaxScopeEntries) + " entries");
|
||||
for (const auto& [k, v] : scope) {
|
||||
if (k.empty() || k.size() > MemoryCaps::kMaxScopeChars ||
|
||||
v.size() > MemoryCaps::kMaxScopeChars)
|
||||
bad("scope key empty or over " + std::to_string(MemoryCaps::kMaxScopeChars) +
|
||||
" characters");
|
||||
if (v.empty()) bad("scope value is empty");
|
||||
if (k.find('*') != std::string::npos || v.find('*') != std::string::npos)
|
||||
bad("scope must not contain the wildcard *");
|
||||
}
|
||||
}
|
||||
|
||||
void Check::labels(const StringMap& labels) {
|
||||
if (labels.size() > SessionsCaps::kMaxLabels)
|
||||
bad("labels over " + std::to_string(SessionsCaps::kMaxLabels));
|
||||
for (const auto& [k, v] : labels)
|
||||
if (k.empty() || k.size() > SessionsCaps::kMaxLabelChars ||
|
||||
v.size() > SessionsCaps::kMaxLabelChars)
|
||||
bad("label key empty or over " + std::to_string(SessionsCaps::kMaxLabelChars) +
|
||||
" characters");
|
||||
}
|
||||
|
||||
void Check::timestamp(const std::string& field, const std::string& value) {
|
||||
if (value.size() < 20 || value.size() > SessionsCaps::kMaxTimestampChars)
|
||||
bad(field + " must be an RFC 3339 timestamp");
|
||||
for (char c : value) {
|
||||
bool ok = std::isdigit(static_cast<unsigned char>(c)) || c == '-' || c == ':' ||
|
||||
c == 'T' || c == 'Z' || c == '.' || c == '+';
|
||||
if (!ok) bad(field + " must be an RFC 3339 timestamp");
|
||||
}
|
||||
if (value[4] != '-' || value[7] != '-' || value[10] != 'T')
|
||||
bad(field + " must be an RFC 3339 timestamp");
|
||||
}
|
||||
|
||||
void Check::ttl(const std::string& value, int min_seconds) {
|
||||
if (value.size() < 2 || value.size() > 24 || value.back() != 's')
|
||||
bad("ttl must look like 86400s");
|
||||
std::string num = value.substr(0, value.size() - 1);
|
||||
int dots = 0;
|
||||
for (char c : num) {
|
||||
if (c == '.') ++dots;
|
||||
else if (!std::isdigit(static_cast<unsigned char>(c))) bad("ttl must look like 86400s");
|
||||
}
|
||||
if (dots > 1 || num.front() == '.' || num.back() == '.')
|
||||
bad("ttl must look like 86400s");
|
||||
double seconds = std::strtod(num.c_str(), nullptr);
|
||||
if (seconds < min_seconds)
|
||||
bad("ttl under the minimum of " + std::to_string(min_seconds) + "s");
|
||||
if (seconds > static_cast<double>(SessionsCaps::kMaxTtlSeconds))
|
||||
bad("ttl over the cap");
|
||||
}
|
||||
|
||||
void Check::page_size(int value, int ceiling) {
|
||||
if (value < 0 || value > ceiling)
|
||||
bad("page_size outside 0.." + std::to_string(ceiling));
|
||||
}
|
||||
|
||||
Json to_json(const StringMap& map) {
|
||||
Json out = Json::object();
|
||||
for (const auto& [k, v] : map) out.set(k, Json(v));
|
||||
return out;
|
||||
}
|
||||
|
||||
StringMap string_map_from(const Json* doc) {
|
||||
StringMap out;
|
||||
if (doc && doc->is_object())
|
||||
for (const auto& [k, v] : doc->as_object())
|
||||
if (v.is_string()) out[k] = v.as_string();
|
||||
return out;
|
||||
}
|
||||
|
||||
std::string str_at(const Json& doc, const std::string& key) {
|
||||
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
|
||||
return v && v->is_string() ? v->as_string() : "";
|
||||
}
|
||||
|
||||
std::string query_of(const std::map<std::string, std::string>& params) {
|
||||
std::string out;
|
||||
for (const auto& [k, v] : params) {
|
||||
if (v.empty()) continue;
|
||||
out += (out.empty() ? "?" : "&") + k + "=" + clients::Url::encode_component(v);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,62 @@
|
||||
#pragma once
|
||||
|
||||
// Validated resource names and shared input checks for the sessions module.
|
||||
// Everything here runs before any network traffic and throws
|
||||
// GoogleError::invalid (HTTP 400 INVALID_ARGUMENT).
|
||||
|
||||
#include <map>
|
||||
#include <string>
|
||||
|
||||
#include "clients/body/json.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
// "projects/{project}/locations/{location}/reasoningEngines/{engine}".
|
||||
// Accepted as a string so this module does not depend on the runtime module.
|
||||
class EngineName {
|
||||
public:
|
||||
explicit EngineName(std::string full); // throws when malformed
|
||||
|
||||
const std::string& str() const { return full_; }
|
||||
const std::string& project() const { return project_; }
|
||||
const std::string& location() const { return location_; }
|
||||
const std::string& engine() const { return engine_; }
|
||||
|
||||
std::string session(const std::string& session_id) const;
|
||||
std::string memory(const std::string& memory_id) const;
|
||||
|
||||
private:
|
||||
std::string full_, project_, location_, engine_;
|
||||
};
|
||||
|
||||
using StringMap = std::map<std::string, std::string>;
|
||||
|
||||
// Input validators.
|
||||
class Check {
|
||||
public:
|
||||
// Session id: 1..63 of [a-z0-9-].
|
||||
static void session_id(const std::string& id);
|
||||
// Memory id: 1..63 of [a-z0-9-], starts with a letter, ends alphanumeric.
|
||||
static void memory_id(const std::string& id);
|
||||
static void text(const std::string& field, const std::string& value,
|
||||
std::size_t max, bool required = false);
|
||||
// Filter / orderBy expression: bounded, no control characters.
|
||||
static void expression(const std::string& field, const std::string& value);
|
||||
// Scope: 1..N entries, bounded, no '*' (Google forbids the wildcard).
|
||||
static void scope(const StringMap& scope, bool required = true);
|
||||
static void labels(const StringMap& labels);
|
||||
// RFC 3339 shape check (not a calendar check).
|
||||
static void timestamp(const std::string& field, const std::string& value);
|
||||
// Duration "86400s" or "3.5s"; within [min_seconds, kMaxTtlSeconds].
|
||||
static void ttl(const std::string& value, int min_seconds);
|
||||
static void page_size(int value, int ceiling);
|
||||
};
|
||||
|
||||
// Wire helpers.
|
||||
clients::body::Json to_json(const StringMap& map);
|
||||
StringMap string_map_from(const clients::body::Json* doc);
|
||||
std::string str_at(const clients::body::Json& doc, const std::string& key);
|
||||
// Query suffix "?k=v&k2=v2" with encoded values; empty values are skipped.
|
||||
std::string query_of(const std::map<std::string, std::string>& params);
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,148 @@
|
||||
#include "google/sessions/session_types.h"
|
||||
|
||||
#include "google/errors.h"
|
||||
#include "google/sessions/caps.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
using clients::body::Json;
|
||||
|
||||
void SessionSpec::validate() const {
|
||||
if (!session_id.empty()) Check::session_id(session_id);
|
||||
Check::text("user_id", user_id, SessionsCaps::kMaxUserIdChars, true);
|
||||
Check::text("display_name", display_name, SessionsCaps::kMaxDisplayChars);
|
||||
Check::labels(labels);
|
||||
if (!session_state.is_null()) {
|
||||
if (!session_state.is_object())
|
||||
throw GoogleError::invalid("session_state must be an object");
|
||||
if (session_state.dump().size() > SessionsCaps::kMaxStateBytes)
|
||||
throw GoogleError::invalid("session_state over " +
|
||||
std::to_string(SessionsCaps::kMaxStateBytes) +
|
||||
" bytes");
|
||||
}
|
||||
if (!ttl.empty()) Check::ttl(ttl, SessionsCaps::kMinTtlSeconds);
|
||||
}
|
||||
|
||||
Json SessionSpec::to_json() const {
|
||||
Json out = Json::object();
|
||||
out.set("userId", Json(user_id));
|
||||
if (!display_name.empty()) out.set("displayName", Json(display_name));
|
||||
if (!labels.empty()) out.set("labels", sessions::to_json(labels));
|
||||
if (session_state.is_object()) out.set("sessionState", session_state);
|
||||
if (!ttl.empty()) out.set("ttl", Json(ttl));
|
||||
return out;
|
||||
}
|
||||
|
||||
void SessionPatch::validate() const {
|
||||
Check::session_id(session_id);
|
||||
Check::text("update_mask", update_mask, 256, true);
|
||||
for (char c : update_mask) {
|
||||
bool ok = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c == ',' || c == '.';
|
||||
if (!ok) throw GoogleError::invalid("update_mask allows letters, comma, dot");
|
||||
}
|
||||
Check::text("display_name", display_name, SessionsCaps::kMaxDisplayChars);
|
||||
Check::labels(labels);
|
||||
if (!session_state.is_null() && !session_state.is_object())
|
||||
throw GoogleError::invalid("session_state must be an object");
|
||||
if (session_state.dump().size() > SessionsCaps::kMaxStateBytes)
|
||||
throw GoogleError::invalid("session_state over " +
|
||||
std::to_string(SessionsCaps::kMaxStateBytes) + " bytes");
|
||||
if (!ttl.empty()) Check::ttl(ttl, SessionsCaps::kMinTtlSeconds);
|
||||
}
|
||||
|
||||
Json SessionPatch::to_json() const {
|
||||
Json out = Json::object();
|
||||
if (!display_name.empty()) out.set("displayName", Json(display_name));
|
||||
if (!labels.empty()) out.set("labels", sessions::to_json(labels));
|
||||
if (session_state.is_object()) out.set("sessionState", session_state);
|
||||
if (!ttl.empty()) out.set("ttl", Json(ttl));
|
||||
return out;
|
||||
}
|
||||
|
||||
void CompactRequest::validate() const {
|
||||
if (!summarization && !event_editing)
|
||||
throw GoogleError::invalid("compact needs summarization or event_editing");
|
||||
}
|
||||
|
||||
Json CompactRequest::to_json() const {
|
||||
Json mode = Json::object();
|
||||
mode.set("mode", Json("AUTO"));
|
||||
Json compaction = Json::object();
|
||||
if (summarization) compaction.set("summarization", mode);
|
||||
if (event_editing) compaction.set("eventEditing", mode);
|
||||
Json out = Json::object();
|
||||
out.set("compaction", compaction);
|
||||
return out;
|
||||
}
|
||||
|
||||
std::string Session::id() const {
|
||||
std::size_t slash = name.rfind('/');
|
||||
return slash == std::string::npos ? name : name.substr(slash + 1);
|
||||
}
|
||||
|
||||
Session Session::from_json(const Json& doc) {
|
||||
Session s;
|
||||
s.name = str_at(doc, "name");
|
||||
s.display_name = str_at(doc, "displayName");
|
||||
s.user_id = str_at(doc, "userId");
|
||||
s.labels = string_map_from(doc.find("labels"));
|
||||
if (const Json* v = doc.find("sessionState")) s.session_state = *v;
|
||||
s.create_time = str_at(doc, "createTime");
|
||||
s.update_time = str_at(doc, "updateTime");
|
||||
s.expire_time = str_at(doc, "expireTime");
|
||||
return s;
|
||||
}
|
||||
|
||||
Json Session::to_json() const {
|
||||
Json out = Json::object();
|
||||
out.set("name", Json(name));
|
||||
out.set("displayName", Json(display_name));
|
||||
out.set("userId", Json(user_id));
|
||||
out.set("labels", sessions::to_json(labels));
|
||||
out.set("sessionState", session_state.is_object() ? session_state : Json::object());
|
||||
out.set("createTime", Json(create_time));
|
||||
out.set("updateTime", Json(update_time));
|
||||
out.set("expireTime", Json(expire_time));
|
||||
return out;
|
||||
}
|
||||
|
||||
void SessionEvent::validate() const {
|
||||
Check::text("author", author, SessionsCaps::kMaxUserIdChars, true);
|
||||
Check::text("invocation_id", invocation_id, SessionsCaps::kMaxUserIdChars, true);
|
||||
Check::timestamp("timestamp", timestamp);
|
||||
if (to_json().dump().size() > SessionsCaps::kMaxEventBytes)
|
||||
throw GoogleError::invalid("event over " +
|
||||
std::to_string(SessionsCaps::kMaxEventBytes) + " bytes");
|
||||
}
|
||||
|
||||
Json SessionEvent::to_json() const {
|
||||
Json out = Json::object();
|
||||
out.set("author", Json(author));
|
||||
out.set("invocationId", Json(invocation_id));
|
||||
out.set("timestamp", Json(timestamp));
|
||||
if (content) out.set("content", content->to_json());
|
||||
if (actions.is_object()) out.set("actions", actions);
|
||||
if (!error_code.empty()) out.set("errorCode", Json(error_code));
|
||||
if (!error_message.empty()) out.set("errorMessage", Json(error_message));
|
||||
if (event_metadata.is_object()) out.set("eventMetadata", event_metadata);
|
||||
if (raw_event.is_object()) out.set("rawEvent", raw_event);
|
||||
return out;
|
||||
}
|
||||
|
||||
SessionEvent SessionEvent::from_json(const Json& doc) {
|
||||
SessionEvent e;
|
||||
e.name = str_at(doc, "name");
|
||||
e.author = str_at(doc, "author");
|
||||
e.invocation_id = str_at(doc, "invocationId");
|
||||
e.timestamp = str_at(doc, "timestamp");
|
||||
if (const Json* c = doc.find("content"); c && c->is_object())
|
||||
e.content = Content::from_json(*c);
|
||||
if (const Json* v = doc.find("actions")) e.actions = *v;
|
||||
e.error_code = str_at(doc, "errorCode");
|
||||
e.error_message = str_at(doc, "errorMessage");
|
||||
if (const Json* v = doc.find("eventMetadata")) e.event_metadata = *v;
|
||||
if (const Json* v = doc.find("rawEvent")) e.raw_event = *v;
|
||||
return e;
|
||||
}
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,92 @@
|
||||
#pragma once
|
||||
|
||||
// Typed Agent Sessions resources (Session, SessionEvent). Wire names are the
|
||||
// REST camelCase names. Free-form parts stay raw Json.
|
||||
|
||||
#include <optional>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
#include "clients/body/json.h"
|
||||
#include "google/gemini_types.h"
|
||||
#include "google/sessions/names.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
struct SessionSpec { // Input to create.
|
||||
std::string session_id; // Optional custom id, [a-z0-9-], 1..63.
|
||||
std::string user_id; // Required, immutable.
|
||||
std::string display_name;
|
||||
StringMap labels;
|
||||
clients::body::Json session_state; // Object or null.
|
||||
std::string ttl; // "86400s" minimum, empty: none.
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
// PATCH of one session; userId is immutable. update_mask is a comma list
|
||||
// of fields (displayName, labels, sessionState, ttl).
|
||||
struct SessionPatch {
|
||||
std::string session_id;
|
||||
std::string display_name;
|
||||
StringMap labels;
|
||||
clients::body::Json session_state;
|
||||
std::string ttl;
|
||||
std::string update_mask; // Required.
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
// Storage-side rewrite of a session's event history. At least one category.
|
||||
struct CompactRequest {
|
||||
bool summarization = false; // LLM summary, mode AUTO
|
||||
bool event_editing = false; // deterministic edits, mode AUTO
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
struct Session {
|
||||
std::string name;
|
||||
std::string display_name;
|
||||
std::string user_id;
|
||||
StringMap labels;
|
||||
clients::body::Json session_state;
|
||||
std::string create_time, update_time, expire_time;
|
||||
|
||||
std::string id() const; // Last component of name.
|
||||
static Session from_json(const clients::body::Json& doc);
|
||||
clients::body::Json to_json() const;
|
||||
};
|
||||
|
||||
struct SessionEvent {
|
||||
std::string name; // Output only.
|
||||
std::string author; // Required: "user", an agent name.
|
||||
std::string invocation_id; // Required.
|
||||
std::string timestamp; // Required, RFC 3339.
|
||||
std::optional<Content> content;
|
||||
clients::body::Json actions; // EventActions, raw.
|
||||
std::string error_code, error_message;
|
||||
clients::body::Json event_metadata; // EventMetadata, raw.
|
||||
clients::body::Json raw_event; // Struct, raw.
|
||||
|
||||
void validate() const;
|
||||
clients::body::Json to_json() const;
|
||||
static SessionEvent from_json(const clients::body::Json& doc);
|
||||
};
|
||||
|
||||
struct SessionListOptions {
|
||||
std::string filter; // displayName="x", userId="y", labels.k="v"
|
||||
std::string order_by; // "createTime desc"
|
||||
int page_size = 0; // 0: Google default (100)
|
||||
};
|
||||
|
||||
struct EventListOptions {
|
||||
std::string filter; // timestamp>="2025-01-31T11:30:00Z"
|
||||
std::string order_by; // "timestamp desc"
|
||||
int page_size = 0;
|
||||
};
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,89 @@
|
||||
#include "google/sessions/sessions.h"
|
||||
|
||||
#include "google/sessions/caps.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
using clients::body::Json;
|
||||
|
||||
namespace {
|
||||
|
||||
std::string list_query(const std::string& filter, const std::string& order_by,
|
||||
int page_size) {
|
||||
Check::expression("filter", filter);
|
||||
Check::expression("order_by", order_by);
|
||||
Check::page_size(page_size, SessionsCaps::kPageSize);
|
||||
return query_of({{"filter", filter},
|
||||
{"orderBy", order_by},
|
||||
{"pageSize", page_size > 0 ? std::to_string(page_size) : ""}});
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
Sessions::Sessions(std::shared_ptr<GoogleClient> client, EngineName engine,
|
||||
Sleeper sleeper)
|
||||
: EngineService(std::move(client), std::move(engine), std::move(sleeper)) {}
|
||||
|
||||
Session Sessions::create(const SessionSpec& spec) const {
|
||||
spec.validate();
|
||||
Json body = spec.to_json();
|
||||
Operation op = settle(send(Call::kSessionCreate, engine_name_.str(), &body,
|
||||
query_of({{"sessionId", spec.session_id}})));
|
||||
if (op.response.is_object() && !str_at(op.response, "name").empty())
|
||||
return Session::from_json(op.response);
|
||||
if (!spec.session_id.empty()) return get(spec.session_id);
|
||||
throw GoogleError(502, "EMPTY_RESPONSE", "create returned no session", endpoint_.name);
|
||||
}
|
||||
|
||||
Session Sessions::get(const std::string& session_id) const {
|
||||
return Session::from_json(send(Call::kSessionGet, engine_name_.session(session_id)));
|
||||
}
|
||||
|
||||
std::vector<Session> Sessions::list(const SessionListOptions& options) const {
|
||||
Json items = list_items(Call::kSessionList, engine_name_.str(),
|
||||
list_query(options.filter, options.order_by, options.page_size),
|
||||
"sessions", SessionsCaps::kMaxListPages,
|
||||
SessionsCaps::kMaxListItems);
|
||||
std::vector<Session> out;
|
||||
for (const Json& item : items.as_array()) out.push_back(Session::from_json(item));
|
||||
return out;
|
||||
}
|
||||
|
||||
Session Sessions::patch(const SessionPatch& patch) const {
|
||||
patch.validate();
|
||||
Json body = patch.to_json();
|
||||
return Session::from_json(send(Call::kSessionPatch,
|
||||
engine_name_.session(patch.session_id), &body,
|
||||
query_of({{"updateMask", patch.update_mask}})));
|
||||
}
|
||||
|
||||
void Sessions::delete_session(const std::string& session_id) const {
|
||||
Json reply = send(Call::kSessionDelete, engine_name_.session(session_id));
|
||||
if (reply.is_object() && !reply.as_object().empty()) settle(reply);
|
||||
}
|
||||
|
||||
void Sessions::compact(const std::string& session_id, const CompactRequest& request) const {
|
||||
request.validate();
|
||||
Json body = request.to_json();
|
||||
settle(send(Call::kSessionCompact, engine_name_.session(session_id), &body));
|
||||
}
|
||||
|
||||
void Sessions::append_event(const std::string& session_id,
|
||||
const SessionEvent& event) const {
|
||||
event.validate();
|
||||
Json body = event.to_json();
|
||||
send(Call::kSessionAppendEvent, engine_name_.session(session_id), &body);
|
||||
}
|
||||
|
||||
std::vector<SessionEvent> Sessions::list_events(const std::string& session_id,
|
||||
const EventListOptions& options) const {
|
||||
Json items = list_items(Call::kEventList, engine_name_.session(session_id),
|
||||
list_query(options.filter, options.order_by, options.page_size),
|
||||
"sessionEvents", SessionsCaps::kMaxListPages,
|
||||
SessionsCaps::kMaxListItems);
|
||||
std::vector<SessionEvent> out;
|
||||
for (const Json& item : items.as_array()) out.push_back(SessionEvent::from_json(item));
|
||||
return out;
|
||||
}
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,35 @@
|
||||
#pragma once
|
||||
|
||||
// Agent Sessions: sessions and their events under one Agent Engine
|
||||
// (reasoningEngines) resource. Every call is a row in calls.h.
|
||||
|
||||
#include <memory>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
#include "google/sessions/engine_service.h"
|
||||
#include "google/sessions/session_types.h"
|
||||
|
||||
namespace molo::google::sessions {
|
||||
|
||||
class Sessions : public EngineService {
|
||||
public:
|
||||
// `sleeper` replaces the real sleep between operation polls (tests).
|
||||
Sessions(std::shared_ptr<GoogleClient> client, EngineName engine,
|
||||
Sleeper sleeper = nullptr);
|
||||
|
||||
Session create(const SessionSpec& spec) const; // waits for the operation
|
||||
Session get(const std::string& session_id) const;
|
||||
std::vector<Session> list(const SessionListOptions& options = {}) const;
|
||||
Session patch(const SessionPatch& patch) const;
|
||||
// Destructive: explicit method, waits for the delete operation.
|
||||
void delete_session(const std::string& session_id) const;
|
||||
// Rewrites the event history (summary and/or edits); waits.
|
||||
void compact(const std::string& session_id, const CompactRequest& request) const;
|
||||
|
||||
void append_event(const std::string& session_id, const SessionEvent& event) const;
|
||||
std::vector<SessionEvent> list_events(const std::string& session_id,
|
||||
const EventListOptions& options = {}) const;
|
||||
};
|
||||
|
||||
} // namespace molo::google::sessions
|
||||
@@ -0,0 +1,207 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Checks src/google/sessions/calls.h against Google's Discovery document.
|
||||
|
||||
Fetches https://aiplatform.googleapis.com/$discovery/rest?version=<v> (no
|
||||
credential needed) and fails when a declared call, verb, path, request schema
|
||||
field, query parameter, enum value or response key is absent.
|
||||
|
||||
python3 src/google/sessions/tools/check_discovery.py [--file discovery.json]
|
||||
|
||||
Exit 0: everything declared exists. Exit 1: mismatches, listed. Exit 2: the
|
||||
discovery document could not be read. Python 3 stdlib only. Sends no secret.
|
||||
"""
|
||||
import datetime
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import urllib.request
|
||||
|
||||
HERE = os.path.dirname(os.path.abspath(__file__))
|
||||
CALLS_H = os.path.join(HERE, "..", "calls.h")
|
||||
SCHEMA_PREFIX = "GoogleCloudAiplatform"
|
||||
|
||||
# (schema suffix, property, expected enum values that the C++ code sends)
|
||||
ENUMS = [
|
||||
("MemoryTopicId", "managedMemoryTopic",
|
||||
["USER_PERSONAL_INFO", "USER_PREFERENCES", "KEY_CONVERSATION_DETAILS",
|
||||
"EXPLICIT_INSTRUCTIONS"]),
|
||||
("GenerateMemoriesRequest", "metadataMergeStrategy",
|
||||
["OVERWRITE", "MERGE", "REQUIRE_EXACT_MATCH"]),
|
||||
("IngestEventsRequest", "metadataMergeStrategy",
|
||||
["OVERWRITE", "MERGE", "REQUIRE_EXACT_MATCH"]),
|
||||
("MemoryFilter", "op", ["EQUAL", "GREATER_THAN", "LESS_THAN"]),
|
||||
("Memory", "memoryType", ["NATURAL_LANGUAGE_COLLECTION", "STRUCTURED_PROFILE"]),
|
||||
("CompactionConfigLlmSummarizationConfig", "mode", ["AUTO"]),
|
||||
("CompactionConfigEventEditingConfig", "mode", ["AUTO"]),
|
||||
]
|
||||
|
||||
# (schema suffix, property) read by the response parsers.
|
||||
RESPONSE_KEYS = [
|
||||
("ListSessionsResponse", "sessions"), ("ListSessionsResponse", "nextPageToken"),
|
||||
("ListEventsResponse", "sessionEvents"), ("ListEventsResponse", "nextPageToken"),
|
||||
("ListMemoriesResponse", "memories"), ("ListMemoriesResponse", "nextPageToken"),
|
||||
("ListMemoryRevisionsResponse", "memoryRevisions"),
|
||||
("RetrieveMemoriesResponse", "retrievedMemories"),
|
||||
("RetrieveMemoriesResponse", "nextPageToken"),
|
||||
("RetrieveMemoriesResponseRetrievedMemory", "memory"),
|
||||
("RetrieveMemoriesResponseRetrievedMemory", "distance"),
|
||||
("RetrieveProfilesResponse", "profiles"),
|
||||
("MemoryProfile", "profile"), ("MemoryProfile", "schemaId"),
|
||||
("MemoryRevision", "fact"), ("MemoryRevision", "context"),
|
||||
("MemoryRevision", "labels"), ("MemoryRevision", "createTime"),
|
||||
("MemoryRevision", "expireTime"),
|
||||
("Session", "name"), ("Session", "createTime"), ("Session", "updateTime"),
|
||||
("Session", "expireTime"), ("Memory", "name"), ("Memory", "expireTime"),
|
||||
]
|
||||
|
||||
# Nested request shapes built by the C++ code: (schema suffix, fields).
|
||||
NESTED = [
|
||||
("GenerateMemoriesRequestVertexSessionSource", "session startTime endTime"),
|
||||
("GenerateMemoriesRequestDirectContentsSource", "events"),
|
||||
("GenerateMemoriesRequestDirectContentsSourceEvent", "content"),
|
||||
("GenerateMemoriesRequestDirectMemoriesSource", "directMemories"),
|
||||
("GenerateMemoriesRequestDirectMemoriesSourceDirectMemory", "fact topics"),
|
||||
("RetrieveMemoriesRequestSimilaritySearchParams", "searchQuery topK"),
|
||||
("RetrieveMemoriesRequestSimpleRetrievalParams", "pageSize pageToken"),
|
||||
("IngestionDirectContentsSource", "events"),
|
||||
("IngestionDirectContentsSourceEvent", "eventId eventTime content"),
|
||||
("MemoryGenerationTriggerConfig", "generationRule"),
|
||||
("MemoryGenerationTriggerConfigGenerationTriggerRule",
|
||||
"eventCount overlapEventCount fixedInterval idleDuration"),
|
||||
("MemoryConjunctionFilter", "filters"),
|
||||
("MemoryFilter", "key op negate value"),
|
||||
("MemoryMetadataValue", "stringValue doubleValue boolValue timestampValue"),
|
||||
("MemoryTopicId", "customMemoryTopicLabel managedMemoryTopic"),
|
||||
("CompactionConfig", "summarization eventEditing"),
|
||||
("CompactionConfigLlmSummarizationConfig", "mode"),
|
||||
("CompactionConfigEventEditingConfig", "mode"),
|
||||
]
|
||||
|
||||
|
||||
def load(path):
|
||||
if path:
|
||||
with open(path, "r", encoding="utf-8") as f:
|
||||
return json.load(f)
|
||||
version = parse_header()["version"]
|
||||
url = "https://aiplatform.googleapis.com/$discovery/rest?version=" + version
|
||||
with urllib.request.urlopen(url, timeout=120) as r:
|
||||
return json.load(r)
|
||||
|
||||
|
||||
def parse_header():
|
||||
text = open(CALLS_H, "r", encoding="utf-8").read()
|
||||
version = re.search(r'kDiscoveryVersion\s*=\s*"([^"]+)"', text).group(1)
|
||||
prefix = re.search(r'kDiscoveryPrefix\s*=\s*"([^"]+)"', text).group(1)
|
||||
rows = []
|
||||
row_re = re.compile(
|
||||
r'^\{Call::(k\w+),\s*"(\w+)",\s*"([^"]*)",\s*"([^"]*)",\s*"([^"]*)",'
|
||||
r'\s*"([^"]*)",\s*"([^"]*)"\},\s*$', re.M)
|
||||
for m in row_re.finditer(text):
|
||||
rows.append({"call": m.group(1), "verb": m.group(2), "path": m.group(3),
|
||||
"method": m.group(4), "request": m.group(5),
|
||||
"fields": m.group(6).split(), "query": m.group(7).split()})
|
||||
enum_names = re.search(r"enum class Call \{(.*?)kCount", text, re.S).group(1)
|
||||
declared = re.findall(r"\bk\w+", enum_names)
|
||||
return {"version": version, "prefix": prefix, "rows": rows, "declared": declared}
|
||||
|
||||
|
||||
def find_method(doc, method_id):
|
||||
found = []
|
||||
|
||||
def walk(res):
|
||||
for m in res.get("methods", {}).values():
|
||||
if m["id"] == method_id:
|
||||
found.append(m)
|
||||
for r in res.get("resources", {}).values():
|
||||
walk(r)
|
||||
|
||||
walk(doc)
|
||||
return found[0] if found else None
|
||||
|
||||
|
||||
def normalize(path, version):
|
||||
path = re.sub(r"\{\+(\w+)\}", r"{\1}", path)
|
||||
return "/" + path[len(version) + 1:] if path.startswith(version + "/") else path
|
||||
|
||||
|
||||
def main():
|
||||
path = None
|
||||
if "--file" in sys.argv:
|
||||
path = sys.argv[sys.argv.index("--file") + 1]
|
||||
header = parse_header()
|
||||
try:
|
||||
doc = load(path)
|
||||
except Exception as exc: # network or parse failure is not a mismatch
|
||||
print("cannot read discovery document: %s" % exc)
|
||||
return 2
|
||||
version, prefix = header["version"], header["prefix"]
|
||||
schemas = doc["schemas"]
|
||||
schema_prefix = SCHEMA_PREFIX + ("V1beta1" if version == "v1beta1" else "V1")
|
||||
errors = []
|
||||
rows = header["rows"]
|
||||
if sorted(r["call"] for r in rows) != sorted(header["declared"]):
|
||||
errors.append("calls.h: enum Call and table rows differ")
|
||||
|
||||
for row in rows:
|
||||
mid = prefix + row["method"]
|
||||
m = find_method(doc, mid)
|
||||
if m is None:
|
||||
errors.append("%s: method %s absent" % (row["call"], mid))
|
||||
continue
|
||||
if m["httpMethod"] != row["verb"]:
|
||||
errors.append("%s: verb %s != %s" % (row["call"], row["verb"], m["httpMethod"]))
|
||||
got = normalize(m["path"], version)
|
||||
if got != row["path"]:
|
||||
errors.append("%s: path %s != %s" % (row["call"], row["path"], got))
|
||||
for q in row["query"]:
|
||||
p = m.get("parameters", {}).get(q)
|
||||
if not p or p.get("location") != "query":
|
||||
errors.append("%s: query parameter %s absent" % (row["call"], q))
|
||||
if row["request"]:
|
||||
want = schema_prefix + row["request"]
|
||||
ref = m.get("request", {}).get("$ref")
|
||||
if ref != want:
|
||||
errors.append("%s: request %s != %s" % (row["call"], want, ref))
|
||||
props = schemas.get(want, {}).get("properties", {})
|
||||
for field in row["fields"]:
|
||||
if field not in props:
|
||||
errors.append("%s: field %s absent from %s" % (row["call"], field, want))
|
||||
elif m.get("request"):
|
||||
errors.append("%s: discovery has a request body %s the table omits" %
|
||||
(row["call"], m["request"]["$ref"]))
|
||||
|
||||
for suffix, prop, values in ENUMS:
|
||||
s = schemas.get(schema_prefix + suffix, {}).get("properties", {}).get(prop)
|
||||
if s is None:
|
||||
errors.append("enum %s.%s absent" % (suffix, prop))
|
||||
continue
|
||||
allowed = s.get("enum")
|
||||
if allowed is None: # Free string in discovery: documented, not enforced.
|
||||
continue
|
||||
for v in values:
|
||||
if v not in allowed:
|
||||
errors.append("enum value %s absent from %s.%s" % (v, suffix, prop))
|
||||
for suffix, prop in RESPONSE_KEYS:
|
||||
if prop not in schemas.get(schema_prefix + suffix, {}).get("properties", {}):
|
||||
errors.append("response key %s.%s absent" % (suffix, prop))
|
||||
for suffix, fields in NESTED:
|
||||
props = schemas.get(schema_prefix + suffix, {}).get("properties", {})
|
||||
for field in fields.split():
|
||||
if field not in props:
|
||||
errors.append("nested %s.%s absent" % (suffix, field))
|
||||
|
||||
stamp = datetime.date.today().isoformat()
|
||||
if errors:
|
||||
print("FAIL (%s, discovery %s): %d mismatches" % (stamp, version, len(errors)))
|
||||
for e in errors:
|
||||
print(" - " + e)
|
||||
return 1
|
||||
print("OK %s: %d calls, %d enums, %d response keys, %d nested schemas match "
|
||||
"aiplatform %s discovery" %
|
||||
(stamp, len(rows), len(ENUMS), len(RESPONSE_KEYS), len(NESTED), version))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,131 @@
|
||||
// Routes: every POST/DELETE under /agent/sessions. Without a credential they
|
||||
// answer 503 google_not_configured; bad input is 422 before any traffic; a
|
||||
// wrong verb is 405. No Google reply is scripted: the mock has no
|
||||
// expectations, so any request that reached it would fail loudly.
|
||||
#include <cstdlib>
|
||||
#include <string>
|
||||
#include <vector>
|
||||
|
||||
#include "fw/Http.hpp"
|
||||
#include "support/GoogleRig.hpp"
|
||||
|
||||
using namespace molo::example::test;
|
||||
|
||||
namespace {
|
||||
const std::string kEngine = "projects/p1/locations/us-central1/reasoningEngines/1";
|
||||
const std::string kJson = "application/json";
|
||||
|
||||
std::string body(const std::string& extra) {
|
||||
return "{\"engine\":\"" + kEngine + "\"," + extra + "}";
|
||||
}
|
||||
|
||||
struct Route {
|
||||
std::string path;
|
||||
std::string valid; // valid input (no credential: expect 503)
|
||||
std::string invalid; // bad input (expect 422)
|
||||
};
|
||||
} // namespace
|
||||
|
||||
int main() {
|
||||
setenv("GOOGLE_CLOUD_PROJECT", "p1", 1);
|
||||
const std::vector<Route> posts = {
|
||||
{"/agent/sessions/create", body("\"user_id\":\"u1\",\"session_id\":\"chat-1\""),
|
||||
body("\"user_id\":\"u1\",\"session_id\":\"Bad_Id\"")},
|
||||
{"/agent/sessions/get", body("\"session_id\":\"chat-1\""), body("\"session_id\":\"\"")},
|
||||
{"/agent/sessions/list", body("\"filter\":\"userId=\\\"u1\\\"\""), "{\"engine\":\"a/b\"}"},
|
||||
{"/agent/sessions/events/append",
|
||||
body("\"session_id\":\"chat-1\",\"author\":\"user\",\"invocation_id\":\"i1\","
|
||||
"\"timestamp\":\"2025-01-31T11:30:00Z\",\"text\":\"hi\""),
|
||||
body("\"session_id\":\"chat-1\",\"author\":\"user\",\"invocation_id\":\"i1\","
|
||||
"\"timestamp\":\"yesterday\"")},
|
||||
{"/agent/sessions/events/list", body("\"session_id\":\"chat-1\""),
|
||||
body("\"session_id\":\"a/b\"")},
|
||||
{"/agent/sessions/memories/generate",
|
||||
body("\"scope_key\":\"user_id\",\"scope_value\":\"1\",\"text\":\"I like tea\""),
|
||||
body("\"scope_key\":\"user_id\",\"scope_value\":\"*\",\"text\":\"x\"")},
|
||||
{"/agent/sessions/memories/retrieve",
|
||||
body("\"scope_key\":\"user_id\",\"scope_value\":\"1\",\"query\":\"tea\",\"top_k\":\"3\""),
|
||||
body("\"scope_key\":\"user_id\",\"scope_value\":\"1\",\"query\":\"tea\",\"top_k\":\"51\"")},
|
||||
{"/agent/sessions/memories/create",
|
||||
body("\"scope_key\":\"user_id\",\"scope_value\":\"1\",\"fact\":\"likes tea\""),
|
||||
body("\"scope_key\":\"user_id\",\"scope_value\":\"1\",\"fact\":\"\"")},
|
||||
{"/agent/sessions/memories/get", body("\"memory_id\":\"mem-1\""),
|
||||
body("\"memory_id\":\"1bad\"")},
|
||||
{"/agent/sessions/memories/list", body("\"filter\":\"topics=\\\"x\\\"\""),
|
||||
"{\"engine\":\"\"}"},
|
||||
{"/agent/sessions/memories/profiles",
|
||||
body("\"scope_key\":\"user_id\",\"scope_value\":\"1\""), body("\"scope_key\":\"\"")},
|
||||
{"/agent/sessions/memories/purge", body("\"filter\":\"scope.user_id=\\\"1\\\"\""),
|
||||
body("\"filter\":\"\"")},
|
||||
};
|
||||
|
||||
GoogleRig rig(false);
|
||||
Fixture f(rig.client);
|
||||
for (const Route& r : posts) {
|
||||
auto none = f.client->post(r.path, r.valid, kJson);
|
||||
check(none.status == 503 && contains(none.body, "google_not_configured"),
|
||||
r.path + ": no credential is a loud 503");
|
||||
auto bad = f.client->post(r.path, r.invalid, kJson);
|
||||
check(bad.status == 422 && contains(bad.body, "validation_error"),
|
||||
r.path + ": bad input is 422");
|
||||
check(f.client->get(r.path).status == 405, r.path + ": get is 405");
|
||||
}
|
||||
|
||||
// Bare engine id resolves through GOOGLE_CLOUD_PROJECT.
|
||||
auto bare = f.client->post("/agent/sessions/get",
|
||||
"{\"engine\":\"1\",\"session_id\":\"chat-1\"}", kJson);
|
||||
check(bare.status == 503, "bare engine id with a project env reaches the client");
|
||||
unsetenv("GOOGLE_CLOUD_PROJECT");
|
||||
auto no_project = f.client->post("/agent/sessions/get",
|
||||
"{\"engine\":\"1\",\"session_id\":\"chat-1\"}", kJson);
|
||||
check(no_project.status == 422, "bare engine id without a project is 422");
|
||||
setenv("GOOGLE_CLOUD_PROJECT", "p1", 1);
|
||||
|
||||
// Limits: id cap (63), purge guard, dry run default.
|
||||
check(f.client->post("/agent/sessions/get",
|
||||
body("\"session_id\":\"" + std::string(64, 'a') + "\""), kJson)
|
||||
.status == 422,
|
||||
"session id over 63 characters is 422");
|
||||
check(f.client->post("/agent/sessions/get",
|
||||
body("\"session_id\":\"" + std::string(63, 'a') + "\""), kJson)
|
||||
.status == 503,
|
||||
"session id of exactly 63 characters passes validation");
|
||||
auto forced = f.client->post(
|
||||
"/agent/sessions/memories/purge",
|
||||
body("\"filter\":\"scope.user_id=\\\"1\\\"\",\"force\":\"true\""), kJson);
|
||||
check(forced.status == 422 && contains(forced.body, "confirm"),
|
||||
"forced purge without confirm is 422");
|
||||
auto confirmed = f.client->post(
|
||||
"/agent/sessions/memories/purge",
|
||||
body("\"filter\":\"scope.user_id=\\\"1\\\"\",\"force\":\"true\",\"confirm\":\"1\""),
|
||||
kJson);
|
||||
check(confirmed.status == 503, "forced purge with the engine id as confirm reaches the client");
|
||||
|
||||
// DELETE routes.
|
||||
using molo::example::fw::Method;
|
||||
auto del_session = f.client->request(
|
||||
Method::Delete, "/agent/sessions/session?engine=" + kEngine + "&id=chat-1");
|
||||
check(del_session.status == 503 && contains(del_session.body, "google_not_configured"),
|
||||
"delete session: no credential is 503");
|
||||
check(f.client->request(Method::Delete,
|
||||
"/agent/sessions/session?engine=" + kEngine + "&id=BAD").status == 422,
|
||||
"delete session: bad id is 422");
|
||||
check(f.client->post("/agent/sessions/session").status == 405, "delete route: post is 405");
|
||||
auto del_memory = f.client->request(
|
||||
Method::Delete, "/agent/sessions/memories/memory?engine=" + kEngine + "&id=mem-1");
|
||||
check(del_memory.status == 503, "delete memory: no credential is 503");
|
||||
check(f.client->request(Method::Delete,
|
||||
"/agent/sessions/memories/memory?engine=" + kEngine + "&id=1x").status ==
|
||||
422,
|
||||
"delete memory: bad id is 422");
|
||||
|
||||
check(rig.mock->send_count() == 0, "side effect: nothing reached the network");
|
||||
|
||||
// With a credential, validation still runs first and still stops traffic.
|
||||
GoogleRig keyed;
|
||||
Fixture g(keyed.client);
|
||||
check(g.client->post("/agent/sessions/get", body("\"session_id\":\"BAD\""), kJson).status == 422,
|
||||
"credentialed bad input is 422");
|
||||
check(keyed.mock->send_count() == 0, "rejected input never reached Google");
|
||||
return finish("agent/sessions calls");
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
// Routes: GET /agent/sessions (page), GET /agent/sessions/status
|
||||
#include "support/GoogleRig.hpp"
|
||||
|
||||
using namespace molo::example::test;
|
||||
|
||||
int main() {
|
||||
{
|
||||
GoogleRig rig;
|
||||
Fixture f(rig.client);
|
||||
auto page = f.client->get("/agent/sessions");
|
||||
check(page.status == 200, "page 200");
|
||||
check(contains(page.headers.get("Content-Type"), "text/html"), "html");
|
||||
check(contains(page.body, "Agent sessions and memory"), "heading");
|
||||
check(contains(page.body, "/agent/sessions/memories/purge"), "lists the purge route");
|
||||
check(contains(page.body, "viewport"), "mobile viewport meta from the base template");
|
||||
|
||||
auto status = f.client->get("/agent/sessions/status");
|
||||
check(status.status == 200, "status 200");
|
||||
check(contains(status.headers.get("Content-Type"), "application/json"), "status is json");
|
||||
check(contains(status.body, "\"configured\":true"), "configured with a credential");
|
||||
check(contains(status.body, "aiplatform v1beta1"), "names the API surface");
|
||||
check(contains(status.body, "\"max_top_k\":50"), "shows the top_k cap");
|
||||
check(!contains(status.body, kTestKey), "credential never shown");
|
||||
check(rig.mock->send_count() == 0, "side effect: GET pages never call Google");
|
||||
}
|
||||
{
|
||||
GoogleRig rig(false);
|
||||
Fixture f(rig.client);
|
||||
check(contains(f.client->get("/agent/sessions/status").body, "\"configured\":false"),
|
||||
"not configured without a credential");
|
||||
check(f.client->get("/agent/sessions").status == 200, "page works without a credential");
|
||||
}
|
||||
Fixture f;
|
||||
check(f.client->post("/agent/sessions").status == 405, "post on the page is 405");
|
||||
check(f.client->post("/agent/sessions/status").status == 405, "post on status is 405");
|
||||
return finish("agent/sessions page");
|
||||
}
|
||||
@@ -0,0 +1,520 @@
|
||||
// Agent Sessions and Memory Bank: deterministic local checks only (names,
|
||||
// ids, caps, validation before traffic, request bodies against the call
|
||||
// table that tools/check_discovery.py verifies against Google's Discovery
|
||||
// document). No scripted Google replies. The opt-in live probe at the end is
|
||||
// read-only and gated on MOLO_LIVE_NET=1 plus a credential.
|
||||
#include <algorithm>
|
||||
#include <cstdlib>
|
||||
#include <functional>
|
||||
#include <iostream>
|
||||
#include <memory>
|
||||
#include <set>
|
||||
#include <sstream>
|
||||
|
||||
#include "framework.h"
|
||||
#include "clients/transports/http_transport.h"
|
||||
#include "clients/transports/mock_transport.h"
|
||||
#include "google/credentials.h"
|
||||
#include "google/sessions/calls.h"
|
||||
#include "google/sessions/caps.h"
|
||||
#include "google/sessions/memory_bank.h"
|
||||
#include "google/sessions/sessions.h"
|
||||
|
||||
using namespace molo::google;
|
||||
using namespace molo::google::sessions;
|
||||
using molo::clients::body::Json;
|
||||
using molo::clients::transports::MockTransport;
|
||||
|
||||
namespace {
|
||||
|
||||
const char* kEngine = "projects/p1/locations/us-central1/reasoningEngines/e1";
|
||||
|
||||
struct Rig {
|
||||
MockTransport* mock;
|
||||
std::shared_ptr<GoogleClient> client;
|
||||
explicit Rig(bool with_credential = true) {
|
||||
auto t = std::make_unique<MockTransport>();
|
||||
mock = t.get();
|
||||
client = std::make_shared<GoogleClient>(
|
||||
std::move(t), with_credential ? Credentials::bearer("tok") : nullptr);
|
||||
}
|
||||
};
|
||||
|
||||
std::set<std::string> words(const std::string& s) {
|
||||
std::set<std::string> out;
|
||||
std::istringstream in(s);
|
||||
for (std::string w; in >> w;) out.insert(w);
|
||||
return out;
|
||||
}
|
||||
|
||||
// Every key of a built body must be a field the call table declares (and the
|
||||
// discovery check proves exists in Google's request schema).
|
||||
void keys_declared(const Json& body, Call call) {
|
||||
std::set<std::string> allowed = words(spec_of(call).fields);
|
||||
ASSERT_TRUE(body.is_object());
|
||||
for (const auto& [key, value] : body.as_object()) {
|
||||
(void)value;
|
||||
if (!allowed.count(key)) FAIL("body key '" << key << "' not in the table row");
|
||||
}
|
||||
}
|
||||
|
||||
void invalid(const std::function<void()>& fn) {
|
||||
try {
|
||||
fn();
|
||||
} catch (const GoogleError& e) {
|
||||
ASSERT_EQ(e.http_status(), 400);
|
||||
ASSERT_EQ(e.status(), std::string("INVALID_ARGUMENT"));
|
||||
ASSERT_TRUE(e.service().empty()); // local validation, not upstream
|
||||
return;
|
||||
}
|
||||
FAIL("expected INVALID_ARGUMENT");
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
TEST(sessions_table, every_call_has_one_well_formed_row) {
|
||||
std::set<int> seen;
|
||||
for (const CallSpec& row : kCalls) {
|
||||
ASSERT_TRUE(seen.insert(static_cast<int>(row.call)).second);
|
||||
std::string path = row.path;
|
||||
ASSERT_TRUE(path.front() == '/');
|
||||
ASSERT_EQ(std::count(path.begin(), path.end(), '{'), 1);
|
||||
ASSERT_TRUE(path.find("{parent}") != std::string::npos ||
|
||||
path.find("{name}") != std::string::npos);
|
||||
std::string verb = row.verb;
|
||||
ASSERT_TRUE(verb == "GET" || verb == "POST" || verb == "PATCH" || verb == "DELETE");
|
||||
if (verb == "GET" || verb == "DELETE") ASSERT_EQ(std::string(row.fields), std::string());
|
||||
}
|
||||
ASSERT_EQ(seen.size(), static_cast<std::size_t>(Call::kCount));
|
||||
ASSERT_EQ(expand(Call::kSessionAppendEvent, "x/y"), std::string("/x/y:appendEvent"));
|
||||
ASSERT_EQ(expand(Call::kMemoryList, "x", "?a=b"), std::string("/x/memories?a=b"));
|
||||
}
|
||||
|
||||
TEST(sessions_names, engine_name_parsing) {
|
||||
EngineName e(kEngine);
|
||||
ASSERT_EQ(e.project(), std::string("p1"));
|
||||
ASSERT_EQ(e.location(), std::string("us-central1"));
|
||||
ASSERT_EQ(e.engine(), std::string("e1"));
|
||||
ASSERT_EQ(e.session("s-1"), std::string(kEngine) + "/sessions/s-1");
|
||||
ASSERT_EQ(e.memory("m-1"), std::string(kEngine) + "/memories/m-1");
|
||||
for (const char* bad : {"", "e1", "projects/p/locations/l/reasoningEngines",
|
||||
"projects/p/locations/l/reasoningEngines/e/extra",
|
||||
"projects/p/locations/l/engines/e",
|
||||
"projects/P/locations/l/reasoningEngines/e",
|
||||
"projects/p/locations/L/reasoningEngines/e",
|
||||
"projects/p/locations/l/reasoningEngines/..",
|
||||
"projects/p/locations/l/reasoningEngines/e?x=1",
|
||||
"projects/p/locations//reasoningEngines/e"})
|
||||
invalid([&] { EngineName n{std::string(bad)}; });
|
||||
invalid([] { EngineName n{std::string(600, 'a')}; });
|
||||
}
|
||||
|
||||
TEST(sessions_names, ids_and_checks) {
|
||||
Check::session_id("a");
|
||||
Check::session_id(std::string(63, 'a'));
|
||||
Check::session_id("0-9-a");
|
||||
for (const char* bad : {"", "A", "a_b", "a/b", "a b", "a.b"})
|
||||
invalid([&] { Check::session_id(bad); });
|
||||
invalid([] { Check::session_id(std::string(64, 'a')); });
|
||||
Check::memory_id("m1");
|
||||
for (const char* bad : {"", "1m", "-m", "m-", "M", "m_1"})
|
||||
invalid([&] { Check::memory_id(bad); });
|
||||
Check::ttl("86400s", 86400);
|
||||
Check::ttl("90000.5s", 86400);
|
||||
for (const char* bad : {"", "s", "86400", "1d", "-5s", "1.s", ".5s", "1.2.3s", "86399s"})
|
||||
invalid([&] { Check::ttl(bad, 86400); });
|
||||
invalid([] { Check::ttl("999999999999s", 1); });
|
||||
Check::timestamp("t", "2025-01-31T11:30:00Z");
|
||||
Check::timestamp("t", "2025-01-31T11:30:00.123+02:00");
|
||||
for (const char* bad : {"", "yesterday", "2025-01-31 11:30:00Z", "2025/01/31T11:30:00Z"})
|
||||
invalid([&] { Check::timestamp("t", bad); });
|
||||
Check::scope({{"user_id", "42"}});
|
||||
invalid([] { Check::scope({}); });
|
||||
invalid([] { Check::scope({{"user_id", "*"}}); });
|
||||
invalid([] { Check::scope({{"u*", "1"}}); });
|
||||
invalid([] { Check::scope({{"u", ""}}); });
|
||||
StringMap many;
|
||||
for (int i = 0; i < 11; ++i) many["k" + std::to_string(i)] = "v";
|
||||
invalid([&] { Check::scope(many); });
|
||||
invalid([] { Check::expression("filter", std::string("a\nb")); });
|
||||
invalid([] { Check::expression("filter", std::string(513, 'a')); });
|
||||
invalid([] { Check::page_size(101, 100); });
|
||||
invalid([] { Check::page_size(-1, 100); });
|
||||
ASSERT_EQ(query_of({{"a", "x y"}, {"b", ""}, {"c", "1&2"}}),
|
||||
std::string("?a=x%20y&c=1%262"));
|
||||
}
|
||||
|
||||
TEST(sessions_bodies, session_create_patch_compact_event) {
|
||||
SessionSpec spec;
|
||||
spec.session_id = "chat-1";
|
||||
spec.user_id = "u1";
|
||||
spec.display_name = "d";
|
||||
spec.labels = {{"env", "test"}};
|
||||
Json state = Json::object();
|
||||
state.set("k", Json("v"));
|
||||
spec.session_state = state;
|
||||
spec.ttl = "86400s";
|
||||
spec.validate();
|
||||
keys_declared(spec.to_json(), Call::kSessionCreate);
|
||||
ASSERT_EQ(spec.to_json().find("userId")->as_string(), std::string("u1"));
|
||||
|
||||
SessionPatch patch;
|
||||
patch.session_id = "chat-1";
|
||||
patch.display_name = "new";
|
||||
patch.update_mask = "displayName";
|
||||
patch.validate();
|
||||
keys_declared(patch.to_json(), Call::kSessionPatch);
|
||||
patch.update_mask = "";
|
||||
invalid([&] { patch.validate(); });
|
||||
patch.update_mask = "a;b";
|
||||
invalid([&] { patch.validate(); });
|
||||
|
||||
CompactRequest compact;
|
||||
invalid([&] { compact.validate(); });
|
||||
compact.summarization = true;
|
||||
compact.validate();
|
||||
keys_declared(compact.to_json(), Call::kSessionCompact);
|
||||
ASSERT_EQ(compact.to_json().dump(), std::string("{\"compaction\":{\"summarization\":{\"mode\":\"AUTO\"}}}"));
|
||||
|
||||
SessionEvent ev;
|
||||
ev.author = "user";
|
||||
ev.invocation_id = "inv-1";
|
||||
ev.timestamp = "2025-01-31T11:30:00Z";
|
||||
ev.content = Content::user("hello");
|
||||
Json actions = Json::object();
|
||||
actions.set("escalate", Json(true));
|
||||
ev.actions = actions;
|
||||
ev.error_code = "E1";
|
||||
ev.validate();
|
||||
keys_declared(ev.to_json(), Call::kSessionAppendEvent);
|
||||
SessionEvent round = SessionEvent::from_json(ev.to_json());
|
||||
ASSERT_EQ(round.author, std::string("user"));
|
||||
ASSERT_EQ(round.content->text(), std::string("hello"));
|
||||
ev.invocation_id.clear();
|
||||
invalid([&] { ev.validate(); });
|
||||
}
|
||||
|
||||
TEST(sessions_bodies, session_validation_caps) {
|
||||
SessionSpec spec;
|
||||
invalid([&] { spec.validate(); }); // user_id required
|
||||
spec.user_id = "u";
|
||||
spec.validate();
|
||||
spec.session_id = "BAD";
|
||||
invalid([&] { spec.validate(); });
|
||||
spec.session_id.clear();
|
||||
spec.ttl = "3600s"; // below the 24 h minimum
|
||||
invalid([&] { spec.validate(); });
|
||||
spec.ttl.clear();
|
||||
spec.session_state = Json(std::string("not an object"));
|
||||
invalid([&] { spec.validate(); });
|
||||
Json big = Json::object();
|
||||
big.set("blob", Json(std::string(70 * 1024, 'x')));
|
||||
spec.session_state = big;
|
||||
invalid([&] { spec.validate(); });
|
||||
spec.session_state = Json();
|
||||
for (int i = 0; i < 21; ++i) spec.labels["l" + std::to_string(i)] = "v";
|
||||
invalid([&] { spec.validate(); });
|
||||
|
||||
SessionEvent ev;
|
||||
ev.author = "a";
|
||||
ev.invocation_id = "i";
|
||||
ev.timestamp = "2025-01-31T11:30:00Z";
|
||||
ev.content = Content::user(std::string(300 * 1024, 'x'));
|
||||
invalid([&] { ev.validate(); });
|
||||
}
|
||||
|
||||
TEST(memory_bodies, generate_sources) {
|
||||
MemoryGenerateRequest g;
|
||||
g.scope = {{"user_id", "1"}};
|
||||
g.contents = {Content::user("I like tea"), Content::model("noted")};
|
||||
g.disable_consolidation = true;
|
||||
g.allowed_topics = {Topic::managed("USER_PREFERENCES"), Topic::custom("hobbies")};
|
||||
g.metadata["src"] = MetadataValue::of_string("chat");
|
||||
g.metadata["score"] = MetadataValue::of_double(1.5);
|
||||
g.metadata_merge_strategy = "MERGE";
|
||||
g.time_zone = "Europe/Amsterdam";
|
||||
g.revision.labels = {{"run", "1"}};
|
||||
g.revision.ttl = "3600s";
|
||||
g.validate();
|
||||
Json body = g.to_json(kEngine);
|
||||
keys_declared(body, Call::kMemoryGenerate);
|
||||
ASSERT_TRUE(body.find("directContentsSource") != nullptr);
|
||||
ASSERT_TRUE(body.find("vertexSessionSource") == nullptr);
|
||||
ASSERT_EQ(body.find("directContentsSource")->find("events")->as_array().size(), std::size_t(2));
|
||||
ASSERT_EQ(body.find("allowedTopics")->as_array()[1].find("customMemoryTopicLabel")->as_string(),
|
||||
std::string("hobbies"));
|
||||
|
||||
g.source = MemoryGenerateRequest::Source::kSession;
|
||||
g.session_id = "chat-1";
|
||||
g.start_time = "2025-01-31T11:30:00Z";
|
||||
g.validate();
|
||||
Json sb = g.to_json(kEngine);
|
||||
keys_declared(sb, Call::kMemoryGenerate);
|
||||
ASSERT_EQ(sb.find("vertexSessionSource")->find("session")->as_string(),
|
||||
std::string(kEngine) + "/sessions/chat-1");
|
||||
|
||||
g.source = MemoryGenerateRequest::Source::kDirectMemories;
|
||||
invalid([&] { g.validate(); }); // none given
|
||||
for (int i = 0; i < 6; ++i) g.direct_memories.push_back({"fact", {}});
|
||||
invalid([&] { g.validate(); }); // Google allows at most 5
|
||||
g.direct_memories.resize(5);
|
||||
g.validate();
|
||||
keys_declared(g.to_json(kEngine), Call::kMemoryGenerate);
|
||||
|
||||
g.source = MemoryGenerateRequest::Source::kContents;
|
||||
g.contents.clear();
|
||||
invalid([&] { g.validate(); });
|
||||
g.contents = {Content::user(std::string(70 * 1024, 'x'))};
|
||||
invalid([&] { g.validate(); });
|
||||
g.contents = {Content::user("ok")};
|
||||
g.scope = {{"u", "*"}};
|
||||
invalid([&] { g.validate(); });
|
||||
g.scope = {{"u", "1"}};
|
||||
g.metadata_merge_strategy = "REPLACE";
|
||||
invalid([&] { g.validate(); });
|
||||
g.metadata_merge_strategy.clear();
|
||||
g.allowed_topics = {Topic::managed("lowercase")};
|
||||
invalid([&] { g.validate(); });
|
||||
}
|
||||
|
||||
TEST(memory_bodies, retrieve_modes) {
|
||||
RetrieveRequest r;
|
||||
r.scope = {{"user_id", "1"}};
|
||||
r.validate();
|
||||
ASSERT_TRUE(r.to_json().find("similaritySearchParams") == nullptr);
|
||||
ASSERT_TRUE(r.to_json().find("simpleRetrievalParams") == nullptr);
|
||||
r.page_size = 10;
|
||||
r.page_token = "tok";
|
||||
r.validate();
|
||||
Json simple = r.to_json();
|
||||
keys_declared(simple, Call::kMemoryRetrieve);
|
||||
ASSERT_EQ(simple.find("simpleRetrievalParams")->find("pageSize")->as_int(), 10);
|
||||
|
||||
RetrieveRequest s;
|
||||
s.scope = {{"user_id", "1"}};
|
||||
s.search_query = "tea";
|
||||
s.filter = "topics=\"x\"";
|
||||
s.memory_types = {"STRUCTURED_PROFILE"};
|
||||
s.filter_groups = {{{"src", MetadataFilter::Op::kEqual, false, MetadataValue::of_string("chat")}}};
|
||||
s.validate();
|
||||
Json sim = s.to_json();
|
||||
keys_declared(sim, Call::kMemoryRetrieve);
|
||||
ASSERT_EQ(sim.find("similaritySearchParams")->find("topK")->as_int(), MemoryCaps::kDefaultTopK);
|
||||
ASSERT_EQ(sim.find("filterGroups")->as_array()[0].find("filters")->as_array()[0].find("op")->as_string(),
|
||||
std::string("EQUAL"));
|
||||
s.top_k = 51;
|
||||
invalid([&] { s.validate(); });
|
||||
s.top_k = 5;
|
||||
s.page_size = 5;
|
||||
invalid([&] { s.validate(); }); // page size is not a similarity knob
|
||||
s.page_size = 0;
|
||||
s.search_query.clear();
|
||||
invalid([&] { s.validate(); }); // top_k without a query
|
||||
s.top_k = 0;
|
||||
s.memory_types = {"BOGUS"};
|
||||
invalid([&] { s.validate(); });
|
||||
s.memory_types.clear();
|
||||
s.search_query = std::string(1001, 'a');
|
||||
invalid([&] { s.validate(); });
|
||||
RetrieveRequest none;
|
||||
invalid([&] { none.validate(); }); // scope required
|
||||
}
|
||||
|
||||
TEST(memory_bodies, create_patch_ingest) {
|
||||
MemorySpec m;
|
||||
m.memory_id = "mem-1";
|
||||
m.fact = "likes tea";
|
||||
m.scope = {{"user_id", "1"}};
|
||||
m.topics = {Topic::managed("USER_PREFERENCES")};
|
||||
m.ttl = "3600s";
|
||||
m.metadata["k"] = MetadataValue::of_bool(true);
|
||||
m.metadata["t"] = MetadataValue::of_timestamp("2025-01-31T11:30:00Z");
|
||||
m.context = "ctx";
|
||||
m.revision.disable = true;
|
||||
m.validate();
|
||||
keys_declared(m.to_json(), Call::kMemoryCreate);
|
||||
m.fact.clear();
|
||||
invalid([&] { m.validate(); }); // fact or structured content
|
||||
m.structured_content = Json::object();
|
||||
invalid([&] { m.validate(); }); // needs schemaId and data
|
||||
Json sc = Json::object();
|
||||
sc.set("schemaId", Json("user-profile"));
|
||||
sc.set("data", Json::object());
|
||||
m.structured_content = sc;
|
||||
m.memory_type = "STRUCTURED_PROFILE";
|
||||
m.validate();
|
||||
keys_declared(m.to_json(), Call::kMemoryCreate);
|
||||
m.memory_type = "OTHER";
|
||||
invalid([&] { m.validate(); });
|
||||
m.memory_type.clear();
|
||||
m.memory_id = "1bad";
|
||||
invalid([&] { m.validate(); });
|
||||
m.memory_id = "ok";
|
||||
m.fact = std::string(4001, 'x');
|
||||
invalid([&] { m.validate(); });
|
||||
|
||||
MemoryPatch p;
|
||||
p.memory_id = "mem-1";
|
||||
p.fact = "likes coffee";
|
||||
p.update_mask = "fact";
|
||||
p.validate();
|
||||
keys_declared(p.to_json(), Call::kMemoryPatch);
|
||||
p.update_mask.clear();
|
||||
invalid([&] { p.validate(); });
|
||||
|
||||
IngestRequest in;
|
||||
in.scope = {{"user_id", "1"}};
|
||||
invalid([&] { in.validate(); }); // no events
|
||||
in.events.push_back({"e1", "2025-01-31T11:30:00Z", Content::user("hi")});
|
||||
in.stream_id = "s1";
|
||||
in.trigger_event_count = 10;
|
||||
in.trigger_idle_duration = "600s";
|
||||
in.force_flush = true;
|
||||
in.validate();
|
||||
Json ib = in.to_json();
|
||||
keys_declared(ib, Call::kMemoryIngestEvents);
|
||||
ASSERT_EQ(ib.find("generationTriggerConfig")->find("generationRule")->find("eventCount")->as_int(), 10);
|
||||
in.trigger_fixed_interval = "30s"; // Google: minute granularity at least
|
||||
invalid([&] { in.validate(); });
|
||||
in.trigger_fixed_interval.clear();
|
||||
in.events[0].event_time = "soon";
|
||||
invalid([&] { in.validate(); });
|
||||
}
|
||||
|
||||
TEST(memory_bodies, topics_metadata_filters) {
|
||||
ASSERT_EQ(Topic::managed("USER_PERSONAL_INFO").to_json().dump(),
|
||||
std::string("{\"managedMemoryTopic\":\"USER_PERSONAL_INFO\"}"));
|
||||
ASSERT_EQ(Topic::custom("x").to_json().dump(), std::string("{\"customMemoryTopicLabel\":\"x\"}"));
|
||||
ASSERT_EQ(Topic::from_json(Topic::custom("y").to_json()).value, std::string("y"));
|
||||
ASSERT_EQ(MetadataValue::of_double(2).to_json().dump(), std::string("{\"doubleValue\":2}"));
|
||||
FilterGroups groups = {{{"a", MetadataFilter::Op::kGreaterThan, true, MetadataValue::of_double(1)}}};
|
||||
check_filter_groups(groups);
|
||||
Json gj = filter_groups_json(groups);
|
||||
const Json& f = gj.as_array()[0].find("filters")->as_array()[0];
|
||||
ASSERT_EQ(f.find("op")->as_string(), std::string("GREATER_THAN"));
|
||||
ASSERT_TRUE(f.find("negate")->as_bool());
|
||||
FilterGroups empty_group(1);
|
||||
invalid([&] { check_filter_groups(empty_group); });
|
||||
FilterGroups too_many(11, groups[0]);
|
||||
invalid([&] { check_filter_groups(too_many); });
|
||||
Memory mem = Memory::from_json(Json::parse(
|
||||
"{\"name\":\"x/memories/m1\",\"fact\":\"f\",\"scope\":{\"u\":\"1\"},"
|
||||
"\"topics\":[{\"managedMemoryTopic\":\"USER_PREFERENCES\"}]}"));
|
||||
ASSERT_EQ(mem.id(), std::string("m1"));
|
||||
ASSERT_EQ(mem.topics[0].value, std::string("USER_PREFERENCES"));
|
||||
ASSERT_EQ(mem.scope.at("u"), std::string("1"));
|
||||
}
|
||||
|
||||
TEST(sessions_service, validation_runs_before_any_traffic) {
|
||||
Rig rig;
|
||||
Sessions s(rig.client, EngineName(kEngine));
|
||||
MemoryBank b(rig.client, EngineName(kEngine));
|
||||
invalid([&] { s.get("BAD ID"); });
|
||||
invalid([&] { s.delete_session(""); });
|
||||
invalid([&] { s.create(SessionSpec{}); });
|
||||
invalid([&] { s.list({"a\nb", "", 0}); });
|
||||
invalid([&] { s.list({"", "", 101}); });
|
||||
invalid([&] { s.list_events("x/y"); });
|
||||
invalid([&] { s.compact("s1", CompactRequest{}); });
|
||||
invalid([&] { s.append_event("s1", SessionEvent{}); });
|
||||
invalid([&] { b.get("1bad"); });
|
||||
invalid([&] { b.delete_memory("Bad"); });
|
||||
invalid([&] { b.retrieve(RetrieveRequest{}); });
|
||||
invalid([&] { b.retrieve_profiles({}); });
|
||||
invalid([&] { b.get_revision("m1", "a/b"); });
|
||||
invalid([&] { b.rollback("m1", ".."); });
|
||||
invalid([&] { b.list({"", "\t", 0}); });
|
||||
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
|
||||
}
|
||||
|
||||
TEST(sessions_service, purge_is_guarded) {
|
||||
Rig rig;
|
||||
MemoryBank b(rig.client, EngineName(kEngine));
|
||||
PurgeRequest empty;
|
||||
invalid([&] { b.purge(empty); }); // a filter is required
|
||||
PurgeRequest forced;
|
||||
forced.filter = "scope.user_id=\"1\"";
|
||||
forced.force = true;
|
||||
invalid([&] { b.purge(forced); }); // no confirm
|
||||
forced.confirm = "wrong";
|
||||
invalid([&] { b.purge(forced); }); // confirm must be the engine id
|
||||
ASSERT_FALSE(PurgeRequest{}.force); // dry run is the default
|
||||
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
|
||||
}
|
||||
|
||||
TEST(sessions_service, operation_names_are_confined_to_the_engine) {
|
||||
Rig rig;
|
||||
Sessions s(rig.client, EngineName(kEngine));
|
||||
for (const char* bad : {"", "operations/1", "projects/p1/locations/us-central1/reasoningEngines/other/operations/1",
|
||||
"projects/p1/locations/us-central1/reasoningEngines/e1/sessions/s",
|
||||
"projects/p1/locations/us-central1/reasoningEngines/e1/operations/../x",
|
||||
"projects/p1/locations/us-central1/reasoningEngines/e1/operations/1?x=1"}) {
|
||||
invalid([&] { s.operation(bad); });
|
||||
invalid([&] { s.cancel_operation(bad); });
|
||||
invalid([&] { s.wait(bad); });
|
||||
}
|
||||
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
|
||||
}
|
||||
|
||||
TEST(sessions_service, no_credential_is_loud_and_offline) {
|
||||
Rig rig(false);
|
||||
Sessions s(rig.client, EngineName(kEngine));
|
||||
MemoryBank b(rig.client, EngineName(kEngine));
|
||||
ASSERT_FALSE(s.configured());
|
||||
ASSERT_THROW(s.get("s1"), NotConfiguredError);
|
||||
ASSERT_THROW(s.list(), NotConfiguredError);
|
||||
ASSERT_THROW(b.get("m1"), NotConfiguredError);
|
||||
ASSERT_THROW(b.list(), NotConfiguredError);
|
||||
MemorySpec m;
|
||||
m.fact = "f";
|
||||
m.scope = {{"u", "1"}};
|
||||
ASSERT_THROW(b.create(m), NotConfiguredError);
|
||||
ASSERT_EQ(rig.mock->send_count(), std::size_t(0));
|
||||
}
|
||||
|
||||
TEST(sessions_service, endpoint_follows_the_engine_location) {
|
||||
Rig rig;
|
||||
Sessions s(rig.client, EngineName(kEngine));
|
||||
ASSERT_EQ(s.endpoint().base_url,
|
||||
std::string("https://us-central1-aiplatform.googleapis.com/v1beta1"));
|
||||
MemoryBank b(rig.client, EngineName("projects/p1/locations/europe-west4/reasoningEngines/e2"));
|
||||
ASSERT_EQ(b.endpoint().base_url,
|
||||
std::string("https://europe-west4-aiplatform.googleapis.com/v1beta1"));
|
||||
ASSERT_EQ(std::string(kDiscoveryVersion), std::string("v1beta1"));
|
||||
}
|
||||
|
||||
// Read-only probe against the real service. Creates nothing. An express API
|
||||
// key (AQ.) is accepted on v1beta1 and a missing engine answers 404; a
|
||||
// project OAuth token (GOOGLE_ACCESS_TOKEN) does the same. Needs
|
||||
// MOLO_LIVE_NET=1, a credential and GOOGLE_CLOUD_PROJECT (read from env,
|
||||
// never printed).
|
||||
TEST(sessions_live, reads_under_a_missing_engine_answer_not_found) {
|
||||
std::string project = Credentials::env("GOOGLE_CLOUD_PROJECT");
|
||||
bool has_credential = !Credentials::env().empty() || !Credentials::env("GOOGLE_ACCESS_TOKEN").empty();
|
||||
if (!std::getenv("MOLO_LIVE_NET") || !has_credential || project.empty()) {
|
||||
std::cout << "SKIP sessions_live (set MOLO_LIVE_NET=1, GOOGLE_API_KEY or "
|
||||
"GOOGLE_ACCESS_TOKEN, and GOOGLE_CLOUD_PROJECT)\n";
|
||||
return;
|
||||
}
|
||||
auto client = GoogleClient::from_env();
|
||||
EngineName engine("projects/" + project +
|
||||
"/locations/us-central1/reasoningEngines/1");
|
||||
Sessions s(client, engine);
|
||||
MemoryBank b(client, engine);
|
||||
auto expect_not_found = [](const std::function<void()>& fn) {
|
||||
try {
|
||||
fn();
|
||||
} catch (const GoogleError& e) {
|
||||
ASSERT_EQ(e.http_status(), 404);
|
||||
ASSERT_EQ(e.status(), std::string("NOT_FOUND"));
|
||||
return;
|
||||
}
|
||||
FAIL("a missing engine must answer NOT_FOUND");
|
||||
};
|
||||
expect_not_found([&] { s.list(); });
|
||||
expect_not_found([&] { s.get("probe"); });
|
||||
expect_not_found([&] { s.list_events("probe"); });
|
||||
expect_not_found([&] { b.list(); });
|
||||
expect_not_found([&] { b.get("probe"); });
|
||||
expect_not_found([&] { b.list_revisions("probe"); });
|
||||
}
|
||||
Reference in New Issue
Block a user