flock-core 0.4.527__py3-none-any.whl → 0.5.0b0__py3-none-any.whl

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

@@ -1,21 +1,25 @@
-"""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 import UtilityComponent
 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.mcp.flock_mcp_server import FlockMCPServerBase
+from flock.core.mcp.flock_mcp_server import FlockMCPServer
+from flock.core.registry import flock_component
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
 
 
 class MetricPoint(BaseModel):
@@ -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(UtilityComponent):
+    """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.
         """
@@ -525,7 +540,7 @@ class MetricsModule(FlockModule):
 
     # --- MCP Server Lifecycle Hooks ---
     async def on_server_error(
-        self, server: FlockMCPServerBase, error: Exception
+        self, server: FlockMCPServer, error: Exception
     ) -> None:
         """Record server error metrics."""
         self._record_metric(
@@ -537,7 +552,7 @@ class MetricsModule(FlockModule):
             },
         )
 
-    async def on_pre_server_init(self, server: FlockMCPServerBase):
+    async def on_pre_server_init(self, server: FlockMCPServer):
         """Initialize metrics collection for server."""
         self._server_start_time = time.time()
 
@@ -549,7 +564,7 @@ class MetricsModule(FlockModule):
                 {"server": server.config.name, "phase": "pre_init"},
             )
 
-    async def on_post_server_init(self, server: FlockMCPServerBase):
+    async def on_post_server_init(self, server: FlockMCPServer):
         """Collect metrics after server starts."""
         if self.config.collect_memory:
             checkpoint_memory = psutil.Process().memory_info().rss
@@ -559,7 +574,7 @@ class MetricsModule(FlockModule):
                 {"server": server.config.name, "phase": "post_init"},
             )
 
-    async def on_pre_server_terminate(self, server: FlockMCPServerBase):
+    async def on_pre_server_terminate(self, server: FlockMCPServer):
         """Collect metrics before server terminates."""
         if self.config.collect_memory:
             checkpoint_memory = psutil.Process().memory_info().rss
@@ -569,7 +584,7 @@ class MetricsModule(FlockModule):
                 {"server": server.config.name, "phase": "pre_terminate"},
             )
 
-    async def on_post_server_terminate(self, server: FlockMCPServerBase):
+    async def on_post_server_terminate(self, server: FlockMCPServer):
         """Collect metrics after server terminates.
 
         Clean up and final metric recording.
@@ -600,7 +615,7 @@ class MetricsModule(FlockModule):
                 json.dump(summary, f, indent=2)
 
     async def on_pre_mcp_call(
-        self, server: FlockMCPServerBase, arguments: Any | None = None
+        self, server: FlockMCPServer, arguments: Any | None = None
     ):
         """Record pre-call metrics."""
         if self.config.collect_cpu:
@@ -630,7 +645,7 @@ class MetricsModule(FlockModule):
             )
 
     async def on_post_mcp_call(
-        self, server: FlockMCPServerBase, result: Any | None = None
+        self, server: FlockMCPServer, result: Any | None = None
     ):
         """Record post-call metrics."""
         if self.config.collect_timing and self._server_start_time:
@@ -661,7 +676,7 @@ class MetricsModule(FlockModule):
             )
 
     async def on_connect(
-        self, server: FlockMCPServerBase, additional_params: dict[str, Any]
+        self, server: FlockMCPServer, additional_params: dict[str, Any]
     ) -> dict[str, Any]:
         """Collect metrics during connect."""
         # We should track the refresh rate for clients

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

@@ -1,31 +1,29 @@
-"""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 import UtilityComponent
 from flock.core.context.context import FlockContext
-from flock.core.flock_module import FlockModule, FlockModuleConfig
+from flock.core.context.context_vars import FLOCK_BATCH_SILENT_MODE
 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.registry import flock_component
 
-# 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 +59,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(UtilityComponent):
+    """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 +97,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 "[]"
 
-    def _format_potential_code(self, text: str) -> str:
-        """Format text that might contain code blocks."""
-        import re
+        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:
+        """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```"
+            return f"[CODE:{language}]\n{code}\n[/CODE]"
 
-        # Replace code blocks with formatted versions
+        # Replace markdown-style code blocks
         text = re.sub(
             r"```(\w+)?\n(.*?)\n```", replace_code_block, text, flags=re.DOTALL
         )
@@ -174,7 +179,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 +191,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

@@ -1,40 +1,48 @@
 """This module contains the core classes of the flock package."""
 
+from flock.core.component import (
+    AgentComponent,
+    AgentComponentConfig,
+    EvaluationComponent,
+    RoutingComponent,
+    UtilityComponent,
+)
 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.mcp.flock_mcp_server import (
+    FlockMCPServer,
+)
+from flock.core.mcp.flock_mcp_tool import FlockMCPTool
+from flock.core.mcp.mcp_client import FlockMCPClient
+from flock.core.mcp.mcp_client_manager import FlockMCPClientManager
+from flock.core.registry import (
+    RegistryHub as FlockRegistry,  # Keep FlockRegistry name for API compatibility
     flock_callable,
     flock_component,
     flock_tool,
     flock_type,
     get_registry,
 )
-from flock.core.mcp.flock_mcp_server import (
-    FlockMCPServerBase,
-)
-from flock.core.mcp.flock_mcp_tool_base import FlockMCPToolBase
-from flock.core.mcp.mcp_client import FlockMCPClientBase
-from flock.core.mcp.mcp_client_manager import FlockMCPClientManagerBase
 
 __all__ = [
     "Flock",
     "FlockAgent",
     "FlockContext",
-    "FlockEvaluator",
-    "FlockEvaluatorConfig",
     "FlockFactory",
-    "FlockMCPClientBase",
-    "FlockMCPClientManagerBase",
-    "FlockMCPServerBase",
+        # Components
+    "AgentComponent",
+    "AgentComponentConfig",
+    "EvaluationComponent",
+    "RoutingComponent",
+    "UtilityComponent",
+
+    "FlockMCPClient",
+    "FlockMCPClientManager",
+    "FlockMCPServer",
     "FlockMCPServerConfig",
-    "FlockMCPToolBase",
-    "FlockModule",
-    "FlockModuleConfig",
+    "FlockMCPTool",
     "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",
+]