crca 1.4.0__py3-none-any.whl

tools/sensors.py

@@ -0,0 +1,285 @@
+"""Sensor interfaces and implementations for policy engine.
+
+Provides standardized sensor interfaces for reading system metrics,
+cloud resources, and custom metrics.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Callable
+from loguru import logger
+
+try:
+    import psutil
+    PSUTIL_AVAILABLE = True
+except ImportError:
+    PSUTIL_AVAILABLE = False
+    logger.warning("psutil not available - SystemMetricsSensor will be disabled")
+
+
+class BaseSensor(ABC):
+    """Abstract base class for sensors.
+    
+    All sensors must implement read() to return metric snapshots
+    matching the doctrine's metric specifications.
+    """
+    
+    @abstractmethod
+    def read(self) -> Dict[str, float]:
+        """
+        Read current metric snapshot.
+        
+        Returns:
+            Dict[str, float]: Metric name -> value mapping
+        """
+        pass
+    
+    def validate(self, snapshot: Dict[str, float], expected_metrics: List[str]) -> bool:
+        """
+        Validate snapshot matches expected metrics.
+        
+        Args:
+            snapshot: Metric snapshot to validate
+            expected_metrics: List of expected metric names
+            
+        Returns:
+            bool: True if snapshot is valid
+        """
+        missing = set(expected_metrics) - set(snapshot.keys())
+        if missing:
+            logger.warning(f"Missing metrics in snapshot: {missing}")
+            return False
+        return True
+    
+    def health_check(self) -> bool:
+        """
+        Check sensor availability.
+        
+        Returns:
+            bool: True if sensor is healthy
+        """
+        try:
+            self.read()
+            return True
+        except Exception as e:
+            logger.error(f"Sensor health check failed: {e}")
+            return False
+
+
+class SystemMetricsSensor(BaseSensor):
+    """OS-level system metrics sensor using psutil.
+    
+    Extracts:
+    - CPU metrics: cpu_percent, cpu_count, cpu_freq
+    - Memory metrics: memory_percent, memory_available, memory_used
+    - Disk metrics: disk_usage_percent, disk_io_read, disk_io_write
+    - Network metrics: network_bytes_sent, network_bytes_recv
+    - Process metrics: process_count
+    """
+    
+    def __init__(self, metric_mapping: Optional[Dict[str, str]] = None):
+        """
+        Initialize system metrics sensor.
+        
+        Args:
+            metric_mapping: Optional mapping from doctrine metric names to psutil attributes
+        """
+        if not PSUTIL_AVAILABLE:
+            raise ImportError("psutil is required for SystemMetricsSensor")
+        
+        self.metric_mapping = metric_mapping or {}
+        self._last_net_io = None
+        self._last_disk_io = None
+    
+    def read(self) -> Dict[str, float]:
+        """Read system metrics."""
+        snapshot = {}
+        
+        # CPU metrics
+        snapshot['cpu_percent'] = psutil.cpu_percent(interval=0.1)
+        snapshot['cpu_count'] = float(psutil.cpu_count())
+        try:
+            cpu_freq = psutil.cpu_freq()
+            snapshot['cpu_freq_mhz'] = cpu_freq.current if cpu_freq else 0.0
+        except:
+            snapshot['cpu_freq_mhz'] = 0.0
+        
+        # Memory metrics
+        mem = psutil.virtual_memory()
+        snapshot['memory_percent'] = mem.percent
+        snapshot['memory_available_gb'] = mem.available / (1024**3)
+        snapshot['memory_used_gb'] = mem.used / (1024**3)
+        
+        # Disk metrics
+        try:
+            disk = psutil.disk_usage('/')
+            snapshot['disk_usage_percent'] = disk.percent
+        except:
+            snapshot['disk_usage_percent'] = 0.0
+        
+        # Disk I/O (delta from last read)
+        try:
+            disk_io = psutil.disk_io_counters()
+            if disk_io and self._last_disk_io:
+                snapshot['disk_io_read_mb'] = (disk_io.read_bytes - self._last_disk_io.read_bytes) / (1024**2)
+                snapshot['disk_io_write_mb'] = (disk_io.write_bytes - self._last_disk_io.write_bytes) / (1024**2)
+            else:
+                snapshot['disk_io_read_mb'] = 0.0
+                snapshot['disk_io_write_mb'] = 0.0
+            self._last_disk_io = disk_io
+        except:
+            snapshot['disk_io_read_mb'] = 0.0
+            snapshot['disk_io_write_mb'] = 0.0
+        
+        # Network I/O (delta from last read)
+        try:
+            net_io = psutil.net_io_counters()
+            if net_io and self._last_net_io:
+                snapshot['network_bytes_sent_mb'] = (net_io.bytes_sent - self._last_net_io.bytes_sent) / (1024**2)
+                snapshot['network_bytes_recv_mb'] = (net_io.bytes_recv - self._last_net_io.bytes_recv) / (1024**2)
+            else:
+                snapshot['network_bytes_sent_mb'] = 0.0
+                snapshot['network_bytes_recv_mb'] = 0.0
+            self._last_net_io = net_io
+        except:
+            snapshot['network_bytes_sent_mb'] = 0.0
+            snapshot['network_bytes_recv_mb'] = 0.0
+        
+        # Process count
+        try:
+            snapshot['process_count'] = float(len(psutil.pids()))
+        except:
+            snapshot['process_count'] = 0.0
+        
+        # Apply metric mapping if provided
+        if self.metric_mapping:
+            mapped_snapshot = {}
+            for doctrine_metric, system_metric in self.metric_mapping.items():
+                if system_metric in snapshot:
+                    mapped_snapshot[doctrine_metric] = snapshot[system_metric]
+                else:
+                    logger.warning(f"Metric mapping failed: {system_metric} not in snapshot")
+            return mapped_snapshot
+        
+        return snapshot
+
+
+class CloudResourceSensor(BaseSensor):
+    """Abstract base for cloud provider metrics.
+    
+    Subclasses should implement provider-specific metric extraction.
+    """
+    
+    def __init__(self, provider: str, config: Optional[Dict[str, Any]] = None):
+        """
+        Initialize cloud resource sensor.
+        
+        Args:
+            provider: Cloud provider name ("aws", "gcp", "azure")
+            config: Provider-specific configuration
+        """
+        self.provider = provider
+        self.config = config or {}
+    
+    @abstractmethod
+    def read(self) -> Dict[str, float]:
+        """Read cloud metrics (implemented by subclasses)."""
+        pass
+
+
+class CustomMetricSensor(BaseSensor):
+    """User-defined metric sensor with custom extraction function.
+    
+    Accepts a custom function that returns metric snapshots.
+    """
+    
+    def __init__(self, extractor: Callable[[], Dict[str, float]]):
+        """
+        Initialize custom metric sensor.
+        
+        Args:
+            extractor: Function that returns Dict[str, float] metric snapshot
+        """
+        self.extractor = extractor
+    
+    def read(self) -> Dict[str, float]:
+        """Read metrics using custom extractor."""
+        try:
+            return self.extractor()
+        except Exception as e:
+            logger.error(f"Custom sensor extractor failed: {e}")
+            return {}
+
+
+class SensorRegistry:
+    """Registry mapping metric extractor keys to sensor instances.
+    
+    Provides auto-discovery and fallback chain for missing metrics.
+    """
+    
+    def __init__(self):
+        """Initialize sensor registry."""
+        self.sensors: Dict[str, BaseSensor] = {}
+        self.metric_to_sensor: Dict[str, str] = {}  # metric_name -> sensor_key
+    
+    def register(self, sensor_key: str, sensor: BaseSensor, metrics: Optional[List[str]] = None) -> None:
+        """
+        Register a sensor.
+        
+        Args:
+            sensor_key: Unique identifier for sensor
+            sensor: Sensor instance
+            metrics: Optional list of metric names this sensor provides
+        """
+        self.sensors[sensor_key] = sensor
+        if metrics:
+            for metric in metrics:
+                self.metric_to_sensor[metric] = sensor_key
+        logger.info(f"Registered sensor: {sensor_key}")
+    
+    def get_sensor(self, sensor_key: str) -> Optional[BaseSensor]:
+        """Get sensor by key."""
+        return self.sensors.get(sensor_key)
+    
+    def read_all(self, required_metrics: Optional[List[str]] = None) -> Dict[str, float]:
+        """
+        Read metrics from all registered sensors.
+        
+        Args:
+            required_metrics: Optional list of required metric names
+            
+        Returns:
+            Dict[str, float]: Combined metric snapshot
+        """
+        snapshot = {}
+        
+        # Read from all sensors
+        for sensor_key, sensor in self.sensors.items():
+            try:
+                sensor_snapshot = sensor.read()
+                snapshot.update(sensor_snapshot)
+            except Exception as e:
+                logger.error(f"Sensor {sensor_key} read failed: {e}")
+        
+        # Validate required metrics
+        if required_metrics:
+            missing = set(required_metrics) - set(snapshot.keys())
+            if missing:
+                logger.warning(f"Missing required metrics: {missing}")
+        
+        return snapshot
+    
+    def auto_discover(self) -> None:
+        """Auto-discover and register available sensors."""
+        # Try to register SystemMetricsSensor if psutil available
+        if PSUTIL_AVAILABLE:
+            try:
+                system_sensor = SystemMetricsSensor()
+                if system_sensor.health_check():
+                    self.register("system", system_sensor)
+            except Exception as e:
+                logger.warning(f"Failed to auto-discover system sensor: {e}")
+    
+    def health_check_all(self) -> Dict[str, bool]:
+        """Check health of all sensors."""
+        return {key: sensor.health_check() for key, sensor in self.sensors.items()}
+

utils/Agent_types.py

@@ -0,0 +1,15 @@
+"""Agent type definitions for CR-CA.
+
+This module provides type aliases for agent-related types used throughout
+the CR-CA codebase.
+"""
+
+from typing import Any, Callable, Sequence, Union
+
+from swarms.structs.agent import Agent
+
+# Unified type for agent
+AgentType = Union[Agent, Callable, Any]
+
+# List of agents
+AgentListType = Sequence[AgentType]

utils/HHCS.py

@@ -0,0 +1,277 @@
+"""
+Hybrid Hierarchical-Cluster Swarm implementation.
+
+Provides intelligent task routing to appropriate swarm configurations
+using an agent-based routing system with hierarchical decision-making.
+"""
+
+import json
+import os
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Callable, List, Union
+
+from swarms.structs.agent import Agent
+from swarms.structs.conversation import Conversation
+from swarms.structs.multi_agent_exec import get_swarms_info
+from swarms.structs.swarm_router import SwarmRouter
+from swarms.utils.history_output_formatter import HistoryOutputType, history_output_formatter
+
+
+_ROUTER_TOOLS = [{
+    "type": "function",
+    "function": {
+        "name": "select_swarm",
+        "description": "Analyzes the input task and selects the most appropriate swarm configuration.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "reasoning": {"type": "string", "description": "Reasoning behind swarm selection."},
+                "swarm_name": {"type": "string", "description": "Name of the selected swarm."},
+                "task_description": {"type": "string", "description": "Structured task description."},
+            },
+            "required": ["reasoning", "swarm_name", "task_description"],
+        },
+    },
+}]
+
+_ROUTER_SYSTEM_PROMPT = """You are an intelligent Router Agent responsible for analyzing tasks and directing them to the most appropriate swarm.
+
+Key Responsibilities:
+1. Task Analysis: Analyze requirements, complexity, and domain
+2. Swarm Selection: Match task requirements with swarm capabilities
+3. Decision Making: Evaluate all available swarms systematically
+4. Output Requirements: Provide clear justification and structured task description
+
+Your output must follow this format:
+{
+    "swarm_name": "Name of the selected swarm",
+    "task_description": "Detailed and structured task description"
+}"""
+
+
+class HybridHierarchicalClusterSwarm:
+    """Hybrid hierarchical-cluster swarm for intelligent task routing.
+    
+    Routes tasks to appropriate swarm configurations using an agent-based
+    routing system. Supports parallel batch processing and maintains
+    conversation history for context management.
+    
+    Attributes:
+        name: Swarm identifier name.
+        description: Description of swarm functionality.
+        swarms: List of available swarm routers.
+        max_loops: Maximum number of processing loops.
+        output_type: Format for output extraction.
+        conversation: Conversation history manager.
+        router_agent: Agent responsible for task routing decisions.
+    """
+    
+    def __init__(self, name: str = "Hybrid Hierarchical-Cluster Swarm",
+                 description: str = "A swarm that uses a hybrid hierarchical-peer model to solve complex tasks.",
+                 swarms: List[Union[SwarmRouter, Callable]] = None,
+                 agents: List[Union[Agent, Callable]] = None,  # Accept agents for convenience
+                 max_loops: int = 1, output_type: HistoryOutputType = "list",
+                 router_agent_model_name: str = "gpt-4o-mini", *args, **kwargs):
+        """Initialize hybrid hierarchical-cluster swarm.
+        
+        Args:
+            name: Swarm identifier name.
+            description: Description of swarm functionality.
+            swarms: List of available swarm routers or callables.
+            max_loops: Maximum number of processing loops.
+            output_type: Format for output extraction.
+            router_agent_model_name: Model name for router agent.
+        """
+        self.name = name
+        self.description = description
+        
+        # Handle both swarms and agents parameters
+        if swarms is not None:
+            self.swarms = swarms
+        elif agents is not None:
+            # Convert agents to swarms by wrapping them in SwarmRouter
+            from utils.router import SwarmRouter
+            self.swarms = [
+                SwarmRouter(
+                    name=f"swarm-{i}",
+                    description=f"Swarm wrapper for agent {i}",
+                    agents=[agent] if not isinstance(agent, list) else agent,
+                    swarm_type="SequentialWorkflow",
+                    max_loops=max_loops,
+                    output_type=output_type,
+                    **kwargs
+                ) for i, agent in enumerate(agents)
+            ]
+        else:
+            self.swarms = []
+        
+        self.max_loops = max_loops
+        self.output_type = output_type
+        self.conversation = Conversation()
+        
+        system_prompt = f"{_ROUTER_SYSTEM_PROMPT}\n\n{get_swarms_info(swarms=self.swarms)}"
+        
+        # Extract model_name from kwargs if provided, otherwise use router_agent_model_name
+        model = kwargs.pop("model_name", router_agent_model_name)
+        
+        self.router_agent = Agent(agent_name="Router Agent",
+                                 agent_description="Routes tasks to appropriate swarms.",
+                                 system_prompt=system_prompt,
+                                 tools_list_dictionary=_ROUTER_TOOLS,
+                                 model_name=model,
+                                 max_loops=1, output_type="final",
+                                 **kwargs)  # Pass remaining kwargs to Agent
+    
+    def _parse_router_response(self, response: Union[str, dict, None]) -> dict:
+        """Parse router agent response into dictionary format.
+        
+        Args:
+            response: Response from router agent (string or dict).
+            
+        Returns:
+            Parsed response dictionary.
+            
+        Raises:
+            ValueError: If response cannot be parsed or is invalid.
+        """
+        if response is None:
+            raise ValueError("Router agent returned None response. Check agent configuration and model availability.")
+        
+        if isinstance(response, str):
+            # Handle empty or "No response generated" messages
+            if not response.strip() or "No response generated" in response:
+                raise ValueError(f"Router agent returned empty or invalid response: {response}")
+            try:
+                # Try to extract JSON from the response if it's embedded in text
+                import re
+                json_match = re.search(r'\{[^{}]*\}', response)
+                if json_match:
+                    return json.loads(json_match.group())
+                return json.loads(response)
+            except json.JSONDecodeError:
+                raise ValueError(f"Invalid JSON response from router agent: {response}")
+        
+        if isinstance(response, dict):
+        return response
+        
+        raise ValueError(f"Unexpected response type from router agent: {type(response)}")
+    
+    def _validate_router_response(self, response: dict) -> tuple:
+        """Validate and extract swarm name and task description.
+        
+        Args:
+            response: Parsed response dictionary.
+            
+        Returns:
+            Tuple of (swarm_name, task_description).
+            
+        Raises:
+            ValueError: If required fields are missing.
+        """
+        swarm_name = response.get("swarm_name")
+        task_description = response.get("task_description")
+        
+        if not swarm_name or not task_description:
+            raise ValueError(f"Invalid response from router agent: both 'swarm_name' and 'task_description' must be present. "
+                           f"Received: swarm_name={swarm_name}, task_description={task_description}. "
+                           f"Model: {self.router_agent.model_name}")
+        return swarm_name, task_description
+    
+    def find_swarm_by_name(self, swarm_name: str) -> Union[SwarmRouter, Callable, None]:
+        """Locate swarm by name identifier.
+        
+        Args:
+            swarm_name: Name of swarm to locate.
+            
+        Returns:
+            Found swarm router or None if not found.
+        """
+        return next((swarm for swarm in self.swarms if swarm.name == swarm_name), None)
+    
+    def route_task(self, swarm_name: str, task_description: str) -> None:
+        """Route task to specified swarm and record output.
+        
+        Args:
+            swarm_name: Name of target swarm.
+            task_description: Task description to execute.
+            
+        Raises:
+            ValueError: If swarm is not found.
+        """
+        swarm = self.find_swarm_by_name(swarm_name)
+        if not swarm:
+            raise ValueError(f"Swarm '{swarm_name}' not found.")
+        
+        output = swarm.run(task_description)
+        self.conversation.add(role=swarm.name, content=output)
+    
+    def run(self, task: str, *args, **kwargs) -> str:
+        """Execute routing process for given task.
+        
+        Args:
+            task: Task string to process.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+            
+        Returns:
+            Formatted history output string.
+            
+        Raises:
+            ValueError: If task is empty or routing fails.
+        """
+        if not task:
+            raise ValueError("Task cannot be empty.")
+        
+        self.conversation.add(role="User", content=task)
+        response = self.router_agent.run(task=task)
+        
+        # Handle None or empty responses
+        if response is None:
+            raise ValueError("Router agent returned None. Check agent configuration, API keys, and model availability.")
+        
+        try:
+        parsed_response = self._parse_router_response(response)
+        except ValueError as e:
+            raise ValueError(f"Failed to parse router response: {e}. Response was: {response}")
+        
+        try:
+        swarm_name, task_description = self._validate_router_response(parsed_response)
+        except ValueError as e:
+            raise ValueError(f"Failed to validate router response: {e}. Parsed response was: {parsed_response}")
+        
+        self.route_task(swarm_name, task_description)
+        
+        return history_output_formatter(self.conversation, self.output_type)
+    
+    def batched_run(self, tasks: List[str]) -> List[str]:
+        """Execute routing process for multiple tasks in parallel.
+        
+        Args:
+            tasks: List of task strings to process.
+            
+        Returns:
+            List of formatted history outputs.
+            
+        Raises:
+            ValueError: If task list is empty.
+        """
+        if not tasks:
+            raise ValueError("Task list cannot be empty.")
+        
+        max_workers = os.cpu_count() * 2
+        results = []
+        
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            future_to_task = {executor.submit(self.run, task): task for task in tasks}
+            
+            for future in as_completed(future_to_task):
+                try:
+                    results.append(future.result())
+                except Exception as e:
+                    results.append(f"Error processing task: {str(e)}")
+        
+        return results
+
+
+# Alias for convenience
+HHCS = HybridHierarchicalClusterSwarm

utils/__init__.py

@@ -0,0 +1,30 @@
+"""
+CRCA Utilities Module
+
+Provides utility functions and classes for formatting, visualization,
+and common operations within the CRCA framework.
+"""
+
+try:
+    from .formatter import Formatter, MarkdownOutputHandler, formatter
+    FORMATTER_AVAILABLE = True
+except ImportError:
+    Formatter = None
+    MarkdownOutputHandler = None
+    formatter = None
+    FORMATTER_AVAILABLE = False
+
+try:
+    from .tui import CorporateSwarmTUI, create_corporate_tui, ViewMode, TUIState
+    TUI_AVAILABLE = True
+except ImportError:
+    CorporateSwarmTUI = None
+    create_corporate_tui = None
+    ViewMode = None
+    TUIState = None
+    TUI_AVAILABLE = False
+
+__all__ = [
+    "Formatter", "MarkdownOutputHandler", "formatter", "FORMATTER_AVAILABLE",
+    "CorporateSwarmTUI", "create_corporate_tui", "ViewMode", "TUIState", "TUI_AVAILABLE"
+]