flock-core 0.4.520__py3-none-any.whl → 0.5.0b2__py3-none-any.whl

flock/{modules/performance/metrics_module.py → components/utility/metrics_utility_component.py}

@@ -1,22 +1,26 @@
-"""Performance and metrics tracking for Flock agents."""
+# src/flock/components/utility/metrics_utility_component.py
+"""Performance and metrics tracking for Flock agents using unified component architecture."""
 
 import json
 import os
 import time
 from collections import defaultdict
 from datetime import datetime
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 import numpy as np
 import psutil
-from pydantic import BaseModel, Field, validator
+from pydantic import BaseModel, Field, field_validator
 
+from flock.core.component.agent_component_base import AgentComponentConfig
+from flock.core.component.utility_component_base import UtilityComponentBase
 from flock.core.context.context import FlockContext
-from flock.core.flock_agent import FlockAgent
-from flock.core.flock_module import FlockModule, FlockModuleConfig
-from flock.core.flock_registry import flock_component
+from flock.core.registry import flock_component
 from flock.core.mcp.flock_mcp_server import FlockMCPServerBase
 
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+
 
 class MetricPoint(BaseModel):
     """Single metric measurement."""
@@ -25,11 +29,10 @@ class MetricPoint(BaseModel):
     value: int | float | str
     tags: dict[str, str] = {}
 
-    class Config:
-        arbitrary_types_allowed = True
+    model_config = {"arbitrary_types_allowed": True}
 
 
-class MetricsModuleConfig(FlockModuleConfig):
+class MetricsUtilityConfig(AgentComponentConfig):
     """Configuration for performance metrics collection."""
 
     # Collection settings
@@ -66,7 +69,8 @@ class MetricsModuleConfig(FlockModuleConfig):
         default=1000, description="Threshold for latency alerts"
     )
 
-    @validator("aggregation_interval")
+    @field_validator("aggregation_interval")
+    @classmethod
     def validate_interval(cls, v):
         """Validate time interval format."""
         if v[-1] not in ["s", "m", "h", "d"]:
@@ -74,23 +78,30 @@ class MetricsModuleConfig(FlockModuleConfig):
         return v
 
 
-@flock_component(config_class=MetricsModuleConfig)
-class MetricsModule(FlockModule):
-    """Module for collecting and analyzing agent performance metrics."""
+@flock_component(config_class=MetricsUtilityConfig)
+class MetricsUtilityComponent(UtilityComponentBase):
+    """Utility component for collecting and analyzing agent performance metrics."""
 
     # --- Singleton holder for convenient static access ---
-    _INSTANCE: "MetricsModule | None" = None
+    _INSTANCE: "MetricsUtilityComponent | None" = None
 
-    name: str = "performance_metrics"
-    config: MetricsModuleConfig = Field(
-        default_factory=MetricsModuleConfig,
+    config: MetricsUtilityConfig = Field(
+        default_factory=MetricsUtilityConfig,
         description="Performance metrics configuration",
     )
 
-    def __init__(self, name, config):
-        super().__init__(name=name, config=config)
+    def __init__(
+        self,
+        name: str = "metrics",
+        config: MetricsUtilityConfig | None = None,
+        **data,
+    ):
+        if config is None:
+            config = MetricsUtilityConfig()
+        super().__init__(name=name, config=config, **data)
+
         # Register singleton for static helpers
-        MetricsModule._INSTANCE = self
+        MetricsUtilityComponent._INSTANCE = self
         self._metrics = defaultdict(list)
         self._start_time: float | None = None
         self._server_start_time: float | None = None
@@ -130,8 +141,6 @@ class MetricsModule(FlockModule):
             except ImportError:
                 self.config.storage_type = "json"
 
-    """Fixes for metrics summary calculation."""
-
     def _load_metrics_from_files(
         self, metric_name: str = None
     ) -> dict[str, list[MetricPoint]]:
@@ -236,40 +245,6 @@ class MetricsModule(FlockModule):
 
         return stats
 
-    async def on_terminate(
-        self,
-        agent: FlockAgent,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-        result: dict[str, Any] | None = None,
-    ) -> None:
-        """Clean up and final metric recording."""
-        if self.config.storage_type == "json":
-            # Save aggregated metrics
-            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-            summary_file = os.path.join(
-                self.config.metrics_dir,
-                f"summary_{agent.name}_{timestamp}.json",
-            )
-
-            # Calculate summary for all metrics
-            summary = {
-                "agent": agent.name,
-                "timestamp": timestamp,
-                "metrics": {},
-            }
-
-            # Get all unique metric names from files
-            all_metrics = self._load_metrics_from_files()
-
-            for metric_name in all_metrics:
-                stats = self.get_statistics(metric_name)
-                if stats:  # Only include metrics that have data
-                    summary["metrics"][metric_name] = stats
-
-            with open(summary_file, "w") as f:
-                json.dump(summary, f, indent=2)
-
     def _record_metric(
         self, name: str, value: int | float | str, tags: dict[str, str] = None
     ) -> None:
@@ -342,29 +317,7 @@ class MetricsModule(FlockModule):
             print(
                 f"Warning: Using estimated token count. Install tiktoken for accurate counting."
             )
-
-    def _should_alert(self, metric: str, value: float) -> bool:
-        """Check if metric should trigger alert."""
-        if metric == "latency" and self.config.alert_on_high_latency:
-            return value * 1000 > self.config.latency_threshold_ms
-        return False
-
-    async def on_initialize(
-        self,
-        agent: FlockAgent,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-    ) -> None:
-        """Initialize metrics collection."""
-        self._start_time = time.time()
-
-        if self.config.collect_memory:
-            self._start_memory = psutil.Process().memory_info().rss
-            self._record_metric(
-                "memory",
-                self._start_memory,
-                {"agent": agent.name, "phase": "start"},
-            )
+            return token_estimate
 
     def _calculate_cost(
         self, text: str, model: str, is_completion: bool = False
@@ -391,9 +344,32 @@ class MetricsModule(FlockModule):
             total_cost = 0.0
             return token_count, total_cost
 
+    def _should_alert(self, metric: str, value: float) -> bool:
+        """Check if metric should trigger alert."""
+        if metric == "latency" and self.config.alert_on_high_latency:
+            return value * 1000 > self.config.latency_threshold_ms
+        return False
+
+    async def on_initialize(
+        self,
+        agent: "FlockAgent",
+        inputs: dict[str, Any],
+        context: FlockContext | None = None,
+    ) -> None:
+        """Initialize metrics collection."""
+        self._start_time = time.time()
+
+        if self.config.collect_memory:
+            self._start_memory = psutil.Process().memory_info().rss
+            self._record_metric(
+                "memory",
+                self._start_memory,
+                {"agent": agent.name, "phase": "start"},
+            )
+
     async def on_pre_evaluate(
         self,
-        agent: FlockAgent,
+        agent: "FlockAgent",
         inputs: dict[str, Any],
         context: FlockContext | None = None,
     ) -> dict[str, Any]:
@@ -434,7 +410,7 @@ class MetricsModule(FlockModule):
 
     async def on_post_evaluate(
         self,
-        agent: FlockAgent,
+        agent: "FlockAgent",
         inputs: dict[str, Any],
         context: FlockContext | None = None,
         result: dict[str, Any] | None = None,
@@ -449,7 +425,7 @@ class MetricsModule(FlockModule):
                 # In practice, you'd want to integrate with a proper alerting system
                 print(f"ALERT: High latency detected: {latency * 1000:.2f}ms")
 
-        if self.config.collect_token_usage:
+        if self.config.collect_token_usage and result:
             # Calculate output tokens and cost
             total_output_tokens = 0
             total_output_cost = 0.0
@@ -493,7 +469,7 @@ class MetricsModule(FlockModule):
 
     async def on_error(
         self,
-        agent: FlockAgent,
+        agent: "FlockAgent",
         error: Exception,
         inputs: dict[str, Any],
         context: FlockContext | None = None,
@@ -505,16 +481,55 @@ class MetricsModule(FlockModule):
             {"agent": agent.name, "error_type": type(error).__name__},
         )
 
+    async def on_terminate(
+        self,
+        agent: "FlockAgent",
+        inputs: dict[str, Any],
+        context: FlockContext | None = None,
+        result: dict[str, Any] | None = None,
+    ) -> None:
+        """Clean up and final metric recording."""
+        if self.config.storage_type == "json":
+            # Save aggregated metrics
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            summary_file = os.path.join(
+                self.config.metrics_dir,
+                f"summary_{agent.name}_{timestamp}.json",
+            )
+
+            # Calculate summary for all metrics
+            summary = {
+                "agent": agent.name,
+                "timestamp": timestamp,
+                "metrics": {},
+            }
+
+            # Get all unique metric names from files
+            all_metrics = self._load_metrics_from_files()
+
+            for metric_name in all_metrics:
+                stats = self.get_statistics(metric_name)
+                if stats:  # Only include metrics that have data
+                    summary["metrics"][metric_name] = stats
+
+            with open(summary_file, "w") as f:
+                json.dump(summary, f, indent=2)
+
     # --------------------------------------------------
     # Public helper for external modules
     # --------------------------------------------------
     @classmethod
-    def record(cls, name: str, value: int | float | str, tags: dict[str, str] | None = None):
+    def record(
+        cls,
+        name: str,
+        value: int | float | str,
+        tags: dict[str, str] | None = None,
+    ):
         """Record a metric from anywhere in the codebase.
 
         Example:
-            MetricsModule.record("custom_latency", 123, {"stage": "inference"})
-        The call will forward to the *first* instantiated MetricsModule.  If no
+            MetricsUtilityComponent.record("custom_latency", 123, {"stage": "inference"})
+        The call will forward to the *first* instantiated MetricsUtilityComponent.  If no
         instance exists in the current run the call is a no-op so that importing
         this helper never crashes test-code.
         """

flock/{modules/output/output_module.py → components/utility/output_utility_component.py}

@@ -1,31 +1,27 @@
-"""Output formatting and display functionality for agents."""
+# src/flock/components/utility/output_utility_component.py
+"""Output formatting and display functionality for agents using unified component architecture."""
 
+import re
 from typing import TYPE_CHECKING, Any
 
 from pydantic import Field
 
-from flock.core.context.context_vars import FLOCK_BATCH_SILENT_MODE
-from flock.core.flock_registry import flock_component
-
-if TYPE_CHECKING:
-    from flock.core import FlockAgent
-
+from flock.core.component.agent_component_base import AgentComponentConfig
+from flock.core.component.utility_component_base import UtilityComponentBase
 from flock.core.context.context import FlockContext
-from flock.core.flock_module import FlockModule, FlockModuleConfig
-from flock.core.logging.formatters.themed_formatter import (
-    ThemedAgentResultFormatter,
-)
+from flock.core.context.context_vars import FLOCK_BATCH_SILENT_MODE
+from flock.core.registry import flock_component
+from flock.core.logging.formatters.themed_formatter import ThemedAgentResultFormatter
 from flock.core.logging.formatters.themes import OutputTheme
 from flock.core.logging.logging import get_logger
 
-# from flock.core.logging.formatters.themes import OutputTheme
-# from flock.core.logging.logging import get_logger
-# from flock.core.serialization.json_encoder import FlockJSONEncoder
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
 
-logger = get_logger("module.output")
+logger = get_logger("components.utility.output")
 
 
-class OutputModuleConfig(FlockModuleConfig):
+class OutputUtilityConfig(AgentComponentConfig):
     """Configuration for output formatting and display."""
 
     theme: OutputTheme = Field(
@@ -61,17 +57,18 @@ class OutputModuleConfig(FlockModuleConfig):
     )
 
 
-@flock_component(config_class=OutputModuleConfig)
-class OutputModule(FlockModule):
-    """Module that handles output formatting and display."""
+@flock_component(config_class=OutputUtilityConfig)
+class OutputUtilityComponent(UtilityComponentBase):
+    """Utility component that handles output formatting and display."""
 
-    name: str = "output"
-    config: OutputModuleConfig = Field(
-        default_factory=OutputModuleConfig, description="Output configuration"
+    config: OutputUtilityConfig = Field(
+        default_factory=OutputUtilityConfig, description="Output configuration"
     )
 
-    def __init__(self, name: str, config: OutputModuleConfig):
-        super().__init__(name=name, config=config)
+    def __init__(self, name: str = "output", config: OutputUtilityConfig | None = None, **data):
+        if config is None:
+            config = OutputUtilityConfig()
+        super().__init__(name=name, config=config, **data)
         self._formatter = ThemedAgentResultFormatter(
             theme=self.config.theme,
             max_length=self.config.max_length,
@@ -98,34 +95,40 @@ class OutputModule(FlockModule):
 
     def _format_dict(self, d: dict[str, Any], indent: int = 0) -> str:
         """Format a dictionary with proper indentation."""
-        lines = []
-        for k, v in d.items():
-            formatted_value = self._format_value(v, k)
-            if (
-                self.config.truncate_long_values
-                and len(formatted_value) > self.config.max_length
-            ):
-                formatted_value = (
-                    formatted_value[: self.config.max_length] + "..."
-                )
-            lines.append(f"{'  ' * indent}{k}: {formatted_value}")
-        return "\n".join(lines)
+        if not d:
+            return "{}"
+        
+        items = []
+        prefix = "  " * indent
+        for key, value in d.items():
+            if self.config.truncate_long_values and isinstance(value, str) and len(value) > 100:
+                value = value[:97] + "..."
+            formatted_value = self._format_value(value, key)
+            items.append(f"{prefix}  {key}: {formatted_value}")
+        
+        return "{\n" + "\n".join(items) + f"\n{prefix}}}"
 
     def _format_list(self, lst: list[Any]) -> str:
-        """Format a list with proper indentation."""
-        return "\n".join(f"- {self._format_value(item, '')}" for item in lst)
+        """Format a list with proper structure."""
+        if not lst:
+            return "[]"
+        
+        if len(lst) <= 3:
+            return str(lst)
+        
+        # For longer lists, show first few items and count
+        preview = [str(item) for item in lst[:3]]
+        return f"[{', '.join(preview)}, ... ({len(lst)} total)]"
 
     def _format_potential_code(self, text: str) -> str:
-        """Format text that might contain code blocks."""
-        import re
-
+        """Apply syntax highlighting to potential code blocks."""
+        # Simple pattern matching for code blocks
         def replace_code_block(match):
+            language = match.group(1) or "text"
             code = match.group(2)
-            lang = match.group(1) if match.group(1) else ""
-            # Here you could add syntax highlighting
-            return f"```{lang}\n{code}\n```"
-
-        # Replace code blocks with formatted versions
+            return f"[CODE:{language}]\n{code}\n[/CODE]"
+        
+        # Replace markdown-style code blocks
         text = re.sub(
             r"```(\w+)?\n(.*?)\n```", replace_code_block, text, flags=re.DOTALL
         )
@@ -174,7 +177,6 @@ class OutputModule(FlockModule):
                 theme=self.config.theme,
                 max_length=self.config.max_length,
                 render_table=self.config.render_table,
-                wait_for_input=self.config.wait_for_input,
             )
         self._formatter.display_result(result_to_display, agent.name)
 
@@ -187,8 +189,6 @@ class OutputModule(FlockModule):
             theme=self.config.theme,
             max_length=self.config.max_length,
             render_table=self.config.render_table,
-            wait_for_input=self.config.wait_for_input,
-            write_to_file=self.config.write_to_file,
         )
 
     def add_custom_formatter(self, key: str, formatter_name: str) -> None:

flock/core/__init__.py

@@ -3,11 +3,9 @@
 from flock.core.context.context import FlockContext
 from flock.core.flock import Flock
 from flock.core.flock_agent import FlockAgent
-from flock.core.flock_evaluator import FlockEvaluator, FlockEvaluatorConfig
 from flock.core.flock_factory import FlockFactory
-from flock.core.flock_module import FlockModule, FlockModuleConfig
-from flock.core.flock_registry import (
-    FlockRegistry,
+from flock.core.registry import (
+    RegistryHub as FlockRegistry,  # Keep FlockRegistry name for API compatibility
     flock_callable,
     flock_component,
     flock_tool,
@@ -25,16 +23,12 @@ __all__ = [
     "Flock",
     "FlockAgent",
     "FlockContext",
-    "FlockEvaluator",
-    "FlockEvaluatorConfig",
     "FlockFactory",
     "FlockMCPClientBase",
     "FlockMCPClientManagerBase",
     "FlockMCPServerBase",
     "FlockMCPServerConfig",
     "FlockMCPToolBase",
-    "FlockModule",
-    "FlockModuleConfig",
     "FlockRegistry",
     "flock_callable",
     "flock_component",

flock/core/agent/__init__.py

@@ -0,0 +1,16 @@
+# src/flock/core/agent/__init__.py
+"""Agent components package."""
+
+from .flock_agent_components import FlockAgentComponents
+from .flock_agent_execution import FlockAgentExecution
+from .flock_agent_integration import FlockAgentIntegration
+from .flock_agent_lifecycle import FlockAgentLifecycle
+from .flock_agent_serialization import FlockAgentSerialization
+
+__all__ = [
+    "FlockAgentComponents",
+    "FlockAgentExecution", 
+    "FlockAgentIntegration",
+    "FlockAgentLifecycle",
+    "FlockAgentSerialization",
+]

flock/core/agent/flock_agent_components.py

@@ -0,0 +1,104 @@
+"""Component management functionality for FlockAgent."""
+
+from typing import TYPE_CHECKING, Any
+
+from flock.core.component.evaluation_component_base import EvaluationComponentBase
+from flock.core.component.routing_component_base import RoutingComponentBase
+from flock.core.component.utility_component_base import UtilityComponentBase
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+    from flock.core.component.agent_component_base import AgentComponent
+
+logger = get_logger("agent.components")
+
+
+class FlockAgentComponents:
+    """Helper class for managing unified components on FlockAgent."""
+
+    def __init__(self, agent: "FlockAgent"):
+        self.agent = agent
+
+    def add_component(self, component: "AgentComponent") -> None:
+        """Add a unified component to this agent."""
+        if not component.name:
+            logger.error("Component must have a name to be added.")
+            return
+        
+        # Check if component with same name already exists
+        existing = self.get_component(component.name)
+        if existing:
+            logger.warning(f"Overwriting existing component: {component.name}")
+            self.agent.components.remove(existing)
+
+        self.agent.components.append(component)
+        logger.debug(f"Added component '{component.name}' to agent '{self.agent.name}'")
+
+    def remove_component(self, component_name: str) -> None:
+        """Remove a component from this agent."""
+        component = self.get_component(component_name)
+        if component:
+            self.agent.components.remove(component)
+            logger.debug(f"Removed component '{component_name}' from agent '{self.agent.name}'")
+        else:
+            logger.warning(f"Component '{component_name}' not found on agent '{self.agent.name}'")
+
+    def get_component(self, component_name: str) -> "AgentComponent | None":
+        """Get a component by name."""
+        for component in self.agent.components:
+            if component.name == component_name:
+                return component
+        return None
+
+    def get_enabled_components(self) -> list["AgentComponent"]:
+        """Get a list of currently enabled components attached to this agent."""
+        return [c for c in self.agent.components if c.config.enabled]
+        
+    def get_components_by_type(self, component_type: type) -> list["AgentComponent"]:
+        """Get all components of a specific type."""
+        return [c for c in self.agent.components if isinstance(c, component_type)]
+
+    def get_evaluation_components(self) -> list[EvaluationComponentBase]:
+        """Get all evaluation components."""
+        return self.get_components_by_type(EvaluationComponentBase)
+
+    def get_routing_components(self) -> list[RoutingComponentBase]:
+        """Get all routing components."""
+        return self.get_components_by_type(RoutingComponentBase)
+        
+    def get_utility_components(self) -> list[UtilityComponentBase]:
+        """Get all utility components."""
+        return self.get_components_by_type(UtilityComponentBase)
+
+    def get_primary_evaluator(self) -> EvaluationComponentBase | None:
+        """Get the primary evaluation component (first one found)."""
+        evaluators = self.get_evaluation_components()
+        return evaluators[0] if evaluators else None
+        
+    def get_primary_router(self) -> RoutingComponentBase | None:
+        """Get the primary routing component (first one found)."""
+        routers = self.get_routing_components()
+        return routers[0] if routers else None
+
+    # Legacy compatibility methods (delegate to new unified approach)
+    def add_module(self, module: Any) -> None:
+        """DEPRECATED: Use add_component() instead."""
+        logger.warning("add_module is deprecated - use add_component() instead")
+        if hasattr(module, 'name'):
+            self.add_component(module)
+
+    def get_module(self, module_name: str) -> Any | None:
+        """DEPRECATED: Use get_component() instead."""
+        logger.warning("get_module is deprecated - use get_component() instead")
+        return self.get_component(module_name)
+
+    def get_evaluator(self) -> Any | None:
+        """DEPRECATED: Use get_primary_evaluator() instead."""
+        logger.warning("get_evaluator is deprecated - use get_primary_evaluator() instead")
+        return self.get_primary_evaluator()
+
+    def get_router(self) -> Any | None:
+        """DEPRECATED: Use get_primary_router() instead."""
+        logger.warning("get_router is deprecated - use get_primary_router() instead")
+        return self.get_primary_router()