xpander-sdk 2.0.157__tar.gz → 2.0.161__tar.gz

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.157
+Version: 2.0.161
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.157",
+    version="2.0.161",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

xpander_sdk-2.0.161/src/xpander_sdk/models/deep_planning.py

@@ -0,0 +1,18 @@
+from typing import List, Optional
+from .shared import XPanderSharedModel
+
+class DeepPlanningItem(XPanderSharedModel):
+    id: str
+    title: str
+    completed: Optional[bool] = False
+
+class DeepPlanning(XPanderSharedModel):
+    enabled: Optional[bool] = False
+    enforce: Optional[bool] = False
+    started: Optional[bool] = False
+    question_raised: Optional[bool] = False
+    tasks: Optional[List[DeepPlanningItem]] = []
+
+class PlanFollowingStatus(XPanderSharedModel):
+    can_finish: bool
+    uncompleted_tasks: Optional[List[DeepPlanningItem]] = []

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/src/xpander_sdk/models/events.py

@@ -68,3 +68,6 @@ class TaskUpdateEventType(str, Enum):
     # reasoning
     Think = "think"
     Analyze = "analyze"
+    
+    # deep planning
+    PlanUpdated = "plan_updated"

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/src/xpander_sdk/modules/agents/sub_modules/agent.py

@@ -153,7 +153,8 @@ class Agent(XPanderSharedModel):
             model_provider: str
             model_name: str
             llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
-            deep_plan: Optional[bool] = False
+            deep_planning: Optional[bool] = False
+            enforce_deep_planning: Optional[bool] = False
             llm_api_base: Optional[str]
             webhook_url: Optional[str]
             created_at: Optional[datetime]
@@ -196,7 +197,8 @@ class Agent(XPanderSharedModel):
     model_provider: str
     model_name: str
     llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
-    deep_plan: Optional[bool] = False
+    deep_planning: Optional[bool] = False
+    enforce_deep_planning: Optional[bool] = False
     llm_api_base: Optional[str] = None
     webhook_url: Optional[str] = None
     created_at: Optional[datetime] = None

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/src/xpander_sdk/modules/backend/frameworks/agno.py

@@ -213,8 +213,244 @@ async def build_agent_args(
     if args["model"] and args["model"].id and args["model"].id.startswith("gpt-5"):
         del args["model"].temperature
     
+    # configure deep planning guidance
+    _configure_deep_planning_guidance(args=args, agent=xpander_agent, task=task)
     return args
 
+def _configure_deep_planning_guidance(args: Dict[str, Any], agent: Agent, task: Optional[Task]) -> None:
+    if args and agent and task and agent.deep_planning and task.deep_planning.enabled == True:
+        # add instructions guidance
+        if not "instructions" in args:
+            args["instructions"] = ""
+        
+        args["instructions"] += """\n
+            <important_planning_instructions>
+            ## **Deep Planning Tools - Essential for Multi-Step Tasks**
+
+            When handling complex tasks with multiple steps, use these planning tools to track progress systematically.
+
+            ### **Core Workflow**
+            1. **CREATE** plan at the start (`xpcreate-agent-plan`)
+            2. **START** plan execution (`xpstart-execution-plan`) - MANDATORY to enable enforcement
+            3. **CHECK** plan before each action (`xpget-agent-plan`)
+            4. **COMPLETE** task immediately after finishing it (`xpcomplete-agent-plan-item`)
+            5. **ASK** user for info if needed (`xpask-for-information`)
+            6. Repeat steps 3-5 until all tasks are done
+
+            ---
+
+            ### **Tool Reference**
+
+            #### **1. xpcreate-agent-plan** - Create Initial Plan
+            **When to use**: At the very start of any multi-step task, ONLY if no plan exists yet
+            **Note**: After creating a plan, you MUST call `xpstart-execution-plan` to begin enforcement
+
+            **How to use**:
+            - Pass an array of task objects (NOT strings)
+            - Each task must have a `title` field with short, explanatory description
+            - Example format:
+            ```json
+            {
+            "body_params": {
+                "tasks": [
+                {"title": "Research API requirements"},
+                {"title": "Design data schema"},
+                {"title": "Implement endpoints"},
+                {"title": "Write tests"},
+                {"title": "Deploy to staging"}
+                ]
+            }
+            }
+            ```
+            **Important**: 
+            - Include ALL steps needed from start to finish
+            - Each title should be clear and actionable (3-6 words)
+            - Do NOT pass plain strings like `["Task 1", "Task 2"]` - must be objects!
+
+            ---
+
+            #### **2. xpget-agent-plan** - View Current Plan
+            **When to use**: Before deciding what to do next; to check progress
+
+            **Returns**: 
+            - All tasks with their IDs, titles, and completion status
+            - Use this to know what's done and what remains
+
+            **No parameters needed** - just call the tool
+
+            ---
+
+            #### **3. xpcomplete-agent-plan-item** - Mark Task Complete
+            **When to use**: **IMMEDIATELY** after finishing each task (NOT before!)
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "id": "task-uuid-from-plan"
+            }
+            }
+            ```
+            **CRITICAL**: 
+            - Only mark complete AFTER work is actually done
+            - This is MANDATORY for progress tracking
+            - Get the task ID from `xpget-agent-plan` results
+
+            ---
+
+            #### **4. xpadd-new-agent-plan-item** - Add Discovered Task
+            **When to use**: When you discover additional work needed during execution
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "title": "Validate input schemas",
+                "completed": false
+            }
+            }
+            ```
+            ---
+
+            #### **5. xpupdate-agent-plan-item** - Modify Existing Task
+            **When to use**: When task details change or need clarification
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "id": "task-uuid",
+                "title": "Updated description",
+                "completed": true
+            }
+            }
+            ```
+            (All fields optional except `id`)
+
+            ---
+
+            #### **6. xpdelete-agent-plan-item** - Remove Task
+            **When to use**: When a task becomes unnecessary or redundant
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "id": "task-uuid"
+            }
+            }
+            ```
+            ---
+
+            #### **7. xpstart-execution-plan** - Start Plan Execution
+            **When to use**: Immediately after creating a plan with `xpcreate-agent-plan`
+            **CRITICAL**: Must be called to enable enforcement mode before executing tasks
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {}
+            }
+            ```
+            **No parameters needed** - just call after plan creation
+
+            **What it does**:
+            - Marks plan as "started" 
+            - Enables enforcement mode if `enforce` flag is true
+            - Allows plan execution to proceed
+
+            ---
+
+            #### **8. xpask-for-information** - Ask User a Question
+            **When to use**: When you need information from the user during plan execution
+            **PREREQUISITE**: Plan must be started (running) first
+
+            **How to use**:
+            ```json
+            {
+            "body_params": {
+                "question": "What is the customer email address?"
+            }
+            }
+            ```
+
+            **What it does**:
+            - Sets `question_raised` flag to true
+            - Prints the question for the user
+            - Keeps enforcement active (does NOT pause execution)
+            - Returns waiting status
+
+            ---
+
+            ### **Best Practices**
+
+            ✅ **DO:**
+            - Create comprehensive plans with ALL necessary steps
+            - **START** the plan with `xpstart-execution-plan` after creating it
+            - Use descriptive, actionable task titles
+            - Check plan before each action to stay oriented
+            - Mark tasks complete immediately after finishing them
+            - Ask for user information when needed with `xpask-for-information`
+            - Call plan tools **sequentially** (one at a time, never in parallel)
+
+            ❌ **DON'T:**
+            - Mark tasks complete before they're actually done
+            - Pass plain string arrays - must be objects with `title` field
+            - Call plan tools in parallel with each other
+            - Skip checking the plan between major steps
+            - Forget to mark completed tasks
+
+            ---
+
+            ### **Example Complete Workflow**
+
+            ```
+            1. User: "Build a REST API for user management"
+
+            2. Call: xpcreate-agent-plan
+            tasks: [
+                {"title": "Design user schema"},
+                {"title": "Create database migration"},
+                {"title": "Implement CRUD endpoints"},
+                {"title": "Add authentication"},
+                {"title": "Write integration tests"}
+            ]
+
+            3. Call: xpstart-execution-plan
+            → Plan now started, enforcement enabled (if enforce=true)
+
+            4. Call: xpget-agent-plan
+            → See: Task 1 (ID: abc-123) - Design user schema - Not complete
+
+            5. [Realize need user input] Call: xpask-for-information
+            question: "Which database should we use - PostgreSQL or MySQL?"
+            → question_raised=true, waiting for response
+
+            6. [After user responds, do the work: Design schema]
+
+            7. Call: xpcomplete-agent-plan-item
+            id: "abc-123"
+
+            8. Call: xpget-agent-plan
+            → See: Task 1 ✓ complete, Task 2 next...
+
+            9. [Continue through remaining tasks]
+            ```
+            **Remember**: The plan is your roadmap. Check it often, update it as needed, and always mark tasks complete when done!
+            </important_planning_instructions>
+        """
+        
+        # add the expected output guidance
+        if not "expected_output" in args:
+            args["expected_output"] = ""
+        args["expected_output"] += "\nAll planned tasks completed and marked as done."
+        
+        # add the plan to additional_context
+        if not "additional_context" in args:
+            args["additional_context"] = ""
+        
+        plan_str = task.deep_planning.model_dump_json() if task.deep_planning and task.deep_planning.enabled and len(task.deep_planning.tasks) != 0 else "No execution plan, please generate"
+        args["additional_context"] += f" \n Current execution plan: {plan_str}"
 
 def _load_llm_model(agent: Agent, override: Optional[Dict[str, Any]]) -> Any:
     """

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/src/xpander_sdk/modules/events/events_module.py

@@ -330,6 +330,7 @@ class Events(ModuleBase):
         agent_worker: DeployedAsset,
         task: Task,
         on_execution_request: ExecutionRequestHandler,
+        retry_count: Optional[int] = 0,
     ) -> None:
         """
         Handle an incoming task execution request.
@@ -338,6 +339,7 @@ class Events(ModuleBase):
             agent_worker (DeployedAsset): The deployed asset (agent) to handle the task.
             task (Task): The task object containing execution details.
             on_execution_request (ExecutionRequestHandler): The handler function to process the task.
+            retry_count (Optional[int]): Current retry attempt count. Defaults to 0.
         """
         error = None
         try:
@@ -351,6 +353,25 @@ class Events(ModuleBase):
                     on_execution_request,
                     task,
                 )
+            
+            # Check if plan is complete, retry if not
+            plan_following_status = await task.aget_plan_following_status()
+            if not plan_following_status.can_finish:
+                # Check if we've exceeded max retries
+                if retry_count >= 2:  # 0, 1, 2 = 3 total attempts
+                    logger.warning(f"Failed to complete plan after {retry_count + 1} attempts. Remaining incomplete tasks.")
+                    return
+                
+                # Recursively call with incremented retry count
+                logger.info(f"Plan not complete, retrying (attempt {retry_count + 2}/3)")
+                await self.handle_task_execution_request(
+                    agent_worker,
+                    task,
+                    on_execution_request,
+                    retry_count=retry_count + 1
+                )
+                return
+            
         except Exception as e:
             logger.exception(f"Execution handler failed - {str(e)}")
             error = str(e)

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/src/xpander_sdk/modules/tasks/sub_modules/task.py

@@ -43,12 +43,14 @@ from httpx import HTTPStatusError
 import httpx
 import json
 from httpx_sse import aconnect_sse
+from pydantic import Field, computed_field
 
 from xpander_sdk.consts.api_routes import APIRoute
 from xpander_sdk.core.xpander_api_client import APIClient
 from xpander_sdk.exceptions.module_exception import ModuleException
 from xpander_sdk.models.activity import AgentActivityThread
 from xpander_sdk.models.configuration import Configuration
+from xpander_sdk.models.deep_planning import PlanFollowingStatus, DeepPlanning
 from xpander_sdk.models.events import (
     TaskUpdateEventType,
     ToolCallRequest,
@@ -85,7 +87,7 @@ from xpander_sdk.utils.event_loop import run_sync
 T = TypeVar("T", bound="Task")
 
 TaskUpdateEventData = Union[
-    T, ToolCallRequest, ToolCallResult, MCPOAuthGetTokenResponse
+    T, ToolCallRequest, ToolCallResult, MCPOAuthGetTokenResponse, DeepPlanning
 ]
 
 
@@ -133,6 +135,7 @@ class Task(XPanderSharedModel):
         mcp_servers (Optional[List[MCPServerDetails]]): Optional list of mcp servers to use.
         triggering_agent_id (Optional[str]): Optional triggering agent id.
         title (Optional[str]): Optional task title.
+        deep_planning: Optional[DeepPlanning] = Field(default_factory=DeepPlanning)
 
     Example:
         >>> task = Task.load(task_id="task_123")
@@ -180,6 +183,7 @@ class Task(XPanderSharedModel):
     title: Optional[str] = (None,)
     think_mode: Optional[ThinkMode] = ThinkMode.Default
     disable_attachment_injection: Optional[bool] = False
+    deep_planning: Optional[DeepPlanning] = Field(default_factory=DeepPlanning)
 
     # metrics
     tokens: Optional[Tokens] = None
@@ -348,7 +352,7 @@ class Task(XPanderSharedModel):
             response = await client.make_request(
                 path=APIRoute.UpdateTask.format(task_id=self.id),
                 method="PATCH",
-                payload=self.model_dump_safe(),
+                payload=self.model_dump_safe(exclude={"configuration","deep_planning"}),
             )
             updated_task = Task(**response, configuration=self.configuration)
             for field, value in updated_task.__dict__.items():
@@ -536,6 +540,17 @@ class Task(XPanderSharedModel):
             for f in readable_files:
                 message += f"\n{json.dumps(f)}"
 
+        if self.deep_planning and self.deep_planning.enabled == True:
+            self.reload()
+            uncompleted_tasks = [task for task in self.deep_planning.tasks if not task.completed]
+            if len(uncompleted_tasks) != 0:
+                message = "\n".join([
+                    "Task not finished, uncompleted tasks detected:",
+                    f"Uncompleted tasks: {[task.model_dump_json() for task in uncompleted_tasks]}",
+                    "You must complete tasks if fulfilled",
+                    f"User's original request: \"{message}\""
+                ])
+        
         return message
 
     async def aget_activity_log(self) -> AgentActivityThread:
@@ -750,6 +765,64 @@ class Task(XPanderSharedModel):
             None
         """
         return run_sync(self.areport_metrics(configuration=configuration))
+    
+    async def aget_plan_following_status(self) -> PlanFollowingStatus:
+        """
+        Asynchronously check if the task's deep planning is complete.
+
+        Reloads the task to get the latest deep planning state and checks for
+        any uncompleted tasks. If deep planning is disabled or all tasks are
+        completed, returns a status indicating the task can finish.
+
+        Returns:
+            PlanFollowingStatus: Status object containing:
+                - can_finish (bool): True if all tasks are completed or deep planning is disabled.
+                - uncompleted_tasks (List[DeepPlanningItem]): List of tasks not yet completed.
+
+        Example:
+            >>> status = await task.aget_plan_following_status()
+            >>> if not status.can_finish:
+            ...     print(f"Remaining tasks: {len(status.uncompleted_tasks)}")
+        """
+        try:
+            if self.deep_planning and self.deep_planning.enabled and self.deep_planning.started and self.deep_planning.enforce:
+                await self.areload()
+                
+                # allow early exit to ask question
+                if self.deep_planning.question_raised:
+                    return PlanFollowingStatus(can_finish=True)
+
+                uncompleted_tasks = [
+                    task for task in self.deep_planning.tasks if not task.completed
+                ]
+                if len(uncompleted_tasks) != 0:
+                    return PlanFollowingStatus(
+                        can_finish=False, uncompleted_tasks=uncompleted_tasks
+                    )
+        except Exception:
+            pass
+
+        return PlanFollowingStatus(can_finish=True)
+
+    def get_plan_following_status(self) -> PlanFollowingStatus:
+        """
+        Check if the task's deep planning is complete synchronously.
+
+        This function wraps the asynchronous aget_plan_following_status method.
+        Reloads the task to get the latest deep planning state and checks for
+        any uncompleted tasks.
+
+        Returns:
+            PlanFollowingStatus: Status object containing:
+                - can_finish (bool): True if all tasks are completed or deep planning is disabled.
+                - uncompleted_tasks (List[DeepPlanningItem]): List of tasks not yet completed.
+
+        Example:
+            >>> status = task.get_plan_following_status()
+            >>> if not status.can_finish:
+            ...     print(f"Remaining tasks: {len(status.uncompleted_tasks)}")
+        """
+        return run_sync(self.aget_plan_following_status())
 
     @classmethod
     async def areport_external_task(
@@ -884,4 +957,4 @@ class Task(XPanderSharedModel):
                 duration=duration,
                 used_tools=used_tools,
             )
-        )
+        )

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/src/xpander_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.157
+Version: 2.0.161
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.157 → xpander_sdk-2.0.161}/src/xpander_sdk.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ src/xpander_sdk/exceptions/module_exception.py
 src/xpander_sdk/models/__init__.py
 src/xpander_sdk/models/activity.py
 src/xpander_sdk/models/configuration.py
+src/xpander_sdk/models/deep_planning.py
 src/xpander_sdk/models/events.py
 src/xpander_sdk/models/frameworks.py
 src/xpander_sdk/models/shared.py