webagents 0.2.0__py3-none-any.whl → 0.2.3__py3-none-any.whl

webagents/agents/tools/decorators.py

@@ -247,74 +247,104 @@ def prompt(priority: int = 50, scope: Union[str, List[str]] = "all"):
     return decorator
 
 
-def handoff(name: Optional[str] = None, handoff_type: str = "agent", description: Optional[str] = None, 
-           scope: Union[str, List[str]] = "all"):
-    """Decorator to mark functions as handoffs for automatic registration
+def handoff(
+    name: Optional[str] = None,
+    prompt: Optional[str] = None,
+    scope: Union[str, List[str]] = "all",
+    priority: int = 50,
+    auto_tool: bool = False,
+    auto_tool_description: Optional[str] = None
+):
+    """Decorator to mark functions as handoff handlers for automatic registration
+    
+    Handoff functions handle chat completions and can be:
+    1. Async generators (streaming native) - work in both streaming and non-streaming modes
+    2. Regular async functions (non-streaming native) - work in both streaming and non-streaming modes
     
     Args:
-        name: Optional override for handoff name (defaults to function name)
-        handoff_type: Type of handoff - "agent", "llm", "pipeline", etc.
-        description: Handoff description (defaults to function docstring)  
+        name: Handoff identifier (defaults to function name)
+        prompt: Description/guidance about when to use this handoff
+                - Used as handoff description for discovery
+                - Added to dynamic prompts to guide the LLM
         scope: Access scope - "all", "owner", "admin", or list of scopes
+        priority: Execution priority - lower numbers = higher priority (determines default)
+                  First handoff with lowest priority becomes the default completion handler
+        auto_tool: If True, automatically create a tool to invoke this handoff dynamically
+        auto_tool_description: Description for the auto-generated tool (defaults to generic description)
     
-    Handoff functions should return HandoffResult:
-    
-    @handoff(handoff_type="agent", scope=["admin"])
-    async def escalate_to_admin(self, issue: str, context: Context = None) -> HandoffResult:
-        # Process handoff
-        return HandoffResult(result="escalated", handoff_type="agent")
+    Examples:
+        # Local LLM handoff (non-streaming)
+        @handoff(name="gpt4", prompt="Primary LLM for general reasoning", priority=10)
+        async def chat_completion(self, messages, tools=None, **kwargs) -> Dict[str, Any]:
+            return await llm_api_call(messages, tools)
+        
+        # Remote agent handoff (streaming)
+        @handoff(name="specialist", prompt="Hand off to specialist for complex tasks", priority=20)
+        async def remote_handoff(self, messages, tools=None, **kwargs) -> AsyncGenerator[Dict, None]:
+            async for chunk in nli_stream(agent_url, messages):
+                yield chunk
+        
+        # With context injection
+        @handoff(name="custom", priority=15)
+        async def my_handoff(self, messages, tools=None, context=None, **kwargs) -> Dict:
+            api_key = context.get("api_key")
+            return await custom_llm_call(messages, api_key)
     """
     def decorator(func: Callable) -> Callable:
-        # Mark function with metadata for BaseAgent discovery
-        func._webagents_is_handoff = True
-        func._handoff_type = handoff_type
-        func._handoff_scope = scope
-        func._handoff_name = name or func.__name__
-        func._handoff_description = description or func.__doc__ or f"Handoff: {func.__name__}"
+        # Validate function type
+        is_async_gen = inspect.isasyncgenfunction(func)
+        is_async = inspect.iscoroutinefunction(func)
+        
+        if not is_async_gen and not is_async:
+            raise ValueError(
+                f"Handoff '{func.__name__}' must be async function or async generator. "
+                f"Got: {type(func).__name__}"
+            )
         
         # Check if function expects context injection
         sig = inspect.signature(func)
         has_context_param = 'context' in sig.parameters
         
+        # Create wrapper if context injection needed
         if has_context_param:
-            @functools.wraps(func)
-            async def async_wrapper(*args, **kwargs):
-                # Inject context if requested and not provided
-                if 'context' not in kwargs:
-                    from ...server.context.context_vars import get_context
-                    context = get_context()
-                    kwargs['context'] = context
+            if is_async_gen:
+                # Async generator with context
+                @functools.wraps(func)
+                async def async_gen_wrapper(*args, **kwargs):
+                    if 'context' not in kwargs:
+                        from ...server.context.context_vars import get_context
+                        context = get_context()
+                        kwargs['context'] = context
+                    
+                    async for item in func(*args, **kwargs):
+                        yield item
                 
-                # Call original function
-                if inspect.iscoroutinefunction(func):
+                wrapper = async_gen_wrapper
+            else:
+                # Regular async function with context
+                @functools.wraps(func)
+                async def async_wrapper(*args, **kwargs):
+                    if 'context' not in kwargs:
+                        from ...server.context.context_vars import get_context
+                        context = get_context()
+                        kwargs['context'] = context
+                    
                     return await func(*args, **kwargs)
-                else:
-                    return func(*args, **kwargs)
-            
-            @functools.wraps(func)
-            def sync_wrapper(*args, **kwargs):
-                # Inject context if requested and not provided  
-                if 'context' not in kwargs:
-                    from ...server.context.context_vars import get_context
-                    context = get_context()
-                    kwargs['context'] = context
                 
-                return func(*args, **kwargs)
-            
-            # Return appropriate wrapper
-            if inspect.iscoroutinefunction(func):
                 wrapper = async_wrapper
-            else:
-                wrapper = sync_wrapper
         else:
+            # No context injection needed
             wrapper = func
         
-        # Copy metadata to wrapper
+        # Mark function with metadata for BaseAgent discovery
         wrapper._webagents_is_handoff = True
-        wrapper._handoff_type = handoff_type
-        wrapper._handoff_scope = scope
         wrapper._handoff_name = name or func.__name__
-        wrapper._handoff_description = description or func.__doc__ or f"Handoff: {func.__name__}"
+        wrapper._handoff_prompt = prompt or func.__doc__ or f"Handoff: {func.__name__}"
+        wrapper._handoff_scope = scope
+        wrapper._handoff_priority = priority
+        wrapper._handoff_is_generator = is_async_gen
+        wrapper._handoff_auto_tool = auto_tool
+        wrapper._handoff_auto_tool_description = auto_tool_description or f"Switch to {name or func.__name__} handoff"
         
         return wrapper
     
@@ -423,4 +453,170 @@ def http(subpath: str, method: str = "get", scope: Union[str, List[str]] = "all"
         
         return wrapper
     
+    return decorator
+
+
+def widget(func: Optional[Callable] = None, *, name: Optional[str] = None, description: Optional[str] = None, template: Optional[str] = None, scope: Union[str, List[str]] = "all", auto_escape: bool = True):
+    """Decorator to mark functions as widgets for automatic registration
+    
+    Widgets are interactive HTML components rendered in sandboxed iframes on the frontend.
+    They support both Jinja2 templates and inline HTML strings.
+    
+    Can be used as:
+        @widget
+        def my_widget(self, param: str) -> str: ...
+    
+    Or:
+        @widget(name="custom", description="Custom widget", scope="owner")  
+        def my_widget(self, param: str) -> str: ...
+    
+    Args:
+        name: Optional override for widget name (defaults to function name)
+        description: Widget description (defaults to function docstring)
+        template: Optional path to Jinja2 template file
+        scope: Access scope - "all", "owner", "admin", or list of scopes
+        auto_escape: Automatically HTML-escape string arguments (default: True)
+                    Set to False if you're passing pre-rendered safe HTML
+    
+    The decorated function should return HTML wrapped in <widget> tags:
+    
+    @widget(scope="all")  # auto_escape=True by default
+    def my_widget(self, param: str, context: Context = None) -> str:
+        # param is automatically escaped! No need for html.escape()
+        html = f"<div>{param}</div>"
+        return f'<widget kind="webagents" id="my_widget">{html}</widget>'
+    
+    For pre-rendered HTML, disable auto-escaping:
+    
+    @widget(scope="all", auto_escape=False)
+    def unsafe_widget(self, raw_html: str) -> str:
+        # raw_html is NOT escaped - use with caution!
+        return f'<widget kind="webagents" id="unsafe">{raw_html}</widget>'
+    
+    Widgets are only included in LLM context for browser requests (detected via User-Agent).
+    """
+    def decorator(f: Callable) -> Callable:
+        # Generate widget schema for LLM awareness
+        sig = inspect.signature(f)
+        parameters = {}
+        required = []
+        
+        for param_name, param in sig.parameters.items():
+            # Skip 'self' and 'context' parameters from schema
+            if param_name in ('self', 'context'):
+                continue
+                
+            param_type = "string"  # Default type
+            param_desc = f"Parameter {param_name}"
+            
+            # Try to infer type from annotation
+            if param.annotation != inspect.Parameter.empty:
+                if param.annotation == int:
+                    param_type = "integer"
+                elif param.annotation == float:
+                    param_type = "number"
+                elif param.annotation == bool:
+                    param_type = "boolean"
+                elif param.annotation == list:
+                    param_type = "array"
+                elif param.annotation == dict:
+                    param_type = "object"
+            
+            parameters[param_name] = {
+                "type": param_type,
+                "description": param_desc
+            }
+            
+            # Mark as required if no default value
+            if param.default == inspect.Parameter.empty:
+                required.append(param_name)
+        
+        # Create widget schema (similar to tool schema for LLM)
+        widget_schema = {
+            "type": "function",
+            "function": {
+                "name": name or f.__name__,
+                "description": description or f.__doc__ or f"Widget: {f.__name__}",
+                "parameters": {
+                    "type": "object",
+                    "properties": parameters,
+                    "required": required
+                }
+            }
+        }
+        
+        # Mark function with metadata for BaseAgent discovery
+        f._webagents_is_widget = True
+        f._webagents_widget_definition = widget_schema
+        f._widget_scope = scope
+        f._widget_scope_was_set = func is None  # If func is None, decorator was called with params
+        f._widget_name = name or f.__name__
+        f._widget_description = description or f.__doc__ or f"Widget: {f.__name__}"
+        f._widget_template = template
+        
+        # Check if function expects context injection
+        has_context_param = 'context' in sig.parameters
+        
+        @functools.wraps(f)
+        async def async_wrapper(*args, **kwargs):
+            # Inject context if function expects it
+            if has_context_param and 'context' not in kwargs:
+                from webagents.server.context.context_vars import get_context
+                kwargs['context'] = get_context()
+            
+            # Auto-escape string arguments if enabled
+            if auto_escape:
+                import html
+                # Escape all string kwargs (except 'context' and 'self')
+                escaped_kwargs = {}
+                for key, value in kwargs.items():
+                    if key not in ('context', 'self') and isinstance(value, str):
+                        escaped_kwargs[key] = html.escape(value)
+                    else:
+                        escaped_kwargs[key] = value
+                kwargs = escaped_kwargs
+            
+            # Call original function
+            if inspect.iscoroutinefunction(f):
+                return await f(*args, **kwargs)
+            else:
+                return f(*args, **kwargs)
+        
+        @functools.wraps(f)
+        def sync_wrapper(*args, **kwargs):
+            # Inject context if function expects it
+            if has_context_param and 'context' not in kwargs:
+                from webagents.server.context.context_vars import get_context
+                kwargs['context'] = get_context()
+            
+            # Auto-escape string arguments if enabled
+            if auto_escape:
+                import html
+                # Escape all string kwargs (except 'context' and 'self')
+                escaped_kwargs = {}
+                for key, value in kwargs.items():
+                    if key not in ('context', 'self') and isinstance(value, str):
+                        escaped_kwargs[key] = html.escape(value)
+                    else:
+                        escaped_kwargs[key] = value
+                kwargs = escaped_kwargs
+            
+            # Call original function
+            return f(*args, **kwargs)
+        
+        # Preserve metadata on wrapper
+        wrapper = async_wrapper if inspect.iscoroutinefunction(f) else sync_wrapper
+        wrapper._webagents_is_widget = True
+        wrapper._webagents_widget_definition = widget_schema
+        wrapper._widget_scope = scope
+        wrapper._widget_scope_was_set = func is None
+        wrapper._widget_name = name or f.__name__
+        wrapper._widget_description = description or f.__doc__ or f"Widget: {f.__name__}"
+        wrapper._widget_template = template
+        
+        return wrapper
+    
+    # Support both @widget and @widget()
+    if func is not None:
+        return decorator(func)
     return decorator 

webagents/agents/widgets/__init__.py

@@ -0,0 +1,6 @@
+"""Widget system for rendering interactive HTML components"""
+
+from .renderer import WidgetTemplateRenderer, ChatKitRenderer
+
+__all__ = ['WidgetTemplateRenderer', 'ChatKitRenderer']  # ChatKitRenderer is deprecated alias
+

webagents/agents/widgets/renderer.py

@@ -0,0 +1,150 @@
+"""Widget template renderer for HTML templates with Jinja2 support"""
+
+import os
+import warnings
+from typing import Dict, Any, Optional
+from jinja2 import Environment, FileSystemLoader, Template, TemplateNotFound
+import html
+
+
+class WidgetTemplateRenderer:
+    """Renders WebAgents widget HTML from Jinja2 templates or inline HTML strings
+    
+    This renderer is specifically for WebAgents HTML widgets (kind="webagents"),
+    NOT for OpenAI ChatKit widgets (kind="openai").
+    
+    Supports both file-based templates and inline HTML with variable substitution.
+    Ensures proper HTML escaping for data attributes to prevent XSS.
+    
+    Example:
+        # File-based template
+        renderer = WidgetTemplateRenderer(template_dir="widgets")
+        html = renderer.render("music_player.html", {"title": "Song Name"})
+        
+        # Inline HTML
+        renderer = WidgetTemplateRenderer()
+        html = renderer.render_inline("<div>{{ title }}</div>", {"title": "Song Name"})
+    """
+    
+    def __init__(self, template_dir: Optional[str] = None):
+        """Initialize widget renderer
+        
+        Args:
+            template_dir: Directory containing Jinja2 template files (optional)
+        """
+        self.template_dir = template_dir or "widgets"
+        
+        # Initialize Jinja2 environment if template directory exists
+        if os.path.exists(self.template_dir):
+            self.env = Environment(
+                loader=FileSystemLoader(self.template_dir),
+                autoescape=True  # Auto-escape HTML for security
+            )
+        else:
+            self.env = None
+    
+    def render(self, template_name: str, context: Dict[str, Any]) -> str:
+        """Render widget HTML from a template file
+        
+        Args:
+            template_name: Name of template file (e.g., "music_player.html")
+            context: Dictionary of variables to pass to template
+        
+        Returns:
+            Rendered HTML string
+        
+        Raises:
+            TemplateNotFound: If template file doesn't exist
+            ValueError: If template directory not configured
+        """
+        if not self.env:
+            raise ValueError(f"Template directory '{self.template_dir}' not found")
+        
+        template = self.env.get_template(template_name)
+        return template.render(**context)
+    
+    def render_inline(self, html_string: str, context: Dict[str, Any]) -> str:
+        """Render widget HTML from an inline string
+        
+        Args:
+            html_string: HTML string with Jinja2 template syntax
+            context: Dictionary of variables to pass to template
+        
+        Returns:
+            Rendered HTML string
+        """
+        template = Template(html_string, autoescape=True)
+        return template.render(**context)
+    
+    @staticmethod
+    def escape_data(data: Any) -> str:
+        """Escape data for safe inclusion in HTML attributes
+        
+        Args:
+            data: Data to escape (will be converted to string)
+        
+        Returns:
+            HTML-escaped string safe for attribute values
+        """
+        return html.escape(str(data), quote=True)
+    
+    @staticmethod
+    def inject_tailwind_cdn(html_content: str) -> str:
+        """Inject Tailwind CSS CDN if not already present
+        
+        Args:
+            html_content: HTML content to check and modify
+        
+        Returns:
+            HTML content with Tailwind CDN injected in <head>
+        """
+        # Check if Tailwind is already present
+        if 'tailwindcss.com' in html_content:
+            return html_content
+        
+        # Check if there's a <head> tag
+        if '<head>' in html_content:
+            # Inject after <head>
+            return html_content.replace(
+                '<head>',
+                '<head>\n    <script src="https://cdn.tailwindcss.com"></script>',
+                1  # Only replace first occurrence
+            )
+        elif '<html>' in html_content:
+            # Inject after <html>
+            return html_content.replace(
+                '<html>',
+                '<html>\n<head>\n    <script src="https://cdn.tailwindcss.com"></script>\n</head>',
+                1
+            )
+        else:
+            # No HTML structure, wrap in basic HTML with Tailwind
+            return f"""<!DOCTYPE html>
+<html>
+<head>
+    <script src="https://cdn.tailwindcss.com"></script>
+</head>
+<body>
+{html_content}
+</body>
+</html>"""
+
+
+# Backward compatibility alias with deprecation warning
+class ChatKitRenderer(WidgetTemplateRenderer):
+    """Deprecated: Use WidgetTemplateRenderer instead.
+    
+    This class was misnamed - it renders WebAgents HTML widgets using Jinja2,
+    NOT OpenAI ChatKit widgets. Use WidgetTemplateRenderer for clarity.
+    """
+    
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "ChatKitRenderer is deprecated and will be removed in a future version. "
+            "Use WidgetTemplateRenderer instead. Note: This class renders WebAgents HTML widgets, "
+            "not OpenAI ChatKit widgets.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        super().__init__(*args, **kwargs)
+