aip-agents-binary 0.5.20__py3-none-manylinux_2_31_x86_64.whl

aip_agents/middleware/todolist.pyi

@@ -0,0 +1,125 @@
+import threading
+from _typeshed import Incomplete
+from aip_agents.middleware.base import ModelRequest as ModelRequest
+from aip_agents.utils.logger import get_logger as get_logger
+from enum import StrEnum
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, SkipValidation
+from typing import Any
+
+logger: Incomplete
+
+class TodoStatus(StrEnum):
+    """Enumeration of possible todo item statuses."""
+    PENDING: str
+    IN_PROGRESS: str
+    COMPLETED: str
+
+WRITE_TODOS_SYSTEM_PROMPT: str
+EMPTY_TODO_REMINDER: str
+
+class TodoItem(BaseModel):
+    """Represents a single todo item in the agent's plan.
+
+    Attributes:
+        content: Human-readable description of the task.
+        active_form: Short imperative phrase for UI display.
+        status: Current status of the todo item.
+    """
+    content: str
+    active_form: str
+    status: TodoStatus
+
+class TodoList(BaseModel):
+    """Represents a complete todo list for a thread.
+
+    Attributes:
+        items: List of todo items in order.
+    """
+    items: list[TodoItem]
+
+WRITE_TODOS_TOOL_DESCRIPTION: str
+
+class WriteTodosInput(BaseModel):
+    """Input schema for the write_todos tool."""
+    todos: TodoList
+
+class WriteTodosTool(BaseTool):
+    """LangChain-compatible tool for managing todo lists via TodoListMiddleware."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    storage: SkipValidation[dict[str, TodoList]]
+    storage_lock: SkipValidation[threading.RLock]
+
+class TodoListMiddleware:
+    """Middleware that provides planning capabilities via todo list management.
+
+    Adds the write_todos tool and enhances the system prompt with planning
+    instructions, encouraging agents to break down complex tasks.
+
+    This middleware maintains thread-isolated todo lists, ensuring that
+    different conversation threads don't interfere with each other.
+
+    Each middleware instance has its own storage, preventing race conditions
+    when multiple agent instances are used concurrently.
+    """
+    tools: Incomplete
+    system_prompt_additions: Incomplete
+    def __init__(self) -> None:
+        """Initialize the TodoList middleware with planning tools and instructions."""
+    def before_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Hook executed before model invocation.
+
+        Syncs todos FROM state TO internal storage for LangGraph agents.
+        This allows todos to be persisted via LangGraph checkpointer.
+
+        Args:
+            state: Current agent state (may contain 'todos' key).
+
+        Returns:
+            Empty dict (no state updates needed).
+        """
+    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
+        """Hook to modify model request before invocation.
+
+        Injects current todo list status into the system prompt, ensuring
+        the agent has visibility into its current plan on every turn.
+        This follows Claude Code's pattern of injecting system reminders.
+
+        Args:
+            request: The model request.
+            state: Current agent state.
+
+        Returns:
+            Modified request with todo status injected into system prompt.
+        """
+    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Hook executed after model invocation.
+
+        Syncs todos FROM internal storage TO state for LangGraph agents.
+        This ensures any tool updates are reflected in the checkpointed state.
+
+        Args:
+            state: Current agent state.
+
+        Returns:
+            Dict with 'todos' key containing updated TodoList, or empty dict.
+        """
+    def get_todos(self, thread_id: str = 'default') -> TodoList:
+        '''Retrieve the todo list for a specific thread.
+
+        Args:
+            thread_id: Thread identifier. Defaults to "default".
+
+        Returns:
+            TodoList for the thread, or empty list if none exists.
+        '''
+    def clear_todos(self, thread_id: str = 'default') -> None:
+        '''Clear the todo list for a specific thread.
+
+        Useful for cleanup between test runs or conversation resets.
+
+        Args:
+            thread_id: Thread identifier. Defaults to "default".
+        '''

aip_agents/schema/__init__.py

@@ -0,0 +1,69 @@
+"""Central schema package for aip_agents data models."""
+
+from aip_agents.schema.a2a import A2AEvent, A2AStreamEventType, ToolCallInfo, ToolResultInfo
+from aip_agents.schema.agent import (
+    A2AClientConfig,
+    AgentConfig,
+    BaseAgentConfig,
+    CredentialType,
+    HttpxClientOptions,
+    LangflowAgentConfig,
+    StreamMode,
+)
+from aip_agents.schema.hitl import (
+    ApprovalDecision,
+    ApprovalDecisionType,
+    ApprovalLogEntry,
+    ApprovalRequest,
+    HitlMetadata,
+)
+from aip_agents.schema.langgraph import ToolCallResult, ToolStorageParams
+from aip_agents.schema.model_id import ModelId, ModelProvider
+from aip_agents.schema.step_limit import (
+    MaxDelegationDepthExceededError,
+    MaxStepsExceededError,
+    StepLimitConfig,
+    StepLimitError,
+    StepLimitErrorResponse,
+    StepLimitErrorType,
+)
+from aip_agents.schema.storage import OBJECT_STORAGE_PREFIX, StorageConfig, StorageType
+
+__all__ = [
+    # A2A
+    "A2AEvent",
+    "A2AStreamEventType",
+    "ToolCallInfo",
+    "ToolResultInfo",
+    # Agent
+    "A2AClientConfig",
+    "AgentConfig",
+    "BaseAgentConfig",
+    "CredentialType",
+    "HttpxClientOptions",
+    "LangflowAgentConfig",
+    "StreamMode",
+    # HITL
+    "ApprovalDecision",
+    "ApprovalDecisionType",
+    "ApprovalLogEntry",
+    "ApprovalRequest",
+    "HitlMetadata",
+    # LangGraph
+    "ToolCallResult",
+    "ToolStorageParams",
+    # Model
+    "ModelId",
+    "ModelProvider",
+    # Storage
+    "OBJECT_STORAGE_PREFIX",
+    "StorageConfig",
+    "StorageType",
+    # Step Limit
+    "MaxDelegationDepthExceededError",
+    "MaxStepsExceededError",
+    "StepLimitConfig",
+    "StepLimitError",
+    "StepLimitErrorResponse",
+    "StepLimitErrorType",
+]

aip_agents/schema/__init__.pyi

@@ -0,0 +1,9 @@
+from aip_agents.schema.a2a import A2AEvent as A2AEvent, A2AStreamEventType as A2AStreamEventType, ToolCallInfo as ToolCallInfo, ToolResultInfo as ToolResultInfo
+from aip_agents.schema.agent import A2AClientConfig as A2AClientConfig, AgentConfig as AgentConfig, BaseAgentConfig as BaseAgentConfig, CredentialType as CredentialType, HttpxClientOptions as HttpxClientOptions, LangflowAgentConfig as LangflowAgentConfig, StreamMode as StreamMode
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest, HitlMetadata as HitlMetadata
+from aip_agents.schema.langgraph import ToolCallResult as ToolCallResult, ToolStorageParams as ToolStorageParams
+from aip_agents.schema.model_id import ModelId as ModelId, ModelProvider as ModelProvider
+from aip_agents.schema.step_limit import MaxDelegationDepthExceededError as MaxDelegationDepthExceededError, MaxStepsExceededError as MaxStepsExceededError, StepLimitConfig as StepLimitConfig, StepLimitError as StepLimitError, StepLimitErrorResponse as StepLimitErrorResponse, StepLimitErrorType as StepLimitErrorType
+from aip_agents.schema.storage import OBJECT_STORAGE_PREFIX as OBJECT_STORAGE_PREFIX, StorageConfig as StorageConfig, StorageType as StorageType
+
+__all__ = ['A2AEvent', 'A2AStreamEventType', 'ToolCallInfo', 'ToolResultInfo', 'A2AClientConfig', 'AgentConfig', 'BaseAgentConfig', 'CredentialType', 'HttpxClientOptions', 'LangflowAgentConfig', 'StreamMode', 'ApprovalDecision', 'ApprovalDecisionType', 'ApprovalLogEntry', 'ApprovalRequest', 'HitlMetadata', 'ToolCallResult', 'ToolStorageParams', 'ModelId', 'ModelProvider', 'OBJECT_STORAGE_PREFIX', 'StorageConfig', 'StorageType', 'MaxDelegationDepthExceededError', 'MaxStepsExceededError', 'StepLimitConfig', 'StepLimitError', 'StepLimitErrorResponse', 'StepLimitErrorType']

aip_agents/schema/a2a.py

@@ -0,0 +1,56 @@
+"""A2A event schema definitions used for agent-executor communication."""
+
+from enum import Enum
+from typing import Any
+
+from typing_extensions import TypedDict
+
+__all__ = [
+    "A2AStreamEventType",
+    "A2AEvent",
+    "ToolCallInfo",
+    "ToolResultInfo",
+]
+
+
+class A2AStreamEventType(Enum):
+    """Semantic event types for A2A agent-executor communication."""
+
+    STATUS_UPDATE = "status_update"
+    CONTENT_CHUNK = "content_chunk"
+    FINAL_RESPONSE = "final_response"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    ERROR = "error"
+    STEP_LIMIT_EXCEEDED = "step_limit_exceeded"
+
+
+class A2AEvent(TypedDict):
+    """Structured event data used by the A2A connector."""
+
+    event_type: A2AStreamEventType
+    content: str
+    metadata: dict[str, Any]
+    tool_info: dict[str, Any] | None
+    is_final: bool
+    artifacts: list[dict[str, Any]] | None
+    references: list[Any] | None
+    step_usage: dict[str, Any] | None
+    total_usage: dict[str, Any] | None
+    thinking_and_activity_info: dict[str, Any] | None
+
+
+class ToolCallInfo(TypedDict):
+    """Structured information for tool invocation events."""
+
+    tool_calls: list[dict[str, Any]]
+    status: str
+
+
+class ToolResultInfo(TypedDict):
+    """Structured information for tool completion events."""
+
+    name: str
+    args: dict[str, Any]
+    output: str
+    execution_time: float | None

aip_agents/schema/a2a.pyi

@@ -0,0 +1,40 @@
+from enum import Enum
+from typing import Any
+from typing_extensions import TypedDict
+
+__all__ = ['A2AStreamEventType', 'A2AEvent', 'ToolCallInfo', 'ToolResultInfo']
+
+class A2AStreamEventType(Enum):
+    """Semantic event types for A2A agent-executor communication."""
+    STATUS_UPDATE: str
+    CONTENT_CHUNK: str
+    FINAL_RESPONSE: str
+    TOOL_CALL: str
+    TOOL_RESULT: str
+    ERROR: str
+    STEP_LIMIT_EXCEEDED: str
+
+class A2AEvent(TypedDict):
+    """Structured event data used by the A2A connector."""
+    event_type: A2AStreamEventType
+    content: str
+    metadata: dict[str, Any]
+    tool_info: dict[str, Any] | None
+    is_final: bool
+    artifacts: list[dict[str, Any]] | None
+    references: list[Any] | None
+    step_usage: dict[str, Any] | None
+    total_usage: dict[str, Any] | None
+    thinking_and_activity_info: dict[str, Any] | None
+
+class ToolCallInfo(TypedDict):
+    """Structured information for tool invocation events."""
+    tool_calls: list[dict[str, Any]]
+    status: str
+
+class ToolResultInfo(TypedDict):
+    """Structured information for tool completion events."""
+    name: str
+    args: dict[str, Any]
+    output: str
+    execution_time: float | None

aip_agents/schema/agent.py

@@ -0,0 +1,111 @@
+"""Schema definitions for agent configuration types."""
+
+from enum import StrEnum
+from typing import Any
+
+from a2a.types import AgentCard
+from gllm_core.utils.retry import RetryConfig
+from pydantic import BaseModel, Field
+
+try:
+    # Pydantic v2 preferred config
+    from pydantic import ConfigDict  # type: ignore
+except Exception:  # pragma: no cover
+    ConfigDict = None  # type: ignore
+
+__all__ = [
+    "CredentialType",
+    "StreamMode",
+    "HttpxClientOptions",
+    "A2AClientConfig",
+    "BaseAgentConfig",
+    "AgentConfig",
+    "LangflowAgentConfig",
+]
+
+
+class CredentialType(StrEnum):
+    """Credential type enumeration for type safety and better developer experience."""
+
+    API_KEY = "api_key"
+    FILE = "file"
+    DICT = "dict"
+
+
+class StreamMode(StrEnum):
+    """LangGraph stream modes for astream operations."""
+
+    VALUES = "values"
+    CUSTOM = "custom"
+    MESSAGES = "messages"
+
+
+class HttpxClientOptions(BaseModel):
+    """Options for the HTTP client."""
+
+    timeout: float = 360.0
+    trust_env: bool = False
+    follow_redirects: bool = True
+
+    if ConfigDict is not None:
+        # Pydantic v2 style config
+        model_config = ConfigDict(extra="allow")  # type: ignore[assignment]
+    else:  # pragma: no cover
+
+        class Config:  # type: ignore[no-redef]
+            """Pydantic v1 fallback config for HttpxClientOptions."""
+
+            extra = "allow"
+
+
+class A2AClientConfig(BaseModel):
+    """Configuration for A2A client."""
+
+    discovery_urls: list[str] | None = None
+    known_agents: dict[str, AgentCard] = Field(default_factory=dict)
+    httpx_client_options: HttpxClientOptions | None = HttpxClientOptions()
+
+
+class BaseAgentConfig(BaseModel):
+    """Base configuration for agent implementations."""
+
+    tools: list[Any] | None = None
+    default_hyperparameters: dict[str, Any] | None = None
+
+    if ConfigDict is not None:
+        model_config = ConfigDict(extra="allow")  # type: ignore[assignment]
+    else:  # pragma: no cover
+
+        class Config:  # type: ignore[no-redef]
+            """Pydantic v1 fallback config for BaseAgentConfig."""
+
+            extra = "allow"
+
+
+class AgentConfig(BaseAgentConfig):
+    """Configuration for agent implementations with language model settings."""
+
+    lm_name: str | None = None
+    lm_hyperparameters: dict[str, Any] | None = None
+    lm_provider: str | None = None
+    lm_base_url: str | None = None
+    lm_api_key: str | None = None
+    lm_credentials: str | dict[str, Any] | None = None
+    lm_retry_config: RetryConfig | None = None
+
+
+class LangflowAgentConfig(BaseAgentConfig):
+    """Configuration for Langflow agent implementations."""
+
+    flow_id: str
+    base_url: str | None = None
+    api_key: str | None = None
+
+    if ConfigDict is not None:
+        model_config = ConfigDict(extra="allow")  # type: ignore[assignment]
+    else:  # pragma: no cover
+
+        class Config:  # type: ignore[no-redef]
+            """Pydantic v1 fallback config for LangflowAgentConfig."""
+
+            extra = "allow"

aip_agents/schema/agent.pyi

@@ -0,0 +1,65 @@
+from _typeshed import Incomplete
+from a2a.types import AgentCard
+from enum import StrEnum
+from gllm_core.utils.retry import RetryConfig
+from pydantic import BaseModel
+from typing import Any
+
+__all__ = ['CredentialType', 'StreamMode', 'HttpxClientOptions', 'A2AClientConfig', 'BaseAgentConfig', 'AgentConfig', 'LangflowAgentConfig']
+
+class CredentialType(StrEnum):
+    """Credential type enumeration for type safety and better developer experience."""
+    API_KEY: str
+    FILE: str
+    DICT: str
+
+class StreamMode(StrEnum):
+    """LangGraph stream modes for astream operations."""
+    VALUES: str
+    CUSTOM: str
+    MESSAGES: str
+
+class HttpxClientOptions(BaseModel):
+    """Options for the HTTP client."""
+    timeout: float
+    trust_env: bool
+    follow_redirects: bool
+    model_config: Incomplete
+    class Config:
+        """Pydantic v1 fallback config for HttpxClientOptions."""
+        extra: str
+
+class A2AClientConfig(BaseModel):
+    """Configuration for A2A client."""
+    discovery_urls: list[str] | None
+    known_agents: dict[str, AgentCard]
+    httpx_client_options: HttpxClientOptions | None
+
+class BaseAgentConfig(BaseModel):
+    """Base configuration for agent implementations."""
+    tools: list[Any] | None
+    default_hyperparameters: dict[str, Any] | None
+    model_config: Incomplete
+    class Config:
+        """Pydantic v1 fallback config for BaseAgentConfig."""
+        extra: str
+
+class AgentConfig(BaseAgentConfig):
+    """Configuration for agent implementations with language model settings."""
+    lm_name: str | None
+    lm_hyperparameters: dict[str, Any] | None
+    lm_provider: str | None
+    lm_base_url: str | None
+    lm_api_key: str | None
+    lm_credentials: str | dict[str, Any] | None
+    lm_retry_config: RetryConfig | None
+
+class LangflowAgentConfig(BaseAgentConfig):
+    """Configuration for Langflow agent implementations."""
+    flow_id: str
+    base_url: str | None
+    api_key: str | None
+    model_config: Incomplete
+    class Config:
+        """Pydantic v1 fallback config for LangflowAgentConfig."""
+        extra: str

aip_agents/schema/hitl.py

@@ -0,0 +1,157 @@
+"""Schema definitions for Human-in-the-Loop approval workflows."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "ApprovalDecisionType",
+    "ApprovalRequest",
+    "ApprovalDecision",
+    "ApprovalLogEntry",
+    "HitlMetadata",
+]
+
+
+class ApprovalDecisionType(StrEnum):
+    """Enumeration of possible approval decision types."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    SKIPPED = "skipped"
+    TIMEOUT_SKIP = "timeout_skip"
+    PENDING = "pending"
+
+
+@dataclass
+class ApprovalRequest:
+    """Represents an in-flight prompt shown to the operator."""
+
+    request_id: str
+    tool_name: str
+    arguments_preview: str
+    context: dict[str, str] | None = None
+    created_at: datetime | None = None
+    timeout_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize timestamps if not provided."""
+        if self.created_at is None:
+            self.created_at = datetime.now()
+        if self.timeout_at is None and self.created_at is not None:
+            # Timeout is set externally when configuration is available
+            pass
+
+    @classmethod
+    def create(
+        cls,
+        tool_name: str,
+        arguments_preview: str,
+        context: dict[str, str] | None = None,
+    ) -> "ApprovalRequest":
+        """Create a new approval request with generated request_id.
+
+        Args:
+            tool_name (str): The name of the tool requiring approval.
+            arguments_preview (str): A preview of the arguments for display.
+            context (dict[str, str] | None, optional): Additional context information.
+
+        Returns:
+            ApprovalRequest: A new approval request instance.
+        """
+        return cls(
+            request_id=str(uuid4()),
+            tool_name=tool_name,
+            arguments_preview=arguments_preview,
+            context=context,
+        )
+
+
+@dataclass
+class ApprovalDecision:
+    """Captures the operator outcome."""
+
+    request_id: str
+    decision: ApprovalDecisionType
+    operator_input: str
+    decided_at: datetime | None = None
+    latency_ms: int | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize timestamp if not provided."""
+        if self.decided_at is None:
+            self.decided_at = datetime.now()
+
+
+@dataclass
+class ApprovalLogEntry:
+    """Structured log entry for HITL decisions."""
+
+    request_id: str
+    tool_name: str
+    decision: str
+    event: str = "hitl_decision"
+    agent_id: str | None = None
+    thread_id: str | None = None
+    additional_context: dict[str, Any] | None = None
+    timestamp: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize timestamp if not provided."""
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+
+
+class HitlMetadata(BaseModel):
+    """Structured metadata payload included in agent streaming events."""
+
+    required: bool = Field(default=True)
+    decision: ApprovalDecisionType
+    request_id: str
+    timeout_seconds: int | None = Field(default=None, ge=0)
+    timeout_at: datetime | None = None
+
+    model_config = ConfigDict(extra="forbid", use_enum_values=True)
+
+    def as_payload(self) -> dict[str, Any]:
+        """Return a JSON-ready metadata payload."""
+        payload = self.model_dump(mode="json", exclude_none=True)
+
+        # Pydantic emits UTC datetimes as Zulu strings when dumping to JSON.
+        # Preserve the canonical ``+00:00`` suffix expected by downstream tests.
+        if "timeout_at" in payload and isinstance(self.timeout_at, datetime):
+            payload["timeout_at"] = self.timeout_at.isoformat()
+
+        return payload
+
+    @classmethod
+    def from_decision(
+        cls,
+        decision: ApprovalDecision,
+        *,
+        required: bool = True,
+        timeout_seconds: int | None = None,
+        timeout_at: datetime | None = None,
+    ) -> "HitlMetadata":
+        """Build metadata from an ``ApprovalDecision``.
+
+        Args:
+            decision (ApprovalDecision): The approval decision to build metadata from.
+            required (bool, optional): Whether approval is required. Defaults to True.
+            timeout_seconds (int | None, optional): Timeout in seconds for the decision.
+            timeout_at (datetime | None, optional): Specific timeout datetime.
+
+        Returns:
+            HitlMetadata: The constructed metadata instance.
+        """
+        return cls(
+            required=required,
+            decision=decision.decision,
+            request_id=decision.request_id,
+            timeout_seconds=timeout_seconds,
+            timeout_at=timeout_at,
+        )