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

aip_agents/middleware/todolist.py

@@ -0,0 +1,274 @@
+"""TodoList middleware for agent planning and task decomposition.
+
+Provides a write_todos tool that allows agents to break down complex tasks
+into discrete, trackable steps with status management.
+"""
+
+import threading
+from enum import StrEnum
+from typing import Any
+
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, SkipValidation
+
+from aip_agents.middleware.base import ModelRequest
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class TodoStatus(StrEnum):
+    """Enumeration of possible todo item statuses."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+
+
+WRITE_TODOS_SYSTEM_PROMPT = """## Task Planning with `write_todos`
+
+Use `write_todos` to plan and track complex multi-step objectives (3+ steps, multiple deliverables, or tasks described as "comprehensive"). Skip for trivial single-action requests.
+
+**Execution rules:**
+1. Create the plan with `write_todos` BEFORE executing work
+2. Execute ALL tasks autonomously—do NOT pause to ask "should I continue?" or "would you like a preview?"
+3. Revise the plan as needed when new information emerges
+4. Mark tasks completed as you finish them
+5. **CRITICAL: Before your final response, call `write_todos` one last time to mark ALL tasks as `completed`. Never respond to the user while any task is `pending` or `in_progress`.**
+"""
+
+EMPTY_TODO_REMINDER = (
+    "\n\n**Todo List Reminder:** Your todo list is currently empty. "
+    "If you are working on tasks that would benefit from a todo list, "
+    "use the write_todos tool to create one. This helps track progress "
+    "and ensures you don't forget important steps.\n"
+)
+
+
+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 = Field(description="Description of what needs to be done")
+    active_form: str = Field(description="Short active form for display (e.g., 'researching topic')")
+    status: TodoStatus = Field(default=TodoStatus.PENDING, description="Current status of this todo")
+
+
+class TodoList(BaseModel):
+    """Represents a complete todo list for a thread.
+
+    Attributes:
+        items: List of todo items in order.
+    """
+
+    items: list[TodoItem] = Field(default_factory=list)
+
+
+WRITE_TODOS_TOOL_DESCRIPTION = """Create and manage a structured task list for complex work sessions (3+ steps).
+
+## When to Use
+- Multi-step tasks with 3+ distinct steps
+- Requests with multiple deliverables
+- User provides a list of tasks
+- User explicitly requests a todo list
+
+## When to Skip
+- Single straightforward action
+- Trivial tasks with no tracking benefit
+
+## Task States
+- `pending`: Not started
+- `in_progress`: Currently working
+- `completed`: Fully finished
+
+## Workflow
+1. **Plan first**: Call `write_todos` before executing work. Mark first task(s) as `in_progress`.
+2. **Stay autonomous**: Execute all tasks without pausing for user confirmation.
+3. **Adapt the plan**: Add new tasks as discovered, remove irrelevant ones.
+4. **Mark progress**: Update task status as you complete work.
+5. **Final update**: Before responding to user, call `write_todos` to mark ALL remaining tasks `completed`.
+
+## CRITICAL: Final Response Rule
+You must NOT respond to the user until EVERY task is marked `completed`. Your final action before responding should be a `write_todos` call that marks the last task(s) complete. If any task remains `pending` or `in_progress`, you are not done—keep working or update the plan."""
+
+
+class WriteTodosInput(BaseModel):
+    """Input schema for the write_todos tool."""
+
+    todos: TodoList = Field(
+        ...,
+        description="List of todo items, each with 'content' and 'activeForm' keys.",
+    )
+
+
+class WriteTodosTool(BaseTool):
+    """LangChain-compatible tool for managing todo lists via TodoListMiddleware."""
+
+    name: str = "write_todos_tool"
+    description: str = WRITE_TODOS_TOOL_DESCRIPTION
+    args_schema: type[BaseModel] = WriteTodosInput
+
+    # Instance reference to middleware storage (excluded from serialization, skip validation)
+    storage: SkipValidation[dict[str, TodoList]] = Field(default_factory=dict, exclude=True)
+    storage_lock: SkipValidation[threading.RLock] = Field(default_factory=threading.RLock, exclude=True)
+
+    def _run(self, todos: TodoList, config: RunnableConfig | None = None) -> str:  # type: ignore[override]
+        """Synchronous entrypoint used by generic tool runners.
+
+        Args:
+            todos: The todo list to write.
+            config: Optional configuration for the tool run.
+
+        Returns:
+            str: A success message indicating the number of todo items written.
+        """
+        tid = "default"
+        if config and "configurable" in config:
+            tid = config["configurable"].get("thread_id", "default")
+
+        try:
+            # Store in thread-safe manner
+            with self.storage_lock:
+                self.storage[tid] = todos
+
+            return f"Successfully wrote {len(todos.items)} todo items to your plan."
+        except Exception as e:  # pragma: no cover - defensive
+            return f"Error writing todos: {str(e)}"
+
+
+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.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the TodoList middleware with planning tools and instructions."""
+        # Instance-level storage to prevent race conditions across agent instances
+        self._storage: dict[str, TodoList] = {}
+        self._storage_lock = threading.RLock()
+
+        # Create tool with reference to this instance's storage
+        self.tools = [WriteTodosTool(storage=self._storage, storage_lock=self._storage_lock)]
+        self.system_prompt_additions = WRITE_TODOS_SYSTEM_PROMPT
+
+    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).
+        """
+        # Sync from LangGraph state to internal storage (if state has todos)
+        if "todos" in state and state["todos"] is not None:
+            thread_id = state.get("thread_id", "default")
+
+            # Deep copy to prevent mutation issues between state and storage
+            with self._storage_lock:
+                self._storage[thread_id] = state["todos"].model_copy(deep=True)
+
+        return {}
+
+    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.
+        """
+        thread_id = state.get("thread_id", "default")
+
+        # Get current todos from storage
+        with self._storage_lock:
+            current_todos = self._storage.get(thread_id)
+
+        # Inject todo status into system prompt
+        if current_todos and current_todos.items:
+            # Build todo status reminder
+            todo_reminder = "\n\n## Current Todo List Status\n\n"
+            todo_reminder += "Your current todo list:\n"
+
+            for item in current_todos.items:
+                todo_reminder += f"[{item.status.value.upper()}] {item.content}\n"
+
+            todo_reminder += "\n**Remember to update the todo list as you complete tasks using write_todos.**\n"
+
+            # Append to system prompt
+            current_system_prompt = request.get("system_prompt", "")
+            request["system_prompt"] = current_system_prompt + todo_reminder
+        else:
+            # Static reminder when no todos exist
+            current_system_prompt = request.get("system_prompt", "")
+            request["system_prompt"] = current_system_prompt + EMPTY_TODO_REMINDER
+
+        return request
+
+    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.
+        """
+        thread_id = state.get("thread_id", "default")
+
+        with self._storage_lock:
+            if thread_id in self._storage:
+                # Deep copy to prevent mutation issues between storage and state
+                return {"todos": self._storage[thread_id].model_copy(deep=True)}
+
+        return {}
+
+    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.
+        """
+        with self._storage_lock:
+            return self._storage.get(thread_id, TodoList())
+
+    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".
+        """
+        with self._storage_lock:
+            if thread_id in self._storage:
+                del self._storage[thread_id]

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/ptc/__init__.py

@@ -0,0 +1,48 @@
+"""PTC (Programmatic Tool Calling) core module (MCP-only).
+
+This module provides the core PTC functionality for MCP tools, including
+executor, prompt builder, and sandbox bridge.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from aip_agents.ptc.exceptions import PTCError, PTCToolError
+from aip_agents.ptc.prompt_builder import PromptConfig, build_ptc_prompt, compute_ptc_prompt_hash
+
+__all__ = [
+    # Exceptions
+    "PTCError",
+    "PTCToolError",
+    # Executor
+    "PTCSandboxConfig",
+    "PTCSandboxExecutor",
+    # Prompt builder
+    "PromptConfig",
+    "build_ptc_prompt",
+    "compute_ptc_prompt_hash",
+    # Sandbox bridge
+    "build_sandbox_payload",
+    "wrap_ptc_code",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid circular dependencies."""
+    if name == "PTCSandboxConfig":
+        from aip_agents.ptc.executor import PTCSandboxConfig
+
+        return PTCSandboxConfig
+    elif name == "PTCSandboxExecutor":
+        from aip_agents.ptc.executor import PTCSandboxExecutor
+
+        return PTCSandboxExecutor
+    elif name == "build_sandbox_payload":
+        from aip_agents.ptc.sandbox_bridge import build_sandbox_payload
+
+        return build_sandbox_payload
+    elif name == "wrap_ptc_code":
+        from aip_agents.ptc.sandbox_bridge import wrap_ptc_code
+
+        return wrap_ptc_code
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

aip_agents/ptc/__init__.pyi

@@ -0,0 +1,10 @@
+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.py

@@ -0,0 +1,122 @@
+"""Documentation generation utilities for PTC.
+
+Shared constants and helpers for generating tool documentation in sandbox payloads.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+
+from aip_agents.ptc.naming import sanitize_function_name
+
+# Documentation limits (fixed constants per plan)
+DOC_DESC_LIMIT = 120  # Tool description trim limit
+DOC_PARAM_DESC_LIMIT = 80  # Parameter description trim limit
+
+
+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.
+    """
+    if isinstance(json_type, list):
+        return "any"
+    type_map = {
+        "string": "str",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "array": "list",
+        "object": "dict",
+        "null": "None",
+    }
+    return type_map.get(str(json_type), "any")
+
+
+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.
+    """
+    if not text:
+        return ""
+    if len(text) > limit:
+        return text[:limit] + "..."
+    return 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.
+    """
+    if is_stub:
+        desc = "Details unavailable because tool definitions are not loaded yet."
+    else:
+        desc = trim_text(description, DOC_DESC_LIMIT) or "No description available."
+
+    lines = [
+        f"# {func_name}",
+        "",
+        f"**Description:** {desc}",
+        "",
+        f"**Signature:** `{signature}`",
+        "",
+    ]
+
+    # Add parameters section
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    if properties:
+        lines.append("## Parameters")
+        lines.append("")
+        for prop_name, prop_schema in sorted(properties.items()):
+            safe_param = sanitize_function_name(prop_name)
+            prop_type = json_type_to_display(prop_schema.get("type", "any"))
+            is_required = "required" if prop_name in required else "optional"
+
+            # Trim param description
+            raw_param_desc = prop_schema.get("description", "")
+            param_desc = trim_text(raw_param_desc, DOC_PARAM_DESC_LIMIT)
+
+            lines.append(f"- **{safe_param}** ({prop_type}, {is_required}): {param_desc}")
+        lines.append("")
+
+    # Add example section
+    if example_code:
+        lines.append(example_heading)
+        lines.append("")
+        lines.append("```python")
+        lines.append(example_code)
+        lines.append("```")
+
+    return "\n".join(lines)

aip_agents/ptc/doc_gen.pyi

@@ -0,0 +1,40 @@
+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.
+    """

aip_agents/ptc/exceptions.py

@@ -0,0 +1,39 @@
+"""PTC-specific exceptions.
+
+This module defines exceptions for Programmatic Tool Calling operations.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+
+class PTCError(Exception):
+    """Base exception for PTC errors."""
+
+    pass
+
+
+class PTCToolError(PTCError):
+    """Error during tool execution.
+
+    Attributes:
+        server_name: The MCP server where the error occurred.
+        tool_name: The tool that failed.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        server_name: str | None = None,
+        tool_name: str | None = None,
+    ) -> None:
+        """Initialize PTCToolError.
+
+        Args:
+            message: Error message.
+            server_name: The MCP server name (optional).
+            tool_name: The tool name (optional).
+        """
+        super().__init__(message)
+        self.server_name = server_name
+        self.tool_name = tool_name

aip_agents/ptc/exceptions.pyi

@@ -0,0 +1,22 @@
+from _typeshed import Incomplete
+
+class PTCError(Exception):
+    """Base exception for PTC errors."""
+
+class PTCToolError(PTCError):
+    """Error during tool execution.
+
+    Attributes:
+        server_name: The MCP server where the error occurred.
+        tool_name: The tool that failed.
+    """
+    server_name: Incomplete
+    tool_name: Incomplete
+    def __init__(self, message: str, server_name: str | None = None, tool_name: str | None = None) -> None:
+        """Initialize PTCToolError.
+
+        Args:
+            message: Error message.
+            server_name: The MCP server name (optional).
+            tool_name: The tool name (optional).
+        """