hindsight-google-adk 0.1.0__tar.gz

hindsight_google_adk-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.mcp.json
+.osgrep
+# Virtual environments
+.venv
+
+# Node
+node_modules/
+
+# Environment variables and local config
+.env
+docker-compose.yml
+docker-compose.override.yml
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# NLTK data (will be downloaded automatically)
+nltk_data/
+
+# Monitoring stack (Prometheus/Grafana binaries and data)
+.monitoring/
+.pgbouncer/
+
+# Large benchmark datasets (will be downloaded automatically)
+**/longmemeval_s_cleaned.json
+
+# Debug logs
+logs/
+
+.DS_Store
+
+# Generated docs files
+hindsight-docs/static/llms-full.txt
+
+
+hindsight-dev/benchmarks/locomo/results/
+hindsight-dev/benchmarks/longmemeval/results/
+hindsight-dev/benchmarks/consolidation/results/
+hindsight-dev/benchmarks/perf/results/
+benchmarks/results/
+hindsight-cli/target
+hindsight-clients/rust/target
+.claude/*
+!.claude/skills/
+whats-next.md
+TASK.md
+# Parked / draft integrations that aren't ready to ship
+hindsight-integrations/_drafts/
+# Changelog is now tracked in hindsight-docs/src/pages/changelog.md
+# CHANGELOG.md
+
+blog-post*

hindsight_google_adk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vectorize
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hindsight_google_adk-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: hindsight-google-adk
+Version: 0.1.0
+Summary: Google ADK integration for Hindsight - persistent long-term memory for ADK agents
+Project-URL: Homepage, https://github.com/vectorize-io/hindsight
+Project-URL: Documentation, https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/google-adk
+Project-URL: Repository, https://github.com/vectorize-io/hindsight
+Author-email: Vectorize <support@vectorize.io>
+License: MIT
+License-File: LICENSE
+Keywords: adk,agents,ai,google-adk,hindsight,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: google-adk>=2.0
+Requires-Dist: hindsight-client>=0.4.0
+Description-Content-Type: text/markdown
+
+# hindsight-google-adk
+
+Persistent long-term memory for [Google ADK](https://adk.dev/) agents via [Hindsight](https://vectorize.io/hindsight).
+
+The package gives you two complementary patterns:
+
+- **`HindsightMemoryService`** — Implements ADK's `BaseMemoryService`. Pass it to `Runner(memory_service=...)` and sessions are automatically retained on completion; agents calling `search_memory` get results back from Hindsight.
+- **`create_hindsight_tools(...)`** — Returns a list of ADK `FunctionTool` instances (`hindsight_retain`, `hindsight_recall`, `hindsight_reflect`) the model can call inside a turn.
+
+## Installation
+
+```bash
+pip install hindsight-google-adk
+```
+
+## Quick Start: Automatic Memory
+
+```python
+import asyncio
+from google.adk.agents import LlmAgent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+
+from hindsight_google_adk import HindsightMemoryService
+
+memory = HindsightMemoryService.from_url(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+)
+
+agent = LlmAgent(name="assistant", model="gemini-2.0-flash")
+
+runner = Runner(
+    app_name="my-app",
+    agent=agent,
+    session_service=InMemorySessionService(),
+    memory_service=memory,
+)
+```
+
+When a session ends, `Runner` calls `add_session_to_memory`, which retains the session's events to a Hindsight bank keyed by `(app_name, user_id)`. When the agent (or another call) invokes `search_memory(app_name, user_id, query)`, the integration runs a Hindsight recall and returns the results as ADK `MemoryEntry` objects.
+
+## Quick Start: Explicit Tools
+
+```python
+from google.adk.agents import LlmAgent
+from hindsight_google_adk import create_hindsight_tools
+
+tools = create_hindsight_tools(
+    bank_id="user-123",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+)
+
+agent = LlmAgent(name="assistant", model="gemini-2.0-flash", tools=tools)
+```
+
+The agent now has three tools (toggle with `include_retain` / `include_recall` / `include_reflect`):
+
+- `hindsight_retain(content)` — store information to long-term memory
+- `hindsight_recall(query)` — search memory and return matches
+- `hindsight_reflect(query)` — synthesize a coherent answer from memory
+
+## Global Configuration
+
+For shared defaults, call `configure(...)` once at startup:
+
+```python
+from hindsight_google_adk import configure
+
+configure(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key=None,                      # falls back to HINDSIGHT_API_KEY env var
+    bank_id_template="{app_name}::{user_id}",
+    budget="mid",
+    max_tokens=4096,
+)
+```
+
+Subsequent `HindsightMemoryService.from_url()` and `create_hindsight_tools()` calls use the global config as a fallback.
+
+## Bank ID Derivation
+
+By default, each `(app_name, user_id)` pair gets its own bank: `"{app_name}::{user_id}"`. Override with `bank_id_template`:
+
+```python
+# Per-user bank shared across apps
+HindsightMemoryService.from_url(..., bank_id_template="user::{user_id}")
+
+# Static bank shared across all users
+HindsightMemoryService.from_url(..., bank_id_template="my-shared-bank")
+```
+
+## Configuration Reference
+
+| Argument | Default | Description |
+|---|---|---|
+| `hindsight_api_url` | `https://api.hindsight.vectorize.io` | Hindsight API URL (Cloud by default). |
+| `api_key` | `HINDSIGHT_API_KEY` env | Bearer token for Hindsight Cloud. |
+| `bank_id_template` | `"{app_name}::{user_id}"` | Format string for deriving the bank id. |
+| `budget` | `"mid"` | Recall budget: `low`/`mid`/`high`. |
+| `max_tokens` | `4096` | Max tokens for recall results. |
+| `tags` | `None` | Extra tags added to retains. `app:` and `user:` are always added. |
+| `recall_tags` | `None` | Extra tags appended to recall queries. `user:` is always added. |
+| `recall_tags_match` | `"any"` | Tag match mode: `any` / `all` / `any_strict` / `all_strict`. |
+| `mission` | `None` | If set, the bank is created (idempotent) on first use with this fact-extraction mission. |
+| `context` | `"google-adk"` | Provenance label attached to retained content. |
+
+## Memory Scoping with Tags
+
+Each retained session/event carries `app:<app_name>` and `user:<user_id>` tags. Recall queries automatically include `user:<user_id>` so users never see each other's memories. Pass `tags=[...]` to extend the retain set or `recall_tags=[...]` to filter recall further.
+
+## Connection Modes
+
+### Hindsight Cloud (recommended)
+
+```python
+HindsightMemoryService.from_url(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+)
+```
+
+### Self-hosted
+
+```python
+HindsightMemoryService.from_url(hindsight_api_url="http://localhost:8888")
+```
+
+## Error Handling
+
+All `add_*` and `search_memory` methods are resilient: Hindsight failures are logged but never propagate to the `Runner`. The explicit tools raise `HindsightError` on failure so the agent can react.
+
+## Requirements
+
+- Python 3.10+
+- `google-adk>=2.0`
+- `hindsight-client>=0.4.0`
+
+## License
+
+MIT

hindsight_google_adk-0.1.0/README.md

@@ -0,0 +1,142 @@
+# hindsight-google-adk
+
+Persistent long-term memory for [Google ADK](https://adk.dev/) agents via [Hindsight](https://vectorize.io/hindsight).
+
+The package gives you two complementary patterns:
+
+- **`HindsightMemoryService`** — Implements ADK's `BaseMemoryService`. Pass it to `Runner(memory_service=...)` and sessions are automatically retained on completion; agents calling `search_memory` get results back from Hindsight.
+- **`create_hindsight_tools(...)`** — Returns a list of ADK `FunctionTool` instances (`hindsight_retain`, `hindsight_recall`, `hindsight_reflect`) the model can call inside a turn.
+
+## Installation
+
+```bash
+pip install hindsight-google-adk
+```
+
+## Quick Start: Automatic Memory
+
+```python
+import asyncio
+from google.adk.agents import LlmAgent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+
+from hindsight_google_adk import HindsightMemoryService
+
+memory = HindsightMemoryService.from_url(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+)
+
+agent = LlmAgent(name="assistant", model="gemini-2.0-flash")
+
+runner = Runner(
+    app_name="my-app",
+    agent=agent,
+    session_service=InMemorySessionService(),
+    memory_service=memory,
+)
+```
+
+When a session ends, `Runner` calls `add_session_to_memory`, which retains the session's events to a Hindsight bank keyed by `(app_name, user_id)`. When the agent (or another call) invokes `search_memory(app_name, user_id, query)`, the integration runs a Hindsight recall and returns the results as ADK `MemoryEntry` objects.
+
+## Quick Start: Explicit Tools
+
+```python
+from google.adk.agents import LlmAgent
+from hindsight_google_adk import create_hindsight_tools
+
+tools = create_hindsight_tools(
+    bank_id="user-123",
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+)
+
+agent = LlmAgent(name="assistant", model="gemini-2.0-flash", tools=tools)
+```
+
+The agent now has three tools (toggle with `include_retain` / `include_recall` / `include_reflect`):
+
+- `hindsight_retain(content)` — store information to long-term memory
+- `hindsight_recall(query)` — search memory and return matches
+- `hindsight_reflect(query)` — synthesize a coherent answer from memory
+
+## Global Configuration
+
+For shared defaults, call `configure(...)` once at startup:
+
+```python
+from hindsight_google_adk import configure
+
+configure(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key=None,                      # falls back to HINDSIGHT_API_KEY env var
+    bank_id_template="{app_name}::{user_id}",
+    budget="mid",
+    max_tokens=4096,
+)
+```
+
+Subsequent `HindsightMemoryService.from_url()` and `create_hindsight_tools()` calls use the global config as a fallback.
+
+## Bank ID Derivation
+
+By default, each `(app_name, user_id)` pair gets its own bank: `"{app_name}::{user_id}"`. Override with `bank_id_template`:
+
+```python
+# Per-user bank shared across apps
+HindsightMemoryService.from_url(..., bank_id_template="user::{user_id}")
+
+# Static bank shared across all users
+HindsightMemoryService.from_url(..., bank_id_template="my-shared-bank")
+```
+
+## Configuration Reference
+
+| Argument | Default | Description |
+|---|---|---|
+| `hindsight_api_url` | `https://api.hindsight.vectorize.io` | Hindsight API URL (Cloud by default). |
+| `api_key` | `HINDSIGHT_API_KEY` env | Bearer token for Hindsight Cloud. |
+| `bank_id_template` | `"{app_name}::{user_id}"` | Format string for deriving the bank id. |
+| `budget` | `"mid"` | Recall budget: `low`/`mid`/`high`. |
+| `max_tokens` | `4096` | Max tokens for recall results. |
+| `tags` | `None` | Extra tags added to retains. `app:` and `user:` are always added. |
+| `recall_tags` | `None` | Extra tags appended to recall queries. `user:` is always added. |
+| `recall_tags_match` | `"any"` | Tag match mode: `any` / `all` / `any_strict` / `all_strict`. |
+| `mission` | `None` | If set, the bank is created (idempotent) on first use with this fact-extraction mission. |
+| `context` | `"google-adk"` | Provenance label attached to retained content. |
+
+## Memory Scoping with Tags
+
+Each retained session/event carries `app:<app_name>` and `user:<user_id>` tags. Recall queries automatically include `user:<user_id>` so users never see each other's memories. Pass `tags=[...]` to extend the retain set or `recall_tags=[...]` to filter recall further.
+
+## Connection Modes
+
+### Hindsight Cloud (recommended)
+
+```python
+HindsightMemoryService.from_url(
+    hindsight_api_url="https://api.hindsight.vectorize.io",
+    api_key="hsk_...",
+)
+```
+
+### Self-hosted
+
+```python
+HindsightMemoryService.from_url(hindsight_api_url="http://localhost:8888")
+```
+
+## Error Handling
+
+All `add_*` and `search_memory` methods are resilient: Hindsight failures are logged but never propagate to the `Runner`. The explicit tools raise `HindsightError` on failure so the agent can react.
+
+## Requirements
+
+- Python 3.10+
+- `google-adk>=2.0`
+- `hindsight-client>=0.4.0`
+
+## License
+
+MIT

hindsight_google_adk-0.1.0/hindsight_google_adk/__init__.py

@@ -0,0 +1,39 @@
+"""Hindsight memory integration for Google ADK agents.
+
+Provides two complementary patterns:
+
+- **Automatic memory** (``HindsightMemoryService``):
+  Implements ADK's ``BaseMemoryService``. Pass an instance to
+  ``Runner(memory_service=...)`` and sessions are retained on completion,
+  with ``search_memory`` queries served from Hindsight.
+
+- **Explicit tools** (``create_hindsight_tools``):
+  ADK ``FunctionTool`` wrappers for retain / recall / reflect, so agents can
+  call Hindsight directly from inside a turn.
+
+Usage::
+
+    from hindsight_google_adk import HindsightMemoryService, create_hindsight_tools
+"""
+
+from .config import (
+    HindsightAdkConfig,
+    configure,
+    get_config,
+    reset_config,
+)
+from .errors import HindsightError
+from .memory import HindsightMemoryService
+from .tools import create_hindsight_tools
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "configure",
+    "get_config",
+    "reset_config",
+    "HindsightAdkConfig",
+    "HindsightError",
+    "HindsightMemoryService",
+    "create_hindsight_tools",
+]

hindsight_google_adk-0.1.0/hindsight_google_adk/_client.py

@@ -0,0 +1,46 @@
+"""Shared Hindsight client resolution logic."""
+
+from importlib import metadata
+from typing import Any, Optional
+
+from hindsight_client import Hindsight
+
+from .config import get_config
+from .errors import HindsightError
+
+try:
+    _VERSION = metadata.version("hindsight-google-adk")
+except metadata.PackageNotFoundError:
+    _VERSION = "0.0.0"
+_USER_AGENT = f"hindsight-google-adk/{_VERSION}"
+
+# Per-operation timeouts (seconds)
+TIMEOUT_RETAIN = 15.0
+TIMEOUT_RECALL = 10.0
+TIMEOUT_REFLECT = 30.0
+TIMEOUT_BANK = 15.0
+TIMEOUT_DEFAULT = 30.0
+
+
+def resolve_client(
+    client: Optional[Hindsight],
+    hindsight_api_url: Optional[str],
+    api_key: Optional[str],
+) -> Hindsight:
+    """Resolve a Hindsight client from explicit args or global config."""
+    if client is not None:
+        return client
+
+    config = get_config()
+    url = hindsight_api_url or (config.hindsight_api_url if config else None)
+    key = api_key or (config.api_key if config else None)
+
+    if url is None:
+        raise HindsightError(
+            "No Hindsight API URL configured. Pass client= or hindsight_api_url=, or call configure() first."
+        )
+
+    kwargs: dict[str, Any] = {"base_url": url, "timeout": TIMEOUT_DEFAULT, "user_agent": _USER_AGENT}
+    if key:
+        kwargs["api_key"] = key
+    return Hindsight(**kwargs)

hindsight_google_adk-0.1.0/hindsight_google_adk/config.py

@@ -0,0 +1,109 @@
+"""Global configuration for Hindsight-Google-ADK integration."""
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_HINDSIGHT_API_URL = "https://api.hindsight.vectorize.io"
+HINDSIGHT_API_KEY_ENV = "HINDSIGHT_API_KEY"
+DEFAULT_BANK_ID_TEMPLATE = "{app_name}::{user_id}"
+
+
+@dataclass
+class HindsightAdkConfig:
+    """Connection and default settings for the Google ADK integration.
+
+    Attributes:
+        hindsight_api_url: URL of the Hindsight API server.
+        api_key: API key for Hindsight authentication.
+        budget: Default recall budget level (low/mid/high).
+        max_tokens: Default maximum tokens for recall results.
+        tags: Default tags applied when storing memories.
+        recall_tags: Default tags to filter when searching memories.
+        recall_tags_match: Tag matching mode (any/all/any_strict/all_strict).
+        context: Source label for retain operations (default: "google-adk").
+        mission: Bank mission for fact extraction context.
+        bank_id_template: Format string used to derive a bank id from
+            ``app_name`` and ``user_id`` (default: ``"{app_name}::{user_id}"``).
+        verbose: Enable verbose logging.
+    """
+
+    hindsight_api_url: str = DEFAULT_HINDSIGHT_API_URL
+    api_key: Optional[str] = None
+    budget: str = "mid"
+    max_tokens: int = 4096
+    tags: Optional[list[str]] = None
+    recall_tags: Optional[list[str]] = None
+    recall_tags_match: str = "any"
+    context: str = "google-adk"
+    mission: Optional[str] = None
+    bank_id_template: str = DEFAULT_BANK_ID_TEMPLATE
+    verbose: bool = False
+
+
+_global_config: Optional[HindsightAdkConfig] = None
+
+
+def configure(
+    hindsight_api_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    budget: str = "mid",
+    max_tokens: int = 4096,
+    tags: Optional[list[str]] = None,
+    recall_tags: Optional[list[str]] = None,
+    recall_tags_match: str = "any",
+    context: str = "google-adk",
+    mission: Optional[str] = None,
+    bank_id_template: str = DEFAULT_BANK_ID_TEMPLATE,
+    verbose: bool = False,
+) -> HindsightAdkConfig:
+    """Configure Hindsight connection and default settings.
+
+    Args:
+        hindsight_api_url: Hindsight API URL (default: production cloud).
+        api_key: API key. Falls back to ``HINDSIGHT_API_KEY`` env var.
+        budget: Default recall budget (low/mid/high).
+        max_tokens: Default max tokens for recall results.
+        tags: Default tags for retain operations.
+        recall_tags: Default tags to filter recall/search.
+        recall_tags_match: Tag matching mode.
+        context: Source label for retain operations.
+        mission: Bank mission for fact extraction context.
+        bank_id_template: Format string for deriving bank ids from
+            ``app_name`` and ``user_id``.
+        verbose: Enable verbose logging.
+
+    Returns:
+        The configured ``HindsightAdkConfig``.
+    """
+    global _global_config
+
+    resolved_url = hindsight_api_url or DEFAULT_HINDSIGHT_API_URL
+    resolved_key = api_key or os.environ.get(HINDSIGHT_API_KEY_ENV)
+
+    _global_config = HindsightAdkConfig(
+        hindsight_api_url=resolved_url,
+        api_key=resolved_key,
+        budget=budget,
+        max_tokens=max_tokens,
+        tags=tags,
+        recall_tags=recall_tags,
+        recall_tags_match=recall_tags_match,
+        context=context,
+        mission=mission,
+        bank_id_template=bank_id_template,
+        verbose=verbose,
+    )
+
+    return _global_config
+
+
+def get_config() -> Optional[HindsightAdkConfig]:
+    """Get the current global configuration."""
+    return _global_config
+
+
+def reset_config() -> None:
+    """Reset global configuration to None."""
+    global _global_config
+    _global_config = None

hindsight_google_adk-0.1.0/hindsight_google_adk/errors.py

@@ -0,0 +1,7 @@
+"""Hindsight-Google-ADK error types."""
+
+
+class HindsightError(Exception):
+    """Exception raised when a Hindsight memory operation fails."""
+
+    pass