aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/agent/google_adk_constants.py

@@ -0,0 +1,11 @@
+"""Shared constants for Google ADK agent integrations."""
+
+# Default authentication URL presented when the ADK agent requires auth.
+DEFAULT_AUTH_URL = "https://auth.example.com"
+
+GOOGLE_ADK_IMPORT_ERROR_MESSAGE = (
+    'Google ADK support requires the optional dependency. Install with: pip install "aip-agents[google-adk]" '
+    'or "aip-agents[google]" for the umbrella extra'
+)
+
+__all__ = ["DEFAULT_AUTH_URL", "GOOGLE_ADK_IMPORT_ERROR_MESSAGE"]

aip_agents/agent/graph_runtime.py

@@ -0,0 +1,185 @@
+"""Internal LangGraph runtime mechanics for agent graph execution.
+
+Author: Ema
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import AsyncGenerator, Callable
+from typing import Annotated, Any
+
+from langchain_core.messages import BaseMessage
+from langgraph.graph import StateGraph
+from langgraph.graph.message import add_messages
+from langgraph.graph.state import CompiledStateGraph
+from langgraph.types import Checkpointer
+from typing_extensions import TypedDict
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+CONFIGURABLE_KEY: str = "configurable"
+RUNNABLE_CONFIG_KEYS: frozenset[str] = frozenset(
+    {"recursion_limit", "tags", "metadata", "run_name", "max_concurrency", "run_id", "callbacks"}
+)
+
+
+class GraphRuntime:
+    """Small internal seam for LangGraph config, compile, invoke, and stream calls."""
+
+    def __init__(
+        self,
+        *,
+        agent_name: Callable[[], str],
+        thread_id_key: Callable[[], str | None],
+        graph_config: Callable[[], dict[str, Any]],
+        recursion_limit: Callable[[], int | None],
+        effective_recursion_limit: Callable[[], int | Callable[[], int]],
+        logger_: Any | None = None,
+    ) -> None:
+        """Initialize the runtime with live accessors for mutable agent state."""
+        self._agent_name = agent_name
+        self._thread_id_key = thread_id_key
+        self._graph_config = graph_config
+        self._recursion_limit = recursion_limit
+        self._effective_recursion_limit = effective_recursion_limit
+        self._logger = logger_ or logger
+
+    def build_and_compile_graph(
+        self,
+        state_schema: type | None,
+        define_graph: Callable[[StateGraph], CompiledStateGraph],
+    ) -> CompiledStateGraph:
+        """Build a graph builder and let the agent define/compile its topology."""
+        if state_schema:
+            graph_builder: StateGraph = StateGraph(state_schema)
+        else:
+
+            class DefaultAgentState(TypedDict):
+                messages: Annotated[list[BaseMessage], add_messages]
+
+            graph_builder = StateGraph(DefaultAgentState)
+
+        return define_graph(graph_builder)
+
+    def compile_graph(
+        self, graph_builder: StateGraph, *, checkpointer: Checkpointer | None = None
+    ) -> CompiledStateGraph:
+        """Compile a configured graph builder with optional checkpointing."""
+        return graph_builder.compile(checkpointer=checkpointer)
+
+    def resolve_configurable(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Return a copied configurable dict with a guaranteed thread ID entry."""
+        configurable = kwargs.get(CONFIGURABLE_KEY, {}).copy()
+        key = self._thread_id_key() or "thread_id"
+        if key not in configurable:
+            configurable[key] = str(uuid.uuid4())
+            self._logger.info("Agent '%s': Generated new thread ID: %s", self._agent_name(), configurable[key])
+        return configurable
+
+    def build_config_metadata(self, kwargs: dict[str, Any]) -> dict[str, Any] | None:
+        """Build config metadata from graph_config, per-call metadata, and internal keys."""
+        baseline_metadata = self._graph_config().get("metadata")
+        per_call_metadata = kwargs.get("metadata")
+        pii_mapping = kwargs.get("pii_mapping")
+        memory_user_id = kwargs.get("memory_user_id")
+
+        if baseline_metadata is None and per_call_metadata is None and pii_mapping is None and memory_user_id is None:
+            return None
+
+        if per_call_metadata is not None:
+            result: dict[str, Any] = dict(per_call_metadata)
+        elif baseline_metadata is not None:
+            result = dict(baseline_metadata)
+        else:
+            result = {}
+
+        if pii_mapping is not None:
+            result["pii_mapping"] = pii_mapping
+        if memory_user_id is not None:
+            result["memory_user_id"] = memory_user_id
+
+        return result
+
+    def apply_config_layers(self, config: dict[str, Any], kwargs: dict[str, Any]) -> None:
+        """Apply construction-time and per-call config layers onto ``config`` in place."""
+        for key, value in self._graph_config().items():
+            if key not in (CONFIGURABLE_KEY, "metadata"):
+                config[key] = value
+
+        if self._recursion_limit() is not None or "recursion_limit" not in config:
+            config["recursion_limit"] = self._resolve_effective_recursion_limit()
+
+        for runnable_key in RUNNABLE_CONFIG_KEYS:
+            if runnable_key == "metadata":
+                continue
+            call_value = kwargs.get(runnable_key)
+            if call_value is not None:
+                config[runnable_key] = call_value
+
+    def create_graph_config(self, **kwargs: Any) -> dict[str, Any]:
+        """Assemble a RunnableConfig-compatible dict for graph invocation."""
+        config: dict[str, Any] = {CONFIGURABLE_KEY: self.resolve_configurable(kwargs)}
+        self.apply_config_layers(config, kwargs)
+        config_metadata = self.build_config_metadata(kwargs)
+        if config_metadata is not None:
+            config["metadata"] = config_metadata
+        self._log_resolved_config(config)
+        return config
+
+    def get_thread_id_from_config(self, config: dict[str, Any]) -> str | None:
+        """Extract the current thread ID from graph config."""
+        configurable = config.get(CONFIGURABLE_KEY, {})
+        key = self._thread_id_key() or "thread_id"
+        return configurable.get(key)
+
+    async def invoke(
+        self,
+        compiled_graph: CompiledStateGraph,
+        graph_input: dict[str, Any],
+        config: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Invoke a compiled graph once."""
+        return await compiled_graph.ainvoke(graph_input, config=config)
+
+    async def stream_events(
+        self,
+        compiled_graph: CompiledStateGraph,
+        graph_input: dict[str, Any],
+        config: dict[str, Any],
+    ) -> AsyncGenerator[Any, None]:
+        """Stream LangGraph v2 events from a compiled graph."""
+        async for event in compiled_graph.astream_events(graph_input, config=config, version="v2"):
+            yield event
+
+    async def stream(
+        self,
+        compiled_graph: CompiledStateGraph,
+        graph_input: dict[str, Any],
+        config: dict[str, Any],
+        stream_modes: list[str],
+    ) -> AsyncGenerator[Any, None]:
+        """Stream graph items using the requested LangGraph stream modes."""
+        async for item in compiled_graph.astream(graph_input, config=config, stream_mode=stream_modes):
+            yield item
+
+    def _resolve_effective_recursion_limit(self) -> int:
+        value = self._effective_recursion_limit()
+        if callable(value):
+            value = value()
+        return value
+
+    def _log_resolved_config(self, config: dict[str, Any]) -> None:
+        log_config = {key: value for key, value in config.items() if key != CONFIGURABLE_KEY}
+        if "metadata" in log_config and isinstance(log_config["metadata"], dict):
+            log_config["metadata"] = {
+                key: (f"<{len(value)} items>" if key == "pii_mapping" and isinstance(value, dict) else value)
+                for key, value in log_config["metadata"].items()
+            }
+        self._logger.debug(
+            "[%s] graph config resolved: %s",
+            self._agent_name(),
+            log_config,
+        )

aip_agents/agent/hitl/__init__.py

@@ -0,0 +1,24 @@
+"""Human-in-the-Loop (HITL) approval system for LangGraph tools.
+
+This package provides components for intercepting tool calls and requiring
+human approval before execution. It includes configuration, models, approval
+management, and prompt handlers for deferred approval flows.
+
+Author:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from aip_agents.agent.hitl.config import ToolApprovalConfig
+from aip_agents.agent.hitl.manager import ApprovalManager
+from aip_agents.agent.hitl.prompt import BasePromptHandler, DeferredPromptHandler
+from aip_agents.schema.hitl import ApprovalDecision, ApprovalLogEntry, ApprovalRequest
+
+__all__ = [
+    "ToolApprovalConfig",
+    "ApprovalManager",
+    "ApprovalDecision",
+    "ApprovalLogEntry",
+    "ApprovalRequest",
+    "BasePromptHandler",
+    "DeferredPromptHandler",
+]

aip_agents/agent/hitl/config.py

@@ -0,0 +1,28 @@
+"""HITL configuration dataclasses.
+
+This module defines configuration structures for Human-in-the-Loop approval settings.
+
+Author:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ToolApprovalConfig:
+    """Configuration for HITL approval behavior attached to a tool.
+
+    Supplying this configuration marks the tool as requiring approval. Only the
+    timeout is configurable; timeouts always result in a safe skip.
+
+    Attributes:
+        timeout_seconds: Defaults to 300; must be >0.
+    """
+
+    timeout_seconds: int = 300
+
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        if self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be > 0")