Files
moloapp/src/google/sessions/SPEC.md
T

169 lines
9.3 KiB
Markdown
Raw Normal View History

# 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).