greennode-agent-bridge 1.0.1__py3-none-any.whl

greennode_agent_bridge/__init__.py

@@ -0,0 +1,34 @@
+"""GreenNode Agent Bridge - Connect agent frameworks with GreenNode AgentBase.
+
+This package provides adaptors for various agent frameworks (LangGraph, CrewAI, etc.)
+to work with GreenNode AgentBase Memory and Runtime services.
+"""
+
+__version__ = "0.1.0"
+
+# Conditional imports for optional dependencies
+try:
+    from greennode_agent_bridge.langgraph.memory import (
+        AgentBaseMemoryEvents,
+        AgentBaseMemoryRecords,
+    )
+
+    __all__ = [
+        "AgentBaseMemoryEvents",
+        "AgentBaseMemoryRecords",
+    ]
+except ImportError as e:
+    # Store the import error for later use
+    _import_error = e
+    __all__ = []
+
+    # Provide helpful error message when optional dependencies are missing
+    def _missing_langgraph_dependencies_error(*args, **kwargs):
+        raise ImportError(
+            "LangGraph functionality requires optional dependencies. "
+            "Install them with: pip install 'greennode-agent-bridge[langgraph]'"
+        ) from _import_error
+
+    # Create placeholder classes that raise helpful error
+    AgentBaseMemoryEvents = _missing_langgraph_dependencies_error  # type: ignore[assignment]
+    AgentBaseMemoryRecords = _missing_langgraph_dependencies_error  # type: ignore[assignment]

greennode_agent_bridge/langgraph/__init__.py

@@ -0,0 +1,21 @@
+"""LangGraph adaptor for GreenNode AgentBase.
+
+This package provides adaptors for LangGraph to work with GreenNode AgentBase.
+"""
+
+# Re-export from memory submodule for backward compatibility and convenience
+try:
+    from greennode_agent_bridge.langgraph.memory import (
+        AgentBaseMemoryEvents,
+        AgentBaseMemoryRecords,
+        langgraph_available,
+    )
+
+    __all__ = [
+        "AgentBaseMemoryEvents",
+        "AgentBaseMemoryRecords",
+        "langgraph_available",
+    ]
+except ImportError:
+    # If memory module is not available, provide empty exports
+    __all__ = []

greennode_agent_bridge/langgraph/memory/__init__.py

@@ -0,0 +1,38 @@
+"""LangGraph Memory adaptor for GreenNode AgentBase.
+
+This module provides checkpoint saver and store implementations for LangGraph
+using GreenNode AgentBase Memory.
+"""
+
+from typing import Any
+
+# Store the import error for later use
+_import_error: ImportError | None = None
+
+# Conditional imports for optional dependencies
+try:
+    from greennode_agent_bridge.langgraph.memory.events import AgentBaseMemoryEvents
+    from greennode_agent_bridge.langgraph.memory.records import AgentBaseMemoryRecords
+
+    langgraph_available = True
+except ImportError as e:
+    # Store the error for later use
+    _import_error = e
+    langgraph_available = False
+
+    # If dependencies are not available, provide helpful error message
+    def _missing_langgraph_dependencies_error(*args: Any, **kwargs: Any) -> Any:
+        raise ImportError(
+            "LangGraph functionality requires optional dependencies. "
+            "Install them with: pip install 'greennode-agent-bridge[langgraph]'"
+        ) from _import_error
+
+    # Create placeholder classes that raise helpful error
+    AgentBaseMemoryEvents: type[Any] = _missing_langgraph_dependencies_error  # type: ignore[assignment,no-redef]
+    AgentBaseMemoryRecords: type[Any] = _missing_langgraph_dependencies_error  # type: ignore[assignment,no-redef]
+
+__all__ = [
+    "AgentBaseMemoryEvents",
+    "AgentBaseMemoryRecords",
+    "langgraph_available",
+]

greennode_agent_bridge/langgraph/memory/constants.py

@@ -0,0 +1,27 @@
+"""Constants and exceptions for AgentBase Memory Checkpoint Saver."""
+
+EMPTY_CHANNEL_VALUE = "_empty"
+
+
+class AgentBaseMemoryError(Exception):
+    """Base exception for AgentBase Memory errors."""
+
+    pass
+
+
+class EventDecodingError(AgentBaseMemoryError):
+    """Raised when event decoding fails."""
+
+    pass
+
+
+class InvalidConfigError(AgentBaseMemoryError):
+    """Raised when configuration is invalid."""
+
+    pass
+
+
+class EventNotFoundError(AgentBaseMemoryError):
+    """Raised when expected event is not found."""
+
+    pass

greennode_agent_bridge/langgraph/memory/events.py

@@ -0,0 +1,349 @@
+"""AgentBase Memory Checkpoint Saver implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Any, TypeAlias, cast
+
+from langchain_core.runnables import RunnableConfig, run_in_executor
+from langgraph.checkpoint.base import (
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    SerializerProtocol,
+    get_checkpoint_id,
+    get_checkpoint_metadata,
+)
+
+from greennode_agent_bridge.langgraph.memory.constants import (
+    EMPTY_CHANNEL_VALUE,
+    InvalidConfigError,
+)
+from greennode_agent_bridge.langgraph.memory.helpers import (
+    DEFAULT_INITIAL_BACKOFF,
+    DEFAULT_MAX_BACKOFF,
+    DEFAULT_MAX_RETRIES,
+    AgentBaseEventClient,
+    EventProcessor,
+    EventSerializer,
+)
+from greennode_agent_bridge.langgraph.memory.models import (
+    ChannelDataEvent,
+    CheckpointerConfig,
+    CheckpointEvent,
+    WriteItem,
+    WritesEvent,
+)
+
+RunnableConfigDict: TypeAlias = dict[str, Any]
+
+
+class AgentBaseMemoryEvents(BaseCheckpointSaver[str]):
+    """
+    AgentBase Memory checkpoint saver.
+
+    This saver persists Checkpoints as serialized blob events in AgentBase Memory.
+
+    Args:
+        memory_id: the ID of the memory resource created in AgentBase Memory
+        serde: serialization protocol to be used. Defaults to JSONPlusSerializer
+        limit: maximum number of events to parse from ListEvents.
+        max_results: maximum number of results to retrieve from AgentBase Memory.
+        max_retries: maximum number of retry attempts for retryable errors.
+        initial_backoff: initial backoff time in seconds for exponential backoff.
+        max_backoff: maximum backoff time in seconds.
+        memory_client: Optional MemoryClient instance. If not provided, creates a new one.
+    """
+
+    def __init__(
+        self,
+        memory_id: str,
+        *,
+        serde: SerializerProtocol | None = None,
+        limit: int | None = None,
+        max_results: int | None = 100,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        initial_backoff: float = DEFAULT_INITIAL_BACKOFF,
+        max_backoff: float = DEFAULT_MAX_BACKOFF,
+        memory_client: Any | None = None,
+    ) -> None:
+        super().__init__(serde=serde)
+
+        self.memory_id = memory_id
+        self.limit = limit
+        self.max_results = max_results
+        self.serializer = EventSerializer(self.serde)
+        self.checkpoint_event_client = AgentBaseEventClient(
+            memory_id,
+            self.serializer,
+            memory_client=memory_client,
+            max_retries=max_retries,
+            initial_backoff=initial_backoff,
+            max_backoff=max_backoff,
+        )
+        self.processor = EventProcessor()
+
+    def get_tuple(
+        self,
+        config: RunnableConfig,
+    ) -> CheckpointTuple | None:
+        """Get a checkpoint tuple from AgentBase Memory.
+
+        Args:
+            config: The runnable config containing checkpoint information
+
+        Returns:
+            CheckpointTuple if found, None otherwise
+        """
+
+        # TODO: There is room for caching here on the client side
+
+        checkpoint_config = CheckpointerConfig.from_runnable_config(
+            RunnableConfigDict(config)
+        )
+
+        events = self.checkpoint_event_client.get_events(
+            checkpoint_config.session_id,
+            checkpoint_config.actor_id,
+            self.limit,
+            self.max_results,
+        )
+
+        checkpoints, writes_by_checkpoint, channel_data = self.processor.process_events(
+            events
+        )
+
+        if not checkpoints:
+            return None
+
+        # Find the specific checkpoint if `checkpoint_id` is provided or return the latest one
+        if checkpoint_config.checkpoint_id:
+            checkpoint_event = checkpoints.get(checkpoint_config.checkpoint_id)
+            if not checkpoint_event:
+                return None
+        else:
+            latest_checkpoint_id = max(checkpoints.keys())
+            checkpoint_event = checkpoints[latest_checkpoint_id]
+
+        # Build and return checkpoint tuple
+        writes = writes_by_checkpoint.get(checkpoint_event.checkpoint_id, [])
+        return self.processor.build_checkpoint_tuple(
+            checkpoint_event, writes, channel_data, checkpoint_config
+        )
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        """List checkpoints from AgentBase Memory."""
+
+        # TODO: There is room for caching here on the client side
+
+        checkpoint_config = CheckpointerConfig.from_runnable_config(
+            RunnableConfigDict(config) if config else {}
+        )
+        config_checkpoint_id = get_checkpoint_id(config) if config else None
+
+        events = self.checkpoint_event_client.get_events(
+            checkpoint_config.session_id,
+            checkpoint_config.actor_id,
+            limit,
+            self.max_results,
+        )
+
+        checkpoints, writes_by_checkpoint, channel_data = self.processor.process_events(
+            events
+        )
+
+        # Build and yield CheckpointTuples
+        count = 0
+        before_checkpoint_id = get_checkpoint_id(before) if before else None
+
+        # Sort checkpoints by ID in descending order (most recent first)
+        for checkpoint_id in sorted(checkpoints.keys(), reverse=True):
+            checkpoint_event = checkpoints[checkpoint_id]
+            # Apply filters
+            if config_checkpoint_id and checkpoint_id != config_checkpoint_id:
+                continue
+
+            if before_checkpoint_id and checkpoint_id >= before_checkpoint_id:
+                continue
+
+            if limit is not None and count >= limit:
+                break
+
+            writes = writes_by_checkpoint.get(checkpoint_id, [])
+
+            yield self.processor.build_checkpoint_tuple(
+                checkpoint_event, writes, channel_data, checkpoint_config
+            )
+
+            count += 1
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        """Save a checkpoint to AgentBase Memory."""
+        checkpoint_config = CheckpointerConfig.from_runnable_config(
+            RunnableConfigDict(config)
+        )
+
+        # Extract channel values
+        checkpoint_copy = dict(checkpoint)
+        channel_values: dict[str, Any] = {}
+        if "channel_values" in checkpoint_copy:
+            channel_values_obj = checkpoint_copy.pop("channel_values")
+            if isinstance(channel_values_obj, dict):
+                channel_values = channel_values_obj.copy()
+
+        # Create all events to be stored in a single batch
+        events_to_store: list[CheckpointEvent | ChannelDataEvent | WritesEvent] = []
+
+        # Create channel data events
+        for channel, version in new_versions.items():
+            channel_event = ChannelDataEvent(
+                channel=channel,
+                version=str(version),
+                value=channel_values.get(channel, EMPTY_CHANNEL_VALUE),
+                thread_id=checkpoint_config.thread_id,
+                checkpoint_ns=checkpoint_config.checkpoint_ns,
+            )
+            events_to_store.append(channel_event)
+
+        checkpoint_event = CheckpointEvent(
+            checkpoint_id=checkpoint["id"],
+            checkpoint_data=checkpoint_copy,
+            metadata=dict(get_checkpoint_metadata(config, metadata)),
+            parent_checkpoint_id=checkpoint_config.checkpoint_id,
+            thread_id=checkpoint_config.thread_id,
+            checkpoint_ns=checkpoint_config.checkpoint_ns,
+        )
+        events_to_store.append(checkpoint_event)
+        typed_events = cast(
+            list[CheckpointEvent | ChannelDataEvent | WritesEvent], events_to_store
+        )
+        self.checkpoint_event_client.store_blob_events_batch(
+            typed_events, checkpoint_config.session_id, checkpoint_config.actor_id
+        )
+
+        return {
+            "configurable": {
+                "thread_id": checkpoint_config.thread_id,
+                "actor_id": checkpoint_config.actor_id,
+                "checkpoint_ns": checkpoint_config.checkpoint_ns,
+                "checkpoint_id": checkpoint["id"],
+            }
+        }
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        """Save pending writes to AgentBase Memory."""
+        checkpoint_config = CheckpointerConfig.from_runnable_config(
+            RunnableConfigDict(config)
+        )
+
+        if not checkpoint_config.checkpoint_id:
+            raise InvalidConfigError("checkpoint_id is required for put_writes")
+
+        # Create write items
+        write_items = [
+            WriteItem(
+                task_id=task_id,
+                channel=channel,
+                value=value,
+                task_path=task_path,
+            )
+            for channel, value in writes
+        ]
+
+        writes_event = WritesEvent(
+            checkpoint_id=checkpoint_config.checkpoint_id,
+            writes=write_items,
+        )
+
+        self.checkpoint_event_client.store_blob_event(
+            writes_event, checkpoint_config.session_id, checkpoint_config.actor_id
+        )
+
+    def delete_thread(self, thread_id: str, actor_id: str = "") -> None:
+        """Delete all checkpoints and writes associated with a thread."""
+        self.checkpoint_event_client.delete_events(thread_id, actor_id)
+
+    # ===== Async methods (Running sync methods inside executor ) =====
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        return await run_in_executor(None, self.get_tuple, config)
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        loop = asyncio.get_running_loop()
+
+        def _sync_list():
+            return list(self.list(config, filter=filter, before=before, limit=limit))
+
+        items = await loop.run_in_executor(None, _sync_list)
+        for item in items:
+            yield item
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        return await run_in_executor(
+            None, self.put, config, checkpoint, metadata, new_versions
+        )
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        return await run_in_executor(
+            None, self.put_writes, config, writes, task_id, task_path
+        )
+
+    async def adelete_thread(self, thread_id: str, actor_id: str = "") -> None:
+        await run_in_executor(None, self.delete_thread, thread_id, actor_id)
+        return None
+
+    def get_next_version(
+        self, current: str | int | None, channel: str | None = None
+    ) -> str:
+        """Generate next version string."""
+        if current is None:
+            current_v = 0
+        elif isinstance(current, int):
+            current_v = current
+        else:
+            current_v = int(current.split(".")[0])
+
+        next_v = current_v + 1
+        next_h = random.random()
+        return f"{next_v:032}.{next_h:016}"