jaf-py 2.5.1__tar.gz → 2.5.3__tar.gz

{jaf_py-2.5.1/jaf_py.egg-info → jaf_py-2.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jaf-py
-Version: 2.5.1
+Version: 2.5.3
 Summary: A purely functional agent framework with immutable state and composable tools - Python implementation
 Author: JAF Contributors
 Maintainer: JAF Contributors
@@ -82,7 +82,7 @@ Dynamic: license-file
 
 <!-- ![JAF Banner](docs/cover.png) -->
 
-[![Version](https://img.shields.io/badge/version-2.3.1-blue.svg)](https://github.com/xynehq/jaf-py)
+[![Version](https://img.shields.io/badge/version-2.5.3-blue.svg)](https://github.com/xynehq/jaf-py)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![Docs](https://img.shields.io/badge/Docs-Live-brightgreen)](https://xynehq.github.io/jaf-py/)
 

{jaf_py-2.5.1 → jaf_py-2.5.3}/README.md

@@ -2,7 +2,7 @@
 
 <!-- ![JAF Banner](docs/cover.png) -->
 
-[![Version](https://img.shields.io/badge/version-2.3.1-blue.svg)](https://github.com/xynehq/jaf-py)
+[![Version](https://img.shields.io/badge/version-2.5.3-blue.svg)](https://github.com/xynehq/jaf-py)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![Docs](https://img.shields.io/badge/Docs-Live-brightgreen)](https://xynehq.github.io/jaf-py/)
 

{jaf_py-2.5.1 → jaf_py-2.5.3}/jaf/__init__.py

@@ -191,7 +191,7 @@ def generate_run_id() -> RunId:
     """Generate a new run ID."""
     return create_run_id(str(uuid.uuid4()))
 
-__version__ = "2.0.0"
+__version__ = "2.5.3"
 __all__ = [
     # Core types and functions
     "TraceId", "RunId", "ValidationResult", "Message", "ModelConfig",

{jaf_py-2.5.1 → jaf_py-2.5.3}/jaf/core/__init__.py

@@ -22,6 +22,7 @@ from .parallel_agents import (
     create_domain_experts_tool,
 )
 from .proxy import ProxyConfig, ProxyAuth, create_proxy_config, get_default_proxy_config
+from .handoff import handoff_tool, handoff, create_handoff_tool, is_handoff_request, extract_handoff_target
 
 __all__ = [
     "Agent",
@@ -52,6 +53,7 @@ __all__ = [
     "create_conditional_enabler",
     "create_default_output_extractor",
     "create_domain_experts_tool",
+    "create_handoff_tool",
     "create_json_output_extractor",
     "create_language_specialists_tool",
     "create_parallel_agents_tool",
@@ -59,8 +61,12 @@ __all__ = [
     "create_run_id",
     "create_simple_parallel_tool",
     "create_trace_id",
+    "extract_handoff_target",
     "get_current_run_config",
     "get_default_proxy_config",
+    "handoff",
+    "handoff_tool",
+    "is_handoff_request",
     "require_permissions",
     "run",
     "set_current_run_config",

jaf_py-2.5.3/jaf/core/handoff.py

@@ -0,0 +1,191 @@
+"""
+Handoff system for JAF framework.
+
+This module provides a simple, elegant handoff mechanism that allows agents
+to seamlessly transfer control to other agents with clean state management.
+"""
+
+import json
+from typing import Any, Optional, TypeVar
+from dataclasses import dataclass
+
+from .types import Tool, ToolSchema, ToolSource
+
+try:
+    from pydantic import BaseModel, Field
+except ImportError:
+    BaseModel = None
+    Field = None
+
+Ctx = TypeVar('Ctx')
+
+
+def _create_handoff_json(agent_name: str, message: str = "") -> str:
+    """Create the JSON structure for handoff requests."""
+    return json.dumps({
+        "handoff_to": agent_name,
+        "message": message or f"Handing off to {agent_name}",
+        "type": "handoff"
+    })
+
+
+if BaseModel is not None and Field is not None:
+    class _HandoffInput(BaseModel):
+        """Input parameters for handoff tool (Pydantic model)."""
+        agent_name: str = Field(description="Name of the agent to hand off to")
+        message: str = Field(description="Message or context to pass to the target agent")
+else:
+    class _HandoffInput(object):
+        """Plain-Python fallback for handoff input when Pydantic is unavailable.
+
+        This class intentionally does not call Field() so it is safe to import
+        when Pydantic is not installed.
+        """
+        agent_name: str
+        message: str
+
+        def __init__(self, agent_name: str, message: str = ""):
+            self.agent_name = agent_name
+            self.message = message
+
+HandoffInput = _HandoffInput
+
+
+@dataclass
+class HandoffResult:
+    """Result of a handoff operation."""
+    target_agent: str
+    message: str
+    success: bool = True
+    error: Optional[str] = None
+
+
+class HandoffTool:
+    """A tool that enables agents to hand off to other agents."""
+
+    def __init__(self):
+        # Create schema
+        if BaseModel:
+            parameters_model = HandoffInput
+        else:
+            # Fallback schema when Pydantic is not available
+            parameters_model = {
+                "type": "object",
+                "properties": {
+                    "agent_name": {
+                        "type": "string",
+                        "description": "Name of the agent to hand off to"
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Message or context to pass to the target agent"
+                    }
+                },
+                "required": ["agent_name", "message"]
+            }
+
+        self.schema = ToolSchema(
+            name="handoff",
+            description="Hand off the conversation to another agent",
+            parameters=parameters_model
+        )
+        self.source = ToolSource.NATIVE
+        self.metadata = {"type": "handoff", "system": True}
+
+    async def execute(self, args: HandoffInput, context: Any) -> str:
+        """
+        Execute the handoff.
+
+        Parameters:
+            args (HandoffInput): The handoff input arguments.
+            context (Any): Context containing current agent and run state information.
+        """
+        # Extract arguments
+        if hasattr(args, 'agent_name'):
+            agent_name = args.agent_name
+            message = args.message
+        elif isinstance(args, dict):
+            agent_name = args.get('agent_name', '')
+            message = args.get('message', '')
+        else:
+            return json.dumps({
+                "error": "invalid_handoff_args",
+                "message": "Invalid handoff arguments provided",
+                "usage": "handoff(agent_name='target_agent', message='optional context')"
+            })
+
+        if not agent_name:
+            return json.dumps({
+                "error": "missing_agent_name",
+                "message": "Agent name is required for handoff",
+                "usage": "handoff(agent_name='target_agent', message='optional context')"
+            })
+
+        # Add agent validation if we have access to current agent info
+        if context and hasattr(context, 'current_agent'):
+            current_agent = context.current_agent
+            if current_agent.handoffs and agent_name not in current_agent.handoffs:
+                return json.dumps({
+                    "error": "handoff_not_allowed",
+                    "message": f"Agent {current_agent.name} cannot handoff to {agent_name}",
+                    "allowed_handoffs": current_agent.handoffs
+                })
+
+        # Return the special handoff JSON that the engine recognizes
+        return _create_handoff_json(agent_name, message)
+
+
+def create_handoff_tool() -> Tool:
+    """Create a handoff tool that can be added to any agent."""
+    return HandoffTool()
+
+handoff_tool = create_handoff_tool()
+
+def handoff(agent_name: str, message: str = "") -> str:
+    """
+    Simple function to perform a handoff (for use in agent tools).
+
+    Args:
+        agent_name: Name of the agent to hand off to
+        message: Optional message to pass to the target agent
+
+    Returns:
+        JSON string that triggers a handoff
+    """
+    return _create_handoff_json(agent_name, message)
+
+
+def is_handoff_request(result: str) -> bool:
+    """
+    Check if a tool result is a handoff request.
+
+    Args:
+        result: Tool execution result
+
+    Returns:
+        True if the result is a handoff request
+    """
+    try:
+        parsed = json.loads(result)
+        return isinstance(parsed, dict) and "handoff_to" in parsed
+    except (json.JSONDecodeError, TypeError):
+        return False
+
+
+def extract_handoff_target(result: str) -> Optional[str]:
+    """
+    Extract the target agent name from a handoff result.
+
+    Args:
+        result: Tool execution result
+
+    Returns:
+        Target agent name if it's a handoff, None otherwise
+    """
+    try:
+        parsed = json.loads(result)
+        if isinstance(parsed, dict) and "handoff_to" in parsed:
+            return parsed["handoff_to"]
+    except (json.JSONDecodeError, TypeError):
+        pass
+    return None

{jaf_py-2.5.1 → jaf_py-2.5.3}/jaf/core/state.py

@@ -5,10 +5,113 @@ This module provides functions to manage approval state transitions
 and integrate with approval storage systems.
 """
 
-from typing import Dict, Any, Optional
+from typing import Dict, Any, Optional, List
 from dataclasses import replace
 
-from .types import RunState, RunConfig, Interruption, ApprovalValue
+from .types import RunState, RunConfig, Interruption, ApprovalValue, Message, ContentRole, Attachment
+
+
+def _extract_attachments_from_messages(messages: List[Dict[str, Any]]) -> List[Attachment]:
+    """Extract attachment objects from message data."""
+    attachments = []
+
+    for msg in messages:
+        msg_attachments = msg.get('attachments', [])
+        for att in msg_attachments:
+            try:
+                # Convert dict to Attachment object
+                attachment = Attachment(
+                    kind=att.get('kind', 'image'),
+                    mime_type=att.get('mime_type'),
+                    name=att.get('name'),
+                    url=att.get('url'),
+                    data=att.get('data'),
+                    format=att.get('format'),
+                    use_litellm_format=att.get('use_litellm_format')
+                )
+                attachments.append(attachment)
+            except Exception as e:
+                print(f"[JAF:APPROVAL] Failed to process attachment: {e}")
+
+    return attachments
+
+
+def _process_additional_context_images(additional_context: Optional[Dict[str, Any]]) -> List[Attachment]:
+    """Process additional context and extract any image attachments."""
+    if not additional_context:
+        return []
+
+    attachments = []
+
+    # Handle messages with attachments
+    messages = additional_context.get('messages', [])
+    if messages:
+        attachments.extend(_extract_attachments_from_messages(messages))
+
+    # Handle legacy image_context format
+    image_context = additional_context.get('image_context')
+    if image_context and image_context.get('type') == 'image_url':
+        try:
+            image_url = image_context.get('image_url', {})
+            url = image_url.get('url', '')
+
+            if url.startswith('data:'):
+                # Parse data URL: data:image/png;base64,iVBORw0KGgo...
+                header, data = url.split(',', 1)
+                mime_type = header.split(':')[1].split(';')[0]
+
+                attachment = Attachment(
+                    kind='image',
+                    mime_type=mime_type,
+                    data=data,
+                    name=f"approval_image.{mime_type.split('/')[-1]}"
+                )
+                attachments.append(attachment)
+        except Exception as e:
+            print(f"[JAF:APPROVAL] Failed to process image_context: {e}")
+
+    return attachments
+
+
+def _add_approval_context_to_conversation(
+    state: RunState[Any],
+    additional_context: Optional[Dict[str, Any]]
+) -> RunState[Any]:
+    """Add approval context including images to the conversation."""
+    if not additional_context:
+        return state
+
+    # Extract image attachments
+    attachments = _process_additional_context_images(additional_context)
+
+    if not attachments:
+        return state
+
+    # Create approval context message
+    approval_message = "Additional context provided during approval process."
+
+    # Check if there are text messages to include
+    messages = additional_context.get('messages', [])
+    if messages:
+        text_content = []
+        for msg in messages:
+            content = msg.get('content', '')
+            if content:
+                text_content.append(content)
+
+        if text_content:
+            approval_message = f"User provided additional context: {' '.join(text_content)}"
+
+    # Create user message with attachments (using USER role for better compatibility)
+    context_message = Message(
+        role=ContentRole.USER,
+        content=approval_message,
+        attachments=attachments
+    )
+
+    # Add to conversation
+    new_messages = state.messages + [context_message]
+    return replace(state, messages=new_messages)
 
 
 async def approve(
@@ -60,8 +163,12 @@ async def approve(
         # Update in-memory state
         new_approvals = {**state.approvals}
         new_approvals[interruption.tool_call.id] = approval_value
-        
-        return replace(state, approvals=new_approvals)
+
+        # Process any image context and add to conversation
+        updated_state = replace(state, approvals=new_approvals)
+        updated_state = _add_approval_context_to_conversation(updated_state, additional_context)
+
+        return updated_state
     
     return state
 
@@ -115,8 +222,12 @@ async def reject(
         # Update in-memory state
         new_approvals = {**state.approvals}
         new_approvals[interruption.tool_call.id] = approval_value
-        
-        return replace(state, approvals=new_approvals)
+
+        # Process any image context and add to conversation
+        updated_state = replace(state, approvals=new_approvals)
+        updated_state = _add_approval_context_to_conversation(updated_state, additional_context)
+
+        return updated_state
     
     return state