diff --git a/Makefile b/Makefile index e61f2fa524..61632644f2 100644 --- a/Makefile +++ b/Makefile @@ -148,7 +148,7 @@ test-integration: # may pin one package incompatibly. SDK_ADAPTERS_RESOLUTION=lowest-direct installs # every direct requirement (the SDK's own, the extra's, pytest) at its lower bound. # mypy is the [dev] pin. `make test-sdk-adapter-crewai` runs one. -SDK_ADAPTER_EXTRAS := langchain llamaindex openai-agents crewai autogen pydantic-ai ag2 +SDK_ADAPTER_EXTRAS := langchain llamaindex openai-agents crewai autogen pydantic-ai ag2 google-adk SDK_ADAPTERS_VENV ?= .venv-sdk-adapters SDK_ADAPTERS_PYTHON ?= 3.12 SDK_ADAPTERS_RESOLUTION ?= highest diff --git a/docs/features/integrations/frameworks.md b/docs/features/integrations/frameworks.md index b642ff7dec..88bf9f8589 100644 --- a/docs/features/integrations/frameworks.md +++ b/docs/features/integrations/frameworks.md @@ -20,6 +20,7 @@ or needs another database, vector store or cache. | CrewAI | `LoomCrewMemory` | Python, `loom.integrations.crewai` | `crewai.memory.Memory` | | AutoGen | `LoomMemory` | Python, `loom.integrations.autogen` | `autogen_core.memory.Memory` | | AG2 | `LoomRecallPolicy`, `loom_tools` | Python, `loom.integrations.ag2` | `ag2.assembly.AssemblyPolicy`, `tool()` from `ag2.tools` | +| Google ADK | `LoomMemoryService` | Python, `loom.integrations.google_adk` | `google.adk.memory.BaseMemoryService` | | Pydantic AI | `loom_toolset` | Python, `loom.integrations.pydantic_ai` | `FunctionToolset` | | Mastra | `loomTools` | TypeScript, `@clickhouse/loom/integrations/mastra` | `createTool` from `@mastra/core` | | AI SDK | `loomTools` | TypeScript, `@clickhouse/loom/integrations/ai-sdk` | `tool()` from `ai` | @@ -342,6 +343,81 @@ trimming policy (`SlidingWindowPolicy`, `TokenBudgetPolicy`), which can cut the request out of the events the policy reads. Those policies trim events, not the prompt, so `top_k` is what bounds the memory block. +## Google ADK + +`LoomMemoryService` implements ADK's `BaseMemoryService`, which a `Runner` takes as +`memory_service=`. ADK's own memory tools read it: `preload_memory` searches with the +user's message before each model call and adds the matches to the prompt, and +`load_memory` lets the model search. A callback saves each turn. Install with +`pip install 'clickhouse-loom[google-adk]'` (`google-adk` 2.14 or later 2.x). + +```python +from google.adk.agents import LlmAgent +from google.adk.runners import Runner +from google.adk.sessions import InMemorySessionService +from google.adk.tools import preload_memory +from google.genai import types +from loom import Agent +from loom.integrations.google_adk import LoomMemoryService + + +async def save_turn(ctx): + turn = [e for e in ctx.session.events if e.invocation_id == ctx.invocation_id] + await ctx.add_events_to_memory(events=turn) + + +async with Agent(org="acme", namespace="support") as loom_agent: + sessions = InMemorySessionService() + runner = Runner( + app_name="support", + agent=LlmAgent( + name="assistant", + model="gemini-flash-latest", + tools=[preload_memory], + after_agent_callback=save_turn, + ), + session_service=sessions, + memory_service=LoomMemoryService(loom_agent, app_name="support"), + ) + session = await sessions.create_session(app_name="support", user_id="alice") + message = types.Content(role="user", parts=[types.Part(text="I prefer aisle seats")]) + async for event in runner.run_async( + user_id="alice", session_id=session.id, new_message=message + ): + ... +``` + +ADK scopes memory by app and user. Loom's boundary is the namespace: a Loom write that +matches a memory of the namespace merges into it, whichever agent wrote that memory, so two +apps sharing a namespace would share and lose memories. A service therefore serves one ADK +app, named by `app_name`, in the namespace of its Loom agent, and refuses a call for +another app; give each app its own namespace and service. The ADK user is the Loom +`user_id`; an empty or `-` user, which names no user in Loom, raises `ValueError`. +Extraction runs under a Loom session derived from the user and the ADK session (`adk-` +and a digest of the pair): Loom files a turn's verbatim chunks by session alone, and ADK +makes a session id unique per user only. A search reads all of the user's memories in the +namespace, from every session. + +| ADK | Loom | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `add_session_to_memory` | the text of the session's events, without the ones a rewind took back, sent to `memory.set_from_messages` (400 messages a call, the op's cap); Loom extracts the facts and resolves duplicates and conflicts. A session added again is extracted again, so a callback that runs every turn, as `after_agent_callback` does, saves that turn's events, as in the example | +| `add_events_to_memory` | the same for the events given, such as the latest turn; a call without a `session_id` raises `ValueError`, since Loom files a turn's verbatim chunks by session. A turn saved before a later rewind keeps its memories: the app deletes its facts by the ids a search returns, and its verbatim passages stay until [erasure](../memory/retention-and-erasure.md) removes them | +| `add_memory` | one `memory.set` per entry with text (an entry without text is skipped) under `/`, its `timestamp` as the memory's `valid_at` when it is ISO 8601 (one without a zone is read as local time, as ADK writes its own) | +| `search_memory` | `memory.search` of the user's memories; with `honour_abstain`, leaves out memories below Loom's floor and returns nothing when Loom abstains; each entry's `custom_metadata` carries `similarity` and `source`, and its `timestamp` is `valid_at` when the row has one | +| `delete_memory` | `memory.delete` of the memory the entry's `id` names: the JSON pair of its key and its session, since users share extracted keys and a key alone finds the key's newest row, which can be another user's, and then deletes nothing. A verbatim passage or a session summary has no `id`: a conversation's passage outlives the facts extracted from it, and [erasure](../memory/retention-and-erasure.md) removes it; a call without an id does nothing, as in ADK's own memory service. A delete removes the fact, it does not refuse it: adding its session again extracts it again (the per-turn callback adds each turn once), and [`blacklist.add`](../memory/conflicts-and-refusal.md#refusal-the-blacklist) refuses it | + +Events keep their text parts only: the model's thoughts and tool calls and results are not +sent, and neither is `custom_metadata` or an entry's `author` and `id`. + +| `LoomMemoryService` argument | Default | Effect | +| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------- | +| `agent` | required | the `loom.Agent` the service calls; ADK awaits its memory service, so a `SyncAgent` is refused | +| `app_name` | required | the ADK app the service serves; a call for another app raises `ValueError` | +| `top_k` | 10 | memories per search, from 1 to 500 | +| `honour_abstain` | `True` | leave out memories below Loom's floor; nothing when Loom abstains | +| `defer` | `True` | queue the extraction on the server instead of waiting for it | +| `key_prefix` | `adk` | the prefix of `add_memory`'s keys; an empty one is refused | + ## Pydantic AI Pydantic AI extends an agent through tools and toolsets. `loom_toolset` returns Loom's @@ -550,6 +626,9 @@ client can speak for several agents. silent. - **An AG2 turn fails when Loom is unreachable.** `LoomRecallPolicy` runs before each model call of the turn, and `AssemblerMiddleware` does not catch a policy's error. +- **ADK carries on without memory when `preload_memory`'s search fails.** It logs a + warning and the model call goes on; a failed `load_memory` search or save callback fails + the run. - **An AutoGen turn fails when Loom is unreachable.** `AssistantAgent` calls `update_context` once per turn, before its first model call, and does not catch its errors. diff --git a/docs/features/integrations/index.md b/docs/features/integrations/index.md index 644f72ed12..c012667fc4 100644 --- a/docs/features/integrations/index.md +++ b/docs/features/integrations/index.md @@ -12,31 +12,31 @@ opt-in; one you leave unconfigured does nothing. They fall into three groups: ## Map -| Integration | Kind | Where | -| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| Claude Code | plugin: MCP tools, hooks, code shunt, skills | `integrations/claude-code-plugin/`: [claude-code.md](claude-code.md) | -| Codex | plugin: MCP tools, hooks, code shunt, skills | `integrations/codex-plugin/`: [codex.md](codex.md) | -| Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed | MCP client config | `loom install --client …`: [mcp-clients.md](mcp-clients.md) | -| VS Code agent mode | MCP tools | install links and `mcp.json`: [vscode.md](vscode.md) | -| Any MCP client without a plugin | an instruction block for the client's rule file | [agent-instructions.md](agent-instructions.md) | -| Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | -| JetBrains, Visual Studio, Neovim, Emacs and other agents | MCP client config | [other editors and agents](mcp-clients.md#other-editors-and-agents) | -| Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | -| Cursor | MCP tools, skills (untested plugin) + `sessionEnd` capture hook | `.cursor-plugin/`, `integrations/cursor/`: [cursor.md](cursor.md) | -| Any Agent-Skills client | the `loom` and `loom-code` skills, no hooks | `skills/loom/`, `skills/loom-code/`: [below](#coding-agents) | -| Aider, Continue, OpenCode, JetBrains AI | transcript capture template | `integrations/generic/`: [below](#transcript-capture-hooks) | -| Agents that only use shell grep | the grep shim | `integrations/grep-shim/`: [grep-shim.md](grep-shim.md) | -| LibreChat v0.8.8 | chat client on the assistant toolset, per-user token | `integrations/librechat/`: [librechat.md](librechat.md) | -| LangChain, LlamaIndex, OpenAI Agents SDK, CrewAI, AutoGen, AG2, Pydantic AI, Mastra, AI SDK, LangGraph, Strands Agents | SDK retrievers, memory adapters and tools | `loom.integrations.*` in Python, `@clickhouse/loom/integrations/*` in TypeScript: [frameworks.md](frameworks.md) | -| Agent orchestrators | shared MCP mount | [frameworks.md](frameworks.md) | -| Agent Substrate | MCP through the egress gateway, per-agent token | [agent-substrate.md](agent-substrate.md) | -| AX (sandboxed agent tasks) | Workspace manifest: MCP config, `AGENTS.md`, run budget | `integrations/ax/`: [README](../../../integrations/ax/README.md) | -| Langfuse | traces, retrieval scores, erasure; needs Langfuse | [langfuse.md](langfuse.md) | -| ClickStack / HyperDX | OpenTelemetry spans, logs, metrics; erasure | [clickstack.md](clickstack.md) | -| Git repositories (OKF bundles) | export, import, CI lint gate | `integrations/okf-ci/`: [okf.md](okf.md) | -| Shell pipelines | `loom memory-search --json-agent` | [below](#command-line-search-for-pipelines) | -| Provider prompt caches | byte-stable `context.pack` prefix | [below](#prompt-caching) | -| GitHub | code index, PR history; needs the code workers enabled | [code index overview](../code-index/overview.md) | +| Integration | Kind | Where | +| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| Claude Code | plugin: MCP tools, hooks, code shunt, skills | `integrations/claude-code-plugin/`: [claude-code.md](claude-code.md) | +| Codex | plugin: MCP tools, hooks, code shunt, skills | `integrations/codex-plugin/`: [codex.md](codex.md) | +| Claude Desktop, Cursor, VS Code, Cline, Windsurf, Zed | MCP client config | `loom install --client …`: [mcp-clients.md](mcp-clients.md) | +| VS Code agent mode | MCP tools | install links and `mcp.json`: [vscode.md](vscode.md) | +| Any MCP client without a plugin | an instruction block for the client's rule file | [agent-instructions.md](agent-instructions.md) | +| Gemini CLI | extension: MCP tools and the `loom`, `loom-code` skills | `gemini extensions install`: [mcp-clients.md](mcp-clients.md#other-editors-and-agents) | +| JetBrains, Visual Studio, Neovim, Emacs and other agents | MCP client config | [other editors and agents](mcp-clients.md#other-editors-and-agents) | +| Cline CLI (experimental) | hooks: session primer, prompt recall, a file's memories on a read | `integrations/cline/`: [README](../../../integrations/cline/README.md) | +| Cursor | MCP tools, skills (untested plugin) + `sessionEnd` capture hook | `.cursor-plugin/`, `integrations/cursor/`: [cursor.md](cursor.md) | +| Any Agent-Skills client | the `loom` and `loom-code` skills, no hooks | `skills/loom/`, `skills/loom-code/`: [below](#coding-agents) | +| Aider, Continue, OpenCode, JetBrains AI | transcript capture template | `integrations/generic/`: [below](#transcript-capture-hooks) | +| Agents that only use shell grep | the grep shim | `integrations/grep-shim/`: [grep-shim.md](grep-shim.md) | +| LibreChat v0.8.8 | chat client on the assistant toolset, per-user token | `integrations/librechat/`: [librechat.md](librechat.md) | +| LangChain, LlamaIndex, OpenAI Agents SDK, CrewAI, AutoGen, AG2, Google ADK, Pydantic AI, Mastra, AI SDK, LangGraph, Strands Agents | SDK retrievers, memory adapters and tools | `loom.integrations.*` in Python, `@clickhouse/loom/integrations/*` in TypeScript: [frameworks.md](frameworks.md) | +| Agent orchestrators | shared MCP mount | [frameworks.md](frameworks.md) | +| Agent Substrate | MCP through the egress gateway, per-agent token | [agent-substrate.md](agent-substrate.md) | +| AX (sandboxed agent tasks) | Workspace manifest: MCP config, `AGENTS.md`, run budget | `integrations/ax/`: [README](../../../integrations/ax/README.md) | +| Langfuse | traces, retrieval scores, erasure; needs Langfuse | [langfuse.md](langfuse.md) | +| ClickStack / HyperDX | OpenTelemetry spans, logs, metrics; erasure | [clickstack.md](clickstack.md) | +| Git repositories (OKF bundles) | export, import, CI lint gate | `integrations/okf-ci/`: [okf.md](okf.md) | +| Shell pipelines | `loom memory-search --json-agent` | [below](#command-line-search-for-pipelines) | +| Provider prompt caches | byte-stable `context.pack` prefix | [below](#prompt-caching) | +| GitHub | code index, PR history; needs the code workers enabled | [code index overview](../code-index/overview.md) | ## Coding agents diff --git a/docs/reference/python-sdk.md b/docs/reference/python-sdk.md index daed457946..229361fcbb 100644 --- a/docs/reference/python-sdk.md +++ b/docs/reference/python-sdk.md @@ -255,6 +255,11 @@ system prompt of an agent with no plugin; `part="reference"` lists every plane. assembly policy that adds the memories `memory.search` finds for the latest user message to the prompt, and `loom_tools(agent, user_id=...)` returns `AgentTools` as AG2 tools; install the `[ag2]` extra. +- `loom.integrations.google_adk.LoomMemoryService(agent, app_name=...)` is a + Google ADK `BaseMemoryService` for one ADK app: a saved session or turn goes + to `memory.set_from_messages`, `add_memory` is `memory.set`, `search_memory` + is `memory.search` scoped to the ADK user, and `delete_memory` is + `memory.delete`; install the `[google-adk]` extra. - `loom.integrations.pydantic_ai.loom_toolset(agent, user_id=...)` returns `AgentTools` as a Pydantic AI `FunctionToolset`; install the `[pydantic-ai]` extra. diff --git a/pyproject.toml b/pyproject.toml index ab417a3c47..33a3aebb36 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -263,6 +263,10 @@ module = [ "pydantic_ai.*", "ag2", "ag2.*", + "google.adk", + "google.adk.*", + "google.genai", + "google.genai.*", "langgraph", "langgraph.*", "strands", diff --git a/sdk/python/README.md b/sdk/python/README.md index 333814bb23..e6ff1c62f9 100644 --- a/sdk/python/README.md +++ b/sdk/python/README.md @@ -51,7 +51,7 @@ services. The `Agent` exposes 28 client modules: `client`, `account`, `deployment`, `assistant`, `memory`, `working_memory`, `knowledge`, `conversations`, `profile`, `context`, `facts`, `learnings`, `conflicts`, `blacklist`, `grants`, `erasure`, `cost`, `audit`, `namespaces`, `procedure`, `run`, `tasks`, `policy`, `decision`, `calibration`, `briefs`, `code`, `tracker`. Each of the named ones is the hand-written layer over a wire-op group on the Loom server (`account`, `deployment` and `assistant` cover the routes outside the op registry: service accounts, MCP setup, model settings, worker health, the assistant's streamed chat); `client` holds every served op as a generated method (below). -Framework adapters live under `loom.integrations`: LangChain retrievers (`pip install 'clickhouse-loom[langchain]'`), a LlamaIndex retriever and memory block (`[llamaindex]`), OpenAI Agents SDK tools (`[openai-agents]`), CrewAI crew memory (`[crewai]`), an AutoGen memory (`[autogen]`), an AG2 recall policy and tools (`[ag2]`), a Pydantic AI toolset (`[pydantic-ai]`), a LangGraph store and a Strands Agents memory store ([frameworks](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/frameworks.md)). +Framework adapters live under `loom.integrations`: LangChain retrievers (`pip install 'clickhouse-loom[langchain]'`), a LlamaIndex retriever and memory block (`[llamaindex]`), OpenAI Agents SDK tools (`[openai-agents]`), CrewAI crew memory (`[crewai]`), an AutoGen memory (`[autogen]`), an AG2 recall policy and tools (`[ag2]`), a Google ADK memory service (`[google-adk]`), a Pydantic AI toolset (`[pydantic-ai]`), a LangGraph store and a Strands Agents memory store ([frameworks](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/frameworks.md)). Full guide: [docs/reference/python-sdk.md](https://github.com/ClickHouse/loom/blob/main/docs/reference/python-sdk.md). Deployment paths (how an operator stands up the server): [docs/operations/deployment.md](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md). diff --git a/sdk/python/loom/integrations/google_adk.py b/sdk/python/loom/integrations/google_adk.py new file mode 100644 index 0000000000..2435dfd61f --- /dev/null +++ b/sdk/python/loom/integrations/google_adk.py @@ -0,0 +1,283 @@ +"""Loom as a Google ADK memory service. + +``LoomMemoryService`` implements ``google.adk.memory.BaseMemoryService``, the +service a ``Runner`` takes as ``memory_service=``. ADK's memory tools read it: +``preload_memory`` searches with the user's message before each model call, +``load_memory`` lets the model search. A callback saves each turn:: + + from google.adk.agents import LlmAgent + from google.adk.runners import Runner + from google.adk.sessions import InMemorySessionService + from google.adk.tools import preload_memory + from google.genai import types + from loom import Agent + from loom.integrations.google_adk import LoomMemoryService + + + async def save_turn(ctx): + turn = [e for e in ctx.session.events if e.invocation_id == ctx.invocation_id] + await ctx.add_events_to_memory(events=turn) + + + async with Agent(org="acme", namespace="support") as loom_agent: + sessions = InMemorySessionService() + runner = Runner( + app_name="support", + agent=LlmAgent( + name="assistant", + model="gemini-flash-latest", + tools=[preload_memory], + after_agent_callback=save_turn, + ), + session_service=sessions, + memory_service=LoomMemoryService(loom_agent, app_name="support"), + ) + session = await sessions.create_session(app_name="support", user_id="alice") + message = types.Content(role="user", parts=[types.Part(text="I prefer aisle seats")]) + async for event in runner.run_async( + user_id="alice", session_id=session.id, new_message=message + ): + ... + +ADK scopes memory by app and user. Loom's boundary is the namespace, so a +service serves one ADK app, the namespace of its Loom agent, and refuses a +call for another app; the ADK user is the Loom ``user_id``, and extraction runs +under a Loom session derived from the user and the ADK session. Install with +``pip install 'clickhouse-loom[google-adk]'``. +""" + +from __future__ import annotations + +import hashlib +import json +from collections.abc import Mapping, Sequence +from datetime import UTC, datetime +from typing import TYPE_CHECKING + +try: + from google.adk.events import Event, get_active_events + from google.adk.memory import BaseMemoryService + from google.adk.memory.base_memory_service import SearchMemoryResponse + from google.adk.memory.memory_entry import MemoryEntry + from google.adk.sessions import Session + from google.genai import types +except ImportError as e: # the framework is an optional extra + raise ImportError( + "loom.integrations.google_adk needs google-adk: pip install 'clickhouse-loom[google-adk]'" + ) from e + +from loom.sync import SyncAgent + +if TYPE_CHECKING: + from loom.agent import Agent + + +# The server's cap on the messages of one memory.set_from_messages call. +_MAX_MESSAGES = 400 + + +class LoomMemoryService(BaseMemoryService): + """ADK ``BaseMemoryService`` over a Loom ``Agent``, for one ADK app. + + Saved sessions and turns go to ``memory.set_from_messages``, ``add_memory`` to + ``memory.set`` and ``search_memory`` to ``memory.search`` of the ADK user's + memories; a returned memory's ``id`` names it for ``delete_memory``. ADK + awaits its memory service, so the service takes a ``loom.Agent``. The mapping of + each method is in ``docs/features/integrations/frameworks.md`` (Google ADK). + """ + + def __init__( + self, + agent: Agent, + *, + app_name: str, + top_k: int = 10, + honour_abstain: bool = True, + defer: bool = True, + key_prefix: str = "adk", + ) -> None: + if isinstance(agent, SyncAgent): + raise TypeError("LoomMemoryService needs a loom.Agent: ADK awaits its memory service") + if not app_name: + raise ValueError("app_name must name the ADK app this service serves") + if not 1 <= top_k <= 500: # memory.search's bounds + raise ValueError("top_k must be between 1 and 500") + key_prefix = key_prefix.strip("/") + if not key_prefix: + raise ValueError("key_prefix must not be empty") + self._agent = agent + self._app_name = app_name + self._top_k = top_k + self._honour_abstain = honour_abstain + self._defer = defer + self._key_prefix = key_prefix + + async def add_session_to_memory(self, session: Session) -> None: + self._check_scope(session.app_name, session.user_id) + await self._extract(session.user_id, session.id, get_active_events(session.events)) + + async def add_events_to_memory( + self, + *, + app_name: str, + user_id: str, + events: Sequence[Event], + session_id: str | None = None, + custom_metadata: Mapping[str, object] | None = None, + ) -> None: + self._check_scope(app_name, user_id) + if not session_id: + # Loom files a turn's verbatim chunks by session alone, not by user. + raise ValueError("add_events_to_memory needs the ADK session_id") + await self._extract(user_id, session_id, get_active_events(list(events))) + + async def add_memory( + self, + *, + app_name: str, + user_id: str, + memories: Sequence[MemoryEntry], + custom_metadata: Mapping[str, object] | None = None, + ) -> None: + self._check_scope(app_name, user_id) + for memory in memories: + text = _text(memory.content) + if not text: + continue + # The user is in the key: Loom files a long value's passages by key alone. + digest = _digest(user_id, text) + await self._agent.memory.set( + f"{self._key_prefix}/{digest}", + text, + user_id=user_id, + valid_at=_iso_time(memory.timestamp), + ) + + async def search_memory( + self, *, app_name: str, user_id: str, query: str + ) -> SearchMemoryResponse: + self._check_scope(app_name, user_id) + if not query.strip(): + return SearchMemoryResponse() + result = await self._agent.memory.search( + query, + top_k=self._top_k, + user_id=user_id, + # Read the namespace this service writes to, whatever the deployment's default. + namespace_scope="this", + # Pinned so every top_k gets full bodies and no per-hit explanation + # (the server's defaults switch at 15). + bodies="full", + explain=False, + ) + hits = list(result) + if self._honour_abstain: + if result.abstain: + return SearchMemoryResponse() + # A response that does not abstain can still carry rows below the floor. + hits = [hit for hit in hits if not hit.below_threshold] + return SearchMemoryResponse( + memories=[ + MemoryEntry( + # Only a fact is deleted by its key; a chunk outlives the fact it names + # and a summary has no key, so erasure removes both. + id=_entry_id(hit.memory_key, hit.session_id) if hit.source == "fact" else None, + content=types.Content( + role="user", parts=[types.Part(text=hit.content_excerpt)] + ), + custom_metadata={"similarity": hit.similarity, "source": hit.source}, + timestamp=hit.valid_at or None, + ) + # Derived rows may come back above the top_k slice: cut after filtering. + for hit in hits[: self._top_k] + ] + ) + + async def delete_memory( + self, *, app_name: str, user_id: str, memory_id: str | None = None + ) -> None: + self._check_scope(app_name, user_id) + if not memory_id: # no id, nothing to delete: ADK's InMemoryMemoryService also returns + return + key, session = _parse_entry_id(memory_id) + await self._agent.memory.delete(key, user_id=user_id, session_id=session) + + def _check_scope(self, app_name: str, user_id: str) -> None: + # Loom merges a write into a matching memory of the namespace whichever agent + # wrote it, so two apps in one namespace would share and lose memories. + if app_name != self._app_name: + raise ValueError( + f"this LoomMemoryService serves the ADK app {self._app_name!r}, not " + f"{app_name!r}: give each app its own Loom namespace and service" + ) + # In Loom an empty or "-" user is no user: writes would land outside the user's reads. + if user_id in ("", "-"): + raise ValueError(f"an ADK user_id names a Loom user; {user_id!r} names none") + + async def _extract(self, user_id: str, session_id: str, events: Sequence[Event]) -> None: + messages: list[dict[str, object]] = [] + for event in events: + text = _text(event.content) + if text: + messages.append( + { + "role": "user" if event.author == "user" else "assistant", + "content": text, + "timestamp": datetime.fromtimestamp(event.timestamp, UTC).isoformat(), + } + ) + session = _loom_session(user_id, session_id) + for start in range(0, len(messages), _MAX_MESSAGES): + await self._agent.memory.set_from_messages( + messages[start : start + _MAX_MESSAGES], + user_id=user_id, + session_id=session, + defer=self._defer, + ) + + +def _entry_id(memory_key: str, session_id: str) -> str: + """A memory's entry id: its key and its session. Users share extracted keys, and a + delete by key alone finds the newest row of the key, which can be another user's.""" + return json.dumps([memory_key, session_id or "-"]) + + +def _parse_entry_id(memory_id: str) -> tuple[str, str]: + try: + parsed = json.loads(memory_id) + except ValueError: + parsed = None + if not ( + isinstance(parsed, list) and len(parsed) == 2 and all(isinstance(p, str) for p in parsed) + ): + raise ValueError(f"{memory_id!r} is not an id this service's search returned") + return parsed[0], parsed[1] + + +def _loom_session(user_id: str, session_id: str) -> str: + """The Loom session of an ADK user's session: ADK makes a session id unique per + user only, and Loom files a turn's verbatim chunks by session alone.""" + return f"adk-{_digest(user_id, session_id)}" + + +def _digest(*parts: str) -> str: + """The first 20 hex of the sha256 of `parts` as a JSON list, so two different tuples + never hash the same text.""" + return hashlib.sha256(json.dumps(parts).encode()).hexdigest()[:20] + + +def _iso_time(text: str | None) -> datetime | None: + """An ISO 8601 timestamp; ADK allows any text, which is not a ``valid_at``. One + without a zone is local time, as ADK formats its own entries' timestamps.""" + try: + moment = datetime.fromisoformat(text) if text else None + except ValueError: + return None + return moment.astimezone() if moment and moment.tzinfo is None else moment + + +def _text(content: types.Content | None) -> str: + """The text of a content, without the model's thoughts or tool calls.""" + if content is None or not content.parts: + return "" + return " ".join(p.text for p in content.parts if p.text and not p.thought).strip() diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml index 4e707a6563..2f23597bc8 100644 --- a/sdk/python/pyproject.toml +++ b/sdk/python/pyproject.toml @@ -69,6 +69,9 @@ pydantic-ai = ["pydantic-ai-slim>=2.68,<3"] # AG2 1.3 has the assembly policies and tool(schema=...) the adapter uses; AG2 changes # its agent and tool APIs between minor versions. ag2 = ["ag2>=1.3,<1.4"] +# ADK 2.14 has get_active_events and the memory service's add_memory and delete_memory; +# 3.0 may change the memory service. +google-adk = ["google-adk>=2.14,<3"] [project.urls] Homepage = "https://clickhouse.github.io/loom/" diff --git a/sdk/python/tests/test_google_adk.py b/sdk/python/tests/test_google_adk.py new file mode 100644 index 0000000000..95ea2ee8bb --- /dev/null +++ b/sdk/python/tests/test_google_adk.py @@ -0,0 +1,512 @@ +"""LoomMemoryService: ADK's memory service over a fake Loom agent — what each +method sends, abstention, and what an ADK Runner's model sees through +preload_memory and load_memory.""" + +from __future__ import annotations + +import asyncio +import importlib +import sys +from collections.abc import AsyncGenerator +from datetime import datetime +from typing import Any + +import pytest +from google.adk.agents import LlmAgent +from google.adk.events import Event, EventActions +from google.adk.memory import BaseMemoryService +from google.adk.memory.memory_entry import MemoryEntry +from google.adk.models.base_llm import BaseLlm +from google.adk.models.llm_request import LlmRequest +from google.adk.models.llm_response import LlmResponse +from google.adk.runners import Runner +from google.adk.sessions import InMemorySessionService, Session +from google.adk.tools import load_memory, preload_memory +from google.genai import types +from loom import Agent, SyncAgent +from loom.integrations.google_adk import LoomMemoryService, _entry_id, _loom_session +from loom.memory import MemorySearchHit, MemorySearchResult +from pydantic import Field + + +class _FakeMemory: + def __init__(self, hits: list[MemorySearchHit] | None = None, abstain: bool = False) -> None: + self.calls: list[tuple[str, tuple[Any, ...], dict[str, Any]]] = [] + self._hits = hits or [] + self._abstain = abstain + + async def search(self, query: str, **kw: Any) -> MemorySearchResult: + self.calls.append(("search", (query,), kw)) + result = MemorySearchResult(self._hits) + result.abstain = self._abstain + return result + + async def set(self, key: str, value: str, **kw: Any) -> dict[str, Any]: + self.calls.append(("set", (key, value), kw)) + return {} + + async def set_from_messages(self, messages: list[dict[str, object]], **kw: Any) -> dict: + self.calls.append(("set_from_messages", (messages,), kw)) + return {} + + async def delete(self, key: str, **kw: Any) -> bool: + self.calls.append(("delete", (key,), kw)) + return True + + +class _Agent: + def __init__(self, memory: _FakeMemory) -> None: + self.memory = memory + + +class _ScriptedLlm(BaseLlm): + """Answers each model call with the next scripted content; keeps the requests.""" + + model: str = "scripted" + script: list[types.Content] = Field(default_factory=list) + requests: list[LlmRequest] = Field(default_factory=list) + + async def generate_content_async( + self, llm_request: LlmRequest, stream: bool = False + ) -> AsyncGenerator[LlmResponse, None]: + self.requests.append(llm_request) + yield LlmResponse(content=self.script.pop(0)) + + +def _hit(key: str, text: str, **kw: Any) -> MemorySearchHit: + return MemorySearchHit( + memory_key=key, memory_type="semantic", content_excerpt=text, similarity=0.9, **kw + ) + + +def _user(text: str) -> types.Content: + return types.Content(role="user", parts=[types.Part(text=text)]) + + +def _model(text: str) -> types.Content: + return types.Content(role="model", parts=[types.Part(text=text)]) + + +def _service(fake: _FakeMemory, **kw: Any) -> LoomMemoryService: + kw.setdefault("app_name", "travel") + return LoomMemoryService(_Agent(fake), **kw) # type: ignore[arg-type] + + +async def _run( + service: LoomMemoryService, llm: _ScriptedLlm, *texts: str, **agent_kw: Any +) -> InMemorySessionService: + sessions = InMemorySessionService() + runner = Runner( + app_name="travel", + agent=LlmAgent(name="assistant", model=llm, **agent_kw), + session_service=sessions, + memory_service=service, + ) + session = await sessions.create_session(app_name="travel", user_id="alice") + for text in texts: + message = types.Content(role="user", parts=[types.Part(text=text)]) + async for _ in runner.run_async( + user_id="alice", session_id=session.id, new_message=message + ): + pass + return sessions + + +def _prompt(request: LlmRequest) -> str: + return " ".join(p.text or "" for c in request.contents for p in c.parts or []) + + +def test_it_is_an_adk_memory_service() -> None: + assert issubclass(LoomMemoryService, BaseMemoryService) + + +def test_it_refuses_bad_construction() -> None: + with pytest.raises(TypeError, match="ADK awaits"): + LoomMemoryService(object.__new__(SyncAgent), app_name="travel") + for top_k in (0, 501): + with pytest.raises(ValueError, match="top_k"): + _service(_FakeMemory(), top_k=top_k) + with pytest.raises(ValueError, match="app_name"): + _service(_FakeMemory(), app_name="") + for prefix in ("", "/"): + with pytest.raises(ValueError, match="key_prefix"): + _service(_FakeMemory(), key_prefix=prefix) + + +def test_preload_memory_puts_the_matches_in_the_prompt() -> None: + fake = _FakeMemory([_hit("adk/1", "Alice prefers aisle seats", valid_at="2026-11-01")]) + llm = _ScriptedLlm(script=[_model("An aisle seat.")]) + asyncio.run(_run(_service(fake), llm, "Which seat for alice?", tools=[preload_memory])) + (search,) = [c for c in fake.calls if c[0] == "search"] + assert search[1] == ("Which seat for alice?",) + assert search[2] == { + "top_k": 10, + "user_id": "alice", + "namespace_scope": "this", + "bodies": "full", + "explain": False, + } + prompt = _prompt(llm.requests[0]) + assert "Alice prefers aisle seats" in prompt and "Time: 2026-11-01" in prompt + + +def test_the_model_reads_load_memory_results() -> None: + fake = _FakeMemory([_hit("adk/1", "Alice prefers aisle seats")]) + call = types.Content( + role="model", + parts=[ + types.Part(function_call=types.FunctionCall(name="load_memory", args={"query": "seat"})) + ], + ) + llm = _ScriptedLlm(script=[call, _model("An aisle seat.")]) + asyncio.run(_run(_service(fake), llm, "Which seat?", tools=[load_memory])) + (response,) = [ + p.function_response + for c in llm.requests[1].contents + for p in c.parts or [] + if p.function_response + ] + (memory,) = response.response["result"].memories + assert memory.id == _entry_id("adk/1", "-") + assert memory.content.parts[0].text == "Alice prefers aisle seats" + + +def test_search_leaves_out_rows_below_the_floor_and_an_abstention() -> None: + hits = [_hit("adk/1", "kept"), _hit("adk/2", "weak", below_threshold=True)] + found = asyncio.run( + _service(_FakeMemory(hits)).search_memory(app_name="travel", user_id="u", query="q") + ) + assert [m.id for m in found.memories] == [_entry_id("adk/1", "-")] + everything = _service(_FakeMemory(hits), honour_abstain=False) + found = asyncio.run(everything.search_memory(app_name="travel", user_id="u", query="q")) + assert [m.id for m in found.memories] == [_entry_id(k, "-") for k in ("adk/1", "adk/2")] + abstained = _service(_FakeMemory(hits, abstain=True)) + assert not asyncio.run( + abstained.search_memory(app_name="travel", user_id="u", query="q") + ).memories + + +def test_search_cuts_to_top_k_and_skips_an_empty_query() -> None: + fake = _FakeMemory([_hit(f"adk/{i}", f"fact {i}") for i in range(4)]) + found = asyncio.run( + _service(fake, top_k=2).search_memory(app_name="travel", user_id="u", query="q") + ) + assert [m.id for m in found.memories] == [_entry_id(k, "-") for k in ("adk/0", "adk/1")] + assert not asyncio.run( + _service(fake).search_memory(app_name="travel", user_id="u", query=" ") + ).memories + assert len(fake.calls) == 1 + + +def test_a_saved_session_goes_to_extraction() -> None: + fake = _FakeMemory() + + async def save(callback_context: Any) -> None: + await callback_context.add_session_to_memory() + + llm = _ScriptedLlm(script=[_model("Noted.")]) + sessions = asyncio.run( + _run(_service(fake), llm, "I prefer aisle seats", after_agent_callback=save) + ) + (session,) = asyncio.run(sessions.list_sessions(app_name="travel", user_id="alice")).sessions + (extract,) = [c for c in fake.calls if c[0] == "set_from_messages"] + messages = extract[1][0] + assert [(m["role"], m["content"]) for m in messages] == [ + ("user", "I prefer aisle seats"), + ("assistant", "Noted."), + ] + assert all(str(m["timestamp"]).endswith("+00:00") for m in messages) + # The session keys Loom's evidence of the turns. + assert extract[2] == { + "user_id": "alice", + "session_id": _loom_session("alice", session.id), + "defer": True, + } + + +def test_the_documented_turn_callback_sends_each_turn_once() -> None: + fake = _FakeMemory() + + async def save_turn(ctx: Any) -> None: + turn = [e for e in ctx.session.events if e.invocation_id == ctx.invocation_id] + await ctx.add_events_to_memory(events=turn) + + llm = _ScriptedLlm(script=[_model("Noted."), _model("Lisbon, then.")]) + sessions = asyncio.run( + _run( + _service(fake), + llm, + "I prefer aisle seats", + "I fly to Lisbon", + after_agent_callback=save_turn, + ) + ) + (session,) = asyncio.run(sessions.list_sessions(app_name="travel", user_id="alice")).sessions + calls = [c for c in fake.calls if c[0] == "set_from_messages"] + sent = [[m["content"] for m in c[1][0]] for c in calls] + assert sent == [["I prefer aisle seats", "Noted."], ["I fly to Lisbon", "Lisbon, then."]] + # ADK's context passes the session; Loom's session is per user. + assert [c[2]["session_id"] for c in calls] == [_loom_session("alice", session.id)] * 2 + + +def test_extraction_leaves_out_thoughts_tool_calls_and_rewound_turns() -> None: + def event(inv: str, author: str, *parts: types.Part, **kw: Any) -> Event: + return Event( + invocation_id=inv, author=author, content=types.Content(parts=list(parts)), **kw + ) + + session = Session( + id="s1", + app_name="travel", + user_id="alice", + events=[ + event("i1", "user", types.Part(text="I live in Lisbon")), + event( + "i1", + "assistant", + types.Part(text="planning", thought=True), + types.Part(function_call=types.FunctionCall(name="f", args={})), + types.Part(text="Lisbon it is"), + ), + event("i2", "user", types.Part(text="Actually Porto")), + Event( + invocation_id="i3", + author="user", + actions=EventActions(rewind_before_invocation_id="i2"), + ), + ], + ) + fake = _FakeMemory() + asyncio.run(_service(fake).add_session_to_memory(session)) + (extract,) = fake.calls + assert [m["content"] for m in extract[1][0]] == ["I live in Lisbon", "Lisbon it is"] + + +def test_events_given_leave_out_a_turn_rewound_among_them() -> None: + events = [ + Event(invocation_id="i1", author="user", content=_user("I live in Lisbon")), + Event(invocation_id="i2", author="user", content=_user("Actually Porto")), + Event( + invocation_id="i3", + author="user", + actions=EventActions(rewind_before_invocation_id="i2"), + ), + ] + fake = _FakeMemory() + asyncio.run( + _service(fake, defer=False).add_events_to_memory( + app_name="travel", user_id="alice", events=events, session_id="s1" + ) + ) + ((_, (messages,), kw),) = fake.calls + assert [m["content"] for m in messages] == ["I live in Lisbon"] + assert kw["session_id"] == _loom_session("alice", "s1") + assert kw["defer"] is False # extraction inline, as the service was built + + +def test_events_without_text_send_nothing() -> None: + fake = _FakeMemory() + silent = Event(author="user", content=types.Content(parts=[types.Part(text=" ")])) + asyncio.run( + _service(fake).add_events_to_memory( + app_name="travel", user_id="u", events=[silent], session_id="s1" + ) + ) + assert fake.calls == [] + + +def test_events_without_a_session_are_refused() -> None: + fake = _FakeMemory() + event = Event(author="user", content=_user("I live in Lisbon")) + with pytest.raises(ValueError, match="session_id"): + asyncio.run( + _service(fake).add_events_to_memory(app_name="travel", user_id="u", events=[event]) + ) + assert fake.calls == [] + + +def test_add_memory_writes_content_keyed_memories() -> None: + fake = _FakeMemory() + entries = [ + MemoryEntry( + content=_user("Alice prefers aisle seats"), timestamp="2026-11-01T09:00:00+00:00" + ), + MemoryEntry(content=_user(" Alice prefers aisle seats ")), + MemoryEntry(content=types.Content(parts=[types.Part(text="hidden", thought=True)])), + ] + asyncio.run(_service(fake).add_memory(app_name="travel", user_id="alice", memories=entries)) + (first, again) = fake.calls + assert first[1][0] == again[1][0] and first[1][0].startswith("adk/") + assert first[1][1] == "Alice prefers aisle seats" + assert first[2]["user_id"] == "alice" + # The user is in the key: Loom files a long value's passages by key alone. + bob = _FakeMemory() + asyncio.run(_service(bob).add_memory(app_name="travel", user_id="bob", memories=entries[:1])) + assert bob.calls[0][1][0] != first[1][0] + assert first[2]["valid_at"].isoformat() == "2026-11-01T09:00:00+00:00" + assert again[2]["valid_at"] is None + + +def test_a_timestamp_without_a_zone_is_local_time() -> None: + fake = _FakeMemory() + entry = MemoryEntry(content=_user("Alice moved to Porto"), timestamp="2026-11-01T09:00:00") + asyncio.run(_service(fake).add_memory(app_name="travel", user_id="alice", memories=[entry])) + ((_, _, kw),) = fake.calls + assert kw["valid_at"] == datetime(2026, 11, 1, 9).astimezone() + assert kw["valid_at"].tzinfo is not None + + +def test_a_timestamp_that_is_not_iso_is_no_valid_at() -> None: + fake = _FakeMemory() + entry = MemoryEntry(content=_user("Alice moved to Porto"), timestamp="last spring") + asyncio.run(_service(fake).add_memory(app_name="travel", user_id="alice", memories=[entry])) + ((_, _, kw),) = fake.calls + assert kw["valid_at"] is None + + +def test_delete_memory_deletes_the_key_and_skips_an_entry_without_one() -> None: + fake = _FakeMemory() + service = _service(fake) + memory_id = _entry_id("user_seat", "adk-1") + asyncio.run(service.delete_memory(app_name="travel", user_id="alice", memory_id=memory_id)) + asyncio.run(service.delete_memory(app_name="travel", user_id="alice")) + # The session is sent: by key alone the delete finds the key's newest row, any user's. + assert fake.calls == [("delete", ("user_seat",), {"user_id": "alice", "session_id": "adk-1"})] + for not_an_id in ("adk/1", '"ab"', '{"k": "s", "x": "y"}', '["k"]', '["k", 1]'): + with pytest.raises(ValueError, match="not an id"): + asyncio.run( + service.delete_memory(app_name="travel", user_id="alice", memory_id=not_an_id) + ) + + +def test_the_loom_session_is_per_user_and_unambiguous() -> None: + assert _loom_session("alice", "main") != _loom_session("bob", "main") + assert _loom_session("a/b", "c") != _loom_session("a", "b/c") + assert _loom_session("alice", "main") == _loom_session("alice", "main") + assert ":" not in _loom_session("a:b", "c") # Loom's chunk keys are `chunk::` + + +def test_a_call_for_another_app_is_refused() -> None: + fake = _FakeMemory() + service = _service(fake) + calls = [ + service.search_memory(app_name="billing", user_id="alice", query="q"), + service.add_memory(app_name="billing", user_id="alice", memories=[]), + service.add_events_to_memory(app_name="billing", user_id="alice", events=[]), + service.add_session_to_memory(Session(id="s", app_name="billing", user_id="alice")), + service.delete_memory(app_name="billing", user_id="alice", memory_id="adk/1"), + ] + for call in calls: + with pytest.raises(ValueError, match="its own Loom namespace"): + asyncio.run(call) + assert fake.calls == [] + + +def test_only_a_fact_gets_an_entry_id_and_it_carries_the_rows_session() -> None: + hits = [ + _hit("user_seat", "a fact", session_id="adk-1"), + _hit("adk/1", "an entry"), + _hit("chunk:adk/1:0", "a passage", source="chunk", parent_memory_key="adk/1"), + _hit("chunk:s1:0", "a turn", source="chunk", parent_memory_key="adk/1"), + _hit("summary:s1", "a session", source="summary"), + ] + fake = _FakeMemory(hits) + service = _service(fake) + found = asyncio.run(service.search_memory(app_name="travel", user_id="u", query="q")) + ids = [m.id for m in found.memories] + assert ids == [_entry_id("user_seat", "adk-1"), _entry_id("adk/1", "-"), None, None, None] + sources = ["fact", "fact", "chunk", "chunk", "summary"] + assert [m.custom_metadata["source"] for m in found.memories] == sources + # The id a search returned deletes that row: its key under its session. + asyncio.run(service.delete_memory(app_name="travel", user_id="u", memory_id=ids[0])) + assert fake.calls[-1] == ("delete", ("user_seat",), {"user_id": "u", "session_id": "adk-1"}) + + +def test_without_google_adk_the_import_names_the_extra(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setitem(sys.modules, "google.adk.events", None) + monkeypatch.delitem(sys.modules, "loom.integrations.google_adk") + with pytest.raises(ImportError, match=r"clickhouse-loom\[google-adk\]"): + importlib.import_module("loom.integrations.google_adk") + + +def test_a_real_agent_posts_the_service_calls() -> None: + posts: list[tuple[str, dict[str, Any]]] = [] + + async def post(path: str, payload: dict[str, Any], *a: Any, **kw: Any) -> dict[str, Any]: + posts.append((path, dict(payload))) + return {"results": []} + + agent = Agent(org="acme", namespace="travel", agent="bot", base_url="http://x", api_key="k") + agent.transport.post = post # type: ignore[method-assign] + service = LoomMemoryService(agent, app_name="travel", top_k=3) + event = Event(author="user", content=_user("I prefer aisle seats")) + entry = MemoryEntry(content=_user("Alice prefers aisle seats")) + + async def calls() -> None: + await service.search_memory(app_name="travel", user_id="alice", query="seat") + await service.add_events_to_memory( + app_name="travel", user_id="alice", events=[event], session_id="s1" + ) + await service.add_memory(app_name="travel", user_id="alice", memories=[entry]) + await service.delete_memory( + app_name="travel", user_id="alice", memory_id=_entry_id("user_seat", "adk-1") + ) + + asyncio.run(calls()) + paths = [p for p, _ in posts] + assert paths == [ + "/v1/memory.search", + "/v1/memory.set_from_messages", + "/v1/memory.set", + "/v1/memory.delete", + ] + search, extract, write, delete = (body for _, body in posts) + assert (search["query"], search["top_k"], search["user_id"]) == ("seat", 3, "alice") + assert (search["namespace_scope"], search["bodies"], search["explain"]) == ( + "this", + "full", + False, + ) + assert (extract["user_id"], extract["session_id"]) == ("alice", _loom_session("alice", "s1")) + assert [m["content"] for m in extract["messages"]] == ["I prefer aisle seats"] + assert write["memory_key"].startswith("adk/") and write["user_id"] == "alice" + assert (delete["memory_key"], delete["user_id"], delete["session_id"]) == ( + "user_seat", + "alice", + "adk-1", + ) + + +@pytest.mark.parametrize("user", ["", "-"]) +def test_a_user_id_that_names_no_loom_user_is_refused(user: str) -> None: + fake = _FakeMemory() + service = _service(fake) + entry = MemoryEntry(content=_user("Alice prefers aisle seats")) + event = Event(author="user", content=_user("I prefer aisle seats")) + + calls = [ + service.add_session_to_memory(Session(id="s", app_name="travel", user_id=user)), + service.search_memory(app_name="travel", user_id=user, query="seat"), + service.add_memory(app_name="travel", user_id=user, memories=[entry]), + service.add_events_to_memory( + app_name="travel", user_id=user, events=[event], session_id="s1" + ), + service.delete_memory(app_name="travel", user_id=user, memory_id="adk/1"), + ] + for call in calls: + with pytest.raises(ValueError, match="names none"): + asyncio.run(call) + assert fake.calls == [] + + +def test_a_long_session_is_sent_in_batches_the_server_takes() -> None: + fake = _FakeMemory() + events = [Event(author="user", content=_user(f"fact {i}")) for i in range(401)] + asyncio.run( + _service(fake).add_events_to_memory( + app_name="travel", user_id="alice", events=events, session_id="s1" + ) + ) + sizes = [len(c[1][0]) for c in fake.calls if c[0] == "set_from_messages"] + assert sizes == [400, 1] + assert {c[2]["session_id"] for c in fake.calls} == {_loom_session("alice", "s1")} diff --git a/tests/integration/test_sdk_google_adk_memory.py b/tests/integration/test_sdk_google_adk_memory.py new file mode 100644 index 0000000000..ab43cdfea0 --- /dev/null +++ b/tests/integration/test_sdk_google_adk_memory.py @@ -0,0 +1,236 @@ +"""LoomMemoryService against a running Loom: a turn an ADK Runner saves is +extracted, and preload_memory puts it in a later session's prompt for the same +user only; a memory, extracted or explicit, is deleted by the id a search +returned.""" + +from __future__ import annotations + +import base64 +import json +import os +from collections.abc import AsyncGenerator +from typing import Any + +import pytest + +from tests.integration._eventually import eventually + +# An SDK extra, outside the server's environment: install google-adk to run these. +pytest.importorskip("google.adk") + +from google.adk.agents import LlmAgent +from google.adk.memory.memory_entry import MemoryEntry +from google.adk.models.base_llm import BaseLlm +from google.adk.models.llm_request import LlmRequest +from google.adk.models.llm_response import LlmResponse +from google.adk.runners import Runner +from google.adk.sessions import InMemorySessionService +from google.adk.tools import preload_memory +from google.genai import types +from loom.integrations.google_adk import LoomMemoryService +from pydantic import Field + + +class _EchoLlm(BaseLlm): + """Answers "Noted." to every call and keeps the requests.""" + + model: str = "echo" + requests: list[LlmRequest] = Field(default_factory=list) + + async def generate_content_async( + self, llm_request: LlmRequest, stream: bool = False + ) -> AsyncGenerator[LlmResponse, None]: + self.requests.append(llm_request) + yield LlmResponse(content=types.Content(role="model", parts=[types.Part(text="Noted.")])) + + +async def _save_turn(ctx: Any) -> None: + turn = [e for e in ctx.session.events if e.invocation_id == ctx.invocation_id] + await ctx.add_events_to_memory(events=turn) + + +async def _turn(service: LoomMemoryService, user: str, text: str) -> str: + """One turn in a new session of the app "travel"; returns the model's prompt text.""" + llm = _EchoLlm() + sessions = InMemorySessionService() + runner = Runner( + app_name="travel", + agent=LlmAgent( + name="assistant", model=llm, tools=[preload_memory], after_agent_callback=_save_turn + ), + session_service=sessions, + memory_service=service, + ) + session = await sessions.create_session(app_name="travel", user_id=user) + message = types.Content(role="user", parts=[types.Part(text=text)]) + async for _ in runner.run_async(user_id=user, session_id=session.id, new_message=message): + pass + return " ".join(p.text or "" for c in llm.requests[0].contents for p in c.parts or []) + + +async def test_a_saved_turn_reaches_a_later_prompt(agent) -> None: + # defer=False: extraction inline, since the test server runs no background workers + service = LoomMemoryService(agent, app_name="travel", honour_abstain=False, defer=False) + await _turn(service, "alice", "I fly to Lisbon every month.") + + async def saved() -> bool: + found = await service.search_memory(app_name="travel", user_id="alice", query="Lisbon") + return any(m.custom_metadata["source"] == "fact" for m in found.memories) + + # A write is searchable once its embedding lands; eventually raises on timeout. + await eventually(saved, description="the saved turn's fact") + prompt = await _turn(service, "alice", "Where does Alice fly every month?") + assert "lisbon" in prompt.lower() + found = await service.search_memory(app_name="travel", user_id="bob", query="Lisbon") + assert not found.memories + found = await service.search_memory(app_name="travel", user_id="alice", query="Lisbon") + facts = {m.id for m in found.memories if m.custom_metadata["source"] == "fact"} + assert facts + for memory_id in facts: + await service.delete_memory(app_name="travel", user_id="alice", memory_id=memory_id) + found = await service.search_memory(app_name="travel", user_id="alice", query="Lisbon") + # The deleted facts do not come back. + assert not {m.id for m in found.memories} & facts + + +async def test_add_memory_then_delete_by_id(agent) -> None: + service = LoomMemoryService(agent, app_name="travel", honour_abstain=False) + entry = MemoryEntry( + content=types.Content(parts=[types.Part(text="Alice prefers aisle seats")]), + timestamp="2026-03-01T09:00:00+00:00", + ) + await service.add_memory(app_name="travel", user_id="alice", memories=[entry]) + + async def ids(user: str) -> list[str | None]: + found = await service.search_memory(app_name="travel", user_id=user, query="aisle seat") + return [m.id for m in found.memories] + + await eventually(lambda: ids("alice"), description="the memory found") + (memory_id,) = await ids("alice") + assert memory_id is not None + key, _session = json.loads(memory_id) + row = await agent.memory.get(key, user_id="alice") + assert row is not None + fields = ("value", "agent", "user_id", "session_id", "memory_type", "source_class", "tags") + assert [row[f] for f in fields] == [ + "Alice prefers aisle seats", + agent.agent, + "alice", + "-", + "semantic", + "asserted", + [], + ] + assert row["valid_at"].startswith("2026-03-01") + # The server stamps the actor from the token: its subject, as `:`. + claims = os.environ["LOOM_API_KEY"].split(".")[1] + subject = json.loads(base64.urlsafe_b64decode(claims + "=" * (-len(claims) % 4)))["sub"] + assert row["actor"].endswith(f":{subject}") + await service.delete_memory(app_name="travel", user_id="bob", memory_id=memory_id) + assert await ids("alice") == [memory_id] # another user's delete reaches nothing + await service.delete_memory(app_name="travel", user_id="alice", memory_id=memory_id) + assert await ids("alice") == [] + + +async def test_two_users_saving_the_same_text_each_find_their_own(agent) -> None: + service = LoomMemoryService(agent, app_name="travel", honour_abstain=False) + entry = MemoryEntry(content=types.Content(parts=[types.Part(text="Prefers window seats")])) + + async def ids(user: str) -> list[str | None]: + found = await service.search_memory(app_name="travel", user_id=user, query="window seat") + return [m.id for m in found.memories] + + await service.add_memory(app_name="travel", user_id="carol", memories=[entry]) + + async def carols_vector() -> list[str]: + hits = await agent.memory.search("window seats", memory_type="semantic", top_k=5) + return [h.memory_key for h in hits] + + # Loom's write-time check reads vectors: dave saves once carol's is searchable. + await eventually(carols_vector, description="carol's vector") + await service.add_memory(app_name="travel", user_id="dave", memories=[entry]) + carol = await ids("carol") + dave = await eventually(lambda: ids("dave"), description="dave's memory") + assert len(carol) == len(dave) == 1 and carol != dave + + +async def test_each_turn_saved_in_one_session_keeps_its_passage(agent) -> None: + """The documented callback saves each turn on its own under one session; a search + for words only the first turn said still finds that turn's verbatim passage.""" + service = LoomMemoryService(agent, app_name="travel", honour_abstain=False, defer=False) + llm = _EchoLlm() + sessions = InMemorySessionService() + runner = Runner( + app_name="travel", + agent=LlmAgent(name="assistant", model=llm, after_agent_callback=_save_turn), + session_service=sessions, + memory_service=service, + ) + session = await sessions.create_session(app_name="travel", user_id="alice") + for text in ( + "My cat Zanzibar loves sardines from the harbour market.", + "Tomorrow I am repainting the garage door bright teal.", + ): + message = types.Content(role="user", parts=[types.Part(text=text)]) + async for _ in runner.run_async( + user_id="alice", session_id=session.id, new_message=message + ): + pass + + async def passage(query: str, words: str) -> bool: + found = await service.search_memory(app_name="travel", user_id="alice", query=query) + return any( + m.custom_metadata["source"] == "chunk" and words in (m.content.parts[0].text or "") + for m in found.memories + if m.content and m.content.parts + ) + + await eventually(lambda: passage("Zanzibar sardines harbour", "Zanzibar"), description="turn 1") + assert await passage("garage door teal", "garage door") + + +async def test_a_users_delete_reaches_their_fact_when_another_user_holds_its_key( + agent, require_fake_llm +) -> None: + """Extracted keys are concept names two users share; the entry id carries the + session, so Alice's delete reaches her row and leaves Bob's.""" + service = LoomMemoryService(agent, app_name="travel", honour_abstain=False, defer=False) + for user in ("alice", "bob"): + await _turn(service, user, "I fly to Lisbon every month.") + + async def facts(user: str) -> set[str | None]: + found = await service.search_memory(app_name="travel", user_id=user, query="Lisbon") + return {m.id for m in found.memories if m.custom_metadata["source"] == "fact"} + + async def both() -> tuple[set[str | None], set[str | None]] | None: + alices, bobs = await facts("alice"), await facts("bob") + keys = {json.loads(i)[0] for i in alices} & {json.loads(i)[0] for i in bobs} + return (alices, bobs) if keys else None # wait until the two share a key + + alices, bobs = await eventually(both, description="the users' facts sharing a key") + for memory_id in alices: + await service.delete_memory(app_name="travel", user_id="alice", memory_id=memory_id) + assert not await facts("alice") & alices + assert bobs <= await facts("bob") + + +async def test_a_delete_reaches_the_key_in_each_session_it_is_served_from(agent) -> None: + """A key the user holds in two sessions is served once per session, each under its + own id, so deleting what a search returns leaves the key unserved.""" + for session, city in (("adk-a", "Lisbon"), ("adk-b", "Porto")): + await agent.memory.set( + "user_home_city", f"Alice lives in {city}", user_id="alice", session_id=session + ) + service = LoomMemoryService(agent, app_name="travel", honour_abstain=False) + + async def facts() -> set[str | None]: + found = await service.search_memory(app_name="travel", user_id="alice", query="Alice lives") + return {m.id for m in found.memories if m.custom_metadata["source"] == "fact"} + + async def two() -> set[str | None] | None: + ids = await facts() + return ids if len(ids) == 2 else None + + for memory_id in await eventually(two, description="both sessions' rows"): + await service.delete_memory(app_name="travel", user_id="alice", memory_id=memory_id) + assert await facts() == set()