hindsight-langgraph 0.1.1__tar.gz

hindsight_langgraph-0.1.1/.gitignore

@@ -0,0 +1,59 @@
+# 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
+whats-next.md
+TASK.md
+# Changelog is now tracked in hindsight-docs/src/pages/changelog.md
+# CHANGELOG.md
+
+blog-post*

hindsight_langgraph-0.1.1/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: hindsight-langgraph
+Version: 0.1.1
+Summary: LangGraph integration for Hindsight - persistent memory tools, nodes, and store for AI agents
+Project-URL: Homepage, https://github.com/vectorize-io/hindsight
+Project-URL: Documentation, https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/langgraph
+Project-URL: Repository, https://github.com/vectorize-io/hindsight
+Author-email: Vectorize <support@vectorize.io>
+License: MIT
+Keywords: agents,ai,hindsight,langchain,langgraph,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: hindsight-client>=0.4.0
+Requires-Dist: langchain-core>=0.3.0
+Provides-Extra: all
+Requires-Dist: langgraph>=0.3.0; extra == 'all'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.3.0; extra == 'langgraph'

hindsight_langgraph-0.1.1/README.md

@@ -0,0 +1,144 @@
+# hindsight-langgraph
+
+LangGraph and LangChain integration for [Hindsight](https://github.com/vectorize-io/hindsight) — persistent long-term memory for AI agents.
+
+Provides three integration patterns:
+- **Tools** — retain/recall/reflect as LangChain `@tool` functions for agent-driven memory. Works with **both LangChain and LangGraph**.
+- **Nodes** *(LangGraph)* — pre-built graph nodes for automatic memory injection and storage
+- **BaseStore** *(LangGraph)* — drop-in `BaseStore` adapter for LangGraph's built-in memory system
+
+## Prerequisites
+
+- A running Hindsight instance ([self-hosted via Docker](https://github.com/vectorize-io/hindsight#quick-start) or [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup))
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install hindsight-langgraph
+```
+
+## Quick Start: Tools
+
+Bind Hindsight memory tools to your LangGraph agent so it can store and retrieve memories on demand.
+
+```python
+from hindsight_client import Hindsight
+from hindsight_langgraph import create_hindsight_tools
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+client = Hindsight(base_url="http://localhost:8888")
+tools = create_hindsight_tools(client=client, bank_id="user-123")
+
+agent = create_react_agent(
+    ChatOpenAI(model="gpt-4o"),
+    tools=tools,
+)
+
+result = await agent.ainvoke(
+    {"messages": [{"role": "user", "content": "Remember that I prefer dark mode"}]}
+)
+```
+
+## Quick Start: Memory Nodes
+
+Add recall and retain nodes to your graph for automatic memory injection before LLM calls and storage after responses.
+
+```python
+from hindsight_client import Hindsight
+from hindsight_langgraph import create_recall_node, create_retain_node
+from langgraph.graph import StateGraph, MessagesState, START, END
+
+client = Hindsight(base_url="http://localhost:8888")
+
+recall = create_recall_node(client=client, bank_id="user-123")
+retain = create_retain_node(client=client, bank_id="user-123")
+
+builder = StateGraph(MessagesState)
+builder.add_node("recall", recall)
+builder.add_node("agent", agent_node)  # your LLM node
+builder.add_node("retain", retain)
+
+builder.add_edge(START, "recall")
+builder.add_edge("recall", "agent")
+builder.add_edge("agent", "retain")
+builder.add_edge("retain", END)
+
+graph = builder.compile()
+```
+
+### Dynamic Bank IDs
+
+Use `bank_id_from_config` to resolve the bank per-request from the graph's config:
+
+```python
+recall = create_recall_node(client=client, bank_id_from_config="user_id")
+retain = create_retain_node(client=client, bank_id_from_config="user_id")
+
+# Bank ID resolved at runtime
+result = await graph.ainvoke(
+    {"messages": [{"role": "user", "content": "hello"}]},
+    config={"configurable": {"user_id": "user-456"}},
+)
+```
+
+## Quick Start: BaseStore
+
+Use Hindsight as a LangGraph `BaseStore` for cross-thread persistent memory with semantic search.
+
+```python
+from hindsight_client import Hindsight
+from hindsight_langgraph import HindsightStore
+
+client = Hindsight(base_url="http://localhost:8888")
+store = HindsightStore(client=client)
+
+graph = builder.compile(checkpointer=checkpointer, store=store)
+
+# Store and search memories via the store API
+await store.aput(("user", "123", "prefs"), "theme", {"value": "dark mode"})
+results = await store.asearch(("user", "123", "prefs"), query="theme preference")
+```
+
+## Configuration
+
+### Global config
+
+```python
+from hindsight_langgraph import configure
+
+configure(
+    hindsight_api_url="http://localhost:8888",
+    api_key="your-api-key",  # or set HINDSIGHT_API_KEY env var
+    budget="mid",
+    tags=["source:langgraph"],
+)
+```
+
+### Per-call overrides
+
+All factory functions accept `client`, `hindsight_api_url`, and `api_key` to override the global config.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `hindsight_api_url` | Hindsight API URL | `https://api.hindsight.vectorize.io` |
+| `api_key` | API key (or `HINDSIGHT_API_KEY` env var) | `None` |
+| `budget` | Recall budget: `low`, `mid`, `high` | `mid` |
+| `max_tokens` | Max tokens for recall results | `4096` |
+| `tags` | Tags applied to retain operations | `None` |
+| `recall_tags` | Tags to filter recall results | `None` |
+| `recall_tags_match` | Tag matching: `any`, `all`, `any_strict`, `all_strict` | `any` |
+
+## Requirements
+
+- Python 3.10+
+- `langchain-core >= 0.3.0`
+- `hindsight-client >= 0.4.0`
+- `langgraph >= 0.3.0` *(only for nodes and store patterns — install with `pip install hindsight-langgraph[langgraph]`)*
+
+## Documentation
+
+- [Integration docs](https://docs.hindsight.vectorize.io/docs/sdks/integrations/langgraph)
+- [Cookbook: ReAct agent with memory](https://docs.hindsight.vectorize.io/cookbook/recipes/langgraph-react-agent)
+- [Hindsight API docs](https://docs.hindsight.vectorize.io)

hindsight_langgraph-0.1.1/hindsight_langgraph/__init__.py

@@ -0,0 +1,93 @@
+"""Hindsight-LangGraph: Persistent memory for LangGraph and LangChain agents.
+
+Provides Hindsight-backed tools, nodes, and a BaseStore adapter,
+giving agents long-term memory across conversations.
+
+The **tools** pattern works with both LangChain and LangGraph — only
+``langchain-core`` is required. The **nodes** and **store** patterns
+require ``langgraph`` (install with ``pip install hindsight-langgraph[langgraph]``).
+
+Basic usage with tools (LangChain or LangGraph)::
+
+    from hindsight_client import Hindsight
+    from hindsight_langgraph import create_hindsight_tools
+
+    client = Hindsight(base_url="http://localhost:8888")
+    tools = create_hindsight_tools(client=client, bank_id="user-123")
+
+    # Bind tools to your model
+    model = ChatOpenAI(model="gpt-4o").bind_tools(tools)
+
+Usage with memory nodes (requires langgraph)::
+
+    from hindsight_langgraph import create_recall_node, create_retain_node
+
+    recall = create_recall_node(client=client, bank_id="user-123")
+    retain = create_retain_node(client=client, bank_id="user-123")
+
+    builder.add_node("recall", recall)
+    builder.add_node("agent", agent_node)
+    builder.add_node("retain", retain)
+    builder.add_edge("recall", "agent")
+    builder.add_edge("agent", "retain")
+
+Usage with BaseStore (requires langgraph)::
+
+    from hindsight_langgraph import HindsightStore
+
+    store = HindsightStore(client=client)
+    graph = builder.compile(checkpointer=checkpointer, store=store)
+"""
+
+from .config import (
+    HindsightLangGraphConfig,
+    configure,
+    get_config,
+    reset_config,
+)
+from .errors import HindsightError
+from .tools import create_hindsight_tools
+
+
+def __getattr__(name: str):
+    """Lazy-import LangGraph-specific modules so langgraph is optional."""
+    if name == "create_recall_node" or name == "create_retain_node":
+        try:
+            from .nodes import create_recall_node, create_retain_node
+        except ImportError:
+            raise ImportError(
+                f"'{name}' requires langgraph. Install with: pip install hindsight-langgraph[langgraph]"
+            ) from None
+        return (
+            create_recall_node if name == "create_recall_node" else create_retain_node
+        )
+
+    if name == "HindsightStore":
+        try:
+            from .store import HindsightStore
+        except ImportError:
+            raise ImportError(
+                "HindsightStore requires langgraph. Install with: pip install hindsight-langgraph[langgraph]"
+            ) from None
+        return HindsightStore
+
+    raise AttributeError(f"module 'hindsight_langgraph' has no attribute {name!r}")
+
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "configure",
+    "get_config",
+    "reset_config",
+    "HindsightLangGraphConfig",
+    "HindsightError",
+    "create_hindsight_tools",
+]
+
+try:
+    import langgraph  # noqa: F401
+
+    __all__ += ["create_recall_node", "create_retain_node", "HindsightStore"]
+except ImportError:
+    pass

hindsight_langgraph-0.1.1/hindsight_langgraph/_client.py

@@ -0,0 +1,32 @@
+"""Shared Hindsight client resolution logic."""
+
+from typing import Any, Optional
+
+from hindsight_client import Hindsight
+
+from .config import get_config
+from .errors import HindsightError
+
+
+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": 30.0}
+    if key:
+        kwargs["api_key"] = key
+    return Hindsight(**kwargs)

hindsight_langgraph-0.1.1/hindsight_langgraph/config.py

@@ -0,0 +1,91 @@
+"""Global configuration for Hindsight-LangGraph 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"
+
+
+@dataclass
+class HindsightLangGraphConfig:
+    """Connection and default settings for the LangGraph 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).
+        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"
+    verbose: bool = False
+
+
+_global_config: Optional[HindsightLangGraphConfig] = 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",
+    verbose: bool = False,
+) -> HindsightLangGraphConfig:
+    """Configure Hindsight connection and default settings.
+
+    Args:
+        hindsight_api_url: Hindsight API URL (default: production).
+        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.
+        tags: Default tags for retain operations.
+        recall_tags: Default tags to filter recall/search.
+        recall_tags_match: Tag matching mode.
+        verbose: Enable verbose logging.
+
+    Returns:
+        The configured HindsightLangGraphConfig.
+    """
+    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 = HindsightLangGraphConfig(
+        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,
+        verbose=verbose,
+    )
+
+    return _global_config
+
+
+def get_config() -> Optional[HindsightLangGraphConfig]:
+    """Get the current global configuration."""
+    return _global_config
+
+
+def reset_config() -> None:
+    """Reset global configuration to None."""
+    global _global_config
+    _global_config = None

hindsight_langgraph-0.1.1/hindsight_langgraph/errors.py

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