kite-agent 0.1.0__py3-none-any.whl

kite/safety/idempotency_manager.py

@@ -0,0 +1,304 @@
+"""
+Idempotency Manager for AI Agent Operations
+
+Ensures that operations are executed exactly once, even if called multiple times.
+Critical for preventing duplicate actions like refunds, emails, database writes.
+
+Author: Agentic AI Systems
+License: MIT
+"""
+
+import hashlib
+import json
+import time
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class IdempotencyConfig:
+    """Configuration for idempotency behavior."""
+    ttl_seconds: int = 3600  # How long to remember operations (1 hour default)
+    storage_backend: str = "memory"  # Options: memory, redis, database
+
+
+class IdempotencyManager:
+    """
+    Manages idempotency for agent operations.
+    
+    Use this to ensure operations like refunds, emails, or database
+    writes only execute once, even if the agent retries.
+    
+    Example:
+        manager = IdempotencyManager()
+        
+        # Generate idempotency key
+        key = manager.generate_id(
+            operation="refund",
+            params={"order_id": "123", "amount": 99.99}
+        )
+        
+        # Check if already executed
+        if manager.is_duplicate(key):
+            return manager.get_result(key)
+        
+        # Execute operation
+        result = process_refund(...)
+        manager.store_result(key, result)
+    """
+    
+    def __init__(self, config: Optional[IdempotencyConfig] = None):
+        self.config = config or IdempotencyConfig()
+        self._storage: Dict[str, Dict[str, Any]] = {}
+        logger.info(f"Idempotency manager initialized: {self.config}")
+    
+    def generate_id(self, operation: str, params: Dict[str, Any]) -> str:
+        """
+        Generate deterministic idempotency key.
+        
+        The same operation + params will always produce the same key.
+        This is critical for detecting duplicates.
+        
+        Args:
+            operation: Name of the operation (e.g., "refund", "send_email")
+            params: Parameters that uniquely identify this operation
+            
+        Returns:
+            Deterministic hash string
+        """
+        # Sort params for deterministic hashing
+        sorted_params = json.dumps(params, sort_keys=True)
+        unique_string = f"{operation}:{sorted_params}"
+        
+        # Generate hash
+        return hashlib.sha256(unique_string.encode()).hexdigest()
+    
+    def is_duplicate(self, idempotency_key: str) -> bool:
+        """
+        Check if this operation has already been executed.
+        
+        Args:
+            idempotency_key: The idempotency key from generate_id()
+            
+        Returns:
+            True if operation already executed, False otherwise
+        """
+        if idempotency_key not in self._storage:
+            return False
+        
+        # Check if TTL expired
+        entry = self._storage[idempotency_key]
+        expiry = entry["expires_at"]
+        
+        if datetime.now() > expiry:
+            # Expired, remove and return False
+            del self._storage[idempotency_key]
+            logger.info(f"Idempotency key expired and removed: {idempotency_key}")
+            return False
+        
+        logger.warning(f"Duplicate operation detected: {idempotency_key}")
+        return True
+    
+    def get_result(self, idempotency_key: str) -> Optional[Any]:
+        """
+        Get the cached result of a previous execution.
+        
+        Args:
+            idempotency_key: The idempotency key
+            
+        Returns:
+            Cached result or None if not found
+        """
+        if idempotency_key not in self._storage:
+            return None
+        
+        entry = self._storage[idempotency_key]
+        
+        # Check expiry
+        if datetime.now() > entry["expires_at"]:
+            del self._storage[idempotency_key]
+            return None
+        
+        logger.info(f"Returning cached result for key: {idempotency_key}")
+        return entry["result"]
+    
+    def store_result(
+        self,
+        idempotency_key: str,
+        result: Any,
+        ttl_seconds: Optional[int] = None
+    ):
+        """
+        Store the result of an operation.
+        
+        Args:
+            idempotency_key: The idempotency key
+            result: The result to cache
+            ttl_seconds: Override default TTL
+        """
+        ttl = ttl_seconds or self.config.ttl_seconds
+        expires_at = datetime.now() + timedelta(seconds=ttl)
+        
+        self._storage[idempotency_key] = {
+            "result": result,
+            "created_at": datetime.now(),
+            "expires_at": expires_at
+        }
+        
+        logger.info(
+            f"Stored result for key: {idempotency_key}, "
+            f"expires: {expires_at.isoformat()}"
+        )
+    
+    def clear_expired(self):
+        """Remove all expired entries (cleanup)."""
+        now = datetime.now()
+        expired_keys = [
+            key for key, entry in self._storage.items()
+            if entry["expires_at"] < now
+        ]
+        
+        for key in expired_keys:
+            del self._storage[key]
+        
+        if expired_keys:
+            logger.info(f"Cleared {len(expired_keys)} expired entries")
+    
+    def clear_all(self):
+        """Clear all cached results."""
+        self._storage.clear()
+        logger.info("All idempotency cache cleared")
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about cached operations."""
+        now = datetime.now()
+        active = sum(
+            1 for entry in self._storage.values()
+            if entry["expires_at"] > now
+        )
+        
+        return {
+            "total_cached": len(self._storage),
+            "active": active,
+            "expired": len(self._storage) - active
+        }
+
+
+# Decorator for easy use
+def idempotent(manager: IdempotencyManager, operation_name: str):
+    """
+    Decorator to make a function idempotent.
+    
+    Example:
+        manager = IdempotencyManager()
+        
+        @idempotent(manager, "process_refund")
+        def process_refund(order_id: str, amount: float):
+            # This will only execute once for the same order_id + amount
+            return stripe.Refund.create(...)
+    """
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            # Generate idempotency key from function args
+            params = {
+                "args": str(args),
+                "kwargs": str(kwargs)
+            }
+            key = manager.generate_id(operation_name, params)
+            
+            # Check if already executed
+            if manager.is_duplicate(key):
+                logger.info(f"Returning cached result for {operation_name}")
+                return manager.get_result(key)
+            
+            # Execute function
+            result = func(*args, **kwargs)
+            
+            # Cache result
+            manager.store_result(key, result)
+            
+            return result
+        
+        return wrapper
+    return decorator
+
+
+if __name__ == "__main__":
+    # Example usage
+    logging.basicConfig(level=logging.INFO)
+    
+    print("=== Idempotency Manager Demo ===\n")
+    
+    manager = IdempotencyManager(
+        config=IdempotencyConfig(ttl_seconds=60)
+    )
+    
+    # Simulate a refund operation
+    def process_refund(order_id: str, amount: float):
+        """Simulate processing a refund."""
+        print(f"    Processing refund: ${amount} for order {order_id}")
+        time.sleep(0.5)  # Simulate API call
+        return {
+            "success": True,
+            "refund_id": f"ref_{int(time.time())}",
+            "amount": amount
+        }
+    
+    # Test idempotency
+    print("1. First refund request:")
+    key1 = manager.generate_id(
+        "refund",
+        {"order_id": "12345", "amount": 299.99}
+    )
+    
+    if not manager.is_duplicate(key1):
+        result1 = process_refund("12345", 299.99)
+        manager.store_result(key1, result1)
+        print(f"  [OK] Result: {result1}\n")
+    
+    print("2. Duplicate refund request (should use cache):")
+    key2 = manager.generate_id(
+        "refund",
+        {"order_id": "12345", "amount": 299.99}
+    )
+    
+    if manager.is_duplicate(key2):
+        cached = manager.get_result(key2)
+        print(f"    Cached result: {cached}\n")
+    
+    print("3. Different refund (should execute):")
+    key3 = manager.generate_id(
+        "refund",
+        {"order_id": "67890", "amount": 199.99}
+    )
+    
+    if not manager.is_duplicate(key3):
+        result3 = process_refund("67890", 199.99)
+        manager.store_result(key3, result3)
+        print(f"  [OK] Result: {result3}\n")
+    
+    # Stats
+    print("Statistics:")
+    print(f"  {manager.get_stats()}\n")
+    
+    # Decorator example
+    print("\n=== Decorator Example ===\n")
+    
+    @idempotent(manager, "send_email")
+    def send_email(to: str, subject: str):
+        print(f"    Sending email to {to}: {subject}")
+        return {"sent": True, "message_id": f"msg_{int(time.time())}"}
+    
+    # First call - executes
+    print("1. First email:")
+    result = send_email("user@example.com", "Welcome!")
+    print(f"  Result: {result}\n")
+    
+    # Duplicate call - cached
+    print("2. Duplicate email (cached):")
+    result = send_email("user@example.com", "Welcome!")
+    print(f"  Result: {result}\n")

kite/safety/kill_switch.py

@@ -0,0 +1,75 @@
+"""
+KillSwitch - Safety limits for autonomous agents.
+"""
+
+import time
+from typing import Dict, Tuple, Optional, Any
+
+
+class KillSwitch:
+    """
+    Safety limits for autonomous agents to prevent infinite loops, 
+    excessive costs, or hanging processes.
+    """
+    
+    def __init__(self, 
+                 max_iterations: int = 10, 
+                 max_cost: float = 1.0, 
+                 max_same_action: int = 2, 
+                 max_time: int = 300):
+        """
+        Initialize KillSwitch with safety limits.
+        
+        Args:
+            max_iterations: Maximum number of steps/loops allowed.
+            max_cost: Maximum total cost in USD allowed.
+            max_same_action: Maximum number of times the same action can be repeated consecutively.
+            max_time: Maximum time in seconds allowed.
+        """
+        self.max_iterations = max_iterations
+        self.max_cost_usd = max_cost
+        self.max_same_action = max_same_action
+        self.max_time_seconds = max_time
+    
+    def check(self, state: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+        """
+        Check all kill switch limits against the current agent state.
+        
+        Args:
+            state: Dictionary containing current agent state:
+                - steps (int): Current iteration count
+                - total_cost (float): Accumulated cost
+                - start_time (float): Time when the process started (time.time())
+                - actions (list): List of actions taken
+                - completed (bool): Whether the goal is achieved
+                
+        Returns:
+            Tuple (should_stop, reason)
+        """
+        
+        # Limit 1: Iteration cap
+        if state.get('steps', 0) >= self.max_iterations:
+            return True, f"Max iterations ({self.max_iterations}) reached."
+        
+        # Limit 2: Budget cap
+        if state.get('total_cost', 0.0) >= self.max_cost_usd:
+            return True, f"Budget exceeded (${self.max_cost_usd})."
+        
+        # Limit 3: Time limit
+        if 'start_time' in state:
+            elapsed = time.time() - state['start_time']
+            if elapsed >= self.max_time_seconds:
+                return True, f"Time limit ({self.max_time_seconds}s) exceeded."
+        
+        # Limit 4: Stupidity check (repeated actions)
+        actions = state.get('actions', [])
+        if len(actions) >= self.max_same_action:
+            recent = [a.get('type') for a in actions[-self.max_same_action:]]
+            if len(set(recent)) == 1 and recent[0] is not None:
+                return True, f"Stuck in loop (same action '{recent[0]}' repeated {self.max_same_action} times)."
+        
+        # Limit 5: Goal completed
+        if state.get('completed', False):
+            return True, "Goal achieved."
+        
+        return False, None

kite/tool.py

@@ -0,0 +1,183 @@
+"""
+General-Purpose Tool
+Wrap any function as a tool for agents.
+"""
+
+from typing import Callable, Dict, Any
+import asyncio
+
+
+class Tool:
+    """
+    General-purpose tool wrapper.
+    
+    Example:
+        def search_database(query: str):
+            return db.execute(query)
+        
+        tool = ai.create_tool(
+            name="search_database",
+            func=search_database,
+            description="Search database with SQL query"
+        )
+    """
+    
+    def __init__(self, 
+                 name: str,
+                 func: Callable,
+                 description: str):
+        self.name = name
+        self.func = func
+        self.description = description
+        
+        # Stats
+        self.call_count = 0
+        self.error_count = 0
+    
+    def to_schema(self) -> Dict:
+        """
+        Generate JSON Schema for the tool (OpenAI/Ollama compatible).
+        """
+        import inspect
+        sig = inspect.signature(self.func)
+        doc = inspect.getdoc(self.func) or self.description
+        
+        properties = {}
+        required = []
+        
+        for name, param in sig.parameters.items():
+            if name == "self" or name == "framework":
+                continue
+            
+            # Skip *args and **kwargs
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+                
+            # Map Python types to JSON types
+            param_type = "string"  # default
+            if param.annotation == int: param_type = "integer"
+            elif param.annotation == float: param_type = "number"
+            elif param.annotation == bool: param_type = "boolean"
+            elif param.annotation == dict: param_type = "object"
+            elif param.annotation == list: param_type = "array"
+            
+            # Extract description from docstring if possible (simple parsing)
+            # Todo: use a better parser later
+            
+            properties[name] = {
+                "type": param_type,
+                "description": f"Parameter {name}" 
+            }
+            
+            if param.default == inspect.Parameter.empty:
+                required.append(name)
+                
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": doc,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required
+                }
+            }
+        }
+
+    async def execute(self, *args, **kwargs) -> Any:
+        """Execute tool."""
+        self.call_count += 1
+        
+        try:
+            # General Monitoring: Emit tool start
+            if kwargs.get('framework'):
+                kwargs['framework'].event_bus.emit("tool:start", {
+                    "tool": self.name,
+                    "args": kwargs.get('args', args) # Best effort capture
+                })
+
+            # Pre-inject framework if required by signature
+            import inspect
+            sig = inspect.signature(self.func)
+            
+            # Check if we should inject the framework
+            should_inject = False
+            if 'framework' in sig.parameters:
+                should_inject = True
+            elif any(p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()):
+                should_inject = True # Accepts **kwargs
+            
+            if should_inject and kwargs.get('framework'):
+                # We need to make sure we don't double-provide if it's already in args/kwargs
+                # But since we control the call, we can just ensure it's in kwargs for binding
+                pass # It's already in kwargs passed to execute
+            elif 'framework' in kwargs and not should_inject:
+                # CRITICAL: Remove framework from kwargs if the function DOES NOT accept it
+                del kwargs['framework']
+            
+            bound_args = sig.bind_partial(*args, **kwargs)
+            
+            casted_args = {}
+            # (Rest of casting logic remains same)
+            for param_name, value in bound_args.arguments.items():
+                param = sig.parameters.get(param_name)
+                if param and param.annotation != inspect.Parameter.empty:
+                    try:
+                        annotation = param.annotation
+                        if annotation == str: casted_args[param_name] = str(value)
+                        elif annotation == float: casted_args[param_name] = float(str(value).replace('$', '').replace(',', '').strip())
+                        elif annotation == int: casted_args[param_name] = int(str(value).replace('$', '').replace(',', '').split('.')[0].strip())
+                        elif annotation == bool: casted_args[param_name] = str(value).lower() in ("true", "1", "yes", "on")
+                        else: casted_args[param_name] = value
+                    except: casted_args[param_name] = value
+                else:
+                    casted_args[param_name] = value
+
+            
+            if asyncio.iscoroutinefunction(self.func):
+                result = await self.func(**casted_args)
+            else:
+                # Regular sync function
+                result = await asyncio.to_thread(self.func, **casted_args)
+
+            # General Monitoring: Emit tool end
+            if kwargs.get('framework'):
+                kwargs['framework'].event_bus.emit("tool:end", {
+                    "tool": self.name,
+                    "status": "success"
+                })
+            
+            return result
+        except Exception as e:
+            self.error_count += 1
+            raise
+        except Exception as e:
+            self.error_count += 1
+            raise
+    
+    def get_definition(self) -> Dict:
+        """Get tool definition for LLM."""
+        import inspect
+        sig = inspect.signature(self.func)
+        params = {}
+        for name, param in sig.parameters.items():
+            params[name] = {
+                "type": str(param.annotation) if param.annotation != inspect.Parameter.empty else "any",
+                "default": str(param.default) if param.default != inspect.Parameter.empty else None,
+                "required": param.default == inspect.Parameter.empty
+            }
+            
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": params
+        }
+    
+    def get_metrics(self) -> Dict:
+        """Get tool metrics."""
+        return {
+            "name": self.name,
+            "calls": self.call_count,
+            "errors": self.error_count
+        }

kite/tool_registry.py

@@ -0,0 +1,87 @@
+"""
+Tool Registry - Register and manage tools.
+"""
+
+from typing import Dict
+import logging
+
+
+class ToolRegistry:
+    """
+    Registry for all tools.
+    
+    Example:
+        ai.tools.register("my_tool", tool)
+        tool = ai.tools.get("my_tool")
+        all_tools = ai.tools.list()
+    """
+    
+    def __init__(self, config, logger):
+        self.config = config
+        self.logger = logger
+        self._tools = {}
+        
+        # Optionally initialize MCP servers
+        self._init_mcp_servers()
+        
+    def load_standard_tools(self, framework):
+        """Automatically load and register all standard contrib tools."""
+        from .tool import Tool
+        from .tools.contrib import (
+            get_current_datetime,
+        )
+        
+        # Try to import optional dependencies
+        try:
+            from .tools.web_search import web_search
+            has_web_search = True
+        except:
+            has_web_search = False
+            
+        try:
+            from .tools.contrib.calculator import calculator
+            has_calculator = True
+        except:
+            has_calculator = False
+        
+        # Basic tools that are always available
+        standard_tools = [
+            ("get_datetime", get_current_datetime, "Get current date and time"),
+        ]
+        
+        # Add optional tools if available
+        if has_web_search:
+            standard_tools.append(("web_search", web_search, "Search the web for information"))
+        if has_calculator:
+            standard_tools.append(("calculator", calculator, "Evaluate mathematical expressions"))
+        
+        for name, func, desc in standard_tools:
+            if name not in self._tools:
+                self.register(name, Tool(name, func, desc))
+
+    def _init_mcp_servers(self):
+        """Initialize MCP servers if credentials available."""
+        try:
+            from .tools_manager import MCPServers
+            self.mcp = MCPServers(self.config, self.logger)
+            self.logger.info("  [OK] Tools (MCP)")
+        except Exception as e:
+            self.logger.info("    Tools (manual registration)")
+            self.mcp = None
+    
+    def register(self, name: str, tool):
+        """Register a tool."""
+        self._tools[name] = tool
+        self.logger.info(f"  [OK] Registered tool: {name}")
+    
+    def get(self, name: str):
+        """Get a tool by name."""
+        return self._tools.get(name)
+    
+    def list(self):
+        """List all registered tools."""
+        return list(self._tools.keys())
+    
+    def get_all(self):
+        """Get all tools."""
+        return self._tools

kite/tools/__init__.py

@@ -0,0 +1,21 @@
+"""
+Kite Tools Module
+
+Standard tools that agents can use directly:
+- WebSearchTool: Web search using DuckDuckGo
+- PythonReplTool: Safe Python code execution
+- ShellTool: Shell command execution (with whitelisting)
+
+MCP Servers are in the mcp/ subpackage.
+"""
+
+from .search import WebSearchTool
+from .code_execution import PythonReplTool
+from .system_tools import ShellTool
+
+__all__ = [
+    'WebSearchTool',
+    'PythonReplTool',
+    'ShellTool'
+]
+