xpander-sdk 2.0.161__py3-none-any.whl → 2.0.192__py3-none-any.whl

xpander_sdk/__init__.py

@@ -17,6 +17,7 @@ For more information, visit: https://xpander.ai
 
 # Backend-related imports
 from .modules.backend.backend_module import Backend
+from .modules.backend.decorators.on_auth_event import on_auth_event
 
 # Agent-related imports
 from .modules.agents.agents_module import Agents, Agent, AgentsListItem
@@ -27,6 +28,7 @@ from .modules.tasks.tasks_module import Tasks, Task, TasksListItem, AgentExecuti
 from xpander_sdk.modules.events.decorators.on_task import on_task
 from xpander_sdk.modules.events.decorators.on_boot import on_boot
 from xpander_sdk.modules.events.decorators.on_shutdown import on_shutdown
+from xpander_sdk.modules.events.decorators.on_tool import on_tool_before, on_tool_after, on_tool_error
 
 # Tools and repository imports
 from .modules.tools_repository.tools_repository_module import ToolsRepository, Tool
@@ -53,6 +55,7 @@ from .models.shared import OutputFormat, Tokens
 __all__ = [
     # xpander.ai Backend
     "Backend",
+    "on_auth_event",
     # Agent management
     "Agents",
     "Agent",
@@ -75,6 +78,9 @@ __all__ = [
     "MCPServerAuthType",
     "register_tool",
     "build_model_from_schema",
+    "on_tool_before",
+    "on_tool_after",
+    "on_tool_error",
     # Knowledge bases
     "KnowledgeBases",
     "KnowledgeBase",

xpander_sdk/consts/api_routes.py

@@ -55,6 +55,14 @@ and deleting resources.
     
     # Tools
     GetOrInvokeToolById = "/tools/{tool_id}"
+    InvokeCustomAgentTool = "/tools/{connector_id}/{tool_id}"
+    GetOrInvokeToolByUUID = "/tools/{connector_id}_{tool_id}"
+    ExecuteCodeInSandbox = "/tools/{task_id}/xp-code-executor"
+    
+    # HITL (Human-in-the-Loop)
+    HITLRequest = "/hitl/request"
+    HITLApprove = "/hitl/{task_id}/approve"
+    HITLReject = "/hitl/{task_id}/reject"
 
     def __str__(self) -> str:
         return str(self.value)

xpander_sdk/models/compactization.py

@@ -0,0 +1,112 @@
+from typing import List, Literal, Union
+
+from pydantic import Field
+from xpander_sdk.models.deep_planning import DeepPlanningItem
+from xpander_sdk.models.shared import XPanderSharedModel
+from xpander_sdk.modules.agents.models.agent import AgentInstructions
+from xpander_sdk.modules.tasks.models.task import AgentExecutionInput
+
+
+class TaskCompactizationInput(XPanderSharedModel):
+    user_input: AgentExecutionInput = Field(
+        ...,
+        description=(
+            "Original user input that initiated the task, including text, optional file URLs, "
+            "and optional user details."
+        ),
+    )
+    agent_instructions: AgentInstructions = Field(
+        ...,
+        description="Agent instructions (role, goals, and general guidance) that were active during execution."
+    )
+    task_context_and_messages: str = Field(
+        ...,
+        description=(
+            "Complete execution context including message history, tool calls, and session state. "
+            "This contains all information about what was attempted and what was achieved."
+        )
+    )
+    uncompleted_tasks: List["DeepPlanningItem"] = Field(
+        default_factory=list,
+        description=(
+            "List of planned tasks that remain incomplete. Each task has an id, title, and completed status. "
+            "ALL of these tasks MUST be completed and marked as completed=true in the continuation."
+        )
+    )
+
+class TaskCompactizationRetryEvent(XPanderSharedModel):
+    is_retry: bool
+
+class TaskCompactizationOutput(XPanderSharedModel):
+    new_task_prompt: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "A continuation prompt that seamlessly continues the running execution. "
+            "This is NOT a new task - it's the next message in an ongoing conversation. "
+            "The prompt must:\n"
+            "1. Resume from where the execution left off (do NOT repeat completed work)\n"
+            "2. Focus on completing ALL remaining uncompleted tasks\n"
+            "3. Include specific instructions to mark each task as completed after finishing it\n"
+            "4. Be written as if you're continuing mid-conversation, not starting fresh\n"
+            "5. Reference the current state and what still needs to be done\n"
+            "Example: 'Continuing from where we left off, we still need to complete tasks X, Y, and Z. "
+            "Let's proceed with task X first, then mark it complete using the appropriate tool.'"
+        ),
+    )
+
+    task_context: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Comprehensive context for continuing the execution. This context will be injected "
+            "into the agent's system prompt to maintain execution continuity.\n\n"
+            "REQUIRED FORMAT (use these exact headings, in this order):\n"
+            "1) ORIGINAL USER REQUEST\n"
+            "- Verbatim user_input text and any file references.\n\n"
+            "2) AGENT INSTRUCTIONS IN EFFECT\n"
+            "- General description from agent instructions.\n"
+            "- Role instructions (bullet list).\n"
+            "- Goals (bullet list).\n"
+            "- Any constraints or special requirements.\n\n"
+            "3) EXECUTION SUMMARY\n"
+            "- What actions were taken (facts only, no speculation).\n"
+            "- What outputs were produced (facts only).\n\n"
+            "4) CURRENT STATE AND ARTIFACTS\n"
+            "- All created artifacts with their identifiers, paths, URLs, or references.\n"
+            "- Current state of variables, decisions, configurations, and assumptions.\n"
+            "- Active session or database state if relevant.\n\n"
+            "5) MESSAGES AND KEY EVIDENCE\n"
+            "- Compact chronological summary of the conversation flow.\n"
+            "- Up to 5 verbatim quotes (max 25 words each) capturing critical details.\n\n"
+            "6) TOOL CALLS AND OBSERVATIONS\n"
+            "- For each tool call: tool name/id, purpose, key inputs, key outputs, errors.\n"
+            "- Include plan tool calls (create/get/complete) if they occurred.\n"
+            "- If no tools used: 'No tool calls were made.'\n\n"
+            "7) COMPLETED VS UNCOMPLETED TASKS\n"
+            "- Completed: List with task IDs and titles that are done.\n"
+            "- Uncompleted: List each task ID, title, and specific reason it's incomplete.\n"
+            "- CRITICAL: All uncompleted tasks MUST be finished in the continuation.\n\n"
+            "8) OPEN QUESTIONS AND UNKNOWNS\n"
+            "- Missing information needed to complete remaining tasks.\n"
+            "- Blockers or dependencies preventing progress.\n"
+            "- If none: 'No open questions.'\n\n"
+            "9) NEXT ACTIONS TO COMPLETE ALL TASKS\n"
+            "- Ordered list of specific actions to complete each uncompleted task.\n"
+            "- Each action should reference the task ID it completes.\n"
+            "- Final action must be to mark all tasks as completed using the plan tools.\n\n"
+            "ACCURACY REQUIREMENTS:\n"
+            "- Do NOT invent details. Use 'Unknown' if information is missing.\n"
+            "- Preserve exact names, IDs, numbers, file paths, and user wording.\n"
+            "- Task completion status must match reality - no implied completion.\n"
+            "- Focus on actionable, specific continuation steps.\n"
+        ),
+    )
+
+
+class TaskCompactizationEvent(XPanderSharedModel):
+    type: Literal["retry", "summarization"]
+    data: Union[
+        TaskCompactizationOutput,
+        TaskCompactizationRetryEvent
+    ]

xpander_sdk/models/events.py

@@ -71,3 +71,6 @@ class TaskUpdateEventType(str, Enum):
     
     # deep planning
     PlanUpdated = "plan_updated"
+    
+    # task compactization
+    TaskCompactization = "task_compactization"

xpander_sdk/models/frameworks.py

@@ -30,7 +30,7 @@ class AgnoSettings(BaseModel):
         session_storage (Optional[bool]): If True, enables session-level storage. Default is True.
         user_memories (Optional[bool]): If True, enables memory of user interactions. Default is True.
         session_summaries (Optional[bool]): If True, enables generation of session summaries. Default is False.
-        num_history_runs (Optional[int]): Number of historical runs to retain or consider. Default is 3.
+        num_history_runs (Optional[int]): Number of historical runs to retain or consider. Default is 10.
         tool_call_limit (Optional[int]): Max tool calls per run.
         coordinate_mode (Optional[bool]): If True, The agent will be loaded as a Team. Default is False.
         pii_detection_enabled (Optional[bool]): If True, enables PII detection guardrail on agent input. Default is False.
@@ -50,7 +50,7 @@ class AgnoSettings(BaseModel):
     agentic_culture: Optional[bool] = False
     
     session_summaries: Optional[bool] = False
-    num_history_runs: Optional[int] = 3
+    num_history_runs: Optional[int] = 10
     max_tool_calls_from_history: Optional[int] = 0
     tool_call_limit: Optional[int] = None
     coordinate_mode: Optional[bool] = False

xpander_sdk/models/generic.py

@@ -0,0 +1,27 @@
+from enum import Enum
+from typing import Optional
+
+from xpander_sdk.models.shared import XPanderSharedModel
+
+class LLMCredentialsKeyType(str, Enum):
+    XPander = "xpander"
+    Custom = "custom"
+
+class LLMCredentials(XPanderSharedModel):
+    name: str
+    description: Optional[str] = None
+    value: str
+
+class LLMModelProvider(Enum):
+    OpenAI = "openai"
+    NvidiaNIM = "nim"
+    AmazonBedrock = "amazon_bedrock"
+    HuggingFace = "huggingFace"
+    FriendliAI = "friendlyAI"
+    Anthropic = "anthropic"
+    GoogleGemini = "gemini"
+    Fireworks = "fireworks"
+    GoogleAIStudio = "google_ai_studio"
+    Helicone = "helicone"
+    OpenRouter = "open_router"
+    Nebius = "nebius"

xpander_sdk/models/notifications.py

@@ -0,0 +1,98 @@
+"""Models for notification configurations and credentials.
+
+This module provides data models for configuring various notification channels
+including email, Slack, and webhooks, along with their authentication details.
+"""
+
+from typing import Dict, List, Literal, Optional, Union
+
+from xpander_sdk.models.shared import XPanderSharedModel
+
+class SlackCredentials(XPanderSharedModel):
+    """Slack API authentication credentials.
+
+    Attributes:
+        authed_user_id: Authenticated user's Slack ID.
+        access_token: OAuth access token for API calls.
+        client_id: Slack app client ID.
+        client_secret: Slack app client secret.
+        verification_token: Token for verifying requests from Slack.
+        signing_secret: Secret for validating webhook signatures.
+        app_configuration_token: Token for app configuration.
+        app_configuration_refresh_token: Refresh token for app configuration.
+    """
+
+    authed_user_id: Optional[str] = None
+    access_token: Optional[str] = None
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+    verification_token: Optional[str] = None
+    signing_secret: Optional[str] = None
+    app_configuration_token: Optional[str] = None
+    app_configuration_refresh_token: Optional[str] = None
+    
+class NotificationSettingsBase(XPanderSharedModel):
+    """Base class for notification settings with common customization fields.
+
+    Attributes:
+        subject_suffix: Optional suffix to append to notification subjects.
+        body_prefix: Optional prefix to prepend to notification bodies.
+    """
+
+    subject_suffix: Optional[str] = None
+    body_prefix: Optional[str] = None
+
+class EmailNotificationSettings(NotificationSettingsBase):
+    """Configuration for email notifications.
+
+    Attributes:
+        to: List of recipient email addresses.
+    """
+
+    to: List[str]
+    
+class SlackNotificationSettings(NotificationSettingsBase):
+    """Configuration for Slack notifications.
+
+    Attributes:
+        channels: List of Slack channel IDs or names to post to.
+        credentials: Slack API authentication credentials.
+    """
+
+    channels: List[str]
+    credentials: SlackCredentials
+
+class WebhookNotificationSettings(NotificationSettingsBase):
+    """Configuration for webhook notifications.
+
+    Attributes:
+        url: Target webhook URL to POST notification data.
+        headers: Optional HTTP headers to include in the webhook request.
+    """
+
+    url: str
+    headers: Optional[Dict[str, str]] = {}
+
+NotificationType = Literal["email", "slack", "webhook"]
+"""Supported notification channel types."""
+
+NotificationDetails = Union[
+    EmailNotificationSettings,
+    SlackNotificationSettings,
+    WebhookNotificationSettings,
+]
+"""Union type for all notification detail configurations."""
+
+
+class NotificationSettings(XPanderSharedModel):
+    """Configuration for event-based notifications.
+
+    Attributes:
+        on_success: Notifications to send when an operation succeeds.
+            Maps notification types to a list of notification configurations.
+        on_error: Notifications to send when an operation fails.
+            Maps notification types to a list of notification configurations.
+    """
+
+    on_success: Optional[Dict[NotificationType, List[NotificationDetails]]] = {}
+    on_error: Optional[Dict[NotificationType, List[NotificationDetails]]] = {}

xpander_sdk/models/orchestrations.py

@@ -0,0 +1,271 @@
+"""Models for orchestration workflows and node definitions.
+
+This module provides data models for building and managing orchestration workflows,
+including various node types, execution strategies, and control flow conditions.
+"""
+
+from enum import Enum
+from typing import Dict, List, Literal, Optional, Union
+from uuid import uuid4
+
+from pydantic import Field
+
+from xpander_sdk.models.generic import (
+    LLMCredentials,
+    LLMCredentialsKeyType,
+    LLMModelProvider,
+)
+from xpander_sdk.models.shared import OutputFormat
+from xpander_sdk.models.notifications import NotificationDetails
+from xpander_sdk.models.shared import XPanderSharedModel
+
+class OrchestrationNodeType(str, Enum):
+    """Types of nodes available in an orchestration workflow.
+
+    Attributes:
+        CustomFunction: Node that executes a custom function.
+        Code: Node that executes arbitrary code.
+        Agent: Node that invokes an AI agent.
+        Orchestration: Node that references another orchestration.
+        Classifier: Node that classifies inputs using LLM.
+        Wait: Node that pauses execution until a condition is met.
+        Action: Node that triggers an action (api).
+    """
+
+    CustomFunction = "custom_function"
+    Code = "code"
+    Agent = "agent"
+    Orchestration = "orchestration"
+    Classifier = "classifier"
+    Wait = "wait"
+    Action = "action"
+
+class OrchestrationConditionType(str, Enum):
+    """Types of conditions for orchestration control flow.
+
+    Attributes:
+        Regex: Condition based on regular expression matching.
+        Contains: Condition based on substring containment.
+    """
+
+    Regex = "regex"
+    Contains = "contains"
+
+class OrchestrationWaitNodeType(str, Enum):
+    """Types of wait nodes in orchestration workflows.
+
+    Attributes:
+        Webhook: Wait for an external webhook call.
+        HITL: Wait for human-in-the-loop interaction.
+    """
+
+    Webhook = "webhook"
+    HITL = "hitl"
+
+class OrchestrationCondition(XPanderSharedModel):
+    """Condition for controlling orchestration flow.
+
+    Attributes:
+        type: Type of condition (regex or contains).
+        term: The pattern or string to match against.
+    """
+
+    type: OrchestrationConditionType
+    term: str
+
+class OrchestrationRetryStrategy(XPanderSharedModel):
+    """Strategy for retrying failed orchestration nodes.
+
+    Attributes:
+        enabled: Whether retry is enabled for this node.
+        max_retries: Maximum number of retry attempts. Defaults to 3.
+    """
+
+    enabled: Optional[bool] = False
+    max_retries: Optional[int] = 3
+
+class OrchestrationIterativeStrategy(XPanderSharedModel):
+    """Strategy for iteratively executing orchestration nodes.
+
+    Attributes:
+        enabled: Whether iterative execution is enabled.
+        max_iterations: Maximum number of iterations. Defaults to 3.
+        end_condition: Optional condition to stop iteration early.
+    """
+
+    enabled: Optional[bool] = False
+    max_iterations: Optional[int] = 3
+    end_condition: Optional[OrchestrationCondition] = None
+
+class OrchestrationStopStrategy(XPanderSharedModel):
+    """Strategy for stopping orchestration execution.
+
+    Attributes:
+        enabled: Whether the stop strategy is enabled.
+        stop_on_failure: Whether to stop the entire orchestration on node failure.
+        stop_on_condition: Optional condition that will stop execution if met.
+    """
+
+    enabled: Optional[bool] = False
+    stop_on_failure: Optional[bool] = True
+    stop_on_condition: Optional[OrchestrationCondition] = None
+
+class OrchestrationClassifierNodeLLMSettings(XPanderSharedModel):
+    """LLM configuration for classifier nodes.
+
+    Attributes:
+        model_provider: The LLM provider to use. Defaults to OpenAI.
+        model_name: Specific model identifier. Defaults to "gpt-5.2".
+        llm_credentials_key: Key identifier for stored credentials.
+        llm_credentials_key_type: Type of credential key storage. Defaults to XPander.
+        llm_credentials: Direct credential object if not using stored credentials.
+    """
+
+    model_provider: Optional[LLMModelProvider] = LLMModelProvider.OpenAI
+    model_name: Optional[str] = "gpt-5.2"
+    llm_credentials_key: Optional[str] = None
+    llm_credentials_key_type: Optional[LLMCredentialsKeyType] = (
+        LLMCredentialsKeyType.XPander
+    )
+    llm_credentials: Optional[LLMCredentials] = None
+
+class OrchestrationPointerNode(XPanderSharedModel):
+    """Node that references an external asset (agent, function, or orchestration).
+
+    Attributes:
+        asset_id: Unique identifier of the asset to execute.
+        type: Type of asset being referenced.
+        output_type: Expected output format. Defaults to Text.
+        output_schema: JSON schema for structured output validation.
+        instructions: Optional instructions for the pointer node (Action only).
+        ignore_response: Should ignore the node result and proceed with previous result?.
+    """
+
+    asset_id: str
+    type: Literal[
+        OrchestrationNodeType.Agent,
+        OrchestrationNodeType.CustomFunction,
+        OrchestrationNodeType.Orchestration,
+        OrchestrationNodeType.Action,
+    ]
+
+    output_type: Optional[OutputFormat] = OutputFormat.Text
+    output_schema: Optional[Dict] = None
+    instructions: Optional[str] = None
+    ignore_response: Optional[bool] = False
+
+class OrchestrationClassifierNode(XPanderSharedModel):
+    """Node that uses LLM to classify or transform inputs.
+
+    Attributes:
+        output_type: Expected output format. Defaults to Text.
+        output_schema: JSON schema for structured output validation.
+        instructions: Classification or transformation instructions for the LLM.
+        examples: Example inputs/outputs to guide the LLM behavior.
+        settings: LLM configuration settings.
+    """
+
+    output_type: Optional[OutputFormat] = OutputFormat.Text
+    output_schema: Optional[Dict] = None
+    instructions: Optional[str] = None
+    examples: Optional[List[str]] = []
+    settings: OrchestrationClassifierNodeLLMSettings
+
+class OrchestrationGuardrailNode(XPanderSharedModel):
+    """Node that uses LLM to evaluate input and enforce guardrails.
+
+    This node can stop execution if the guardrail check fails.
+
+    Attributes:
+        instructions: Evaluation instructions for the LLM to assess the input.
+        examples: Example inputs/outputs to guide the LLM behavior.
+        settings: LLM configuration settings.
+        stop_on_false: Whether to stop execution if the guardrail check fails. Defaults to True.
+    """
+
+    instructions: str
+    examples: Optional[List[str]] = []
+    settings: OrchestrationClassifierNodeLLMSettings
+    stop_on_false: Optional[bool] = True
+
+class OrchestrationSummarizerNode(XPanderSharedModel):
+    """Node that processes large payloads and answers specific questions.
+
+    This node uses an LLM to summarize or extract information from large inputs.
+
+    Attributes:
+        instructions: Summarization or question-answering instructions for the LLM.
+        examples: Example inputs/outputs to guide the LLM behavior.
+        settings: LLM configuration settings.
+    """
+
+    instructions: str
+    examples: Optional[List[str]] = []
+    settings: OrchestrationClassifierNodeLLMSettings
+
+class OrchestrationCodeNode(XPanderSharedModel):
+    """Node that executes arbitrary code.
+
+    Attributes:
+        code: The code string to execute.
+    """
+
+    code: str
+
+class OrchestrationWaitNode(XPanderSharedModel):
+    """Node that pauses execution until an external event occurs.
+
+    Attributes:
+        type: Type of wait event (webhook or human-in-the-loop).
+        definition: Notification configuration for triggering continuation.
+    """
+
+    type: Literal[OrchestrationWaitNodeType.Webhook, OrchestrationWaitNodeType.HITL]
+    definition: NotificationDetails
+
+class OrchestrationNode(XPanderSharedModel):
+    """A node in an orchestration workflow.
+
+    Represents a single execution unit in an orchestration with control flow,
+    execution strategies, and a specific node type definition.
+
+    Attributes:
+        id: Unique identifier for the node. Auto-generated if not provided.
+        next_node_ids: List of IDs of the next nodes to execute in the workflow (supports branching).
+        name: Human-readable name for the node.
+        description: Detailed description of the node's purpose.
+        condition: Conditional logic for executing this node.
+        retry_strategy: Strategy for retrying failed executions.
+        iterative_strategy: Strategy for iterative execution.
+        stop_strategy: Strategy for stopping the workflow.
+        definition: The actual node implementation (code, classifier, pointer, or wait).
+        input_type: Expected input format. Defaults to Text.
+        input_schema: JSON schema for structured input validation.
+        input_instructions: Instructions to use for structured input.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    next_node_ids: List[str] = Field(default_factory=list)
+    name: Optional[str] = None
+    description: Optional[str] = None
+    condition: Optional[OrchestrationCondition] = None
+    retry_strategy: Optional[OrchestrationRetryStrategy] = Field(
+        default_factory=OrchestrationRetryStrategy
+    )
+    iterative_strategy: Optional[OrchestrationIterativeStrategy] = Field(
+        default_factory=OrchestrationIterativeStrategy
+    )
+    stop_strategy: Optional[OrchestrationStopStrategy] = Field(
+        default_factory=OrchestrationStopStrategy
+    )
+    definition: Union[
+        OrchestrationCodeNode,
+        OrchestrationClassifierNode,
+        OrchestrationPointerNode,
+        OrchestrationWaitNode,
+        OrchestrationGuardrailNode,
+        OrchestrationSummarizerNode,
+    ]
+    input_type: Optional[OutputFormat] = OutputFormat.Text
+    input_schema: Optional[Dict] = None
+    input_instructions: Optional[str] = None

xpander_sdk/modules/agents/models/agent.py

@@ -10,6 +10,7 @@ from enum import Enum
 from typing import Dict, List, Literal, Optional, Type
 from pydantic import BaseModel, computed_field
 
+from xpander_sdk.models.orchestrations import OrchestrationIterativeStrategy, OrchestrationRetryStrategy, OrchestrationStopStrategy
 from xpander_sdk.models.shared import XPanderSharedModel
 from xpander_sdk.modules.tools_repository.models.mcp import MCPServerDetails
 
@@ -420,12 +421,14 @@ class AgentType(str, Enum):
         Regular: Standard agent for individual task execution.
         A2A: Agent that is used via A2A protocol.
         Curl: Custom Agent that is used via curl.
+        Orchestration: marks the agent as an Orchestration object.
     """
 
     Manager = "manager"
     Regular = "regular"
     A2A = "a2a"
     Curl = "curl"
+    Orchestration = "orchestration"
 
 
 @dataclass
@@ -471,7 +474,7 @@ class AgentOutput(BaseModel):
     is_markdown: Optional[bool] = False
     use_json_mode: Optional[bool] = False
 
-class LLMCredentials(XPanderSharedModel):
-    name: str
-    description: Optional[str] = None
-    value: str
+class TaskLevelStrategies(XPanderSharedModel):
+    retry_strategy: Optional[OrchestrationRetryStrategy] = None
+    iterative_strategy: Optional[OrchestrationIterativeStrategy] = None
+    stop_strategy: Optional[OrchestrationStopStrategy] = None