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

flock/core/orchestration/flock_web_server.py

@@ -0,0 +1,117 @@
+# src/flock/core/orchestration/flock_web_server.py
+"""Web server and CLI management functionality for Flock orchestrator."""
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.api.custom_endpoint import FlockEndpoint
+    from flock.core.flock import Flock
+    from flock.core.flock_agent import FlockAgent
+
+logger = get_logger("flock.web_server")
+
+
+class FlockWebServer:
+    """Handles web server and CLI functionality for Flock orchestrator."""
+
+    def __init__(self, flock: "Flock"):
+        self.flock = flock
+
+    def serve(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 8344,
+        server_name: str = "Flock Server",
+        ui: bool = True,
+        chat: bool = False,
+        chat_agent: str | None = None,
+        chat_message_key: str = "message",
+        chat_history_key: str = "history",
+        chat_response_key: str = "response",
+        ui_theme: str | None = None,
+        custom_endpoints: Sequence["FlockEndpoint"]
+        | dict[tuple[str, list[str] | None], Callable[..., Any]]
+        | None = None,
+    ) -> None:
+        """Launch an HTTP server that exposes the core REST API and, optionally, the browser-based UI."""
+        try:
+            from flock.webapp.run import start_unified_server
+        except ImportError:
+            logger.error(
+                "Web application components not found (flock.webapp.run). "
+                "Cannot start HTTP server. Ensure webapp dependencies are installed."
+            )
+            return
+
+        logger.info(
+            f"Attempting to start server for Flock '{self.flock.name}' on {host}:{port}. UI enabled: {ui}"
+        )
+
+        start_unified_server(
+            flock_instance=self.flock,
+            host=host,
+            port=port,
+            server_title=server_name,
+            enable_ui_routes=ui,
+            enable_chat_routes=chat,
+            ui_theme=ui_theme,
+            custom_endpoints=custom_endpoints,
+        )
+
+    def start_api(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 8344,
+        server_name: str = "Flock Server",
+        create_ui: bool = True,
+        ui_theme: str | None = None,
+        custom_endpoints: Sequence["FlockEndpoint"]
+        | dict[tuple[str, list[str] | None], Callable[..., Any]]
+        | None = None,
+    ) -> None:
+        """Deprecated: Use serve() instead."""
+        import warnings
+
+        warnings.warn(
+            "start_api() is deprecated and will be removed in a future release. "
+            "Use serve() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        # Delegate to the new serve() method (create_ui maps to ui)
+        return self.serve(
+            host=host,
+            port=port,
+            server_name=server_name,
+            ui=create_ui,
+            ui_theme=ui_theme,
+            custom_endpoints=custom_endpoints,
+        )
+
+    def start_cli(
+        self,
+        start_agent: "FlockAgent | str | None" = None,
+        server_name: str = "Flock CLI",
+        show_results: bool = False,
+        edit_mode: bool = False,
+    ) -> None:
+        """Starts an interactive CLI for this Flock instance."""
+        try:
+            from flock.cli.runner import start_flock_cli
+        except ImportError:
+            logger.error(
+                "CLI components not found. Cannot start CLI. "
+                "Ensure CLI dependencies are installed."
+            )
+            return
+
+        logger.info(f"Starting CLI for Flock '{self.flock.name}'...")
+        start_flock_cli(
+            flock=self.flock,  # Pass the Flock instance
+            server_name=server_name,
+            show_results=show_results,
+            edit_mode=edit_mode,
+        )

flock/core/registry/__init__.py

@@ -0,0 +1,45 @@
+# src/flock/core/registry/__init__.py
+"""Modern thread-safe registry system using composition pattern.
+
+This module provides a complete refactor of the FlockRegistry using
+the proven composition pattern from Flock and FlockAgent refactoring.
+"""
+
+
+from flock.core.registry.agent_registry import AgentRegistry
+from flock.core.registry.callable_registry import CallableRegistry
+from flock.core.registry.component_discovery import ComponentDiscovery
+
+# Specialized registry components (for advanced usage)
+from flock.core.registry.component_registry import ComponentRegistry
+from flock.core.registry.config_mapping import ConfigMapping
+from flock.core.registry.decorators import (
+    flock_callable,
+    flock_component,
+    flock_tool,
+    flock_type,
+)
+from flock.core.registry.registry_hub import RegistryHub, get_registry
+from flock.core.registry.server_registry import ServerRegistry
+from flock.core.registry.type_registry import TypeRegistry
+
+__all__ = [
+    # Main API
+    "RegistryHub",
+    "get_registry",
+
+    # Decorators
+    "flock_component",
+    "flock_tool",
+    "flock_callable",
+    "flock_type",
+
+    # Specialized registries (for advanced usage)
+    "ComponentRegistry",
+    "CallableRegistry",
+    "AgentRegistry",
+    "ServerRegistry",
+    "TypeRegistry",
+    "ConfigMapping",
+    "ComponentDiscovery",
+]

flock/core/registry/agent_registry.py

@@ -0,0 +1,69 @@
+# src/flock/core/registry/agent_registry.py
+"""Agent instance registration and lookup functionality."""
+
+import threading
+from typing import TYPE_CHECKING
+
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+
+logger = get_logger("registry.agents")
+
+
+class AgentRegistry:
+    """Manages FlockAgent instance registration and lookup with thread safety."""
+
+    def __init__(self, lock: threading.RLock):
+        self._lock = lock
+        self._agents: dict[str, "FlockAgent"] = {}
+
+    def register_agent(self, agent: "FlockAgent", *, force: bool = False) -> None:
+        """Register a FlockAgent instance by its name.
+
+        Args:
+            agent: The agent instance to register.
+            force: If True, allow overwriting an existing **different** agent registered under the same name.
+                   If False and a conflicting registration exists, a ValueError is raised.
+        """
+        if not hasattr(agent, "name") or not agent.name:
+            logger.error("Attempted to register an agent without a valid 'name' attribute.")
+            return
+
+        with self._lock:
+            if agent.name in self._agents and self._agents[agent.name] is not agent:
+                # Same agent already registered → silently ignore; different instance → error/force.
+                if not force:
+                    raise ValueError(
+                        f"Agent '{agent.name}' already registered with a different instance. "
+                        "Pass force=True to overwrite the existing registration."
+                    )
+                logger.warning(f"Overwriting existing agent '{agent.name}' registration due to force=True.")
+
+            self._agents[agent.name] = agent
+            logger.debug(f"Registered agent: {agent.name}")
+
+    def get_agent(self, name: str) -> "FlockAgent | None":
+        """Retrieve a registered FlockAgent instance by name."""
+        with self._lock:
+            agent = self._agents.get(name)
+            if not agent:
+                logger.warning(f"Agent '{name}' not found in registry.")
+            return agent
+
+    def get_all_agent_names(self) -> list[str]:
+        """Return a list of names of all registered agents."""
+        with self._lock:
+            return list(self._agents.keys())
+
+    def get_all_agents(self) -> dict[str, "FlockAgent"]:
+        """Get all registered agents."""
+        with self._lock:
+            return self._agents.copy()
+
+    def clear(self) -> None:
+        """Clear all registered agents."""
+        with self._lock:
+            self._agents.clear()
+            logger.debug("Cleared all registered agents")

flock/core/registry/callable_registry.py

@@ -0,0 +1,139 @@
+# src/flock/core/registry/callable_registry.py
+"""Callable function/method registration and lookup functionality."""
+
+import builtins
+import importlib
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("registry.callables")
+
+
+class CallableRegistry:
+    """Manages callable registration with smart lookup and thread safety."""
+
+    def __init__(self, lock: threading.RLock):
+        self._lock = lock
+        self._callables: dict[str, Callable] = {}
+
+    def register_callable(self, func: Callable, name: str | None = None) -> str | None:
+        """Register a callable (function/method). Returns its path string identifier."""
+        path_str = name or self._get_path_string(func)
+        if not path_str:
+            logger.warning(f"Could not register callable {getattr(func, '__name__', 'unknown')}: Unable to determine path string")
+            return None
+
+        with self._lock:
+            if path_str in self._callables and self._callables[path_str] != func:
+                logger.warning(f"Callable '{path_str}' already registered with a different function. Overwriting.")
+            
+            self._callables[path_str] = func
+            logger.debug(f"Registered callable: '{path_str}' ({getattr(func, '__name__', 'unknown')})")
+            return path_str
+
+    def get_callable(self, name_or_path: str) -> Callable:
+        """Retrieve a callable by its registered name or full path string.
+        
+        Attempts dynamic import if not found directly. Prioritizes exact match,
+        then searches for matches ending with '.{name}'.
+        """
+        # 1. Try exact match first (covers full paths and simple names if registered that way)
+        with self._lock:
+            if name_or_path in self._callables:
+                logger.debug(f"Found callable '{name_or_path}' directly in registry.")
+                return self._callables[name_or_path]
+
+        # 2. If not found, and it looks like a simple name, search registered paths
+        if "." not in name_or_path:
+            with self._lock:
+                matches = []
+                for path_str, func in self._callables.items():
+                    # Check if path ends with ".{simple_name}" or exactly matches simple_name
+                    if path_str == name_or_path or path_str.endswith(f".{name_or_path}"):
+                        matches.append(func)
+
+                if len(matches) == 1:
+                    logger.debug(f"Found unique callable for simple name '{name_or_path}' via path '{self.get_callable_path_string(matches[0])}'.")
+                    return matches[0]
+                elif len(matches) > 1:
+                    # Ambiguous simple name - require full path
+                    found_paths = [self.get_callable_path_string(f) for f in matches]
+                    logger.error(f"Ambiguous callable name '{name_or_path}'. Found matches: {found_paths}. Use full path string for lookup.")
+                    raise KeyError(f"Ambiguous callable name '{name_or_path}'. Use full path string.")
+
+        # 3. Attempt dynamic import if it looks like a full path
+        if "." in name_or_path:
+            logger.debug(f"Callable '{name_or_path}' not in registry cache, attempting dynamic import.")
+            try:
+                module_name, func_name = name_or_path.rsplit(".", 1)
+                module = importlib.import_module(module_name)
+                func = getattr(module, func_name)
+                if callable(func):
+                    self.register_callable(func, name_or_path)  # Cache dynamically imported
+                    logger.info(f"Successfully imported and registered module callable '{name_or_path}'")
+                    return func
+                else:
+                    raise TypeError(f"Dynamically imported object '{name_or_path}' is not callable.")
+            except (ImportError, AttributeError, TypeError) as e:
+                logger.error(f"Failed to dynamically load/find callable '{name_or_path}': {e}", exc_info=False)
+
+        # 4. Handle built-ins if not found yet (might be redundant if simple name check worked)
+        elif name_or_path in builtins.__dict__:
+            func = builtins.__dict__[name_or_path]
+            if callable(func):
+                self.register_callable(func, name_or_path)  # Cache it
+                logger.info(f"Found and registered built-in callable '{name_or_path}'")
+                return func
+
+        # 5. Final failure
+        logger.error(f"Callable '{name_or_path}' not found in registry or via import.")
+        raise KeyError(f"Callable '{name_or_path}' not found.")
+
+    def get_callable_path_string(self, func: Callable) -> str | None:
+        """Get the path string for a callable, registering it if necessary."""
+        # First try to find by direct identity
+        with self._lock:
+            for path_str, registered_func in self._callables.items():
+                if func == registered_func:
+                    logger.debug(f"Found existing path string for callable: '{path_str}'")
+                    return path_str
+
+        # If not found by identity, generate path, register, and return
+        path_str = self.register_callable(func)
+        if path_str:
+            logger.debug(f"Generated and registered new path string for callable: '{path_str}'")
+        else:
+            logger.warning(f"Failed to generate path string for callable {getattr(func, '__name__', 'unknown')}")
+
+        return path_str
+
+    def get_all_callables(self) -> dict[str, Callable]:
+        """Get all registered callables."""
+        with self._lock:
+            return self._callables.copy()
+
+    def clear(self) -> None:
+        """Clear all registered callables."""
+        with self._lock:
+            self._callables.clear()
+            logger.debug("Cleared all registered callables")
+
+    @staticmethod
+    def _get_path_string(obj: Callable | type) -> str | None:
+        """Generate a unique path string 'module.ClassName' or 'module.function_name'."""
+        try:
+            module = obj.__module__
+            name = obj.__name__
+            if module == "builtins":
+                return name
+            # Check if it's nested (basic check, might not cover all edge cases)
+            if "." in name and hasattr(__import__(module).__dict__, name.split(".")[0]):
+                # Likely a nested class/method - serialization might need custom handling or pickle
+                logger.warning(f"Object {name} appears nested in {module}. Path string might be ambiguous.")
+            return f"{module}.{name}"
+        except AttributeError:
+            logger.warning(f"Could not determine module/name for object: {obj}")
+            return None

flock/core/registry/component_discovery.py

@@ -0,0 +1,142 @@
+# src/flock/core/registry/component_discovery.py
+"""Component discovery and auto-registration functionality."""
+
+import importlib
+import importlib.util
+import inspect
+import os
+import pkgutil
+import threading
+from dataclasses import is_dataclass
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.registry.registry_hub import RegistryHub
+    from flock.core.component.agent_component_base import AgentComponent
+
+logger = get_logger("registry.discovery")
+
+
+class ComponentDiscovery:
+    """Handles automatic component discovery and registration."""
+
+    def __init__(self, registry_hub: "RegistryHub"):
+        self.registry_hub = registry_hub
+        self._packages_to_scan = [
+            "flock.tools",
+            "flock.components",  # Updated to use unified components
+        ]
+
+    def discover_and_register_components(self) -> None:
+        """Auto-register components from known core packages."""
+        for package_name in self._packages_to_scan:
+            try:
+                package_spec = importlib.util.find_spec(package_name)
+                if package_spec and package_spec.origin:
+                    package_path_list = [os.path.dirname(package_spec.origin)]
+                    logger.info(f"Recursively scanning for modules in package: {package_name} (path: {package_path_list[0]})")
+
+                    # Use walk_packages to recursively find all modules
+                    for module_loader, module_name, is_pkg in pkgutil.walk_packages(
+                        path=package_path_list,
+                        prefix=package_name + ".",  # Ensures module_name is fully qualified
+                        onerror=lambda name: logger.warning(f"Error importing module {name} during scan.")
+                    ):
+                        if not is_pkg and not module_name.split('.')[-1].startswith("_"):
+                            # We are interested in actual modules, not sub-packages themselves for registration
+                            # And also skip modules starting with underscore (e.g. __main__.py)
+                            try:
+                                logger.debug(f"Attempting to auto-register components from module: {module_name}")
+                                self.register_module_components(module_name)
+                            except ImportError as e:
+                                logger.warning(
+                                    f"Could not auto-register from {module_name}: Module not found or import error: {e}"
+                                )
+                            except Exception as e:  # Catch other potential errors during registration
+                                logger.error(
+                                    f"Unexpected error during auto-registration of {module_name}: {e}",
+                                    exc_info=True
+                                )
+                else:
+                    logger.warning(f"Could not find package spec for '{package_name}' to auto-register components/tools.")
+            except Exception as e:
+                logger.error(f"Error while trying to dynamically register from '{package_name}': {e}", exc_info=True)
+
+    def register_module_components(self, module_or_path: Any) -> None:
+        """Scan a module (object or path string) and automatically register.
+
+        - Functions as callables.
+        - Pydantic Models and Dataclasses as types.
+        - Subclasses of AgentComponent as components.
+        """
+        try:
+            if isinstance(module_or_path, str):
+                module = importlib.import_module(module_or_path)
+            elif inspect.ismodule(module_or_path):
+                module = module_or_path
+            else:
+                logger.error(
+                    f"Invalid input for auto-registration: {module_or_path}. Must be module object or path string."
+                )
+                return
+
+            logger.info(f"Auto-registering components from module: {module.__name__}")
+            registered_count = {"callable": 0, "type": 0, "component": 0}
+
+            for name, obj in inspect.getmembers(module):
+                if name.startswith("_"):
+                    continue  # Skip private/internal
+
+                # Register Functions as Callables
+                if (
+                    inspect.isfunction(obj)
+                    and obj.__module__ == module.__name__
+                ):
+                    if self.registry_hub.callables.register_callable(obj):
+                        registered_count["callable"] += 1
+
+                # Register Classes (Types and Components)
+                elif inspect.isclass(obj) and obj.__module__ == module.__name__:
+                    is_component = False
+                    
+                    # Register as Component if subclass of AgentComponent
+                    try:
+                        from flock.core.component.agent_component_base import AgentComponent
+                        if (
+                            issubclass(obj, AgentComponent)
+                            and self.registry_hub.components.register_component(obj)
+                        ):
+                            registered_count["component"] += 1
+                            is_component = True  # Mark as component
+                    except ImportError:
+                        # AgentComponent not available during setup
+                        pass
+
+                    # Register as Type if Pydantic Model or Dataclass
+                    # A component can also be a type used in signatures
+                    base_model_or_dataclass = isinstance(obj, type) and (
+                        issubclass(obj, BaseModel) or is_dataclass(obj)
+                    )
+                    if (
+                        base_model_or_dataclass
+                        and self.registry_hub.types.register_type(obj)
+                        and not is_component
+                    ):
+                        # Only increment type count if it wasn't already counted as component
+                        registered_count["type"] += 1
+
+            logger.info(
+                f"Auto-registration summary for {module.__name__}: "
+                f"{registered_count['callable']} callables, "
+                f"{registered_count['type']} types, "
+                f"{registered_count['component']} components."
+            )
+
+        except Exception as e:
+            logger.error(
+                f"Error during auto-registration for {module_or_path}: {e}",
+                exc_info=True,
+            )

flock/core/registry/component_registry.py

@@ -0,0 +1,64 @@
+# src/flock/core/registry/component_registry.py
+"""Component class registration and lookup functionality."""
+
+import threading
+from typing import TYPE_CHECKING, Any
+
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.component.agent_component_base import AgentComponent
+
+logger = get_logger("registry.components")
+
+
+class ComponentRegistry:
+    """Manages component class registration and lookup with thread safety."""
+
+    def __init__(self, lock: threading.RLock):
+        self._lock = lock
+        self._components: dict[str, type] = {}
+
+    def register_component(self, component_class: type, name: str | None = None) -> str | None:
+        """Register a component class (evaluation, routing, utility components)."""
+        type_name = name or component_class.__name__
+        if not type_name:
+            logger.error(f"Could not determine name for component class: {component_class}")
+            return None
+
+        with self._lock:
+            if type_name in self._components and self._components[type_name] != component_class:
+                logger.warning(f"Component class '{type_name}' already registered. Overwriting.")
+            
+            self._components[type_name] = component_class
+            logger.debug(f"Registered component class: {type_name}")
+            return type_name
+
+    def get_component(self, type_name: str) -> type:
+        """Retrieve a component class by its type name."""
+        with self._lock:
+            if type_name in self._components:
+                return self._components[type_name]
+            
+            logger.error(f"Component class '{type_name}' not found in registry.")
+            raise KeyError(f"Component class '{type_name}' not found. Ensure it is registered.")
+
+    def get_component_type_name(self, component_class: type) -> str | None:
+        """Get the type name for a component class, registering it if necessary."""
+        with self._lock:
+            for type_name, registered_class in self._components.items():
+                if component_class == registered_class:
+                    return type_name
+            # If not found, register using class name and return
+            return self.register_component(component_class)
+
+    def get_all_components(self) -> dict[str, type]:
+        """Get all registered components."""
+        with self._lock:
+            return self._components.copy()
+
+    def clear(self) -> None:
+        """Clear all registered components."""
+        with self._lock:
+            self._components.clear()
+            logger.debug("Cleared all registered components")

flock/core/registry/config_mapping.py

@@ -0,0 +1,64 @@
+# src/flock/core/registry/config_mapping.py
+"""Config-to-component mapping functionality."""
+
+import threading
+from typing import TypeVar
+
+from pydantic import BaseModel
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("registry.config_mapping")
+
+ConfigType = TypeVar("ConfigType", bound=BaseModel)
+ClassType = TypeVar("ClassType", bound=type)
+
+# Global config mapping with thread safety
+_component_config_map: dict[type[BaseModel], type] = {}
+_config_map_lock = threading.RLock()
+
+
+class ConfigMapping:
+    """Manages config-to-component mappings with thread safety."""
+
+    def __init__(self, lock: threading.RLock):
+        self._lock = lock
+
+    def register_config_component_pair(
+        self, config_cls: type[ConfigType], component_cls: type[ClassType]
+    ) -> None:
+        """Explicitly register the mapping between a config and component class."""
+        # Component config validation can be added here if needed
+        # Add more checks if needed (e.g., component_cls inherits from Module/Router/Evaluator)
+
+        with _config_map_lock:
+            if (
+                config_cls in _component_config_map
+                and _component_config_map[config_cls] != component_cls
+            ):
+                logger.warning(
+                    f"Config class {config_cls.__name__} already mapped to {_component_config_map[config_cls].__name__}. "
+                    f"Overwriting with {component_cls.__name__}."
+                )
+
+            _component_config_map[config_cls] = component_cls
+            logger.debug(
+                f"Registered config mapping: {config_cls.__name__} -> {component_cls.__name__}"
+            )
+
+    def get_component_class_for_config(
+        self, config_cls: type[ConfigType]
+    ) -> type[ClassType] | None:
+        """Look up the Component Class associated with a Config Class."""
+        with _config_map_lock:
+            return _component_config_map.get(config_cls)
+
+    def get_all_config_mappings(self) -> dict[type[BaseModel], type]:
+        """Get all config-to-component mappings."""
+        with _config_map_lock:
+            return _component_config_map.copy()
+
+    def clear_config_mappings(self) -> None:
+        """Clear all config-to-component mappings."""
+        with _config_map_lock:
+            _component_config_map.clear()
+            logger.debug("Cleared all config-to-component mappings")