crca 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

utils/rate_limiter.py

@@ -0,0 +1,283 @@
+"""
+Rate limiting utility module.
+
+Provides rate limiting functionality for agents and API calls with support for:
+- Token-based and request-based limiting
+- Per-user/session rate limits
+- Queue management for rate-limited requests
+- Configurable limits (RPM, RPH)
+"""
+
+import time
+import threading
+from collections import deque, defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Any, Tuple
+from loguru import logger
+
+
+@dataclass
+class RateLimitConfig:
+    """Configuration for rate limiting.
+    
+    Attributes:
+        requests_per_minute: Maximum requests per minute (0 = unlimited)
+        requests_per_hour: Maximum requests per hour (0 = unlimited)
+        tokens_per_minute: Maximum tokens per minute (0 = unlimited)
+        tokens_per_hour: Maximum tokens per hour (0 = unlimited)
+        queue_enabled: Whether to queue requests when rate limited
+        max_queue_size: Maximum queue size
+    """
+    requests_per_minute: int = 60
+    requests_per_hour: int = 1000
+    tokens_per_minute: int = 0  # 0 = unlimited
+    tokens_per_hour: int = 0  # 0 = unlimited
+    queue_enabled: bool = True
+    max_queue_size: int = 1000
+
+
+class RateLimiter:
+    """Rate limiter with per-user/session tracking.
+    
+    Provides rate limiting functionality with support for:
+    - Request-based limiting (RPM, RPH)
+    - Token-based limiting (TPM, TPH)
+    - Per-user/session tracking
+    - Queue management for rate-limited requests
+    """
+    
+    def __init__(self, config: Optional[RateLimitConfig] = None):
+        """Initialize rate limiter.
+        
+        Args:
+            config: Rate limit configuration. Uses defaults if None.
+        """
+        self.config = config or RateLimitConfig()
+        self._lock = threading.RLock()
+        
+        # Per-user tracking: {user_id: {type: deque of timestamps}}
+        self._request_history: Dict[str, Dict[str, deque]] = defaultdict(
+            lambda: {
+                "minute": deque(maxlen=self.config.requests_per_minute * 2),
+                "hour": deque(maxlen=self.config.requests_per_hour * 2),
+            }
+        )
+        
+        self._token_history: Dict[str, Dict[str, deque]] = defaultdict(
+            lambda: {
+                "minute": deque(maxlen=1000),
+                "hour": deque(maxlen=10000),
+            }
+        )
+        
+        # Queue for rate-limited requests
+        self._queues: Dict[str, deque] = defaultdict(lambda: deque(maxlen=self.config.max_queue_size))
+        
+        logger.debug(f"Initialized RateLimiter with config: {self.config}")
+    
+    def _clean_old_entries(self, user_id: str, window: str) -> None:
+        """Remove old entries outside the time window.
+        
+        Args:
+            user_id: User identifier
+            window: Time window ('minute' or 'hour')
+        """
+        current_time = time.time()
+        cutoff = current_time - (60 if window == "minute" else 3600)
+        
+        # Clean request history
+        if user_id in self._request_history:
+            history = self._request_history[user_id][window]
+            while history and history[0] < cutoff:
+                history.popleft()
+        
+        # Clean token history
+        if user_id in self._token_history:
+            history = self._token_history[user_id][window]
+            while history and len(history) > 0:
+                if history[0][0] < cutoff:
+                    history.popleft()
+                else:
+                    break
+    
+    def check_rate_limit(
+        self,
+        user_id: str = "default",
+        token_count: int = 0,
+    ) -> Tuple[bool, Optional[str]]:
+        """Check if request is within rate limits.
+        
+        Args:
+            user_id: User identifier for per-user tracking
+            token_count: Number of tokens in the request (0 if not applicable)
+            
+        Returns:
+            Tuple of (is_allowed, error_message)
+            - is_allowed: True if request is allowed, False otherwise
+            - error_message: Error message if not allowed, None otherwise
+        """
+        with self._lock:
+            current_time = time.time()
+            
+            # Clean old entries
+            self._clean_old_entries(user_id, "minute")
+            self._clean_old_entries(user_id, "hour")
+            
+            # Check request-based limits
+            if self.config.requests_per_minute > 0:
+                minute_requests = len(self._request_history[user_id]["minute"])
+                if minute_requests >= self.config.requests_per_minute:
+                    return False, f"Rate limit exceeded: {minute_requests}/{self.config.requests_per_minute} requests per minute"
+            
+            if self.config.requests_per_hour > 0:
+                hour_requests = len(self._request_history[user_id]["hour"])
+                if hour_requests >= self.config.requests_per_hour:
+                    return False, f"Rate limit exceeded: {hour_requests}/{self.config.requests_per_hour} requests per hour"
+            
+            # Check token-based limits
+            if token_count > 0:
+                if self.config.tokens_per_minute > 0:
+                    minute_tokens = sum(
+                        tokens for _, tokens in self._token_history[user_id]["minute"]
+                    )
+                    if minute_tokens + token_count > self.config.tokens_per_minute:
+                        return False, f"Token limit exceeded: {minute_tokens + token_count}/{self.config.tokens_per_minute} tokens per minute"
+                
+                if self.config.tokens_per_hour > 0:
+                    hour_tokens = sum(
+                        tokens for _, tokens in self._token_history[user_id]["hour"]
+                    )
+                    if hour_tokens + token_count > self.config.tokens_per_hour:
+                        return False, f"Token limit exceeded: {hour_tokens + token_count}/{self.config.tokens_per_hour} tokens per hour"
+            
+            # Record request
+            self._request_history[user_id]["minute"].append(current_time)
+            self._request_history[user_id]["hour"].append(current_time)
+            
+            # Record tokens if applicable
+            if token_count > 0:
+                self._token_history[user_id]["minute"].append((current_time, token_count))
+                self._token_history[user_id]["hour"].append((current_time, token_count))
+            
+            return True, None
+    
+    def wait_if_rate_limited(
+        self,
+        user_id: str = "default",
+        token_count: int = 0,
+        max_wait: float = 60.0,
+    ) -> bool:
+        """Wait if rate limited, up to max_wait seconds.
+        
+        Args:
+            user_id: User identifier
+            token_count: Number of tokens in the request
+            max_wait: Maximum time to wait in seconds
+            
+        Returns:
+            True if request can proceed, False if still rate limited after waiting
+        """
+        start_time = time.time()
+        
+        while time.time() - start_time < max_wait:
+            is_allowed, error_msg = self.check_rate_limit(user_id, token_count)
+            if is_allowed:
+                return True
+            
+            # Calculate wait time
+            if "minute" in error_msg:
+                # Wait until oldest request in minute window expires
+                if self._request_history[user_id]["minute"]:
+                    oldest = self._request_history[user_id]["minute"][0]
+                    wait_time = min(60 - (time.time() - oldest) + 1, max_wait)
+                    if wait_time > 0:
+                        time.sleep(min(wait_time, 1.0))  # Sleep in 1s increments
+                else:
+                    time.sleep(0.1)
+            elif "hour" in error_msg:
+                # Wait until oldest request in hour window expires
+                if self._request_history[user_id]["hour"]:
+                    oldest = self._request_history[user_id]["hour"][0]
+                    wait_time = min(3600 - (time.time() - oldest) + 1, max_wait)
+                    if wait_time > 0:
+                        time.sleep(min(wait_time, 1.0))
+                else:
+                    time.sleep(0.1)
+            else:
+                time.sleep(0.1)
+        
+        return False
+    
+    def get_rate_limit_status(self, user_id: str = "default") -> Dict[str, Any]:
+        """Get current rate limit status for a user.
+        
+        Args:
+            user_id: User identifier
+            
+        Returns:
+            Dictionary with rate limit status information
+        """
+        with self._lock:
+            self._clean_old_entries(user_id, "minute")
+            self._clean_old_entries(user_id, "hour")
+            
+            minute_requests = len(self._request_history[user_id]["minute"])
+            hour_requests = len(self._request_history[user_id]["hour"])
+            
+            minute_tokens = sum(
+                tokens for _, tokens in self._token_history[user_id]["minute"]
+            )
+            hour_tokens = sum(
+                tokens for _, tokens in self._token_history[user_id]["hour"]
+            )
+            
+            return {
+                "user_id": user_id,
+                "requests": {
+                    "minute": {
+                        "current": minute_requests,
+                        "limit": self.config.requests_per_minute,
+                        "remaining": max(0, self.config.requests_per_minute - minute_requests),
+                    },
+                    "hour": {
+                        "current": hour_requests,
+                        "limit": self.config.requests_per_hour,
+                        "remaining": max(0, self.config.requests_per_hour - hour_requests),
+                    },
+                },
+                "tokens": {
+                    "minute": {
+                        "current": minute_tokens,
+                        "limit": self.config.tokens_per_minute,
+                        "remaining": max(0, self.config.tokens_per_minute - minute_tokens) if self.config.tokens_per_minute > 0 else -1,
+                    },
+                    "hour": {
+                        "current": hour_tokens,
+                        "limit": self.config.tokens_per_hour,
+                        "remaining": max(0, self.config.tokens_per_hour - hour_tokens) if self.config.tokens_per_hour > 0 else -1,
+                    },
+                },
+            }
+    
+    def reset_user(self, user_id: str) -> None:
+        """Reset rate limit tracking for a user.
+        
+        Args:
+            user_id: User identifier
+        """
+        with self._lock:
+            if user_id in self._request_history:
+                del self._request_history[user_id]
+            if user_id in self._token_history:
+                del self._token_history[user_id]
+            if user_id in self._queues:
+                del self._queues[user_id]
+            logger.debug(f"Reset rate limit tracking for user: {user_id}")
+    
+    def reset_all(self) -> None:
+        """Reset rate limit tracking for all users."""
+        with self._lock:
+            self._request_history.clear()
+            self._token_history.clear()
+            self._queues.clear()
+            logger.debug("Reset rate limit tracking for all users")

utils/router.py

@@ -24,7 +24,7 @@ from swarms.structs.concurrent_workflow import ConcurrentWorkflow
 from swarms.structs.council_as_judge import CouncilAsAJudge
 # DebateWithJudge may not be available - make optional
 try:
-from swarms.structs.debate_with_judge import DebateWithJudge
+    from swarms.structs.debate_with_judge import DebateWithJudge
 except ImportError:
     DebateWithJudge = None  # Will be handled in factory
 from swarms.structs.groupchat import GroupChat
@@ -43,7 +43,7 @@ from swarms.utils.loguru_logger import initialize_logger
 from swarms.utils.output_types import OutputType
 # LLMCouncil may not be available - make optional
 try:
-from swarms.structs.llm_council import LLMCouncil
+    from swarms.structs.llm_council import LLMCouncil
 except ImportError:
     LLMCouncil = None  # Will be handled in factory
 from swarms.structs.round_robin import RoundRobinSwarm

utils/tool_discovery.py

@@ -0,0 +1,307 @@
+"""
+Dynamic tool discovery utilities.
+
+Provides functionality for:
+- Tool registry and scanning
+- Tool metadata extraction
+- Tool schema generation
+"""
+
+import inspect
+from typing import Any, Callable, Dict, List, Optional
+from loguru import logger
+
+try:
+    from swarms.tools.tool import convert_function_to_openai_function_schema
+    TOOL_CONVERSION_AVAILABLE = True
+except ImportError:
+    TOOL_CONVERSION_AVAILABLE = False
+    logger.debug("Tool conversion utilities not available")
+
+
+class ToolRegistry:
+    """Registry for managing and discovering tools."""
+    
+    def __init__(self):
+        """Initialize tool registry."""
+        self._tools: Dict[str, Callable] = {}
+        self._tool_metadata: Dict[str, Dict[str, Any]] = {}
+        logger.debug("Initialized ToolRegistry")
+    
+    def register_tool(
+        self,
+        tool: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Register a tool in the registry.
+        
+        Args:
+            tool: Callable tool function
+            name: Optional tool name (uses function name if None)
+            description: Optional tool description
+            metadata: Optional additional metadata
+            
+        Returns:
+            Registered tool name
+        """
+        tool_name = name or tool.__name__
+        
+        if tool_name in self._tools:
+            logger.warning(f"Tool '{tool_name}' already registered, overwriting")
+        
+        self._tools[tool_name] = tool
+        
+        # Extract metadata
+        tool_metadata = {
+            "name": tool_name,
+            "description": description or tool.__doc__ or "No description",
+            "function": tool,
+            "signature": str(inspect.signature(tool)),
+        }
+        
+        if metadata:
+            tool_metadata.update(metadata)
+        
+        self._tool_metadata[tool_name] = tool_metadata
+        
+        logger.debug(f"Registered tool: {tool_name}")
+        return tool_name
+    
+    def unregister_tool(self, name: str) -> bool:
+        """Unregister a tool from the registry.
+        
+        Args:
+            name: Tool name to unregister
+            
+        Returns:
+            True if tool was unregistered, False if not found
+        """
+        if name in self._tools:
+            del self._tools[name]
+            if name in self._tool_metadata:
+                del self._tool_metadata[name]
+            logger.debug(f"Unregistered tool: {name}")
+            return True
+        return False
+    
+    def get_tool(self, name: str) -> Optional[Callable]:
+        """Get a tool by name.
+        
+        Args:
+            name: Tool name
+            
+        Returns:
+            Tool function or None if not found
+        """
+        return self._tools.get(name)
+    
+    def get_tool_metadata(self, name: str) -> Optional[Dict[str, Any]]:
+        """Get tool metadata by name.
+        
+        Args:
+            name: Tool name
+            
+        Returns:
+            Tool metadata dictionary or None if not found
+        """
+        return self._tool_metadata.get(name)
+    
+    def list_tools(self) -> List[str]:
+        """List all registered tool names.
+        
+        Returns:
+            List of tool names
+        """
+        return list(self._tools.keys())
+    
+    def get_all_tools(self) -> Dict[str, Callable]:
+        """Get all registered tools.
+        
+        Returns:
+            Dictionary mapping tool names to tool functions
+        """
+        return self._tools.copy()
+    
+    def get_all_metadata(self) -> Dict[str, Dict[str, Any]]:
+        """Get metadata for all tools.
+        
+        Returns:
+            Dictionary mapping tool names to metadata
+        """
+        return self._tool_metadata.copy()
+
+
+# Global tool registry instance
+_global_registry = ToolRegistry()
+
+
+def get_global_registry() -> ToolRegistry:
+    """Get the global tool registry instance.
+    
+    Returns:
+        Global ToolRegistry instance
+    """
+    return _global_registry
+
+
+def discover_tools_in_module(module: Any) -> List[Callable]:
+    """Discover all callable tools in a module.
+    
+    Args:
+        module: Module to scan for tools
+        
+    Returns:
+        List of discovered tool functions
+    """
+    tools = []
+    
+    try:
+        for name in dir(module):
+            obj = getattr(module, name)
+            if callable(obj) and not name.startswith("_"):
+                # Check if it looks like a tool (has docstring, takes parameters, etc.)
+                if inspect.isfunction(obj) or inspect.ismethod(obj):
+                    tools.append(obj)
+    except Exception as e:
+        logger.error(f"Error discovering tools in module: {e}")
+    
+    return tools
+
+
+def discover_tools_in_object(obj: Any) -> List[Callable]:
+    """Discover all callable tools in an object.
+    
+    Args:
+        obj: Object to scan for tools
+        
+    Returns:
+        List of discovered tool methods
+    """
+    tools = []
+    
+    try:
+        for name in dir(obj):
+            attr = getattr(obj, name)
+            if callable(attr) and not name.startswith("_"):
+                if inspect.ismethod(attr) or (inspect.isfunction(attr) and hasattr(obj, name)):
+                    tools.append(attr)
+    except Exception as e:
+        logger.error(f"Error discovering tools in object: {e}")
+    
+    return tools
+
+
+def extract_tool_schema(tool: Callable) -> Optional[Dict[str, Any]]:
+    """Extract OpenAI function schema from a tool.
+    
+    Args:
+        tool: Tool function to extract schema from
+        
+    Returns:
+        OpenAI function schema dictionary or None if extraction fails
+    """
+    if not TOOL_CONVERSION_AVAILABLE:
+        # Fallback: create basic schema from function signature
+        try:
+            sig = inspect.signature(tool)
+            params = {}
+            for param_name, param in sig.parameters.items():
+                param_type = "string"
+                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"
+                
+                params[param_name] = {
+                    "type": param_type,
+                    "description": param_name,
+                }
+            
+            return {
+                "name": tool.__name__,
+                "description": tool.__doc__ or "No description",
+                "parameters": {
+                    "type": "object",
+                    "properties": params,
+                    "required": [
+                        name for name, param in sig.parameters.items()
+                        if param.default == inspect.Parameter.empty
+                    ],
+                },
+            }
+        except Exception as e:
+            logger.error(f"Error extracting tool schema: {e}")
+            return None
+    
+    try:
+        schema = convert_function_to_openai_function_schema(tool)
+        return schema
+    except Exception as e:
+        logger.error(f"Error converting tool to schema: {e}")
+        return None
+
+
+def generate_tool_schemas(tools: List[Callable]) -> List[Dict[str, Any]]:
+    """Generate OpenAI function schemas for a list of tools.
+    
+    Args:
+        tools: List of tool functions
+        
+    Returns:
+        List of OpenAI function schema dictionaries
+    """
+    schemas = []
+    
+    for tool in tools:
+        schema = extract_tool_schema(tool)
+        if schema:
+            schemas.append(schema)
+    
+    return schemas
+
+
+def discover_and_register_tools(
+    source: Any,
+    registry: Optional[ToolRegistry] = None,
+) -> List[str]:
+    """Discover tools from a source and register them.
+    
+    Args:
+        source: Module, object, or list of tools to discover from
+        registry: Optional tool registry (uses global if None)
+        
+    Returns:
+        List of registered tool names
+    """
+    if registry is None:
+        registry = get_global_registry()
+    
+    tools = []
+    
+    # Handle different source types
+    if inspect.ismodule(source):
+        tools = discover_tools_in_module(source)
+    elif isinstance(source, list):
+        tools = [t for t in source if callable(t)]
+    elif hasattr(source, "__dict__"):
+        tools = discover_tools_in_object(source)
+    elif callable(source):
+        tools = [source]
+    
+    registered = []
+    for tool in tools:
+        try:
+            name = registry.register_tool(tool)
+            registered.append(name)
+        except Exception as e:
+            logger.error(f"Error registering tool {tool}: {e}")
+    
+    logger.info(f"Registered {len(registered)} tool(s)")
+    return registered

webui/__init__.py

@@ -0,0 +1,10 @@
+"""
+CRCA Web UI Module
+
+Simple, institutional web interface for CRCA agents.
+"""
+
+from webui.app import app
+from webui.config import AGENTS, TOOLS
+
+__all__ = ["app", "AGENTS", "TOOLS"]