PraisonAI 3.0.0__py3-none-any.whl

praisonai/endpoints/providers/agents_api.py

@@ -0,0 +1,171 @@
+"""
+Agents API Provider
+
+Provider adapter for agents-as-API endpoints (single agent or multi-agent router).
+"""
+
+from typing import Any, Dict, List, Optional
+
+from .base import BaseProvider, InvokeResult, HealthResult
+from ..discovery import EndpointInfo, ProviderInfo
+
+
+class AgentsAPIProvider(BaseProvider):
+    """
+    Provider adapter for agents-as-API endpoints.
+    
+    Connects to FastAPI-based agent servers launched via Agent.launch() or Agents.launch()
+    and provides unified discovery and invocation interface.
+    """
+    
+    provider_type = "agents-api"
+    
+    def get_provider_info(self) -> ProviderInfo:
+        """Get provider information."""
+        return ProviderInfo(
+            type=self.provider_type,
+            name="Agents API",
+            description="Agent HTTP API endpoints",
+            capabilities=["list", "describe", "invoke", "health"],
+        )
+    
+    def list_endpoints(self, tags: Optional[List[str]] = None) -> List[EndpointInfo]:
+        """List available agent endpoints."""
+        # Try unified discovery first
+        result = self._make_request("GET", "/__praisonai__/discovery")
+        
+        if not result.get("error") and result.get("data"):
+            data = result.get("data", {})
+            endpoints = []
+            for ep in data.get("endpoints", []):
+                if ep.get("provider_type") == self.provider_type:
+                    endpoints.append(EndpointInfo(
+                        name=ep.get("name", ""),
+                        description=ep.get("description", ""),
+                        provider_type=self.provider_type,
+                        tags=ep.get("tags", []),
+                        version=ep.get("version", "1.0.0"),
+                        streaming=ep.get("streaming", ["none"]),
+                        auth_modes=ep.get("auth_modes", ["none"]),
+                    ))
+            return endpoints
+        
+        # Fallback: try root endpoint for endpoint list
+        result = self._make_request("GET", "/")
+        
+        if result.get("error"):
+            return []
+        
+        data = result.get("data", {})
+        endpoint_paths = data.get("endpoints", [])
+        
+        endpoints = []
+        for path in endpoint_paths:
+            endpoints.append(EndpointInfo(
+                name=path.lstrip("/"),
+                description=f"Agent endpoint at {path}",
+                provider_type=self.provider_type,
+                streaming=["none"],
+                auth_modes=["none"],
+            ))
+        
+        return endpoints
+    
+    def describe_endpoint(self, name: str) -> Optional[EndpointInfo]:
+        """Get detailed information about an agent endpoint."""
+        # Try unified discovery first
+        result = self._make_request("GET", "/__praisonai__/discovery")
+        
+        if not result.get("error") and result.get("data"):
+            data = result.get("data", {})
+            for ep in data.get("endpoints", []):
+                if ep.get("name") == name:
+                    return EndpointInfo(
+                        name=ep.get("name", name),
+                        description=ep.get("description", ""),
+                        provider_type=self.provider_type,
+                        tags=ep.get("tags", []),
+                        version=ep.get("version", "1.0.0"),
+                        input_schema=ep.get("input_schema"),
+                        output_schema=ep.get("output_schema"),
+                        streaming=ep.get("streaming", ["none"]),
+                        auth_modes=ep.get("auth_modes", ["none"]),
+                        metadata=ep.get("metadata", {}),
+                    )
+        
+        # Fallback: return basic info
+        return EndpointInfo(
+            name=name,
+            description=f"Agent endpoint: {name}",
+            provider_type=self.provider_type,
+            input_schema={"type": "object", "properties": {"query": {"type": "string"}}},
+            streaming=["none"],
+            auth_modes=["none"],
+        )
+    
+    def invoke(
+        self,
+        name: str,
+        input_data: Optional[Dict[str, Any]] = None,
+        config: Optional[Dict[str, Any]] = None,
+        stream: bool = False,
+    ) -> InvokeResult:
+        """Invoke an agent endpoint."""
+        # Normalize endpoint path
+        path = name if name.startswith("/") else f"/{name}"
+        
+        # Build request body
+        body = input_data or {}
+        if "query" not in body and config and "query" in config:
+            body["query"] = config["query"]
+        
+        result = self._make_request("POST", path, json_data=body)
+        
+        if result.get("status") == 401:
+            return InvokeResult(
+                ok=False,
+                status="auth_error",
+                error="Authentication required",
+            )
+        
+        if result.get("status") == 404:
+            return InvokeResult(
+                ok=False,
+                status="not_found",
+                error=f"Endpoint not found: {name}",
+            )
+        
+        if result.get("error"):
+            return InvokeResult(
+                ok=False,
+                status="error",
+                error=result["error"].get("message", str(result["error"])),
+            )
+        
+        data = result.get("data", {})
+        return InvokeResult(
+            ok=True,
+            status="success",
+            data=data.get("response", data),
+        )
+    
+    def health(self) -> HealthResult:
+        """Check agent server health."""
+        result = self._make_request("GET", "/health")
+        
+        if result.get("error"):
+            return HealthResult(
+                healthy=False,
+                status="unhealthy",
+                provider_type=self.provider_type,
+                metadata={"error": result["error"].get("message", str(result["error"]))},
+            )
+        
+        data = result.get("data", {})
+        return HealthResult(
+            healthy=data.get("status") == "ok",
+            status=data.get("status", "unknown"),
+            server_name="PraisonAI Agents API",
+            provider_type=self.provider_type,
+            metadata={"endpoints": data.get("endpoints", [])},
+        )

praisonai/endpoints/providers/base.py

@@ -0,0 +1,231 @@
+"""
+Base Provider Interface
+
+Abstract base class for all provider adapters.
+Each provider implements discovery, invocation, and health check methods.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, Iterator, List, Optional
+
+from ..discovery import EndpointInfo, ProviderInfo
+
+
+@dataclass
+class InvokeResult:
+    """Result from invoking an endpoint."""
+    ok: bool
+    status: str = "success"
+    data: Optional[Any] = None
+    error: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "ok": self.ok,
+            "status": self.status,
+            "data": self.data,
+            "error": self.error,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class HealthResult:
+    """Result from health check."""
+    healthy: bool
+    status: str = "healthy"
+    server_name: Optional[str] = None
+    server_version: Optional[str] = None
+    provider_type: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "healthy": self.healthy,
+            "status": self.status,
+            "server_name": self.server_name,
+            "server_version": self.server_version,
+            "provider_type": self.provider_type,
+            "metadata": self.metadata,
+        }
+
+
+class BaseProvider(ABC):
+    """
+    Abstract base class for provider adapters.
+    
+    Each provider type (recipe, agents-api, mcp, etc.) implements this interface
+    to provide consistent discovery and invocation behavior.
+    """
+    
+    # Provider type identifier
+    provider_type: str = "base"
+    
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8765",
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        """
+        Initialize the provider.
+        
+        Args:
+            base_url: Base URL of the server
+            api_key: Optional API key for authentication
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+    
+    @abstractmethod
+    def get_provider_info(self) -> ProviderInfo:
+        """
+        Get provider information.
+        
+        Returns:
+            ProviderInfo with provider details
+        """
+        pass
+    
+    @abstractmethod
+    def list_endpoints(self, tags: Optional[List[str]] = None) -> List[EndpointInfo]:
+        """
+        List available endpoints.
+        
+        Args:
+            tags: Optional list of tags to filter by
+            
+        Returns:
+            List of EndpointInfo objects
+        """
+        pass
+    
+    @abstractmethod
+    def describe_endpoint(self, name: str) -> Optional[EndpointInfo]:
+        """
+        Get detailed information about an endpoint.
+        
+        Args:
+            name: Endpoint name
+            
+        Returns:
+            EndpointInfo or None if not found
+        """
+        pass
+    
+    @abstractmethod
+    def invoke(
+        self,
+        name: str,
+        input_data: Optional[Dict[str, Any]] = None,
+        config: Optional[Dict[str, Any]] = None,
+        stream: bool = False,
+    ) -> InvokeResult:
+        """
+        Invoke an endpoint.
+        
+        Args:
+            name: Endpoint name
+            input_data: Input data for the endpoint
+            config: Optional configuration overrides
+            stream: Whether to stream the response
+            
+        Returns:
+            InvokeResult with response data
+        """
+        pass
+    
+    def invoke_stream(
+        self,
+        name: str,
+        input_data: Optional[Dict[str, Any]] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        """
+        Invoke an endpoint with streaming.
+        
+        Args:
+            name: Endpoint name
+            input_data: Input data for the endpoint
+            config: Optional configuration overrides
+            
+        Yields:
+            Stream events as dictionaries
+        """
+        # Default implementation - subclasses can override
+        result = self.invoke(name, input_data, config, stream=True)
+        if result.ok:
+            yield {"event": "complete", "data": result.data}
+        else:
+            yield {"event": "error", "data": {"error": result.error}}
+    
+    @abstractmethod
+    def health(self) -> HealthResult:
+        """
+        Check server health.
+        
+        Returns:
+            HealthResult with health status
+        """
+        pass
+    
+    def _make_request(
+        self,
+        method: str,
+        path: str,
+        json_data: Optional[Dict] = None,
+    ) -> Dict[str, Any]:
+        """
+        Make HTTP request to server.
+        
+        Args:
+            method: HTTP method
+            path: URL path
+            json_data: Optional JSON body
+            
+        Returns:
+            Response data dictionary
+        """
+        import json
+        import urllib.request
+        import urllib.error
+        
+        full_url = f"{self.base_url}{path}"
+        
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        
+        data = None
+        if json_data:
+            data = json.dumps(json_data).encode("utf-8")
+        
+        try:
+            req = urllib.request.Request(
+                full_url,
+                data=data,
+                headers=headers,
+                method=method,
+            )
+            
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                body = response.read().decode("utf-8")
+                return {"status": response.status, "data": json.loads(body) if body else {}}
+                
+        except urllib.error.HTTPError as e:
+            body = e.read().decode("utf-8") if e.fp else ""
+            try:
+                error_data = json.loads(body) if body else {}
+            except json.JSONDecodeError:
+                error_data = {"message": body}
+            return {"status": e.code, "error": error_data}
+        except urllib.error.URLError as e:
+            return {"status": 0, "error": {"message": f"Connection error: {e.reason}"}}
+        except Exception as e:
+            return {"status": 0, "error": {"message": str(e)}}

praisonai/endpoints/providers/mcp.py

@@ -0,0 +1,263 @@
+"""
+MCP Provider
+
+Provider adapter for MCP server endpoints (stdio, http, sse).
+"""
+
+from typing import Any, Dict, Iterator, List, Optional
+
+from .base import BaseProvider, InvokeResult, HealthResult
+from ..discovery import EndpointInfo, ProviderInfo
+
+
+class MCPProvider(BaseProvider):
+    """
+    Provider adapter for MCP server endpoints.
+    
+    Supports multiple MCP transport types:
+    - stdio: Standard input/output (requires subprocess)
+    - http: HTTP-based MCP server
+    - sse: Server-Sent Events MCP gateway
+    """
+    
+    provider_type = "mcp"
+    
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8765",
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: str = "http",
+        command: Optional[str] = None,
+        args: Optional[List[str]] = None,
+        env: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Initialize MCP provider.
+        
+        Args:
+            base_url: Base URL for HTTP/SSE transport
+            api_key: Optional API key
+            timeout: Request timeout
+            transport: Transport type (stdio, http, sse)
+            command: Command for stdio transport
+            args: Command arguments for stdio transport
+            env: Environment variables for stdio transport
+        """
+        super().__init__(base_url, api_key, timeout)
+        self.transport = transport
+        self.command = command
+        self.args = args or []
+        self.env = env or {}
+    
+    def get_provider_info(self) -> ProviderInfo:
+        """Get provider information."""
+        return ProviderInfo(
+            type=self.provider_type,
+            name="MCP Server",
+            description=f"MCP server ({self.transport} transport)",
+            capabilities=["list-tools", "call-tool", "list-resources"],
+        )
+    
+    def list_endpoints(self, tags: Optional[List[str]] = None) -> List[EndpointInfo]:
+        """List available MCP tools as endpoints."""
+        if self.transport == "stdio":
+            return self._list_stdio_tools(tags)
+        else:
+            return self._list_http_tools(tags)
+    
+    def _list_stdio_tools(self, tags: Optional[List[str]] = None) -> List[EndpointInfo]:
+        """List tools from stdio MCP server."""
+        try:
+            from praisonaiagents.mcp import MCP
+            
+            mcp = MCP(command=self.command, args=self.args, env=self.env)
+            tools = mcp.get_tools()
+            
+            endpoints = []
+            for tool in tools:
+                tool_name = getattr(tool, 'name', str(tool))
+                tool_desc = getattr(tool, 'description', '')
+                
+                endpoints.append(EndpointInfo(
+                    name=tool_name,
+                    description=tool_desc,
+                    provider_type=self.provider_type,
+                    streaming=["mcp-stream"],
+                    auth_modes=["none"],
+                    metadata={"transport": "stdio"},
+                ))
+            
+            return endpoints
+        except Exception:
+            return []
+    
+    def _list_http_tools(self, tags: Optional[List[str]] = None) -> List[EndpointInfo]:
+        """List tools from HTTP MCP server."""
+        # Try unified discovery first
+        result = self._make_request("GET", "/__praisonai__/discovery")
+        
+        if not result.get("error") and result.get("data"):
+            data = result.get("data", {})
+            endpoints = []
+            for ep in data.get("endpoints", []):
+                if ep.get("provider_type") == self.provider_type:
+                    endpoints.append(EndpointInfo(
+                        name=ep.get("name", ""),
+                        description=ep.get("description", ""),
+                        provider_type=self.provider_type,
+                        tags=ep.get("tags", []),
+                        streaming=ep.get("streaming", ["mcp-stream"]),
+                        auth_modes=ep.get("auth_modes", ["none"]),
+                    ))
+            return endpoints
+        
+        # Fallback: try MCP tools endpoint
+        result = self._make_request("GET", "/mcp/tools")
+        
+        if result.get("error"):
+            return []
+        
+        tools = result.get("data", {}).get("tools", [])
+        endpoints = []
+        
+        for tool in tools:
+            endpoints.append(EndpointInfo(
+                name=tool.get("name", ""),
+                description=tool.get("description", ""),
+                provider_type=self.provider_type,
+                input_schema=tool.get("inputSchema"),
+                streaming=["mcp-stream"],
+                auth_modes=["none"],
+            ))
+        
+        return endpoints
+    
+    def describe_endpoint(self, name: str) -> Optional[EndpointInfo]:
+        """Get detailed information about an MCP tool."""
+        endpoints = self.list_endpoints()
+        for ep in endpoints:
+            if ep.name == name:
+                return ep
+        return None
+    
+    def invoke(
+        self,
+        name: str,
+        input_data: Optional[Dict[str, Any]] = None,
+        config: Optional[Dict[str, Any]] = None,
+        stream: bool = False,
+    ) -> InvokeResult:
+        """Invoke an MCP tool."""
+        if self.transport == "stdio":
+            return self._invoke_stdio(name, input_data)
+        else:
+            return self._invoke_http(name, input_data)
+    
+    def _invoke_stdio(self, name: str, input_data: Optional[Dict[str, Any]] = None) -> InvokeResult:
+        """Invoke tool via stdio MCP."""
+        try:
+            from praisonaiagents.mcp import MCP
+            
+            mcp = MCP(command=self.command, args=self.args, env=self.env)
+            tools = mcp.get_tools()
+            
+            for tool in tools:
+                tool_name = getattr(tool, 'name', str(tool))
+                if tool_name == name:
+                    if callable(tool):
+                        result = tool(**(input_data or {}))
+                        return InvokeResult(
+                            ok=True,
+                            status="success",
+                            data=result,
+                        )
+            
+            return InvokeResult(
+                ok=False,
+                status="not_found",
+                error=f"Tool not found: {name}",
+            )
+        except Exception as e:
+            return InvokeResult(
+                ok=False,
+                status="error",
+                error=str(e),
+            )
+    
+    def _invoke_http(self, name: str, input_data: Optional[Dict[str, Any]] = None) -> InvokeResult:
+        """Invoke tool via HTTP MCP."""
+        body = {
+            "tool": name,
+            "arguments": input_data or {},
+        }
+        
+        result = self._make_request("POST", "/mcp/tools/call", json_data=body)
+        
+        if result.get("error"):
+            return InvokeResult(
+                ok=False,
+                status="error",
+                error=result["error"].get("message", str(result["error"])),
+            )
+        
+        data = result.get("data", {})
+        return InvokeResult(
+            ok=True,
+            status="success",
+            data=data.get("result", data),
+        )
+    
+    def invoke_stream(
+        self,
+        name: str,
+        input_data: Optional[Dict[str, Any]] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        """Invoke MCP tool with streaming."""
+        # MCP streaming is tool-specific; for now, wrap sync call
+        result = self.invoke(name, input_data, config)
+        if result.ok:
+            yield {"event": "result", "data": result.data}
+        else:
+            yield {"event": "error", "data": {"error": result.error}}
+    
+    def health(self) -> HealthResult:
+        """Check MCP server health."""
+        if self.transport == "stdio":
+            # For stdio, check if command exists
+            import shutil
+            if self.command and shutil.which(self.command):
+                return HealthResult(
+                    healthy=True,
+                    status="available",
+                    server_name=self.command,
+                    provider_type=self.provider_type,
+                    metadata={"transport": "stdio"},
+                )
+            return HealthResult(
+                healthy=False,
+                status="unavailable",
+                provider_type=self.provider_type,
+                metadata={"error": f"Command not found: {self.command}"},
+            )
+        
+        # HTTP health check
+        result = self._make_request("GET", "/health")
+        
+        if result.get("error"):
+            return HealthResult(
+                healthy=False,
+                status="unhealthy",
+                provider_type=self.provider_type,
+                metadata={"error": result["error"].get("message", str(result["error"]))},
+            )
+        
+        data = result.get("data", {})
+        return HealthResult(
+            healthy=True,
+            status="healthy",
+            server_name=data.get("server_name", "MCP Server"),
+            server_version=data.get("version"),
+            provider_type=self.provider_type,
+        )