xpander-sdk 2.0.169__tar.gz → 2.0.219__tar.gz

{xpander_sdk-2.0.169/src/xpander_sdk.egg-info → xpander_sdk-2.0.219}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.169
+Version: 2.0.219
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI
@@ -11,17 +11,18 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: python-dotenv
-Requires-Dist: packaging
-Requires-Dist: pydantic
-Requires-Dist: loguru
-Requires-Dist: httpx
-Requires-Dist: httpx_sse
-Requires-Dist: nest-asyncio
-Requires-Dist: strands-agents
-Requires-Dist: openai-agents
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: packaging>=25.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: httpx_sse>=0.4.3
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: strands-agents>=1.20.0
+Requires-Dist: openai-agents>=0.6.4
+Requires-Dist: python-toon>=0.1.3
 Provides-Extra: agno
-Requires-Dist: agno; extra == "agno"
+Requires-Dist: agno==2.3.26; extra == "agno"
 Requires-Dist: sqlalchemy; extra == "agno"
 Requires-Dist: psycopg[binary,pool]; extra == "agno"
 Requires-Dist: greenlet; extra == "agno"
@@ -292,6 +293,89 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Authentication Events Callback
+
+Handle authentication events in real-time. This callback is triggered only for authentication flows (e.g., MCP OAuth requiring user login).
+
+**You can use both approaches simultaneously** - decorated handlers will always be invoked, and you can also pass an explicit callback for additional handling.
+
+You can provide the callback in two ways:
+
+#### Option 1: Direct Function
+
+```python
+from xpander_sdk import Backend
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Define event callback (async or sync)
+async def my_event_callback(agent: Agent, task: Task, event: TaskUpdateEvent):
+    """Called for authentication events only"""
+    # event.type will always be "auth_event"
+    print(f"Authentication required: {event.data}")
+    # Display login URL or handle OAuth flow
+
+# Get args with callback
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task,
+    auth_events_callback=my_event_callback
+)
+```
+
+#### Option 2: Decorator (Auto-registered)
+
+```python
+from xpander_sdk import Backend, on_auth_event
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Use decorator - auto-registers globally
+@on_auth_event
+async def handle_auth(agent: Agent, task: Task, event: TaskUpdateEvent):
+    # event.type will always be "auth_event"
+    print(f"Authentication required for {agent.name}")
+    print(f"Auth data: {event.data}")
+
+# Decorated handler is automatically invoked - no need to pass it
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task
+)
+```
+
+#### Option 3: Combine Both
+
+```python
+from xpander_sdk import Backend, on_auth_event
+
+# Global handler for all auth events
+@on_auth_event
+async def log_auth(agent, task, event):
+    print(f"[GLOBAL] Auth event for {agent.name}")
+
+# Additional one-time handler
+async def custom_handler(agent, task, event):
+    print(f"[CUSTOM] Specific handling for this call")
+
+# Both handlers will be invoked
+args = await backend.aget_args(
+    agent_id="agent-123",
+    auth_events_callback=custom_handler  # Optional additional callback
+)
+
+# Use with Agno
+agno_agent = AgnoAgent(**args)
+result = await agno_agent.arun(
+    input="Process this data",
+    stream=True
+)
+```
+
 ### Task Activity Monitoring
 
 ```python
@@ -483,11 +567,11 @@ async def main():
         organization_id="your-org-id",
         base_url="https://agent-controller.my-company.com"
     )
-    
+
     # Load agent from self-hosted deployment
     agent = await Agent.aload("agent-123", configuration=config)
     print(f"Agent: {agent.name}")
-    
+
     # Create and execute task
     task = await agent.acreate_task(
         prompt="Analyze Q4 sales data",

xpander_sdk-2.0.169/PKG-INFO → xpander_sdk-2.0.219/README.md

@@ -1,52 +1,3 @@
-Metadata-Version: 2.4
-Name: xpander-sdk
-Version: 2.0.169
-Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
-Home-page: https://www.xpander.ai
-Author: xpanderAI
-Author-email: dev@xpander.ai
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: python-dotenv
-Requires-Dist: packaging
-Requires-Dist: pydantic
-Requires-Dist: loguru
-Requires-Dist: httpx
-Requires-Dist: httpx_sse
-Requires-Dist: nest-asyncio
-Requires-Dist: strands-agents
-Requires-Dist: openai-agents
-Provides-Extra: agno
-Requires-Dist: agno; extra == "agno"
-Requires-Dist: sqlalchemy; extra == "agno"
-Requires-Dist: psycopg[binary,pool]; extra == "agno"
-Requires-Dist: greenlet; extra == "agno"
-Provides-Extra: dev
-Requires-Dist: black; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: anthropic; extra == "dev"
-Requires-Dist: mcp; extra == "dev"
-Requires-Dist: openai; extra == "dev"
-Requires-Dist: fireworks-ai; extra == "dev"
-Requires-Dist: aioboto3; extra == "dev"
-Requires-Dist: google-genai; extra == "dev"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
 # xpander.ai SDK
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.xpander.ai) [![PyPI Version](https://img.shields.io/pypi/v/xpander-sdk?label=PyPI)](https://pypi.org/project/xpander-sdk/) [![Downloads](https://pepy.tech/badge/xpander-sdk)](https://pepy.tech/project/xpander-sdk)
@@ -292,6 +243,89 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Authentication Events Callback
+
+Handle authentication events in real-time. This callback is triggered only for authentication flows (e.g., MCP OAuth requiring user login).
+
+**You can use both approaches simultaneously** - decorated handlers will always be invoked, and you can also pass an explicit callback for additional handling.
+
+You can provide the callback in two ways:
+
+#### Option 1: Direct Function
+
+```python
+from xpander_sdk import Backend
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Define event callback (async or sync)
+async def my_event_callback(agent: Agent, task: Task, event: TaskUpdateEvent):
+    """Called for authentication events only"""
+    # event.type will always be "auth_event"
+    print(f"Authentication required: {event.data}")
+    # Display login URL or handle OAuth flow
+
+# Get args with callback
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task,
+    auth_events_callback=my_event_callback
+)
+```
+
+#### Option 2: Decorator (Auto-registered)
+
+```python
+from xpander_sdk import Backend, on_auth_event
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Use decorator - auto-registers globally
+@on_auth_event
+async def handle_auth(agent: Agent, task: Task, event: TaskUpdateEvent):
+    # event.type will always be "auth_event"
+    print(f"Authentication required for {agent.name}")
+    print(f"Auth data: {event.data}")
+
+# Decorated handler is automatically invoked - no need to pass it
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task
+)
+```
+
+#### Option 3: Combine Both
+
+```python
+from xpander_sdk import Backend, on_auth_event
+
+# Global handler for all auth events
+@on_auth_event
+async def log_auth(agent, task, event):
+    print(f"[GLOBAL] Auth event for {agent.name}")
+
+# Additional one-time handler
+async def custom_handler(agent, task, event):
+    print(f"[CUSTOM] Specific handling for this call")
+
+# Both handlers will be invoked
+args = await backend.aget_args(
+    agent_id="agent-123",
+    auth_events_callback=custom_handler  # Optional additional callback
+)
+
+# Use with Agno
+agno_agent = AgnoAgent(**args)
+result = await agno_agent.arun(
+    input="Process this data",
+    stream=True
+)
+```
+
 ### Task Activity Monitoring
 
 ```python
@@ -483,11 +517,11 @@ async def main():
         organization_id="your-org-id",
         base_url="https://agent-controller.my-company.com"
     )
-    
+
     # Load agent from self-hosted deployment
     agent = await Agent.aload("agent-123", configuration=config)
     print(f"Agent: {agent.name}")
-    
+
     # Create and execute task
     task = await agent.acreate_task(
         prompt="Analyze Q4 sales data",

{xpander_sdk-2.0.169 → xpander_sdk-2.0.219}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.169",
+    version="2.0.219",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",
@@ -15,18 +15,19 @@ setup(
     packages=find_packages(where="src"),
     package_dir={"": "src"},
     install_requires=[
-        "python-dotenv",
-        "packaging",
-        "pydantic",
-        "loguru",
-        "httpx",
-        "httpx_sse",
-        "nest-asyncio",
-        "strands-agents",
-        "openai-agents",
+        "python-dotenv>=1.2.1",
+        "packaging>=25.0",
+        "pydantic>=2.12.5",
+        "loguru>=0.7.3",
+        "httpx>=0.28.1",
+        "httpx_sse>=0.4.3",
+        "nest-asyncio>=1.6.0",
+        "strands-agents>=1.20.0",
+        "openai-agents>=0.6.4",
+        "python-toon>=0.1.3",
     ],
     extras_require={
-        "agno": ["agno", "sqlalchemy" ,"psycopg[binary,pool]", "greenlet"],
+        "agno": ["agno==2.3.26", "sqlalchemy" ,"psycopg[binary,pool]", "greenlet"],
         "dev": ["black", "pre-commit", "pytest", "anthropic", "mcp", "openai", "fireworks-ai", "aioboto3", "google-genai"],
     },
     classifiers=[

{xpander_sdk-2.0.169 → xpander_sdk-2.0.219}/src/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-2.0.169 → xpander_sdk-2.0.219}/src/xpander_sdk/consts/api_routes.py

@@ -55,6 +55,19 @@ and deleting resources.
     
     # Tools
     GetOrInvokeToolById = "/tools/{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"
+    
+    # Metadata
+    GetOrgDefaultLLMExtraHeaders = "/metadata/default_llm_extra_headers"
+    
+    # Agentic context
+    GetOrSetAgenticContext = "/agentic_context/{agent_id}"
 
     def __str__(self) -> str:
         return str(self.value)

xpander_sdk-2.0.219/src/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-2.0.219/src/xpander_sdk/models/notifications.py

@@ -0,0 +1,111 @@
+"""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
+    
+# Default values for HITL notifications
+DEFAULT_HITL_BODY = "Hello, workflow {title} is waiting for your approval and will not continue until approved. The workflow request is: {content}. By clicking approve, the workflow will auto-execute."
+DEFAULT_LOGO_URL = "https://assets.xpanderai.io/xpander-logo-512.png"
+DEFAULT_APPROVE_BUTTON_TEXT = "Approve"
+DEFAULT_DENY_BUTTON_TEXT = "Deny"
+
+
+class NotificationSettingsBase(XPanderSharedModel):
+    """Base class for notification settings with common customization fields.
+
+    Attributes:
+        subject: Optional custom subject line for notifications.
+        body: Optional custom body content for notifications.
+        approve_button_text: Text for approval button (HITL only). Defaults to "Approve".
+        deny_button_text: Text for denial button (HITL only). Defaults to "Deny".
+        logo_url: URL for logo image. Defaults to xpander logo.
+    """
+
+    subject: Optional[str] = None
+    body: Optional[str] = None
+    approve_button_text: Optional[str] = DEFAULT_APPROVE_BUTTON_TEXT
+    deny_button_text: Optional[str] = DEFAULT_DENY_BUTTON_TEXT
+    logo_url: Optional[str] = DEFAULT_LOGO_URL
+
+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]]] = {}