webagents 0.1.0__py3-none-any.whl

webagents/agents/tools/decorators.py

@@ -0,0 +1,426 @@
+"""
+Tool, Hook, Handoff, and HTTP Decorators - WebAgents V2.0
+
+Decorators for automatic registration of tools, hooks, handoffs, and HTTP handlers with BaseAgent.
+Supports context injection and scope-based access control.
+"""
+
+import inspect
+import functools
+from typing import Dict, Any, List, Optional, Callable, Union
+from dataclasses import dataclass
+
+
+def tool(func: Optional[Callable] = None, *, name: Optional[str] = None, description: Optional[str] = None, scope: Union[str, List[str]] = "all"):
+    """Decorator to mark functions as tools for automatic registration
+    
+    Can be used as:
+        @tool
+        def my_tool(param: str) -> str: ...
+    
+    Or:
+        @tool(name="custom", description="Custom tool", scope="owner")  
+        def my_tool(param: str) -> str: ...
+    
+    Args:
+        name: Optional override for tool name (defaults to function name)
+        description: Tool description (defaults to function docstring)
+        scope: Access scope - "all", "owner", "admin", or list of scopes
+    
+    The decorated function can optionally receive Context via dependency injection:
+    
+    @tool(scope="owner")
+    def my_tool(self, param: str, context: Context = None) -> str:
+        # Context automatically injected if parameter exists
+        if context:
+            user_id = context.peer_user_id
+            # ... use context
+        return result
+    """
+    def decorator(f: Callable) -> Callable:
+        # Generate OpenAI-compatible tool schema
+        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 OpenAI tool schema
+        tool_schema = {
+            "type": "function",
+            "function": {
+                "name": name or f.__name__,
+                "description": description or f.__doc__ or f"Tool: {f.__name__}",
+                "parameters": {
+                    "type": "object",
+                    "properties": parameters,
+                    "required": required
+                }
+            }
+        }
+        
+        # Mark function with metadata for BaseAgent discovery
+        f._webagents_is_tool = True
+        f._webagents_tool_definition = tool_schema
+        f._tool_scope = scope
+        f._tool_scope_was_set = func is None  # If func is None, decorator was called with params
+        f._tool_name = name or f.__name__
+        f._tool_description = description or f.__doc__ or f"Tool: {f.__name__}"
+        
+        # Check if function expects context injection
+        has_context_param = 'context' in sig.parameters
+        
+        if has_context_param:
+            @functools.wraps(f)
+            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
+                # Call original function and return directly; BaseAgent will log usage
+                return await f(*args, **kwargs) if inspect.iscoroutinefunction(f) else f(*args, **kwargs)
+            
+            @functools.wraps(f) 
+            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
+                # Call original function and return directly; BaseAgent will log usage
+                return f(*args, **kwargs)
+            
+            # Return appropriate wrapper based on function type
+            if inspect.iscoroutinefunction(f):
+                wrapper = async_wrapper
+            else:
+                wrapper = sync_wrapper
+        else:
+            # No context injection needed; return function directly
+            wrapper = f
+        
+        # Copy metadata to wrapper
+        wrapper._webagents_is_tool = True
+        wrapper._webagents_tool_definition = tool_schema
+        wrapper._tool_scope = scope
+        wrapper._tool_scope_was_set = func is None  # If func is None, decorator was called with params
+        wrapper._tool_name = name or f.__name__
+        wrapper._tool_description = description or f.__doc__ or f"Tool: {f.__name__}"
+        
+        return wrapper
+    
+    if func is None:
+        # Called with arguments: @tool(name="...", ...)
+        return decorator
+    else:
+        # Called without arguments: @tool
+        return decorator(func)
+
+
+def hook(event: str, priority: int = 50, scope: Union[str, List[str]] = "all"):
+    """Decorator to mark functions as lifecycle hooks for automatic registration
+    
+    Args:
+        event: Lifecycle event name (on_connection, on_chunk, on_message, etc.)
+        priority: Execution priority (lower numbers execute first)
+        scope: Access scope - "all", "owner", "admin", or list of scopes
+    
+    Hook functions should accept and return Context:
+    
+    @hook("on_message", priority=10, scope="owner")
+    async def my_hook(self, context: Context) -> Context:
+        # Process context
+        return context
+    """
+    def decorator(func: Callable) -> Callable:
+        # Mark function with metadata for BaseAgent discovery
+        func._webagents_is_hook = True
+        func._hook_event_type = event
+        func._hook_priority = priority
+        func._hook_scope = scope
+        
+        return func
+    
+    return decorator
+
+
+def prompt(priority: int = 50, scope: Union[str, List[str]] = "all"):
+    """Decorator to mark functions as system prompt providers for automatic registration
+    
+    Args:
+        priority: Execution priority (lower numbers execute first)
+        scope: Access scope - "all", "owner", "admin", or list of scopes
+    
+    Prompt functions should accept context and return a string to be added to the system prompt:
+    
+    @prompt(priority=10, scope="owner")
+    def my_prompt(self, context: Context) -> str:
+        # Generate dynamic prompt content
+        return f"Current user: {context.user_id}"
+    
+    @prompt(priority=20)
+    async def async_prompt(self, context: Context) -> str:
+        # Async prompt generation
+        data = await some_async_call()
+        return f"Dynamic data: {data}"
+    """
+    def decorator(func: Callable) -> Callable:
+        # Mark function with metadata for BaseAgent discovery
+        func._webagents_is_prompt = True
+        func._prompt_priority = priority
+        func._prompt_scope = scope
+        
+        # Check if function expects context injection
+        sig = inspect.signature(func)
+        has_context_param = 'context' in sig.parameters
+        
+        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
+                
+                # Call original function
+                if inspect.iscoroutinefunction(func):
+                    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 based on function type
+            if inspect.iscoroutinefunction(func):
+                wrapper = async_wrapper
+            else:
+                wrapper = sync_wrapper
+        else:
+            # No context injection needed
+            wrapper = func
+        
+        # Copy metadata to wrapper
+        wrapper._webagents_is_prompt = True
+        wrapper._prompt_priority = priority
+        wrapper._prompt_scope = scope
+        
+        return wrapper
+    
+    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
+    
+    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)  
+        scope: Access scope - "all", "owner", "admin", or list of scopes
+    
+    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")
+    """
+    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__}"
+        
+        # Check if function expects context injection
+        sig = inspect.signature(func)
+        has_context_param = 'context' in sig.parameters
+        
+        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
+                
+                # Call original function
+                if inspect.iscoroutinefunction(func):
+                    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:
+            wrapper = func
+        
+        # Copy metadata to wrapper
+        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__}"
+        
+        return wrapper
+    
+    return decorator 
+
+
+def http(subpath: str, method: str = "get", scope: Union[str, List[str]] = "all"):
+    """Decorator to mark functions as HTTP handlers for automatic registration
+    
+    Args:
+        subpath: URL path after agent name (e.g., "/myapi" -> /{agentname}/myapi)
+                 Supports dynamic parameters: "/users/{user_id}/posts/{post_id}"
+        method: HTTP method - "get", "post", "put", "delete", etc. (default: "get")
+        scope: Access scope - "all", "owner", "admin", or list of scopes
+    
+    HTTP handler functions receive FastAPI request arguments directly:
+    
+    @http("/weather", method="get", scope="owner")
+    def get_weather(location: str, units: str = "celsius") -> dict:
+        # Function receives query parameters as arguments
+        return {"location": location, "temperature": 25, "units": units}
+    
+    @http("/data", method="post")
+    async def post_data(request: Request, data: dict) -> dict:
+        # Function can receive Request object and body data
+        return {"received": data, "status": "success"}
+    
+    @http("/users/{user_id}", method="get")
+    def get_user(user_id: str) -> dict:
+        # Function receives path parameters as arguments
+        return {"user_id": user_id, "name": f"User {user_id}"}
+    
+    @http("/users/{user_id}/posts/{post_id}", method="get")
+    def get_user_post(user_id: str, post_id: str, include_comments: bool = False) -> dict:
+        # Function receives both path parameters and query parameters
+        return {
+            "user_id": user_id,
+            "post_id": post_id, 
+            "include_comments": include_comments
+        }
+    
+    Dynamic path parameters are automatically extracted by FastAPI and passed
+    to the handler function. Query parameters and JSON body data are also
+    automatically passed as function arguments.
+    """
+    def decorator(func: Callable) -> Callable:
+        # Validate HTTP method
+        valid_methods = ["get", "post", "put", "delete", "patch", "head", "options"]
+        if method.lower() not in valid_methods:
+            raise ValueError(f"Invalid HTTP method '{method}'. Must be one of: {valid_methods}")
+        
+        # Ensure subpath starts with /
+        normalized_subpath = subpath if subpath.startswith('/') else f'/{subpath}'
+        
+        # Mark function with metadata for BaseAgent discovery
+        func._webagents_is_http = True
+        func._http_subpath = normalized_subpath
+        func._http_method = method.lower()
+        func._http_scope = scope
+        func._http_description = func.__doc__ or f"HTTP {method.upper()} handler for {normalized_subpath}"
+        
+        # Check if function expects context injection
+        sig = inspect.signature(func)
+        has_context_param = 'context' in sig.parameters
+        
+        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
+                
+                # Call original function
+                if inspect.iscoroutinefunction(func):
+                    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 based on function type
+            if inspect.iscoroutinefunction(func):
+                wrapper = async_wrapper
+            else:
+                wrapper = sync_wrapper
+        else:
+            # No context injection needed
+            wrapper = func
+        
+        # Copy metadata to wrapper
+        wrapper._webagents_is_http = True
+        wrapper._http_subpath = normalized_subpath
+        wrapper._http_method = method.lower()
+        wrapper._http_scope = scope
+        wrapper._http_description = func.__doc__ or f"HTTP {method.upper()} handler for {normalized_subpath}"
+        
+        return wrapper
+    
+    return decorator 

webagents/server/__init__.py

@@ -0,0 +1,28 @@
+"""
+WebAgents V2.0 Server Package
+
+FastAPI server implementation with OpenAI compatibility,
+streaming support, and comprehensive agent management.
+"""
+
+# Import moved to avoid circular dependency
+# from .core.app import WebAgentsServer, create_server
+from .models import (
+    ChatCompletionRequest,
+    OpenAIResponse, 
+    OpenAIStreamChunk,
+    AgentInfoResponse,
+    ServerInfo,
+    HealthResponse
+)
+
+__all__ = [
+    # 'WebAgentsServer',
+    # 'create_server', 
+    'ChatCompletionRequest',
+    'OpenAIResponse',
+    'OpenAIStreamChunk', 
+    'AgentInfoResponse',
+    'ServerInfo',
+    'HealthResponse'
+]

webagents/server/context/context_vars.py

@@ -0,0 +1,121 @@
+"""
+Context Variables and Unified Context - WebAgents V2.0
+
+Unified context management using Python's contextvars for thread-safe,
+async-compatible context handling.
+"""
+
+import time
+import uuid
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Dict, Any, List, Optional, Union
+from datetime import datetime
+
+
+# Single ContextVar for unified context
+CONTEXT: ContextVar['Context'] = ContextVar('webagents_context')
+
+
+@dataclass
+class Context:
+    """Unified Context containing ALL request data AND agent capabilities
+    
+    This replaces the previous multiple context variables with a single,
+    comprehensive context object that contains everything skills and
+    tools need access to.
+    """
+    
+    # Request identification
+    request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    start_time: float = field(default_factory=time.time)
+    
+    # Request data
+    messages: List[Dict[str, Any]] = field(default_factory=list)
+    stream: bool = False
+    
+    agent: Optional[Any] = None  # BaseAgent instance
+    request: Optional[Any] = None  # Incoming HTTP request wrapper
+
+    # Authentication namespace (populated by AuthSkill)
+    auth: Optional[Any] = None
+
+    # Usage data
+    usage: List[Dict[str, Any]] = field(default_factory=list)
+    
+    # Custom data storage (for skills/tools to store temporary data)
+    custom_data: Dict[str, Any] = field(default_factory=dict)
+    
+    # --- Properties for clean access ---
+    
+    @property
+    def skills(self) -> Dict[str, Any]:
+        """Access to agent's skills"""
+        return self.agent.skills if self.agent else {}
+
+    @property
+    def tools(self) -> List[Dict[str, Any]]:
+        """Access to agent's registered tools"""
+        return self.agent.get_all_tools() if self.agent else []
+    
+    @property
+    def handoffs(self) -> List[Dict[str, Any]]:
+        """Access to agent's registered handoffs"""  
+        return self.agent.get_all_handoffs() if self.agent else []
+    
+    @property
+    def auth_scope(self) -> str:
+        """Determine user scope based on user context"""
+        return self.auth.scope.value if self.auth else 'all'
+    
+    # --- Methods for data manipulation ---
+    
+    def set(self, key: str, value: Any) -> None:
+        """Store custom data"""
+        self.custom_data[key] = value
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve custom data"""
+        return self.custom_data.get(key, default)
+    
+    
+    def add_message(self, message: Dict[str, Any]) -> None:
+        """Add message to context"""
+        self.messages.append(message)
+    
+    def update_agent_context(self, agent: Any, agent_name: str) -> None:
+        """Update agent-related context"""
+        self.agent = agent
+        self.agent_name_resolved = agent_name
+
+
+# Context management functions
+def get_context() -> Optional[Context]:
+    """Get current context from context variable"""
+    try:
+        return CONTEXT.get()
+    except LookupError:
+        return None
+
+
+def set_context(context: Context) -> None:
+    """Set current context in context variable"""
+    CONTEXT.set(context)
+
+
+def create_context(
+    request_id: Optional[str] = None,
+    messages: Optional[List[Dict[str, Any]]] = None,
+    stream: bool = False,
+    request: Any = None,
+    agent: Any = None
+) -> Context:
+    """Create new context with provided data"""
+    context = Context(
+        request_id=request_id or str(uuid.uuid4()),
+        messages=messages or [],
+        stream=stream,
+        agent=agent,
+        request=request
+    )
+    return context