aip-agents-binary 0.6.3__py3-none-any.whl → 0.6.5__py3-none-any.whl

aip_agents/memory/adapters/base_adapter.pyi

@@ -1,150 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.memory.base import BaseMemory as BaseMemory
-from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
-from aip_agents.types import ChatMessage as ChatMessage
-from aip_agents.utils.datetime import format_created_updated_label as format_created_updated_label
-from aip_agents.utils.logger import get_logger as get_logger
-from concurrent.futures import Future
-from dataclasses import dataclass
-from gllm_memory import MemoryManager
-from gllm_memory.enums import MemoryScope
-from typing import Any, ClassVar
-
-MemoryManager = Any
-MemoryScope = Any
-logger: Incomplete
-DEFAULT_SCOPE: ClassVar[set[MemoryScope]]
-
-@dataclass(frozen=True)
-class _RetrieveOptions:
-    user_id: str
-    top_k: int
-    metadata: dict[str, str] | None
-    keywords: Any
-    page: int
-    categories: list[str] | None
-
-class _AsyncRunner:
-    """Runs async coroutines on a dedicated background event loop."""
-    def __init__(self) -> None: ...
-    def run(self, awaitable: Any) -> Any:
-        """Execute an awaitable on the background loop and block for the result.
-
-        Args:
-            awaitable: The coroutine to execute.
-
-        Returns:
-            The result of the coroutine execution.
-        """
-    def shutdown(self, timeout: float | None = 5.0) -> None:
-        """Gracefully stop the event loop thread.
-
-        Args:
-            timeout: Maximum time to wait for the thread to stop.
-        """
-    def __del__(self) -> None: ...
-
-class BaseMemoryAdapter(BaseMemory):
-    """Provider-agnostic long-term memory adapter backed by gllm_memory."""
-    agent_id: Incomplete
-    namespace: Incomplete
-    limit: Incomplete
-    max_chars: Incomplete
-    def __init__(self, *, agent_id: str, manager: MemoryManager, namespace: str | None = None, limit: int = ..., max_chars: int = ...) -> None:
-        """Initialize the GLLM memory adapter.
-
-        Args:
-            agent_id: Unique identifier for the agent using this memory.
-            manager: Configured gllm_memory MemoryManager instance.
-            namespace: Optional namespace for organizing memories.
-            limit: Maximum number of memories to retrieve in search operations.
-            max_chars: Maximum character length for text content.
-        """
-    @classmethod
-    def validate_env(cls) -> None:
-        """Base adapter does not enforce environment validation."""
-    def get_messages(self) -> list[ChatMessage]:
-        """Retrieve all stored chat messages.
-
-        Returns:
-            An empty list as GLLM adapter doesn't support message retrieval.
-        """
-    def add_message(self, message: ChatMessage) -> None:
-        """Best-effort single-message persistence for API parity.
-
-        Args:
-            message: The chat message to add to memory.
-        """
-    def clear(self) -> None:
-        """Clear all stored memories.
-
-        Raises:
-            NotImplementedError: This method is not implemented for GLLM adapter.
-        """
-    def search(self, query: str, *, user_id: str, limit: int | None = None, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
-        """Search for memories using a text query.
-
-        Args:
-            query: The search query string.
-            user_id: User identifier for the search scope.
-            limit: Maximum number of results to return.
-            filters: Optional filters to apply to the search.
-
-        Returns:
-            List of memory hits matching the search criteria.
-        """
-    def retrieve(self, *, query: str | None, user_id: str, limit: int | None = None, filters: dict[str, Any] | None = None, page: int | None = None) -> list[dict[str, Any]]:
-        """Retrieve memories with optional search query and filters.
-
-        Args:
-            query: Optional search query string. If None, retrieves all memories.
-            user_id: User identifier for the retrieval scope.
-            limit: Maximum number of results to return.
-            filters: Optional filters to apply to the retrieval.
-            page: Page number for pagination.
-
-        Returns:
-            List of memory hits matching the criteria.
-        """
-    def save_interaction(self, *, user_text: str, ai_text: str, user_id: str) -> None:
-        """Save a user-AI interaction as memories.
-
-        Args:
-            user_text: The user's input text.
-            ai_text: The AI's response text.
-            user_id: User identifier for the memory storage.
-        """
-    def save_interaction_async(self, *, user_text: str, ai_text: str, user_id: str) -> Future[Any]:
-        """Schedule save_interaction without blocking the caller.
-
-        Args:
-            user_text: The user's input text to save.
-            ai_text: The AI's response text to save.
-            user_id: User identifier for the memory storage.
-        """
-    def format_hits(self, hits: list[dict[str, Any]], max_items: int = ..., with_tag: bool = True) -> str:
-        """Format memory hits into a readable string.
-
-        Args:
-            hits: List of memory hit dictionaries to format.
-            max_items: Maximum number of hits to include in the output.
-            with_tag: Whether to wrap the output with memory tags.
-
-        Returns:
-            Formatted string representation of the memory hits.
-        """
-    def flush_pending_writes(self, timeout: float | None = None) -> None:
-        """Block until current async writes complete.
-
-        Args:
-            timeout: Maximum time to wait for pending writes to complete.
-        """
-    def close(self, *, wait: bool = True, timeout: float | None = None) -> None:
-        """Release background resources and optionally wait for pending saves.
-
-        Args:
-            wait: Whether to wait for pending async operations to complete.
-            timeout: Maximum time to wait when wait=True.
-        """
-    def __del__(self) -> None:
-        """Clean up resources when the adapter is garbage collected."""

aip_agents/memory/adapters/mem0.pyi

@@ -1,22 +0,0 @@
-from aip_agents.memory.adapters.base_adapter import BaseMemoryAdapter as BaseMemoryAdapter
-from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
-from typing import Any
-
-MemoryManager = Any
-
-class Mem0Memory(BaseMemoryAdapter):
-    """Mem0-backed long-term memory adapter using the gllm_memory SDK."""
-    def __init__(self, *, agent_id: str, namespace: str | None = None, limit: int = ..., max_chars: int = ..., host: str | None = None, instruction: str | None = None) -> None:
-        """Initialize the Mem0 memory adapter.
-
-        Args:
-            agent_id: Unique identifier for the agent using this memory.
-            namespace: Optional namespace for organizing memories.
-            limit: Maximum number of memories to retrieve in search operations.
-            max_chars: Maximum character length for text content.
-            host: Optional host URL for the Mem0 service.
-            instruction: Optional instruction text for memory operations.
-        """
-    @classmethod
-    def validate_env(cls) -> None:
-        """Ensure the Mem0 API key is available."""

aip_agents/memory/base.pyi

@@ -1,60 +0,0 @@
-from abc import ABC, abstractmethod
-from aip_agents.types import ChatMessage as ChatMessage
-from collections.abc import Sequence
-from typing import Any
-
-class BaseMemory(ABC):
-    """Base class for agent memory.
-
-    This concrete base class provides a default structure. Subclasses
-    can inherit from this class to implement specific memory management
-    behaviors.
-    """
-    @classmethod
-    def validate_env(cls) -> None:
-        """Validate environment prerequisites for a memory backend.
-
-        This hook allows memory implementations to fail fast when required
-        environment variables or credentials are missing. Default is a no-op.
-        """
-    @abstractmethod
-    def get_messages(self) -> list[ChatMessage]:
-        """Retrieve a list of messages.
-
-        Returns:
-            List[ChatMessage]: A list of messages in a generic format.
-        """
-    @abstractmethod
-    def add_message(self, message: ChatMessage) -> None:
-        """Add a message to the memory.
-
-        Adds a single ChatMessage to the memory storage. The exact implementation
-        depends on the specific memory backend.
-
-        Args:
-            message: The ChatMessage object to add to memory. The message should
-                contain role and content information.
-        """
-    def add_messages(self, messages: Sequence[ChatMessage]) -> None:
-        """Add multiple messages to the memory.
-
-        Args:
-            messages: A sequence of ChatMessage objects to add.
-        """
-    @abstractmethod
-    def clear(self) -> None:
-        """Clears the memory or resets the state of the agent.
-
-        This method must be implemented to define the specific behavior
-        for clearing or resetting the memory of the agent.
-        """
-    def get_memory_variables(self) -> dict[str, Any]:
-        """Retrieve memory variables.
-
-        This method returns a dictionary containing memory-related variables.
-        The default implementation returns a dictionary with chat_history.
-
-        Returns:
-            Dict[str, Any]: A dictionary where keys are variable names and values
-            are the corresponding memory-related data.
-        """

aip_agents/memory/constants.pyi

@@ -1,25 +0,0 @@
-from _typeshed import Incomplete
-
-class MemoryMethod:
-    """Constants for memory method names used in hasattr checks."""
-    SEARCH: str
-    SAVE_INTERACTION: str
-    FORMAT_HITS: str
-
-class MemoryDefaults:
-    """Default values for memory configuration parameters."""
-    MAX_ITEMS: int
-    RETRIEVAL_LIMIT: int
-    MAX_CHARS: int
-    LOG_PREVIEW_LENGTH: int
-    SMALL_PREVIEW_LENGTH: int
-    AGENT_ID_PREFIX: str
-    MEMORY_TAG_OPEN: str
-    MEMORY_TAG_CLOSE: str
-    DEFAULT_USER_ID: str
-    DATE_STRING_LENGTH: int
-
-class MemoryBackends:
-    """Supported memory backend identifiers."""
-    MEM0: str
-    SUPPORTED: Incomplete

aip_agents/memory/factory.pyi

@@ -1,24 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.memory.base import BaseMemory as BaseMemory
-from aip_agents.utils.logger import get_logger as get_logger
-from typing import Any
-
-logger: Incomplete
-BACKENDS: Incomplete
-
-class MemoryFactory:
-    """Factory to build concrete memory adapters by backend name."""
-    @staticmethod
-    def create(backend: str, **kwargs: Any) -> BaseMemory:
-        '''Create a memory adapter instance.
-
-        Args:
-            backend: Backend identifier (e.g., "mem0").
-            **kwargs: Keyword args passed to adapter constructor (e.g., limit, max_chars, namespace).
-
-        Returns:
-            BaseMemory: A constructed memory adapter instance.
-
-        Raises:
-            ValueError: If backend is unknown or adapter can\'t be constructed.
-        '''

aip_agents/memory/guidance.pyi

@@ -1,3 +0,0 @@
-from _typeshed import Incomplete
-
-MEM0_MEMORY_RECALL_GUIDANCE: Incomplete

aip_agents/memory/simple_memory.pyi

@@ -1,23 +0,0 @@
-from aip_agents.memory.base import BaseMemory as BaseMemory, ChatMessage as ChatMessage
-
-class SimpleMemory(BaseMemory):
-    """A simple memory implementation that stores messages in a list."""
-    messages: list[ChatMessage]
-    def __init__(self) -> None:
-        """Initialize the SimpleMemory instance with an empty message list."""
-    def add_message(self, message_or_role, content=None) -> None:
-        '''Add a message to memory.
-
-        Supports two calling patterns for backward compatibility:
-        1. add_message(ChatMessage) - Adds a ChatMessage object directly
-        2. add_message(role, content) - Creates and adds a ChatMessage with the given role and content
-
-        Args:
-            message_or_role: Either a ChatMessage object or a string role (e.g., "user", "assistant").
-            content: Optional content string when using the role+content pattern.
-                Required when message_or_role is a string role.
-        '''
-    def get_messages(self) -> list[ChatMessage]:
-        """Get all messages from memory."""
-    def clear(self) -> None:
-        """Clear all messages from memory."""

aip_agents/middleware/__init__.pyi

@@ -1,5 +0,0 @@
-from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
-from aip_agents.middleware.manager import MiddlewareManager as MiddlewareManager
-from aip_agents.middleware.todolist import TodoListMiddleware as TodoListMiddleware, TodoStatus as TodoStatus
-
-__all__ = ['AgentMiddleware', 'ModelRequest', 'MiddlewareManager', 'TodoListMiddleware', 'TodoStatus']

aip_agents/middleware/base.pyi

@@ -1,75 +0,0 @@
-from langchain_core.tools import BaseTool as BaseTool
-from typing import Any, Protocol, TypedDict
-
-class ModelRequest(TypedDict, total=False):
-    """Represents parameters for a model invocation that middleware can modify.
-
-    This TypedDict defines the structure of requests passed to the LLM, allowing
-    middleware to add tools or modify prompts before each invocation.
-
-    Attributes:
-        messages: List of messages in the conversation.
-        tools: List of tools available to the model.
-        system_prompt: System-level instruction for the model.
-    """
-    messages: list[Any]
-    tools: list[BaseTool]
-    system_prompt: str
-
-class AgentMiddleware(Protocol):
-    """Protocol defining the interface for composable agent middleware.
-
-    Middleware components can contribute tools, enhance system prompts, and provide
-    lifecycle hooks that execute before, during, and after model invocations.
-
-    All middleware must implement this protocol to be compatible with MiddlewareManager.
-
-    Attributes:
-        tools: List of tools contributed by this middleware.
-        system_prompt_additions: Optional text to append to the agent's system prompt.
-    """
-    tools: list[BaseTool]
-    system_prompt_additions: str | None
-    def before_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Hook executed before each model invocation.
-
-        Use this hook to prepare state, log context, or perform setup tasks
-        before the model is called.
-
-        Args:
-            state: Current agent state containing messages and other context.
-
-        Returns:
-            Dict of state updates to merge into the agent state. Return empty dict
-            if no updates are needed.
-        """
-    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
-        """Hook to modify the model request before invocation.
-
-        Use this hook to add tools, modify the system prompt, adjust model parameters,
-        or change tool selection strategy.
-
-        Args:
-            request: The model request that will be sent to the LLM.
-            state: Current agent state for context.
-
-        Returns:
-            Modified ModelRequest. Can return the same request if no changes needed.
-        """
-    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Hook executed after each model invocation.
-
-        Use this hook for cleanup, logging, state updates, or post-processing
-        of model outputs.
-
-        Args:
-            state: Current agent state after model invocation.
-
-        Returns:
-            Dict of state updates to merge into the agent state. Return empty dict
-            if no updates are needed.
-        """
-    async def abefore_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Asynchronous version of before_model hook."""
-    async def aafter_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Asynchronous version of after_model hook."""

aip_agents/middleware/manager.pyi

@@ -1,84 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
-from langchain_core.tools import BaseTool as BaseTool
-from typing import Any
-
-class MiddlewareManager:
-    """Orchestrates multiple middleware components and manages hook execution.
-
-    The manager collects tools from all middleware, builds enhanced system prompts,
-    and executes lifecycle hooks in the correct order (forward for setup, reverse
-    for cleanup).
-
-    Attributes:
-        middleware: List of middleware components in registration order.
-    """
-    middleware: Incomplete
-    def __init__(self, middleware: list[AgentMiddleware]) -> None:
-        """Initialize the middleware manager.
-
-        Args:
-            middleware: List of middleware components to manage. Order matters:
-                       hooks execute forward (first to last) for before/modify,
-                       and reverse (last to first) for after.
-        """
-    def get_all_tools(self) -> list[BaseTool]:
-        """Collect tools from all registered middleware.
-
-        Returns:
-            Combined list of all tools contributed by all middleware components.
-            Empty list if no middleware or if middleware provide no tools.
-        """
-    def build_system_prompt(self, base_instruction: str) -> str:
-        """Build enhanced system prompt by concatenating base instruction with middleware additions.
-
-        Args:
-            base_instruction: The base system prompt for the agent.
-
-        Returns:
-            Enhanced system prompt with all middleware additions appended.
-            If no middleware provide additions, returns base_instruction unchanged.
-        """
-    def before_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Execute before_model hooks for all middleware in forward order.
-
-        Hooks run first to last, allowing earlier middleware to prepare state
-        for later middleware.
-
-        Args:
-            state: Current agent state.
-
-        Returns:
-            Merged dictionary of all state updates from all middleware.
-            Updates are accumulated in order of execution.
-        """
-    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
-        """Execute modify_model_request hooks for all middleware in forward order.
-
-        Each middleware receives the request modified by previous middleware,
-        allowing them to build on each other's changes.
-
-        Args:
-            request: The model request to be modified.
-            state: Current agent state for context.
-
-        Returns:
-            Final modified request after all middleware have processed it.
-        """
-    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Execute after_model hooks for all middleware in reverse order.
-
-        Hooks run last to first (reverse of registration order), allowing
-        proper cleanup and unwinding of middleware operations.
-
-        Args:
-            state: Current agent state after model invocation.
-
-        Returns:
-            Merged dictionary of all state updates from all middleware.
-            Updates are accumulated in reverse order of execution.
-        """
-    async def abefore_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Asynchronously execute before_model hooks for all middleware."""
-    async def aafter_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Asynchronously execute after_model hooks for all middleware in reverse order."""

aip_agents/middleware/todolist.pyi

@@ -1,125 +0,0 @@
-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/ptc/__init__.pyi

@@ -1,10 +0,0 @@
-from aip_agents.ptc.exceptions import PTCError as PTCError, PTCToolError as PTCToolError
-from aip_agents.ptc.prompt_builder import PromptConfig as PromptConfig, build_ptc_prompt as build_ptc_prompt, compute_ptc_prompt_hash as compute_ptc_prompt_hash
-
-__all__ = ['PTCError', 'PTCToolError', 'PTCSandboxConfig', 'PTCSandboxExecutor', 'PromptConfig', 'build_ptc_prompt', 'compute_ptc_prompt_hash', 'build_sandbox_payload', 'wrap_ptc_code']
-
-# Names in __all__ with no definition:
-#   PTCSandboxConfig
-#   PTCSandboxExecutor
-#   build_sandbox_payload
-#   wrap_ptc_code

aip_agents/ptc/doc_gen.pyi

@@ -1,40 +0,0 @@
-from aip_agents.ptc.naming import sanitize_function_name as sanitize_function_name
-from typing import Any
-
-DOC_DESC_LIMIT: int
-DOC_PARAM_DESC_LIMIT: int
-
-def json_type_to_display(json_type: Any) -> str:
-    """Convert JSON type to display string.
-
-    Args:
-        json_type: JSON schema type.
-
-    Returns:
-        Human-readable type string.
-    """
-def trim_text(text: str | None, limit: int) -> str:
-    """Trim text to limit with ellipsis if needed.
-
-    Args:
-        text: Text to trim.
-        limit: Maximum length before trimming.
-
-    Returns:
-        Trimmed text.
-    """
-def render_tool_doc(func_name: str, signature: str, description: str, schema: dict[str, Any], is_stub: bool = False, example_code: str | None = None, example_heading: str = '## Example') -> str:
-    """Render markdown documentation for a tool.
-
-    Args:
-        func_name: Sanitized function name.
-        signature: Full function signature.
-        description: Tool description.
-        schema: Input schema for parameters.
-        is_stub: Whether this is a stub documentation.
-        example_code: Optional example code block content (without ```python).
-        example_heading: Heading for the example section.
-
-    Returns:
-        Markdown documentation string.
-    """