flock-core 0.4.519__py3-none-any.whl → 0.5.0b1__py3-none-any.whl

flock/core/registry/decorators.py

@@ -0,0 +1,137 @@
+# src/flock/core/registry/decorators.py
+"""Registry decorators for component, tool, and type registration."""
+
+import inspect
+from collections.abc import Callable
+from typing import Any, TypeVar, overload
+
+from flock.core.registry.registry_hub import get_registry
+
+ClassType = TypeVar("ClassType", bound=type)
+FuncType = TypeVar("FuncType", bound=Callable)
+ConfigType = TypeVar("ConfigType")
+
+
+# --- Component Registration Decorator ---
+
+@overload
+def flock_component(cls: ClassType) -> ClassType: ...  # Basic registration
+
+
+@overload
+def flock_component(
+    *, name: str | None = None, config_class: type[ConfigType] | None = None
+) -> Callable[[ClassType], ClassType]: ...  # With options
+
+
+def flock_component(
+    cls: ClassType | None = None,
+    *,
+    name: str | None = None,
+    config_class: type[ConfigType] | None = None,
+) -> Any:
+    """Decorator to register a Flock Component class and optionally link its config class."""
+    registry = get_registry()
+
+    def decorator(inner_cls: ClassType) -> ClassType:
+        if not inspect.isclass(inner_cls):
+            raise TypeError("@flock_component can only decorate classes.")
+
+        component_name = name or inner_cls.__name__
+        registry.register_component(inner_cls, name=component_name)
+
+        # If config_class is provided, register the mapping
+        if config_class:
+            registry.register_config_component_pair(config_class, inner_cls)
+
+        return inner_cls
+
+    if cls is None:
+        # Called as @flock_component(name="...", config_class=...)
+        return decorator
+    else:
+        # Called as @flock_component
+        return decorator(cls)
+
+
+# --- Tool/Callable Registration Decorator ---
+
+@overload
+def flock_tool(func: FuncType) -> FuncType: ...
+
+
+@overload
+def flock_tool(
+    *, name: str | None = None
+) -> Callable[[FuncType], FuncType]: ...
+
+
+def flock_tool(func: FuncType | None = None, *, name: str | None = None) -> Any:
+    """Decorator to register a callable function/method as a Tool (or general callable).
+
+    Usage:
+        @flock_tool
+        def my_web_search(query: str): ...
+
+        @flock_tool(name="utils.calculate_pi")
+        def compute_pi(): ...
+    """
+    registry = get_registry()
+
+    def decorator(inner_func: FuncType) -> FuncType:
+        if not callable(inner_func):
+            raise TypeError("@flock_tool can only decorate callables.")
+        # Let registry handle default name generation if None
+        registry.register_callable(inner_func, name=name)
+        return inner_func
+
+    if func is None:
+        # Called as @flock_tool(name="...")
+        return decorator
+    else:
+        # Called as @flock_tool
+        return decorator(func)
+
+
+# Alias for clarity
+flock_callable = flock_tool
+
+
+# --- Type Registration Decorator ---
+
+@overload
+def flock_type(cls: ClassType) -> ClassType: ...
+
+
+@overload
+def flock_type(
+    *, name: str | None = None
+) -> Callable[[ClassType], ClassType]: ...
+
+
+def flock_type(cls: ClassType | None = None, *, name: str | None = None) -> Any:
+    """Decorator to register a Type (Pydantic Model, Dataclass) used in signatures.
+
+    Usage:
+        @flock_type
+        class MyDataModel(BaseModel): ...
+
+        @flock_type(name="UserInput")
+        @dataclass
+        class UserQuery: ...
+    """
+    registry = get_registry()
+
+    def decorator(inner_cls: ClassType) -> ClassType:
+        if not inspect.isclass(inner_cls):
+            raise TypeError("@flock_type can only decorate classes.")
+        type_name = name or inner_cls.__name__
+        registry.register_type(inner_cls, name=type_name)
+        return inner_cls
+
+    if cls is None:
+        # Called as @flock_type(name="...")
+        return decorator
+    else:
+        # Called as @flock_type
+        return decorator(cls)

flock/core/registry/registry_hub.py

@@ -0,0 +1,202 @@
+# src/flock/core/registry/registry_hub.py
+"""Main registry hub using composition pattern with thread safety."""
+
+import threading
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from flock.core.flock_agent import FlockAgent
+    from flock.core.mcp.flock_mcp_server import FlockMCPServerBase
+
+logger = get_logger("registry.hub")
+
+T = TypeVar("T")
+ConfigType = TypeVar("ConfigType")
+ClassType = TypeVar("ClassType")
+
+
+class RegistryHub:
+    """Thread-safe registry hub using composition pattern.
+    
+    Main coordinator for all registry types following the successful
+    pattern from Flock and FlockAgent refactoring.
+    """
+
+    def __init__(self):
+        self._lock = threading.RLock()
+        logger.debug("RegistryHub initialized with thread safety")
+
+    # --- Lazy-loaded composition helpers (following Flock pattern) ---
+
+    @property
+    def components(self):
+        """Component class registry helper."""
+        if not hasattr(self, '_components_helper'):
+            from flock.core.registry.component_registry import ComponentRegistry
+            self._components_helper = ComponentRegistry(self._lock)
+        return self._components_helper
+
+    @property
+    def callables(self):
+        """Callable registry helper."""
+        if not hasattr(self, '_callables_helper'):
+            from flock.core.registry.callable_registry import CallableRegistry
+            self._callables_helper = CallableRegistry(self._lock)
+        return self._callables_helper
+
+    @property
+    def agents(self):
+        """Agent registry helper."""
+        if not hasattr(self, '_agents_helper'):
+            from flock.core.registry.agent_registry import AgentRegistry
+            self._agents_helper = AgentRegistry(self._lock)
+        return self._agents_helper
+
+    @property
+    def servers(self):
+        """Server registry helper."""
+        if not hasattr(self, '_servers_helper'):
+            from flock.core.registry.server_registry import ServerRegistry
+            self._servers_helper = ServerRegistry(self._lock)
+        return self._servers_helper
+
+    @property
+    def types(self):
+        """Type registry helper."""
+        if not hasattr(self, '_types_helper'):
+            from flock.core.registry.type_registry import TypeRegistry
+            self._types_helper = TypeRegistry(self._lock)
+        return self._types_helper
+
+    @property
+    def config_mapping(self):
+        """Config mapping helper."""
+        if not hasattr(self, '_config_mapping_helper'):
+            from flock.core.registry.config_mapping import ConfigMapping
+            self._config_mapping_helper = ConfigMapping(self._lock)
+        return self._config_mapping_helper
+
+    @property
+    def discovery(self):
+        """Component discovery helper."""
+        if not hasattr(self, '_discovery_helper'):
+            from flock.core.registry.component_discovery import ComponentDiscovery
+            self._discovery_helper = ComponentDiscovery(self)
+        return self._discovery_helper
+
+    # --- High-level registry operations (delegate to helpers) ---
+
+    def register_agent(self, agent: "FlockAgent", *, force: bool = False) -> None:
+        """Register a FlockAgent instance."""
+        self.agents.register_agent(agent, force=force)
+
+    def get_agent(self, name: str) -> "FlockAgent | None":
+        """Get a registered FlockAgent instance by name."""
+        return self.agents.get_agent(name)
+
+    def get_all_agent_names(self) -> list[str]:
+        """Get all registered agent names."""
+        return self.agents.get_all_agent_names()
+
+    def register_server(self, server: "FlockMCPServerBase") -> None:
+        """Register a FlockMCPServer instance."""
+        self.servers.register_server(server)
+
+    def get_server(self, name: str) -> "FlockMCPServerBase | None":
+        """Get a registered FlockMCPServer instance by name."""
+        return self.servers.get_server(name)
+
+    def get_all_server_names(self) -> list[str]:
+        """Get all registered server names."""
+        return self.servers.get_all_server_names()
+
+    def register_callable(self, func: "Callable", name: str | None = None) -> str | None:
+        """Register a callable function/method."""
+        return self.callables.register_callable(func, name)
+
+    def get_callable(self, name_or_path: str) -> "Callable":
+        """Get a registered callable by name or path."""
+        return self.callables.get_callable(name_or_path)
+
+    def get_callable_path_string(self, func: "Callable") -> str | None:
+        """Get the path string for a callable."""
+        return self.callables.get_callable_path_string(func)
+
+    def register_type(self, type_obj: type, name: str | None = None) -> str | None:
+        """Register a type (Pydantic Model, Dataclass, etc.)."""
+        return self.types.register_type(type_obj, name)
+
+    def get_type(self, type_name: str) -> type:
+        """Get a registered type by name."""
+        return self.types.get_type(type_name)
+
+    def register_component(self, component_class: type, name: str | None = None) -> str | None:
+        """Register a component class."""
+        return self.components.register_component(component_class, name)
+
+    def get_component(self, type_name: str) -> type:
+        """Get a registered component class by name."""
+        return self.components.get_component(type_name)
+
+    def get_component_type_name(self, component_class: type) -> str | None:
+        """Get the type name for a component class."""
+        return self.components.get_component_type_name(component_class)
+
+    def register_config_component_pair(self, config_cls: type[ConfigType], component_cls: type[ClassType]) -> None:
+        """Register a config-to-component mapping."""
+        self.config_mapping.register_config_component_pair(config_cls, component_cls)
+
+    def get_component_class_for_config(self, config_cls: type[ConfigType]) -> type[ClassType] | None:
+        """Get the component class for a config class."""
+        return self.config_mapping.get_component_class_for_config(config_cls)
+
+    def discover_and_register_components(self) -> None:
+        """Auto-discover and register components from known packages."""
+        self.discovery.discover_and_register_components()
+
+    def register_module_components(self, module_or_path: Any) -> None:
+        """Register components from a specific module."""
+        self.discovery.register_module_components(module_or_path)
+
+    # --- Utility methods ---
+
+    def clear_all(self) -> None:
+        """Clear all registries (useful for testing)."""
+        with self._lock:
+            if hasattr(self, '_agents_helper'):
+                self.agents.clear()
+            if hasattr(self, '_servers_helper'):
+                self.servers.clear()
+            if hasattr(self, '_callables_helper'):
+                self.callables.clear()
+            if hasattr(self, '_types_helper'):
+                self.types.clear()
+            if hasattr(self, '_components_helper'):
+                self.components.clear()
+            if hasattr(self, '_config_mapping_helper'):
+                self.config_mapping.clear_config_mappings()
+            logger.debug("Cleared all registries")
+
+    def get_registry_summary(self) -> dict[str, int]:
+        """Get a summary of all registries."""
+        with self._lock:
+            return {
+                "agents": len(self.agents.get_all_agents()),
+                "servers": len(self.servers.get_all_servers()),
+                "callables": len(self.callables.get_all_callables()),
+                "types": len(self.types.get_all_types()),
+                "components": len(self.components.get_all_components()),
+                "config_mappings": len(self.config_mapping.get_all_config_mappings()),
+            }
+
+
+# --- Global singleton instance ---
+_default_registry_hub = RegistryHub()
+
+
+def get_registry() -> RegistryHub:
+    """Get the default thread-safe registry hub instance."""
+    return _default_registry_hub

flock/core/registry/server_registry.py

@@ -0,0 +1,57 @@
+# src/flock/core/registry/server_registry.py
+"""MCP Server 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.mcp.flock_mcp_server import FlockMCPServerBase
+
+logger = get_logger("registry.servers")
+
+
+class ServerRegistry:
+    """Manages FlockMCPServerBase registration and lookup with thread safety."""
+
+    def __init__(self, lock: threading.RLock):
+        self._lock = lock
+        self._servers: dict[str, "FlockMCPServerBase"] = {}
+
+    def register_server(self, server: "FlockMCPServerBase") -> None:
+        """Register a flock mcp server by its name."""
+        if not hasattr(server.config, "name") or not server.config.name:
+            logger.error("Attempted to register a server without a valid 'name' attribute.")
+            return
+
+        with self._lock:
+            if server.config.name in self._servers and self._servers[server.config.name] != server:
+                logger.warning(f"Server '{server.config.name}' already registered. Overwriting.")
+            
+            self._servers[server.config.name] = server
+            logger.debug(f"Registered server: {server.config.name}")
+
+    def get_server(self, name: str) -> "FlockMCPServerBase | None":
+        """Retrieve a registered FlockMCPServer instance by name."""
+        with self._lock:
+            server = self._servers.get(name)
+            if not server:
+                logger.warning(f"Server '{name}' not found in registry.")
+            return server
+
+    def get_all_server_names(self) -> list[str]:
+        """Return a list of names for all registered servers."""
+        with self._lock:
+            return list(self._servers.keys())
+
+    def get_all_servers(self) -> dict[str, "FlockMCPServerBase"]:
+        """Get all registered servers."""
+        with self._lock:
+            return self._servers.copy()
+
+    def clear(self) -> None:
+        """Clear all registered servers."""
+        with self._lock:
+            self._servers.clear()
+            logger.debug("Cleared all registered servers")

flock/core/registry/type_registry.py

@@ -0,0 +1,86 @@
+# src/flock/core/registry/type_registry.py
+"""Type registration and lookup functionality."""
+
+import threading
+from typing import Any, Literal, Mapping, Optional, Sequence, TypeVar, Union
+
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("registry.types")
+
+
+class TypeRegistry:
+    """Manages type registration and lookup with thread safety."""
+
+    def __init__(self, lock: threading.RLock):
+        self._lock = lock
+        self._types: dict[str, type] = {}
+        self._register_core_types()
+
+    def register_type(self, type_obj: type, name: str | None = None) -> str | None:
+        """Register a class/type (Pydantic, Dataclass, etc.) used in signatures."""
+        type_name = name or type_obj.__name__
+        if not type_name:
+            logger.error(f"Could not determine name for type: {type_obj}")
+            return None
+
+        with self._lock:
+            if type_name in self._types and self._types[type_name] != type_obj:
+                logger.warning(f"Type '{type_name}' already registered. Overwriting.")
+            
+            self._types[type_name] = type_obj
+            logger.debug(f"Registered type: {type_name}")
+            return type_name
+
+    def get_type(self, type_name: str) -> type:
+        """Retrieve a registered type by its name."""
+        with self._lock:
+            if type_name in self._types:
+                return self._types[type_name]
+            
+            # Consider adding dynamic import attempts for types if needed,
+            # but explicit registration is generally safer for types.
+            logger.warning(f"Type '{type_name}' not found in registry. Will attempt to build it from builtins.")
+            raise KeyError(f"Type '{type_name}' not found. Ensure it is registered.")
+
+    def get_all_types(self) -> dict[str, type]:
+        """Get all registered types."""
+        with self._lock:
+            return self._types.copy()
+
+    def clear(self) -> None:
+        """Clear all registered types (except core types)."""
+        with self._lock:
+            # Save core types
+            core_types = {
+                name: type_obj for name, type_obj in self._types.items()
+                if type_obj in [str, int, float, bool, list, dict, tuple, set, Any, Mapping, Sequence, TypeVar, Literal, Optional, Union]
+            }
+            self._types.clear()
+            self._types.update(core_types)
+            logger.debug("Cleared all registered types (keeping core types)")
+
+    def _register_core_types(self):
+        """Register common built-in and typing types."""
+        core_types = [
+            str,
+            int, 
+            float,
+            bool,
+            list,
+            dict,
+            tuple,
+            set,
+            Any,
+            Mapping,
+            Sequence,
+            TypeVar,
+            Literal,
+            Optional,
+            Union,  # Common typing generics
+        ]
+        for t in core_types:
+            try:
+                self.register_type(t)
+            except Exception as e:
+                logger.error(f"Failed to auto-register core type {t}: {e}")

flock/core/serialization/flock_serializer.py

@@ -1,7 +1,6 @@
 # src/flock/core/serialization/flock_serializer.py
 """Handles serialization and deserialization logic for Flock instances."""
 
-import builtins
 import importlib
 import importlib.util
 import inspect
@@ -14,7 +13,7 @@ from typing import TYPE_CHECKING, Any, Literal
 from pydantic import BaseModel, create_model
 
 # Need registry access
-from flock.core.flock_registry import get_registry
+from flock.core.registry import get_registry
 from flock.core.logging.logging import get_logger
 from flock.core.serialization.serialization_utils import (
     # Assuming this handles basic serialization needs
@@ -26,7 +25,7 @@ if TYPE_CHECKING:
 
 
 logger = get_logger("serialization.flock")
-FlockRegistry = get_registry()
+registry = get_registry()
 
 
 class FlockSerializer:
@@ -186,7 +185,7 @@ class FlockSerializer:
                         "description_callable"
                     ]
                     description_callable = agent_instance.description
-                    path_str = FlockRegistry.get_callable_path_string(
+                    path_str = registry.get_callable_path_string(
                         description_callable
                     )
                     if path_str:
@@ -205,7 +204,7 @@ class FlockSerializer:
                     )
                     input_callable_name = agent_data["input_callable"]
                     input_callable = agent_instance.input
-                    path_str = FlockRegistry.get_callable_path_string(
+                    path_str = registry.get_callable_path_string(
                         input_callable
                     )
                     if path_str:
@@ -224,7 +223,7 @@ class FlockSerializer:
                     )
                     output_callable_name = agent_data["output_callable"]
                     output_callable = agent_instance.output
-                    path_str = FlockRegistry.get_callable_path_string(
+                    path_str = registry.get_callable_path_string(
                         output_callable
                     )
                     if path_str:
@@ -250,7 +249,7 @@ class FlockSerializer:
                             tool = tool_objs[i]
                             if callable(tool) and not isinstance(tool, type):
                                 path_str = (
-                                    FlockRegistry.get_callable_path_string(tool)
+                                    registry.get_callable_path_string(tool)
                                 )
                                 if path_str:
                                     logger.debug(
@@ -415,7 +414,7 @@ class FlockSerializer:
         type_definitions = {}
         for type_name in type_names:
             try:
-                type_obj = FlockRegistry.get_type(
+                type_obj = registry.get_type(
                     type_name
                 )  # Throws KeyError if not found
                 type_def = FlockSerializer._extract_type_definition(
@@ -490,7 +489,7 @@ class FlockSerializer:
             "file_path": None,
         }
         try:
-            component_class = FlockRegistry.get_component(
+            component_class = registry.get_component(
                 component_type_name
             )  # Raises KeyError if not found
             component_def["module_path"] = getattr(
@@ -540,7 +539,7 @@ class FlockSerializer:
             "file_path": None,
         }
         try:
-            func = FlockRegistry.get_callable(
+            func = registry.get_callable(
                 callable_path
             )  # Raises KeyError if not found
             callable_def["module_path"] = getattr(func, "__module__", "unknown")
@@ -596,7 +595,7 @@ class FlockSerializer:
                     module = importlib.import_module(module_path)
                     if hasattr(module, type_name):
                         type_obj = getattr(module, type_name)
-                        FlockRegistry.register_type(type_obj, type_name)
+                        registry.register_type(type_obj, type_name)
                         logger.info(
                             f"Registered type '{type_name}' from module '{module_path}'"
                         )
@@ -629,7 +628,7 @@ class FlockSerializer:
         type_name: str, type_def: dict[str, Any]
     ) -> None:
         """Dynamically create and register a Pydantic model from schema."""
-        # (Logic remains the same, ensure it uses FlockRegistry.register_type)
+        # (Logic remains the same, ensure it uses registry.register_type)
         schema = type_def.get("schema", {})
         try:
             fields = {}
@@ -641,7 +640,7 @@ class FlockSerializer:
                 fields[field_name] = (field_type, default)
 
             DynamicModel = create_model(type_name, **fields)
-            FlockRegistry.register_type(DynamicModel, type_name)
+            registry.register_type(DynamicModel, type_name)
             logger.info(
                 f"Dynamically created and registered Pydantic model: {type_name}"
             )
@@ -672,27 +671,31 @@ class FlockSerializer:
     @staticmethod
     def _create_dataclass(type_name: str, type_def: dict[str, Any]) -> None:
         """Dynamically create and register a dataclass."""
-        # (Logic remains the same, ensure it uses FlockRegistry.register_type)
+        # (Logic remains the same, ensure it uses registry.register_type)
         from dataclasses import make_dataclass
 
         fields_def = type_def.get("fields", {})
         try:
             fields = []
             for field_name, field_props in fields_def.items():
-                # Safely evaluate type string - requires care!
+                # Safely map type strings to actual types
                 field_type_str = field_props.get("type", "str")
-                try:
-                    field_type = eval(
-                        field_type_str,
-                        {"__builtins__": builtins.__dict__},
-                        {"List": list, "Dict": dict},
-                    )  # Allow basic types
-                except Exception:
-                    field_type = Any
+                type_mapping = {
+                    "str": str,
+                    "int": int,
+                    "float": float,
+                    "bool": bool,
+                    "list": list,
+                    "dict": dict,
+                    "List": list,
+                    "Dict": dict,
+                    "Any": Any,
+                }
+                field_type = type_mapping.get(field_type_str, Any)
                 fields.append((field_name, field_type))
 
             DynamicDataclass = make_dataclass(type_name, fields)
-            FlockRegistry.register_type(DynamicDataclass, type_name)
+            registry.register_type(DynamicDataclass, type_name)
             logger.info(
                 f"Dynamically created and registered dataclass: {type_name}"
             )
@@ -705,7 +708,7 @@ class FlockSerializer:
         path_type: Literal["absolute", "relative"],
     ) -> None:
         """Register component/callable definitions from serialized data."""
-        # (Logic remains the same, ensure it uses FlockRegistry.register_component/register_callable)
+        # (Logic remains the same, ensure it uses registry.register_component/register_callable)
         # Key change: Ensure file_path is handled correctly based on path_type from metadata
         for name, comp_def in component_defs.items():
             logger.debug(
@@ -735,13 +738,13 @@ class FlockSerializer:
                     if hasattr(module, name):
                         obj = getattr(module, name)
                         if kind == "flock_callable" and callable(obj):
-                            FlockRegistry.register_callable(
+                            registry.register_callable(
                                 obj, name
                             )  # Register by simple name
                             # Also register by full path if possible
                             full_path = f"{module_path}.{name}"
                             if full_path != name:
-                                FlockRegistry.register_callable(obj, full_path)
+                                registry.register_callable(obj, full_path)
                             logger.info(
                                 f"Registered callable '{name}' from module '{module_path}'"
                             )
@@ -749,7 +752,7 @@ class FlockSerializer:
                         elif kind == "flock_component" and isinstance(
                             obj, type
                         ):
-                            FlockRegistry.register_component(obj, name)
+                            registry.register_component(obj, name)
                             logger.info(
                                 f"Registered component '{name}' from module '{module_path}'"
                             )
@@ -785,14 +788,14 @@ class FlockSerializer:
                         if hasattr(module, name):
                             obj = getattr(module, name)
                             if kind == "flock_callable" and callable(obj):
-                                FlockRegistry.register_callable(obj, name)
+                                registry.register_callable(obj, name)
                                 logger.info(
                                     f"Registered callable '{name}' from file '{file_path}'"
                                 )
                             elif kind == "flock_component" and isinstance(
                                 obj, type
                             ):
-                                FlockRegistry.register_component(obj, name)
+                                registry.register_component(obj, name)
                                 logger.info(
                                     f"Registered component '{name}' from file '{file_path}'"
                                 )