agentic-fabriq-sdk 0.1.3__py3-none-any.whl

af_sdk/connectors/__init__.py

@@ -0,0 +1,23 @@
+"""
+Connector framework for Agentic Fabric SDK.
+"""
+
+from .base import (
+    AgentConnector,
+    BaseConnector,
+    ConnectorContext,
+    HTTPConnectorMixin,
+    MCPConnector,
+    ToolConnector,
+)
+from .registry import ConnectorRegistry
+
+__all__ = [
+    "BaseConnector",
+    "ToolConnector",
+    "AgentConnector",
+    "MCPConnector",
+    "ConnectorContext",
+    "HTTPConnectorMixin",
+    "ConnectorRegistry",
+] 

af_sdk/connectors/base.py

@@ -0,0 +1,231 @@
+"""
+Base connector classes for Agentic Fabric SDK.
+"""
+
+import abc
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+from pydantic import BaseModel
+
+from ..auth.token_cache import TokenManager
+from ..exceptions import ConnectorError
+
+
+class ConnectorContext(BaseModel):
+    """Context object passed to connector instances."""
+
+    tenant_id: str
+    user_id: Optional[str] = None
+    http: httpx.AsyncClient
+    token_manager: "TokenManager"
+    logger: logging.Logger
+    metadata: Dict[str, Any] = {}
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class BaseConnector(abc.ABC):
+    """Base class for all connectors."""
+
+    def __init__(self, ctx: ConnectorContext):
+        self.ctx = ctx
+        self.session = ctx.http
+        self.logger = ctx.logger
+        self.token_manager = ctx.token_manager
+
+    @abc.abstractmethod
+    async def invoke(self, method: str, **kwargs) -> Any:
+        """Generic fallback invocation method."""
+        pass
+
+    async def health_check(self) -> Dict[str, Any]:
+        """Health check for the connector."""
+        return {"status": "healthy", "connector": self.__class__.__name__}
+
+    def get_metadata(self) -> Dict[str, Any]:
+        """Get connector metadata."""
+        return {
+            "name": self.__class__.__name__,
+            "version": getattr(self, "__version__", "unknown"),
+            "description": self.__doc__ or "No description available",
+        }
+
+
+class ToolConnector(BaseConnector):
+    """Base class for tool connectors."""
+
+    # Override in subclass
+    TOOL_ID: str = ""
+
+    def __init__(self, ctx: ConnectorContext):
+        super().__init__(ctx)
+        if not self.TOOL_ID:
+            raise ConnectorError("TOOL_ID must be set in connector subclass")
+
+    @abc.abstractmethod
+    async def invoke(self, method: str, **kwargs) -> Any:
+        """
+        Invoke a tool method.
+        
+        Args:
+            method: The tool method to invoke
+            **kwargs: Method arguments
+            
+        Returns:
+            The result of the tool invocation
+        """
+        pass
+
+    async def get_schema(self) -> Dict[str, Any]:
+        """Get the tool schema/specification."""
+        return {
+            "tool_id": self.TOOL_ID,
+            "methods": self._get_available_methods(),
+            "auth_required": True,
+            "scopes": getattr(self, "REQUIRED_SCOPES", []),
+        }
+
+    def _get_available_methods(self) -> list[str]:
+        """Get list of available methods for this tool."""
+        methods = []
+        for attr_name in dir(self):
+            if not attr_name.startswith("_") and callable(getattr(self, attr_name)):
+                attr = getattr(self, attr_name)
+                if hasattr(attr, "__annotations__") and not attr_name in [
+                    "invoke",
+                    "health_check",
+                    "get_metadata",
+                    "get_schema",
+                ]:
+                    methods.append(attr_name)
+        return methods
+
+
+class AgentConnector(BaseConnector):
+    """Base class for agent connectors that speak A2A or MCP."""
+
+    AGENT_ID: str = ""
+
+    def __init__(self, ctx: ConnectorContext):
+        super().__init__(ctx)
+        if not self.AGENT_ID:
+            raise ConnectorError("AGENT_ID must be set in connector subclass")
+
+    @abc.abstractmethod
+    async def invoke(self, input_text: str, **params) -> str:
+        """
+        Invoke the agent.
+        
+        Args:
+            input_text: The input text/prompt for the agent
+            **params: Additional parameters for the agent
+            
+        Returns:
+            The agent's response
+        """
+        pass
+
+    async def get_capabilities(self) -> Dict[str, Any]:
+        """Get agent capabilities."""
+        return {
+            "agent_id": self.AGENT_ID,
+            "supports_streaming": getattr(self, "SUPPORTS_STREAMING", False),
+            "max_tokens": getattr(self, "MAX_TOKENS", None),
+            "supported_models": getattr(self, "SUPPORTED_MODELS", []),
+        }
+
+    async def validate_input(self, input_text: str, **params) -> bool:
+        """Validate input before processing."""
+        if not input_text or not input_text.strip():
+            return False
+        return True
+
+
+class MCPConnector(BaseConnector):
+    """Base class for MCP (Model Context Protocol) connectors."""
+
+    MCP_VERSION: str = "1.0"
+    SERVER_NAME: str = ""
+
+    def __init__(self, ctx: ConnectorContext):
+        super().__init__(ctx)
+        if not self.SERVER_NAME:
+            raise ConnectorError("SERVER_NAME must be set in MCP connector subclass")
+
+    @abc.abstractmethod
+    async def list_tools(self) -> list[Dict[str, Any]]:
+        """List available tools from the MCP server."""
+        pass
+
+    @abc.abstractmethod
+    async def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Any:
+        """Call a specific tool on the MCP server."""
+        pass
+
+    async def invoke(self, method: str, **kwargs) -> Any:
+        """Generic invoke method for MCP connectors."""
+        if method == "list_tools":
+            return await self.list_tools()
+        elif method == "call_tool":
+            return await self.call_tool(
+                kwargs.get("tool_name", ""), kwargs.get("arguments", {})
+            )
+        else:
+            raise ConnectorError(f"Unknown method: {method}")
+
+    async def get_server_info(self) -> Dict[str, Any]:
+        """Get MCP server information."""
+        return {
+            "name": self.SERVER_NAME,
+            "version": self.MCP_VERSION,
+            "tools": await self.list_tools(),
+        }
+
+
+class HTTPConnectorMixin:
+    """Mixin for connectors that make HTTP requests."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.base_url = kwargs.get("base_url", "")
+        self.default_headers = kwargs.get("default_headers", {})
+
+    async def _make_request(
+        self,
+        method: str,
+        path: str,
+        headers: Optional[Dict[str, str]] = None,
+        **kwargs,
+    ) -> httpx.Response:
+        """Make an HTTP request with proper error handling."""
+        url = f"{self.base_url.rstrip('/')}/{path.lstrip('/')}"
+        request_headers = {**self.default_headers, **(headers or {})}
+
+        try:
+            response = await self.session.request(
+                method, url, headers=request_headers, **kwargs
+            )
+            response.raise_for_status()
+            return response
+        except httpx.HTTPError as e:
+            self.logger.error(f"HTTP request failed: {e}")
+            raise ConnectorError(f"HTTP request failed: {e}")
+
+    async def _get(self, path: str, **kwargs) -> httpx.Response:
+        """Make a GET request."""
+        return await self._make_request("GET", path, **kwargs)
+
+    async def _post(self, path: str, **kwargs) -> httpx.Response:
+        """Make a POST request."""
+        return await self._make_request("POST", path, **kwargs)
+
+    async def _put(self, path: str, **kwargs) -> httpx.Response:
+        """Make a PUT request."""
+        return await self._make_request("PUT", path, **kwargs)
+
+    async def _delete(self, path: str, **kwargs) -> httpx.Response:
+        """Make a DELETE request."""
+        return await self._make_request("DELETE", path, **kwargs) 

af_sdk/connectors/registry.py

@@ -0,0 +1,262 @@
+"""
+Connector registry for plugin discovery and management.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Type
+
+from stevedore import driver, named
+
+from ..exceptions import ConnectorError
+from .base import BaseConnector, ConnectorContext
+
+
+class ConnectorRegistry:
+    """Registry for managing connector plugins."""
+
+    def __init__(self, logger: Optional[logging.Logger] = None):
+        self.logger = logger or logging.getLogger(__name__)
+        self._loaded_connectors: Dict[str, Type[BaseConnector]] = {}
+
+    def load_connector(self, connector_id: str) -> Type[BaseConnector]:
+        """
+        Load a connector by ID.
+
+        Args:
+            connector_id: The connector ID (e.g., 'slack', 'github')
+
+        Returns:
+            The connector class
+
+        Raises:
+            ConnectorError: If connector cannot be loaded
+        """
+        if connector_id in self._loaded_connectors:
+            return self._loaded_connectors[connector_id]
+
+        try:
+            # Load via stevedore
+            mgr = driver.DriverManager(
+                namespace="af_connector_plugins",
+                name=connector_id,
+                invoke_on_load=False,
+            )
+            connector_class = mgr.driver
+            
+            # Validate connector class
+            if not issubclass(connector_class, BaseConnector):
+                raise ConnectorError(
+                    f"Connector {connector_id} must inherit from BaseConnector"
+                )
+
+            self._loaded_connectors[connector_id] = connector_class
+            self.logger.info(f"Loaded connector: {connector_id}")
+            return connector_class
+
+        except Exception as e:
+            self.logger.error(f"Failed to load connector {connector_id}: {e}")
+            raise ConnectorError(f"Failed to load connector {connector_id}: {e}")
+
+    def list_available_connectors(self) -> List[str]:
+        """
+        List all available connector IDs.
+
+        Returns:
+            List of connector IDs
+        """
+        try:
+            from stevedore import extension
+            mgr = extension.ExtensionManager(
+                namespace="af_connector_plugins",
+                invoke_on_load=False,
+            )
+            return [ep.name for ep in mgr.extensions]
+        except Exception as e:
+            self.logger.error(f"Failed to list connectors: {e}")
+            return []
+
+    def get_connector_info(self, connector_id: str) -> Dict[str, Any]:
+        """
+        Get information about a connector.
+
+        Args:
+            connector_id: The connector ID
+
+        Returns:
+            Connector information
+        """
+        try:
+            connector_class = self.load_connector(connector_id)
+            return {
+                "id": connector_id,
+                "name": connector_class.__name__,
+                "description": connector_class.__doc__ or "No description",
+                "version": getattr(connector_class, "__version__", "unknown"),
+                "tool_id": getattr(connector_class, "TOOL_ID", None),
+                "agent_id": getattr(connector_class, "AGENT_ID", None),
+                "required_scopes": getattr(connector_class, "REQUIRED_SCOPES", []),
+            }
+        except Exception as e:
+            return {
+                "id": connector_id,
+                "error": str(e),
+            }
+
+    def create_connector_instance(
+        self, connector_id: str, context: ConnectorContext
+    ) -> BaseConnector:
+        """
+        Create a connector instance.
+
+        Args:
+            connector_id: The connector ID
+            context: Connector context
+
+        Returns:
+            Connector instance
+
+        Raises:
+            ConnectorError: If connector cannot be created
+        """
+        try:
+            connector_class = self.load_connector(connector_id)
+            return connector_class(context)
+        except Exception as e:
+            self.logger.error(f"Failed to create connector {connector_id}: {e}")
+            raise ConnectorError(f"Failed to create connector {connector_id}: {e}")
+
+    def load_multiple_connectors(self, connector_ids: List[str]) -> Dict[str, Type[BaseConnector]]:
+        """
+        Load multiple connectors.
+
+        Args:
+            connector_ids: List of connector IDs
+
+        Returns:
+            Dictionary of connector_id -> connector_class
+        """
+        try:
+            mgr = named.NamedExtensionManager(
+                namespace="af_connector_plugins",
+                names=connector_ids,
+                invoke_on_load=False,
+            )
+            
+            result = {}
+            for ext in mgr.extensions:
+                connector_class = ext.obj
+                if not issubclass(connector_class, BaseConnector):
+                    self.logger.warning(
+                        f"Skipping {ext.name}: not a BaseConnector subclass"
+                    )
+                    continue
+                
+                result[ext.name] = connector_class
+                self._loaded_connectors[ext.name] = connector_class
+            
+            return result
+        except Exception as e:
+            self.logger.error(f"Failed to load connectors {connector_ids}: {e}")
+            raise ConnectorError(f"Failed to load connectors: {e}")
+
+    def validate_connector(self, connector_id: str) -> bool:
+        """
+        Validate a connector.
+
+        Args:
+            connector_id: The connector ID
+
+        Returns:
+            True if connector is valid, False otherwise
+        """
+        try:
+            connector_class = self.load_connector(connector_id)
+            
+            # Check required attributes
+            if hasattr(connector_class, "TOOL_ID"):
+                if not connector_class.TOOL_ID:
+                    self.logger.error(f"Connector {connector_id} has empty TOOL_ID")
+                    return False
+            elif hasattr(connector_class, "AGENT_ID"):
+                if not connector_class.AGENT_ID:
+                    self.logger.error(f"Connector {connector_id} has empty AGENT_ID")
+                    return False
+            else:
+                self.logger.error(f"Connector {connector_id} missing TOOL_ID or AGENT_ID")
+                return False
+            
+            # Check required methods
+            if not hasattr(connector_class, "invoke"):
+                self.logger.error(f"Connector {connector_id} missing invoke method")
+                return False
+            
+            return True
+        except Exception as e:
+            self.logger.error(f"Connector {connector_id} validation failed: {e}")
+            return False
+
+    def get_connector_schema(self, connector_id: str) -> Dict[str, Any]:
+        """
+        Get the schema for a connector.
+
+        Args:
+            connector_id: The connector ID
+
+        Returns:
+            Connector schema
+        """
+        try:
+            connector_class = self.load_connector(connector_id)
+            
+            # Create a dummy context for schema generation
+            import logging
+            import httpx
+            from ..auth.token_cache import TokenManager, VaultClient
+            
+            dummy_http = httpx.AsyncClient()
+            dummy_vault = VaultClient("http://localhost", dummy_http, logging.getLogger())
+            dummy_token_manager = TokenManager("default", dummy_vault)
+            
+            dummy_context = ConnectorContext(
+                tenant_id="default",
+                user_id="system",
+                http=dummy_http,
+                token_manager=dummy_token_manager,
+                logger=logging.getLogger(),
+            )
+            
+            # Create instance to get schema
+            instance = connector_class(dummy_context)
+            
+            if hasattr(instance, "get_schema"):
+                return instance.get_schema()
+            else:
+                return {
+                    "connector_id": connector_id,
+                    "methods": [],
+                    "description": "Schema not available",
+                }
+        except Exception as e:
+            self.logger.error(f"Failed to get schema for {connector_id}: {e}")
+            return {
+                "connector_id": connector_id,
+                "error": str(e),
+            }
+
+    def clear_cache(self):
+        """Clear the connector cache."""
+        self._loaded_connectors.clear()
+        self.logger.info("Connector cache cleared")
+
+    def get_loaded_connectors(self) -> Dict[str, Type[BaseConnector]]:
+        """Get all loaded connectors."""
+        return self._loaded_connectors.copy()
+
+
+# Global registry instance
+_registry = ConnectorRegistry()
+
+
+def get_connector_registry() -> ConnectorRegistry:
+    """Get the global connector registry."""
+    return _registry 

af_sdk/dx/__init__.py

@@ -0,0 +1,12 @@
+from .decorators import tool
+from .runtime import ToolFabric, AgentFabric, MCPServer, Agent
+
+__all__ = [
+  "tool",
+  "ToolFabric",
+  "AgentFabric",
+  "MCPServer",
+  "Agent",
+]
+
+

af_sdk/dx/decorators.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+from functools import wraps
+
+
+class ToolFunction:
+    """Simple wrapper that carries metadata for a Python function tool."""
+
+    def __init__(self, fn: Callable[..., Any], name: Optional[str] = None, description: Optional[str] = None):
+        self.fn = fn
+        self.name = name or fn.__name__
+        self.description = description or (fn.__doc__ or "")
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.fn(*args, **kwargs)
+
+    def spec(self) -> Dict[str, Any]:
+        return {"name": self.name, "description": self.description}
+
+
+def tool(fn: Callable[..., Any] | None = None, *, name: Optional[str] = None, description: Optional[str] = None):
+    """Decorator to mark a function as a tool.
+
+    Usage:
+        @tool
+        def do(x: str) -> str: ...
+    """
+
+    def _wrap(func: Callable[..., Any]) -> ToolFunction:
+        wrapped = ToolFunction(func, name=name, description=description)
+        @wraps(func)
+        def inner(*args: Any, **kwargs: Any) -> Any:
+            return wrapped(*args, **kwargs)
+        inner._af_tool = wrapped  # type: ignore[attr-defined]
+        return inner  # type: ignore[return-value]
+
+    return _wrap if fn is None else _wrap(fn)
+
+