agentfield 0.1.22rc2__py3-none-any.whl

agentfield/agent_utils.py

@@ -0,0 +1,269 @@
+import os
+import re
+import socket
+import time
+from typing import Any, Dict, List, Optional, Type
+
+from pydantic import BaseModel, create_model
+
+
+class AgentUtils:
+    """Utility functions extracted from Agent class for better code organization."""
+
+    @staticmethod
+    def detect_input_type(input_data: Any) -> str:
+        """Intelligently detect input type without explicit declarations"""
+
+        if isinstance(input_data, str):
+            # Smart string detection
+            if input_data.startswith(("http://", "https://")):
+                return "image_url" if AgentUtils.is_image_url(input_data) else "url"
+            elif input_data.startswith("data:image"):
+                return "image_base64"
+            elif input_data.startswith("data:audio"):
+                return "audio_base64"
+            elif os.path.isfile(input_data):
+                ext = os.path.splitext(input_data)[1].lower()
+                if ext in [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".tiff"]:
+                    return "image_file"
+                elif ext in [".mp3", ".wav", ".m4a", ".ogg", ".flac", ".aac"]:
+                    return "audio_file"
+                elif ext in [".pdf", ".doc", ".docx", ".txt", ".rtf", ".md"]:
+                    return "document_file"
+                elif ext in [".mp4", ".avi", ".mov", ".wmv", ".flv", ".webm"]:
+                    return "video_file"
+                else:
+                    return "file"
+            return "text"
+
+        elif isinstance(input_data, bytes):
+            # Detect file type from bytes
+            if input_data.startswith(b"\xff\xd8\xff"):  # JPEG
+                return "image_bytes"
+            elif input_data.startswith(b"\x89PNG"):  # PNG
+                return "image_bytes"
+            elif input_data.startswith(b"GIF8"):  # GIF
+                return "image_bytes"
+            elif input_data.startswith(b"RIFF") and b"WAVE" in input_data[:12]:  # WAV
+                return "audio_bytes"
+            elif input_data.startswith(b"ID3") or input_data.startswith(
+                b"\xff\xfb"
+            ):  # MP3
+                return "audio_bytes"
+            elif b"ftyp" in input_data[:20]:  # MP4/M4A
+                return "audio_bytes"
+            elif input_data.startswith(b"%PDF"):  # PDF
+                return "document_bytes"
+            return "binary_data"
+
+        elif isinstance(input_data, dict):
+            # Check for structured input patterns
+            if any(
+                key in input_data for key in ["system", "user", "assistant", "role"]
+            ):
+                return "message_dict"
+            elif any(
+                key in input_data
+                for key in ["image", "image_url", "audio", "file", "text"]
+            ):
+                return "structured_input"
+            return "dict"
+
+        elif isinstance(input_data, list):
+            if len(input_data) > 0:
+                # Check if it's a conversation format
+                if isinstance(input_data[0], dict) and "role" in input_data[0]:
+                    return "conversation_list"
+                # Check if it's multimodal content
+                elif any(isinstance(item, (str, dict)) for item in input_data):
+                    return "multimodal_list"
+            return "list"
+
+        return "unknown"
+
+    @staticmethod
+    def is_image_url(url: str) -> bool:
+        """Check if URL points to an image based on extension or content type"""
+        image_extensions = [
+            ".jpg",
+            ".jpeg",
+            ".png",
+            ".gif",
+            ".webp",
+            ".bmp",
+            ".tiff",
+            ".svg",
+        ]
+        return any(url.lower().endswith(ext) for ext in image_extensions)
+
+    @staticmethod
+    def is_audio_url(url: str) -> bool:
+        """Check if URL points to audio based on extension"""
+        audio_extensions = [".mp3", ".wav", ".m4a", ".ogg", ".flac", ".aac"]
+        return any(url.lower().endswith(ext) for ext in audio_extensions)
+
+    @staticmethod
+    def get_mime_type(extension: str) -> str:
+        """Get MIME type from file extension"""
+        mime_types = {
+            ".jpg": "image/jpeg",
+            ".jpeg": "image/jpeg",
+            ".png": "image/png",
+            ".gif": "image/gif",
+            ".webp": "image/webp",
+            ".bmp": "image/bmp",
+            ".tiff": "image/tiff",
+            ".svg": "image/svg+xml",
+            ".mp3": "audio/mpeg",
+            ".wav": "audio/wav",
+            ".m4a": "audio/mp4",
+            ".ogg": "audio/ogg",
+            ".flac": "audio/flac",
+            ".aac": "audio/aac",
+            ".pdf": "application/pdf",
+            ".doc": "application/msword",
+            ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            ".txt": "text/plain",
+            ".md": "text/markdown",
+            ".rtf": "application/rtf",
+        }
+        return mime_types.get(extension.lower(), "application/octet-stream")
+
+    @staticmethod
+    def map_json_type_to_python(json_type: str) -> Type:
+        """
+        Map JSON Schema types to Python types.
+
+        Args:
+            json_type: JSON Schema type string
+
+        Returns:
+            Python type
+        """
+        type_mapping = {
+            "string": str,
+            "integer": int,
+            "number": float,
+            "boolean": bool,
+            "array": List[Any],
+            "object": Dict[str, Any],
+            "null": type(None),
+        }
+
+        return type_mapping.get(json_type, str)
+
+    @staticmethod
+    def generate_skill_name(server_alias: str, tool_name: str) -> str:
+        """
+        Generate a valid Python function name for the MCP skill.
+
+        Args:
+            server_alias: MCP server alias
+            tool_name: MCP tool name
+
+        Returns:
+            Valid Python function name
+        """
+        # Convert to snake_case and ensure it's a valid Python identifier
+        name = f"{server_alias}_{tool_name}"
+        name = re.sub(
+            r"[^a-zA-Z0-9_]", "_", name
+        )  # Replace invalid chars with underscore
+        name = re.sub(r"_+", "_", name)  # Replace multiple underscores with single
+        name = name.strip("_")  # Remove leading/trailing underscores
+
+        # Ensure it starts with a letter or underscore
+        if name and name[0].isdigit():
+            name = "_" + name
+
+        # Ensure it's not empty
+        if not name:
+            name = f"mcp_tool_{int(time.time())}"
+
+        return name
+
+    @staticmethod
+    def create_input_schema_from_mcp_tool(
+        skill_name: str, tool: Dict[str, Any]
+    ) -> Type[BaseModel]:
+        """
+        Create a Pydantic input schema from MCP tool definition.
+
+        Args:
+            skill_name: Name of the skill function
+            tool: MCP tool definition
+
+        Returns:
+            Pydantic model class for input validation
+        """
+        input_schema = tool.get("input_schema", {})
+        properties = input_schema.get("properties", {})
+        required = input_schema.get("required", [])
+
+        # Create fields for Pydantic model
+        fields = {}
+
+        for prop_name, prop_def in properties.items():
+            prop_type = AgentUtils.map_json_type_to_python(
+                prop_def.get("type", "string")
+            )
+            is_required = prop_name in required
+
+            if is_required:
+                fields[prop_name] = (prop_type, ...)
+            else:
+                default_value = prop_def.get("default")
+                if default_value is not None:
+                    fields[prop_name] = (prop_type, default_value)
+                else:
+                    fields[prop_name] = (Optional[prop_type], None)
+
+        # If no fields defined, create a generic schema
+        if not fields:
+            fields["data"] = (Optional[Dict[str, Any]], None)
+
+        # Create the Pydantic model
+        InputModel = create_model(f"{skill_name}Input", **fields)
+        return InputModel
+
+    @staticmethod
+    def is_port_available(port: int) -> bool:
+        """
+        Check if a port is available for use.
+
+        Args:
+            port: Port number to check
+
+        Returns:
+            True if port is available, False otherwise
+        """
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("localhost", port))
+                return True
+        except OSError:
+            return False
+
+    @staticmethod
+    def serialize_result(result: Any) -> Any:
+        """Convert complex objects to JSON-serializable format"""
+        try:
+            if hasattr(result, "model_dump"):  # Pydantic v2
+                return result.model_dump()
+            elif hasattr(result, "dict"):  # Pydantic v1
+                return result.model_dump()
+            elif hasattr(result, "__dict__"):  # Regular objects with attributes
+                return {
+                    k: AgentUtils.serialize_result(v)
+                    for k, v in result.__dict__.items()
+                }
+            elif isinstance(result, (list, tuple)):
+                return [AgentUtils.serialize_result(item) for item in result]
+            elif isinstance(result, dict):
+                return {k: AgentUtils.serialize_result(v) for k, v in result.items()}
+            else:
+                # Primitive types (str, int, float, bool, None) are already JSON-serializable
+                return result
+        except Exception:
+            # Fallback: convert to string if serialization fails
+            return str(result)

agentfield/agent_workflow.py

@@ -0,0 +1,323 @@
+import inspect
+import time
+from typing import Any, Callable, Dict, Optional
+
+from agentfield.logger import log_debug, log_warn
+
+from .execution_context import (
+    ExecutionContext,
+    get_current_context,
+    set_execution_context,
+    reset_execution_context,
+)
+from fastapi.encoders import jsonable_encoder
+
+
+class AgentWorkflow:
+    """Workflow helper that keeps local execution metadata in sync with AgentField."""
+
+    def __init__(self, agent_instance):
+        self.agent = agent_instance
+
+    # --------------------------------------------------------------------- #
+    # Public API                                                            #
+    # --------------------------------------------------------------------- #
+
+    def replace_function_references(
+        self, original_func: Callable, tracked_func: Callable, func_name: str
+    ) -> None:
+        """Replace the agent attribute with the tracked wrapper."""
+        setattr(self.agent, func_name, tracked_func)
+
+    async def execute_with_tracking(
+        self, original_func: Callable, args: tuple, kwargs: dict
+    ) -> Any:
+        """
+        Execute the wrapped function with automatic workflow instrumentation.
+        """
+
+        reasoner_name = getattr(original_func, "__name__", "reasoner")
+
+        parent_context = self._get_parent_context()
+        execution_context = self._build_execution_context(reasoner_name, parent_context)
+
+        # Ensure this execution is registered when running under an existing workflow
+        execution_context = await self._ensure_execution_registered(
+            execution_context, reasoner_name, parent_context
+        )
+
+        call_args = args
+        call_kwargs = dict(kwargs or {})
+        signature = self._safe_signature(original_func)
+
+        if "execution_context" in signature.parameters:
+            call_kwargs.setdefault("execution_context", execution_context)
+
+        input_data = self._build_input_payload(signature, call_args, call_kwargs)
+
+        previous_agent_context = getattr(self.agent, "_current_execution_context", None)
+        client_context = getattr(self.agent, "client", None)
+        previous_client_context = None
+        if client_context is not None:
+            previous_client_context = getattr(
+                client_context, "_current_workflow_context", None
+            )
+
+        token = set_execution_context(execution_context)
+        self.agent._current_execution_context = execution_context
+        if client_context is not None:
+            client_context._current_workflow_context = execution_context
+
+        start_time = time.time()
+        parent_execution_id = parent_context.execution_id if parent_context else None
+
+        await self.notify_call_start(
+            execution_context.execution_id,
+            execution_context,
+            reasoner_name,
+            input_data,
+            parent_execution_id=parent_execution_id,
+        )
+
+        try:
+            result = original_func(*call_args, **call_kwargs)
+            if inspect.isawaitable(result):
+                result = await result
+            duration_ms = int((time.time() - start_time) * 1000)
+            await self.notify_call_complete(
+                execution_context.execution_id,
+                execution_context.workflow_id,
+                result,
+                duration_ms,
+                execution_context,
+                input_data=input_data,
+                parent_execution_id=parent_execution_id,
+            )
+            return result
+        except Exception as exc:  # pragma: no cover - re-raised
+            duration_ms = int((time.time() - start_time) * 1000)
+            await self.notify_call_error(
+                execution_context.execution_id,
+                execution_context.workflow_id,
+                str(exc),
+                duration_ms,
+                execution_context,
+                input_data=input_data,
+                parent_execution_id=parent_execution_id,
+            )
+            raise
+        finally:
+            reset_execution_context(token)
+            self.agent._current_execution_context = previous_agent_context
+            if client_context is not None:
+                client_context._current_workflow_context = previous_client_context
+
+    async def notify_call_start(
+        self,
+        execution_id: str,
+        context: ExecutionContext,
+        reasoner_name: str,
+        input_data: Dict[str, Any],
+        *,
+        parent_execution_id: Optional[str] = None,
+    ) -> None:
+        payload = self._build_event_payload(
+            context,
+            reasoner_name,
+            status="running",
+            parent_execution_id=parent_execution_id,
+            input_data=input_data,
+        )
+        await self.fire_and_forget_update(payload)
+
+    async def notify_call_complete(
+        self,
+        execution_id: str,
+        workflow_id: str,
+        result: Any,
+        duration_ms: int,
+        context: ExecutionContext,
+        *,
+        input_data: Optional[Dict[str, Any]] = None,
+        parent_execution_id: Optional[str] = None,
+    ) -> None:
+        payload = self._build_event_payload(
+            context,
+            context.reasoner_name,
+            status="succeeded",
+            parent_execution_id=parent_execution_id,
+            input_data=input_data,
+        )
+        payload["result"] = result
+        payload["duration_ms"] = duration_ms
+        await self.fire_and_forget_update(payload)
+
+    async def notify_call_error(
+        self,
+        execution_id: str,
+        workflow_id: str,
+        error: str,
+        duration_ms: int,
+        context: ExecutionContext,
+        *,
+        input_data: Optional[Dict[str, Any]] = None,
+        parent_execution_id: Optional[str] = None,
+    ) -> None:
+        payload = self._build_event_payload(
+            context,
+            context.reasoner_name,
+            status="failed",
+            parent_execution_id=parent_execution_id,
+            input_data=input_data,
+        )
+        payload["error"] = error
+        payload["duration_ms"] = duration_ms
+        await self.fire_and_forget_update(payload)
+
+    async def fire_and_forget_update(self, payload: Dict[str, Any]) -> None:
+        """Send workflow update to AgentField when a client is available."""
+
+        client = getattr(self.agent, "client", None)
+        base_url = getattr(self.agent, "agentfield_server", None)
+        if not client or not hasattr(client, "_async_request") or not base_url:
+            return
+
+        url = base_url.rstrip("/") + "/api/v1/workflow/executions/events"
+        try:
+            safe_payload = jsonable_encoder(payload)
+            await client._async_request("POST", url, json=safe_payload)
+        except Exception:  # pragma: no cover - best effort logging
+            if getattr(self.agent, "dev_mode", False):
+                log_debug("Failed to publish workflow update", exc_info=True)
+
+    # --------------------------------------------------------------------- #
+    # Internal helpers                                                      #
+    # --------------------------------------------------------------------- #
+
+    def _get_parent_context(self) -> Optional[ExecutionContext]:
+        return (
+            getattr(self.agent, "_current_execution_context", None)
+            or get_current_context()
+        )
+
+    def _build_execution_context(
+        self,
+        reasoner_name: str,
+        parent_context: Optional[ExecutionContext],
+    ) -> ExecutionContext:
+        if parent_context:
+            context = parent_context.create_child_context()
+            context.reasoner_name = reasoner_name
+        else:
+            context = ExecutionContext.create_new(
+                getattr(self.agent, "node_id", "agent"), reasoner_name
+            )
+            context.reasoner_name = reasoner_name
+        context.agent_instance = self.agent
+        return context
+
+    async def _ensure_execution_registered(
+        self,
+        context: ExecutionContext,
+        reasoner_name: str,
+        parent_context: Optional[ExecutionContext],
+    ) -> ExecutionContext:
+        if context.registered:
+            return context
+
+        client = getattr(self.agent, "client", None)
+        base_url = getattr(self.agent, "agentfield_server", None)
+        if not client or not hasattr(client, "_async_request") or not base_url:
+            context.registered = True
+            return context
+
+        payload = {
+            "execution_id": context.execution_id,
+            "run_id": context.run_id,
+            "workflow_id": context.workflow_id,
+            "reasoner_name": reasoner_name,
+            "node_id": getattr(self.agent, "node_id", None),
+            "parent_execution_id": (
+                parent_context.execution_id if parent_context else None
+            ),
+            "parent_workflow_id": (
+                parent_context.workflow_id if parent_context else None
+            ),
+            "session_id": context.session_id,
+            "caller_did": context.caller_did,
+            "target_did": context.target_did,
+            "agent_node_did": context.agent_node_did,
+        }
+
+        url = base_url.rstrip("/") + "/api/v1/workflow/executions"
+        try:
+            response = await client._async_request("POST", url, json=payload)
+            body = response.json() if hasattr(response, "json") else response
+            if isinstance(body, dict):
+                context.execution_id = body.get("execution_id", context.execution_id)
+                context.workflow_id = body.get("workflow_id", context.workflow_id)
+                context.run_id = body.get("run_id", context.run_id)
+        except Exception as exc:  # pragma: no cover - network failure path
+            if getattr(self.agent, "dev_mode", False):
+                log_warn(f"Workflow registration failed: {exc}")
+        finally:
+            context.registered = True
+
+        return context
+
+    @staticmethod
+    def _safe_signature(func: Callable) -> inspect.Signature:
+        try:
+            return inspect.signature(func)
+        except (TypeError, ValueError):
+            return inspect.Signature()
+
+    def _build_event_payload(
+        self,
+        context: ExecutionContext,
+        reasoner_name: str,
+        *,
+        status: str,
+        parent_execution_id: Optional[str],
+        input_data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "execution_id": context.execution_id,
+            "workflow_id": context.workflow_id,
+            "run_id": context.run_id,
+            "reasoner_id": reasoner_name,
+            "agent_node_id": getattr(self.agent, "node_id", None),
+            "status": status,
+            "type": reasoner_name,
+            "parent_execution_id": parent_execution_id,
+            "parent_workflow_id": context.parent_workflow_id,
+        }
+        if input_data is not None:
+            payload["input_data"] = input_data
+        return payload
+
+    @staticmethod
+    def _build_input_payload(
+        signature: inspect.Signature, args: tuple, kwargs: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        if not signature.parameters:
+            return dict(kwargs)
+
+        try:
+            bound = signature.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+        except Exception:
+            # Fallback when binding fails (e.g., C extensions)
+            payload = {f"arg_{idx}": value for idx, value in enumerate(args)}
+            payload.update(kwargs)
+            return payload
+
+        payload = {}
+        for name, value in bound.arguments.items():
+            if name == "self":
+                continue
+            payload[name] = value
+        return payload
+
+
+__all__ = ["AgentWorkflow"]