xpander-sdk 1.60.8__py3-none-any.whl → 2.0.155__py3-none-any.whl

xpander_sdk/utils/env.py

@@ -0,0 +1,44 @@
+"""
+Environment utilities for the xpander.ai SDK.
+
+This module provides utilities for reading environment variables and
+configuring SDK behavior based on environment settings.
+"""
+
+from os import getenv
+
+def get_base_url() -> str:
+    """
+    Get the base URL for xpander.ai API endpoints.
+    
+    This function determines the appropriate base URL for API requests based on
+    environment variables. It supports both production and staging environments,
+    with the ability to override via environment variables.
+    
+    Environment Variables:
+        XPANDER_BASE_URL: Override URL for API endpoints (optional).
+        IS_STG: Set to "true" for staging environment (optional, defaults to "false").
+        
+    Returns:
+        str: The base URL for xpander.ai API endpoints, always prefixed with "https://".
+        
+    Example:
+        >>> url = get_base_url()
+        >>> print(url)  # "https://inbound.xpander.ai"
+        
+        >>> import os
+        >>> os.environ["XPANDER_BASE_URL"] = "custom.api.endpoint"
+        >>> url = get_base_url()
+        >>> print(url)  # "https://custom.api.endpoint"
+    """
+    # Support override by environment variable
+    base_url = getenv("XPANDER_BASE_URL")
+    
+    if not base_url:
+        is_stg = getenv("IS_STG", "false") == "true"
+        base_url = "inbound.stg.xpander.ai" if is_stg else "inbound.xpander.ai"
+    
+    if not base_url.startswith("http://") and not base_url.startswith("https://"):
+        base_url = f"https://{base_url}"
+    
+    return base_url

xpander_sdk/utils/event_loop.py

@@ -0,0 +1,67 @@
+"""
+Utilities for managing event loop execution in the xpander.ai SDK.
+
+This module provides utilities for handling asyncio event loops, enabling
+synchronous execution of coroutines in environments that may not natively
+support asynchronous operations.
+"""
+
+import asyncio
+from typing import Any, Awaitable
+
+
+def run_sync(coro: Awaitable[Any]) -> Any:
+    """
+    Synchronously run an asynchronous coroutine, ensuring compatibility
+    with nested event loops in environments like Jupyter Notebooks or
+    web frameworks such as FastAPI.
+    
+    This function detects and manages running event loops to prevent
+    runtime errors. For uvloop compatibility, it uses asyncio.create_task
+    and waits for completion instead of nest_asyncio when uvloop is detected.
+    
+    Args:
+        coro (Awaitable[Any]): The coroutine to be executed.
+        
+    Returns:
+        Any: The result of the coroutine execution.
+        
+    Example:
+        >>> async def fetch_data():
+        ...     # simulate async operation
+        ...     await asyncio.sleep(1)
+        ...     return "data"
+        
+        >>> result = run_sync(fetch_data())
+        >>> print(result)  # Outputs: "data"
+    """
+    try:
+        loop = asyncio.get_running_loop()
+        if loop.is_running():
+            # Check if we're running with uvloop
+            loop_module = type(loop).__module__
+            if 'uvloop' in loop_module.lower():
+                # uvloop doesn't support nest_asyncio, so we need a different approach
+                # Create a task and run it in the current loop context
+                import concurrent.futures
+                
+                # Use a separate thread with a new event loop
+                def _run_in_thread():
+                    new_loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(new_loop)
+                    try:
+                        return new_loop.run_until_complete(coro)
+                    finally:
+                        new_loop.close()
+                
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(_run_in_thread)
+                    return future.result()
+            else:
+                # Use `nest_asyncio` for standard asyncio loops
+                import nest_asyncio
+                nest_asyncio.apply()
+                return loop.run_until_complete(coro)
+    except RuntimeError:
+        # No event loop in this context, safe to run
+        return asyncio.run(coro)

xpander_sdk/utils/tools.py

@@ -0,0 +1,32 @@
+from typing import Any, List
+from agents.tool import ToolContext as OpenAIAgentSDKToolContext, FunctionTool as OpenAIAgentSDKTool
+import json
+from xpander_sdk.modules.tools_repository.sub_modules.tool import Tool
+
+def get_openai_agents_sdk_tools(agent: Any) -> List[OpenAIAgentSDKTool]:
+    tools: List[OpenAIAgentSDKTool] = []
+    agent_tools: List[Tool] = agent.tools.list
+    for _tool in agent_tools:
+        def make_tool(_tool_def: Tool):
+            async def invoke(context: OpenAIAgentSDKToolContext, args: str):
+                return await _tool_def.ainvoke(
+                    task_id=agent.configuration.state.task.id
+                        if agent.configuration.state.task
+                        else None,
+                    agent_id=agent.id,
+                    agent_version=agent.version,
+                    payload=json.loads(args),
+                    configuration=_tool.configuration
+                )
+            return invoke
+        
+        tools.append(
+            OpenAIAgentSDKTool(
+                on_invoke_tool=make_tool(_tool),
+                name=_tool.id,
+                description=_tool.description,
+                params_json_schema=_tool.parameters
+            )
+        )
+    
+    return tools

xpander_sdk-2.0.155.dist-info/METADATA

@@ -0,0 +1,538 @@
+Metadata-Version: 2.4
+Name: xpander-sdk
+Version: 2.0.155
+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)
+
+The official Python SDK for xpander.ai - a powerful Backend-as-a-Service (BaaS) platform for building, deploying, and managing AI agents at scale.
+
+## 🚀 Overview
+
+xpander.ai SDK provides comprehensive tools for:
+
+- **Agent Management**: Create, configure, and manage AI agents
+- **Task Execution**: Handle complex task workflows and execution
+- **Tools Repository**: Integrate external tools and services
+- **Knowledge Bases**: Manage and search knowledge repositories
+- **Event Handling**: Event-driven programming with decorators
+- **Real-time Monitoring**: Track agent performance and execution
+
+## 📦 Installation
+
+```bash
+pip install xpander-sdk
+```
+
+### With Optional Dependencies
+
+```bash
+# For Agno framework support (2.0+)
+pip install xpander-sdk[agno]
+
+# For development
+pip install xpander-sdk[dev]
+```
+
+## 🔧 Quick Start
+
+### 1. Configuration
+
+```python
+from xpander_sdk import Configuration
+
+# Using environment variables (recommended)
+config = Configuration()
+
+# Or explicit configuration
+config = Configuration(
+    api_key="your-api-key",
+    organization_id="your-org-id",
+    base_url="https://inbound.xpander.ai"
+)
+```
+
+### 2. Basic Agent Operations
+
+```python
+from xpander_sdk import Agents, Agent, Tasks, AgentDeploymentType
+
+# Initialize agents module
+agents = Agents(configuration=config)
+
+# List all agents
+agent_list = await agents.alist()
+
+# Load existing agent
+agent = await agents.aget("agent-id")
+
+# Create and execute a task
+task = await agent.acreate_task(
+    prompt="Help me analyze this data",
+    file_urls=["https://example.com/data.csv"]
+)
+```
+
+### 3. Task Management
+
+```python
+from xpander_sdk import Tasks, Task
+
+# Initialize tasks module
+tasks = Tasks(configuration=config)
+
+# Load and manage tasks
+task = await tasks.aget("task-id")
+await task.aset_status(AgentExecutionStatus.Running)
+await task.asave()
+
+# Retrieve task activity log
+activity_log = await task.aget_activity_log()
+for message in activity_log.messages:
+    print(f"{message.role}: {message.content.text}")
+```
+
+### 4. Tools Integration
+
+```python
+from xpander_sdk import register_tool, ToolsRepository
+
+# Register a local tool
+@register_tool
+def check_weather(location: str) -> str:
+    """Check weather for a given location."""
+    return f"Weather in {location}: Sunny, 25°C"
+
+# Register a tool with graph synchronization
+@register_tool(add_to_graph=True)
+async def analyze_data(data: list, analysis_type: str) -> dict:
+    """Analyze data from multiple sources."""
+    return {
+        "analysis_type": analysis_type,
+        "data_points": len(data),
+        "status": "completed"
+    }
+
+# Use tools repository
+tools = ToolsRepository(configuration=config)
+weather_tool = tools.get_tool_by_id("check_weather")
+result = await weather_tool.ainvoke(
+    agent_id="agent-id",
+    payload={"location": "New York"}
+)
+```
+
+### 5. Knowledge Base Operations
+
+```python
+from xpander_sdk import KnowledgeBases, KnowledgeBase
+
+# Initialize knowledge bases
+kb_module = KnowledgeBases(configuration=config)
+
+# Create knowledge base
+kb = await kb_module.acreate(
+    name="Company Docs",
+    description="Internal documentation"
+)
+
+# Add documents
+documents = await kb.aadd_documents([
+    "https://example.com/doc1.pdf",
+    "https://example.com/doc2.txt"
+])
+
+# Search knowledge base
+results = await kb.asearch(
+    search_query="product pricing",
+    top_k=5
+)
+```
+
+### 6. Event-Driven Programming
+
+```python
+from xpander_sdk import on_task, Events
+
+# Basic task handler
+@on_task
+async def handle_task(task):
+    print(f"Processing task: {task.id}")
+    # Task processing logic here
+    task.result = "Task processed successfully"
+    return task
+
+# Task handler with configuration
+@on_task(configuration=config)
+def sync_task_handler(task):
+    print(f"Handling task synchronously: {task.id}")
+    task.result = "Sync processing complete"
+    return task
+
+```
+
+## 📚 Core Modules
+
+| Module              | Description                               | Documentation                                                                            |
+| ------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Agents**          | Agent creation, management, and execution | [Agents Guide](https://github.com/xpander-ai/xpander-sdk/blob/main/docs/AGENTS.md)       |
+| **Tasks**           | Task lifecycle and execution management   | [Tasks Guide](https://github.com/xpander-ai/xpander-sdk/blob/main/docs/TASKS.md)         |
+| **ToolsRepository** | External tools and integrations           | [Tools Guide](https://github.com/xpander-ai/xpander-sdk/blob/main/docs/TOOLS.md)         |
+| **KnowledgeBases**  | Knowledge management and search           | [Knowledge Guide](https://github.com/xpander-ai/xpander-sdk/blob/main/docs/KNOWLEDGE.md) |
+| **Events**          | Event-driven programming                  | [Events Guide](https://github.com/xpander-ai/xpander-sdk/blob/main/docs/EVENTS.md)       |
+| **Backend**         | Agent runtime arguments for frameworks    | [Backend Guide](https://github.com/xpander-ai/xpander-sdk/blob/main/docs/BACKEND.md)     |
+
+## 🔄 Async/Sync Support
+
+The SDK provides both asynchronous and synchronous interfaces:
+
+```python
+# Asynchronous (recommended for production)
+agent = await Agent.aload("agent-id")
+task = await agent.acreate_task(prompt="input data")
+
+# Synchronous (convenient for scripts)
+agent = Agent.load("agent-id")
+task = agent.create_task(prompt="input data")
+```
+
+## 📖 Advanced Examples
+
+### Multi-Agent Orchestration
+
+```python
+# Load multiple specialized agents
+agents_list = await agents.alist()
+data_agent = await agents.aget("data-agent-id")
+writer_agent = await agents.aget("writer-agent-id")
+
+# Chain agent executions
+analysis_task = await data_agent.acreate_task(prompt="Analyze sales data")
+report_task = await writer_agent.acreate_task(
+    prompt=f"Write a report based on: {analysis_task.result}"
+)
+```
+
+### Tool Integration with MCP Servers
+
+```python
+from xpander_sdk import MCPServerDetails, MCPServerType
+
+# Configure MCP server
+mcp_server = MCPServerDetails(
+    name="data-server",
+    type=MCPServerType.STDIO,
+    command="python",
+    args=["-m", "mcp_server"],
+    env={"API_KEY": "your-key"}
+)
+
+# MCP servers are configured at the platform level
+# and tools become available through ToolsRepository
+```
+
+### Streaming Task Execution
+
+```python
+# Create a task with event streaming enabled
+task = await agent.acreate_task(
+    prompt="complex analysis task",
+    events_streaming=True
+)
+
+# Stream events from the task
+async for event in task.aevents():
+    print(f"Event Type: {event.type}")
+    print(f"Event Data: {event.data}")
+```
+
+### Task Activity Monitoring
+
+```python
+from xpander_sdk import Task
+from xpander_sdk.models.activity import (
+    AgentActivityThreadMessage,
+    AgentActivityThreadToolCall,
+    AgentActivityThreadReasoning
+)
+
+# Load a completed task
+task = await Task.aload("task-id")
+
+# Get detailed activity log
+activity_log = await task.aget_activity_log()
+
+# Analyze messages between user and agent
+for message in activity_log.messages:
+    if isinstance(message, AgentActivityThreadMessage):
+        print(f"{message.role}: {message.content.text}")
+    elif isinstance(message, AgentActivityThreadToolCall):
+        # Tool call
+        print(f"Tool: {message.tool_name}")
+        print(f"Payload: {message.payload}")
+        print(f"Result: {message.result}")
+    elif isinstance(message, AgentActivityThreadReasoning):
+        # Reasoning step
+        print(f"Reasoning ({message.type}): {message.thought}")
+
+# Synchronous version
+task = Task.load("task-id")
+activity_log = task.get_activity_log()
+```
+
+### Local Task Testing
+
+```python
+from xpander_sdk.modules.tasks.models.task import LocalTaskTest, AgentExecutionInput
+from xpander_sdk.models.shared import OutputFormat
+from xpander_sdk import on_task
+
+# Define a local test task
+local_task = LocalTaskTest(
+    input=AgentExecutionInput(text="What can you do?"),
+    output_format=OutputFormat.Json,
+    output_schema={"capabilities": "list of capabilities"}
+)
+
+# Test with local task
+@on_task(test_task=local_task)
+async def handle_test_task(task):
+    task.result = {
+        "capabilities": [
+            "Data analysis",
+            "Text processing",
+            "API integration"
+        ]
+    }
+    return task
+```
+
+## 🧪 Testing
+
+```bash
+# Run tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=xpander_sdk
+
+# Run specific test
+pytest tests/test_agents.py::test_agent_creation
+```
+
+## 🏗️ Architecture
+
+```plaintext
+xpander_sdk/
+├── core/                   # Core API client and base classes
+├── models/                 # Pydantic models and configurations
+├── modules/
+│   ├── agents/            # Agent management
+│   ├── tasks/             # Task execution
+│   ├── tools_repository/  # Tools and integrations
+│   ├── knowledge_bases/   # Knowledge management
+│   ├── events/            # Event handling
+│   └── backend/           # Agent runtime arguments for frameworks
+└── utils/                 # Utility functions
+```
+
+## 🔒 Authentication
+
+The SDK supports multiple authentication methods:
+
+### Environment Variables (Recommended)
+
+```bash
+export XPANDER_API_KEY="your-api-key"
+export XPANDER_ORGANIZATION_ID="your-org-id"
+export XPANDER_BASE_URL="https://inbound.xpander.ai" # Optional
+export XPANDER_AGENT_ID="your-agent-id" # Optional for Backend module
+```
+
+### Configuration Object
+
+```python
+config = Configuration(
+    api_key="your-api-key",
+    organization_id="your-org-id"
+)
+```
+
+### From File
+
+```python
+# .env file
+XPANDER_API_KEY=your-api-key
+XPANDER_ORGANIZATION_ID=your-org-id
+
+# Python code
+from dotenv import load_dotenv
+load_dotenv()
+config = Configuration()
+```
+
+## 🏢 Self-Hosted Deployment
+
+If you're using a self-hosted xpander.ai deployment, configure the SDK to point to your Agent Controller endpoint.
+
+**Important**: Use the **Agent Controller API key** generated during Helm installation, not your xpander.ai cloud API key.
+
+### Configuration
+
+```bash
+# Set environment variables
+export XPANDER_API_KEY="your-agent-controller-api-key"  # From Helm installation
+export XPANDER_ORGANIZATION_ID="your-org-id"
+export XPANDER_BASE_URL="https://agent-controller.my-company.com"
+```
+
+Or configure explicitly:
+
+```python
+from xpander_sdk import Configuration
+
+config = Configuration(
+    api_key="your-agent-controller-api-key",  # From Helm installation
+    organization_id="your-org-id",
+    base_url="https://agent-controller.my-company.com"
+)
+```
+
+### Using with Agno Framework
+
+```python
+from xpander_sdk import Backend, Configuration
+from agno.agent import Agent
+
+# Configure for self-hosted
+config = Configuration(
+    api_key="your-agent-controller-api-key",  # From Helm installation
+    organization_id="your-org-id",
+    base_url="https://agent-controller.my-company.com"
+)
+
+# Initialize Backend with self-hosted config
+backend = Backend(configuration=config)
+
+# Create agent - it will use your self-hosted infrastructure
+agno_agent = Agent(**backend.get_args(agent_id="agent-123"))
+
+# Run agent
+result = await agno_agent.arun(
+    input="What can you help me with?",
+    stream=True
+)
+```
+
+### Complete Self-Hosted Example
+
+```python
+import asyncio
+from xpander_sdk import Configuration, Agent
+
+async def main():
+    # Configure for self-hosted deployment
+    config = Configuration(
+        api_key="your-agent-controller-api-key",  # From Helm installation
+        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",
+        file_urls=["https://example.com/sales-q4.csv"]
+    )
+    print(f"Task created: {task.id}")
+    print(f"Status: {task.status}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Important**: Make sure your `base_url` points to the Agent Controller endpoint (e.g., `https://agent-controller.{your-domain}`), not the root domain.
+
+📖 **Full Guide**: [Self-Hosted Configuration Documentation](https://docs.xpander.ai/api-reference/configuration/self-hosted)
+
+## 🔄 Error Handling
+
+```python
+from xpander_sdk.exceptions import ModuleException
+
+try:
+    agent = await Agent.aload("invalid-agent-id")
+except ModuleException as e:
+    print(f"Error {e.status_code}: {e.description}")
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/{base_branch}/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat/chore/fix: Add amazing feature'`)
+4. Push to the branch (`git push origin feature/{base_branch}/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🆘 Support
+
+- **Documentation**: [https://docs.xpander.ai](https://docs.xpander.ai)
+- **Issues**: [GitHub Issues](https://github.com/xpander-ai/xpander-sdk/issues)
+- **Email**: support@xpander.ai
+
+---
+
+Built with ❤️ by the xpander.ai team