flock-core 0.3.41__py3-none-any.whl → 0.4.0b1__py3-none-any.whl

flock/core/flock_agent.py

@@ -374,10 +374,12 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
             mode="json",  # Use json mode for better handling of standard types by Pydantic
             exclude_none=True,  # Exclude None values for cleaner output
         )
+        logger.debug(f"Base agent data for '{self.name}': {list(data.keys())}")
 
         # --- Serialize Components using Registry Type Names ---
         # Evaluator
         if self.evaluator:
+            logger.debug(f"Serializing evaluator for agent '{self.name}'")
             evaluator_type_name = FlockRegistry.get_component_type_name(
                 type(self.evaluator)
             )
@@ -388,6 +390,9 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
                 )
                 evaluator_dict["type"] = evaluator_type_name  # Add type marker
                 data["evaluator"] = evaluator_dict
+                logger.debug(
+                    f"Added evaluator of type '{evaluator_type_name}' to agent '{self.name}'"
+                )
             else:
                 logger.warning(
                     f"Could not get registered type name for evaluator {type(self.evaluator).__name__} in agent '{self.name}'. Skipping serialization."
@@ -395,6 +400,7 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
 
         # Router
         if self.handoff_router:
+            logger.debug(f"Serializing router for agent '{self.name}'")
             router_type_name = FlockRegistry.get_component_type_name(
                 type(self.handoff_router)
             )
@@ -406,6 +412,9 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
                 )
                 router_dict["type"] = router_type_name
                 data["handoff_router"] = router_dict
+                logger.debug(
+                    f"Added router of type '{router_type_name}' to agent '{self.name}'"
+                )
             else:
                 logger.warning(
                     f"Could not get registered type name for router {type(self.handoff_router).__name__} in agent '{self.name}'. Skipping serialization."
@@ -413,6 +422,9 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
 
         # Modules
         if self.modules:
+            logger.debug(
+                f"Serializing {len(self.modules)} modules for agent '{self.name}'"
+            )
             serialized_modules = {}
             for name, module_instance in self.modules.items():
                 module_type_name = FlockRegistry.get_component_type_name(
@@ -426,32 +438,55 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
                     )
                     module_dict["type"] = module_type_name
                     serialized_modules[name] = module_dict
+                    logger.debug(
+                        f"Added module '{name}' of type '{module_type_name}' to agent '{self.name}'"
+                    )
                 else:
                     logger.warning(
                         f"Could not get registered type name for module {type(module_instance).__name__} ('{name}') in agent '{self.name}'. Skipping."
                     )
             if serialized_modules:
                 data["modules"] = serialized_modules
+                logger.debug(
+                    f"Added {len(serialized_modules)} modules to agent '{self.name}'"
+                )
 
         # --- Serialize Tools (Callables) ---
         if self.tools:
+            logger.debug(
+                f"Serializing {len(self.tools)} tools for agent '{self.name}'"
+            )
             serialized_tools = []
             for tool in self.tools:
                 if callable(tool) and not isinstance(tool, type):
                     path_str = FlockRegistry.get_callable_path_string(tool)
                     if path_str:
-                        serialized_tools.append({"__callable_ref__": path_str})
+                        # Get just the function name from the path string
+                        # If it's a namespaced path like module.submodule.function_name
+                        # Just use the function_name part
+                        func_name = path_str.split(".")[-1]
+                        serialized_tools.append(func_name)
+                        logger.debug(
+                            f"Added tool '{func_name}' (from path '{path_str}') to agent '{self.name}'"
+                        )
                     else:
                         logger.warning(
                             f"Could not get path string for tool {tool} in agent '{self.name}'. Skipping."
                         )
-                # Silently skip non-callable items or log warning
-                # else:
-                #      logger.warning(f"Non-callable item found in tools list for agent '{self.name}': {tool}. Skipping.")
+                else:
+                    logger.warning(
+                        f"Non-callable item found in tools list for agent '{self.name}': {tool}. Skipping."
+                    )
             if serialized_tools:
                 data["tools"] = serialized_tools
+                logger.debug(
+                    f"Added {len(serialized_tools)} tools to agent '{self.name}'"
+                )
 
         # No need to call _filter_none_values here as model_dump(exclude_none=True) handles it
+        logger.info(
+            f"Serialization of agent '{self.name}' complete with {len(data)} fields"
+        )
         return data
 
     @classmethod
@@ -466,6 +501,7 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
             raise ValueError("Agent data must include a 'name' field.")
         FlockRegistry = get_registry()
         agent_name = data["name"]  # For logging context
+        logger.info(f"Deserializing agent '{agent_name}'")
 
         # Pop complex components to handle them after basic agent instantiation
         evaluator_data = data.pop("evaluator", None)
@@ -473,6 +509,10 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         modules_data = data.pop("modules", {})
         tools_data = data.pop("tools", [])
 
+        logger.debug(
+            f"Agent '{agent_name}' has {len(modules_data)} modules and {len(tools_data)} tools"
+        )
+
         # Deserialize remaining data recursively (handles nested basic types/callables)
         # Note: Pydantic v2 handles most basic deserialization well if types match.
         # Explicit deserialize_item might be needed if complex non-pydantic structures exist.
@@ -481,6 +521,9 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
 
         try:
             # Create the agent instance using Pydantic's constructor
+            logger.debug(
+                f"Creating agent instance with fields: {list(deserialized_basic_data.keys())}"
+            )
             agent = cls(**deserialized_basic_data)
         except Exception as e:
             logger.error(
@@ -495,13 +538,16 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         # Evaluator
         if evaluator_data:
             try:
+                logger.debug(
+                    f"Deserializing evaluator for agent '{agent_name}'"
+                )
                 agent.evaluator = deserialize_component(
                     evaluator_data, FlockEvaluator
                 )
                 if agent.evaluator is None:
                     raise ValueError("deserialize_component returned None")
                 logger.debug(
-                    f"Deserialized evaluator '{agent.evaluator.name}' for agent '{agent_name}'"
+                    f"Deserialized evaluator '{agent.evaluator.name}' of type '{evaluator_data.get('type')}' for agent '{agent_name}'"
                 )
             except Exception as e:
                 logger.error(
@@ -514,13 +560,14 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         # Router
         if router_data:
             try:
+                logger.debug(f"Deserializing router for agent '{agent_name}'")
                 agent.handoff_router = deserialize_component(
                     router_data, FlockRouter
                 )
                 if agent.handoff_router is None:
                     raise ValueError("deserialize_component returned None")
                 logger.debug(
-                    f"Deserialized router '{agent.handoff_router.name}' for agent '{agent_name}'"
+                    f"Deserialized router '{agent.handoff_router.name}' of type '{router_data.get('type')}' for agent '{agent_name}'"
                 )
             except Exception as e:
                 logger.error(
@@ -532,8 +579,14 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         # Modules
         if modules_data:
             agent.modules = {}  # Ensure it's initialized
+            logger.debug(
+                f"Deserializing {len(modules_data)} modules for agent '{agent_name}'"
+            )
             for name, module_data in modules_data.items():
                 try:
+                    logger.debug(
+                        f"Deserializing module '{name}' of type '{module_data.get('type')}' for agent '{agent_name}'"
+                    )
                     module_instance = deserialize_component(
                         module_data, FlockModule
                     )
@@ -543,6 +596,9 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
                         agent.add_module(
                             module_instance
                         )  # Use add_module for consistency
+                        logger.debug(
+                            f"Successfully added module '{name}' to agent '{agent_name}'"
+                        )
                     else:
                         raise ValueError("deserialize_component returned None")
                 except Exception as e:
@@ -555,25 +611,61 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         # --- Deserialize Tools ---
         agent.tools = []  # Initialize tools list
         if tools_data:
-            for tool_ref in tools_data:
-                if (
-                    isinstance(tool_ref, dict)
-                    and "__callable_ref__" in tool_ref
-                ):
-                    path_str = tool_ref["__callable_ref__"]
-                    try:
-                        tool_func = FlockRegistry.get_callable(path_str)
-                        agent.tools.append(tool_func)
-                    except KeyError:
-                        logger.error(
-                            f"Tool callable '{path_str}' not found in registry for agent '{agent_name}'. Skipping."
+            # Get component registry to look up function imports
+            registry = get_registry()
+            components = getattr(registry, "_callables", {})
+            logger.debug(
+                f"Deserializing {len(tools_data)} tools for agent '{agent_name}'"
+            )
+            logger.debug(
+                f"Available callables in registry: {list(components.keys())}"
+            )
+
+            for tool_name in tools_data:
+                try:
+                    logger.debug(f"Looking for tool '{tool_name}' in registry")
+                    # First try to lookup by simple name in the registry's callables
+                    found = False
+                    for path_str, func in components.items():
+                        if (
+                            path_str.endswith("." + tool_name)
+                            or path_str == tool_name
+                        ):
+                            agent.tools.append(func)
+                            found = True
+                            logger.info(
+                                f"Found tool '{tool_name}' via path '{path_str}' for agent '{agent_name}'"
+                            )
+                            break
+
+                    # If not found by simple name, try manual import
+                    if not found:
+                        logger.debug(
+                            f"Attempting to import tool '{tool_name}' from modules"
                         )
-                else:
-                    logger.warning(
-                        f"Invalid tool format found during deserialization for agent '{agent_name}': {tool_ref}. Skipping."
+                        # Check in relevant modules (could be customized based on project structure)
+                        import __main__
+
+                        if hasattr(__main__, tool_name):
+                            agent.tools.append(getattr(__main__, tool_name))
+                            found = True
+                            logger.info(
+                                f"Found tool '{tool_name}' in __main__ module for agent '{agent_name}'"
+                            )
+
+                    if not found:
+                        logger.warning(
+                            f"Could not find tool '{tool_name}' for agent '{agent_name}'"
+                        )
+                except Exception as e:
+                    logger.error(
+                        f"Error adding tool '{tool_name}' to agent '{agent_name}': {e}",
+                        exc_info=True,
                     )
 
-        logger.info(f"Successfully deserialized agent: {agent.name}")
+        logger.info(
+            f"Successfully deserialized agent '{agent_name}' with {len(agent.modules)} modules and {len(agent.tools)} tools"
+        )
         return agent
 
     # --- Pydantic v2 Configuration ---

flock/core/flock_registry.py

@@ -162,16 +162,20 @@ class FlockRegistry:
                 and self._callables[path_str] != func
             ):
                 logger.warning(
-                    f"Callable '{path_str}' already registered. Overwriting."
+                    f"Callable '{path_str}' already registered with a different function. Overwriting."
                 )
             self._callables[path_str] = func
-            logger.debug(f"Registered callable: {path_str}")
+            logger.debug(f"Registered callable: '{path_str}' ({func.__name__})")
             return path_str
+        logger.warning(
+            f"Could not register callable {func.__name__}: Unable to determine path string"
+        )
         return None
 
     def get_callable(self, path_str: str) -> Callable:
         """Retrieves a callable by its path string, attempting dynamic import if not found."""
         if path_str in self._callables:
+            logger.debug(f"Found callable '{path_str}' in registry")
             return self._callables[path_str]
 
         logger.debug(
@@ -179,14 +183,20 @@ class FlockRegistry:
         )
         try:
             if "." not in path_str:  # Built-ins
+                logger.debug(f"Trying to import built-in callable '{path_str}'")
                 builtins_module = importlib.import_module("builtins")
                 if hasattr(builtins_module, path_str):
                     func = getattr(builtins_module, path_str)
                     if callable(func):
                         self.register_callable(func, path_str)  # Cache it
+                        logger.info(
+                            f"Successfully imported built-in callable '{path_str}'"
+                        )
                         return func
+                logger.error(f"Built-in callable '{path_str}' not found.")
                 raise KeyError(f"Built-in callable '{path_str}' not found.")
 
+            logger.debug(f"Trying to import module callable '{path_str}'")
             module_name, func_name = path_str.rsplit(".", 1)
             module = importlib.import_module(module_name)
             func = getattr(module, func_name)
@@ -194,14 +204,21 @@ class FlockRegistry:
                 self.register_callable(
                     func, path_str
                 )  # Cache dynamically imported
+                logger.info(
+                    f"Successfully imported module callable '{path_str}'"
+                )
                 return func
             else:
+                logger.error(
+                    f"Dynamically imported object '{path_str}' is not callable."
+                )
                 raise TypeError(
                     f"Dynamically imported object '{path_str}' is not callable."
                 )
         except (ImportError, AttributeError, KeyError, TypeError) as e:
             logger.error(
-                f"Failed to dynamically load/find callable '{path_str}': {e}"
+                f"Failed to dynamically load/find callable '{path_str}': {e}",
+                exc_info=True,
             )
             raise KeyError(
                 f"Callable '{path_str}' not found or failed to load: {e}"
@@ -209,11 +226,26 @@ class FlockRegistry:
 
     def get_callable_path_string(self, func: Callable) -> str | None:
         """Gets the path string for a callable, registering it if necessary."""
+        # First try to find by direct identity
         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
-        return self.register_callable(func)
+        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 {func.__name__}"
+            )
+
+        return path_str
 
     # --- Type Registration ---
     def register_type(

flock/core/serialization/serializable.py

@@ -2,7 +2,7 @@
 import json
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Any, TypeVar
+from typing import Any, Literal, TypeVar
 
 # Use yaml if available, otherwise skip yaml methods
 try:
@@ -85,16 +85,32 @@ class Serializable(ABC):
             ) from e
 
     # --- YAML Methods ---
-    def to_yaml(self, sort_keys=False, default_flow_style=False) -> str:
-        """Serialize to YAML string."""
+    def to_yaml(
+        self,
+        path_type: Literal["absolute", "relative"],
+        sort_keys=False,
+        default_flow_style=False,
+    ) -> str:
+        """Serialize to YAML string.
+
+        Args:
+            path_type: How file paths should be formatted ('absolute' or 'relative')
+            sort_keys: Whether to sort dictionary keys
+            default_flow_style: YAML flow style setting
+        """
         if not YAML_AVAILABLE:
             raise NotImplementedError(
                 "YAML support requires PyYAML: pip install pyyaml"
             )
         try:
-            # to_dict should prepare a structure suitable for YAML dumping
+            # If to_dict supports path_type, pass it; otherwise use standard to_dict
+            if "path_type" in self.to_dict.__code__.co_varnames:
+                dict_data = self.to_dict(path_type=path_type)
+            else:
+                dict_data = self.to_dict()
+
             return yaml.dump(
-                self.to_dict(),
+                dict_data,
                 sort_keys=sort_keys,
                 default_flow_style=default_flow_style,
                 allow_unicode=True,
@@ -125,8 +141,19 @@ class Serializable(ABC):
                 f"Failed to deserialize {cls.__name__} from YAML: {e}"
             ) from e
 
-    def to_yaml_file(self, path: Path | str, **yaml_dump_kwargs) -> None:
-        """Serialize to YAML file."""
+    def to_yaml_file(
+        self,
+        path: Path | str,
+        path_type: Literal["absolute", "relative"] = "absolute",
+        **yaml_dump_kwargs,
+    ) -> None:
+        """Serialize to YAML file.
+
+        Args:
+            path: File path to write to
+            path_type: How file paths should be formatted ('absolute' or 'relative')
+            **yaml_dump_kwargs: Additional arguments to pass to yaml.dump
+        """
         if not YAML_AVAILABLE:
             raise NotImplementedError(
                 "YAML support requires PyYAML: pip install pyyaml"
@@ -134,7 +161,7 @@ class Serializable(ABC):
         path = Path(path)
         try:
             path.parent.mkdir(parents=True, exist_ok=True)
-            yaml_str = self.to_yaml(**yaml_dump_kwargs)
+            yaml_str = self.to_yaml(path_type=path_type, **yaml_dump_kwargs)
             path.write_text(yaml_str, encoding="utf-8")
         except Exception as e:
             raise RuntimeError(

flock/core/util/cli_helper.py

@@ -52,7 +52,7 @@ def init_console(clear_screen: bool = True):
 │ ▒█▀▀▀ █░░ █▀▀█ █▀▀ █░█ │
 │ ▒█▀▀▀ █░░ █░░█ █░░ █▀▄ │
 │ ▒█░░░ ▀▀▀ ▀▀▀▀ ▀▀▀ ▀░▀ │
-╰━━━━━━━━━v{__version__}━━━━━━━━╯
+╰━━━━━━━━v{__version__}━━━━━━━━╯
 🦆     🐤    🐧     🐓
 """,
         justify="center",
@@ -62,7 +62,7 @@ def init_console(clear_screen: bool = True):
         console.clear()
     console.print(banner_text)
     console.print(
-        f"[italic]'Hummingbird'[/] milestone - [bold]white duck GmbH[/] - [cyan]https://whiteduck.de[/]\n"
+        f"[italic]'Magpie'[/] milestone - [bold]white duck GmbH[/] - [cyan]https://whiteduck.de[/]\n"
     )
 
 

flock/core/util/file_path_utils.py

@@ -0,0 +1,223 @@
+"""Utility functions for handling file paths in Flock.
+
+This module provides utilities for working with file paths,
+especially for components that may be loaded from file system paths
+rather than module imports.
+"""
+
+import importlib.util
+import inspect
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def get_file_path(obj: Any) -> str | None:
+    """Get the file path for a Python object.
+
+    Args:
+        obj: The object to get the file path for
+
+    Returns:
+        The file path if it can be determined, None otherwise
+    """
+    try:
+        if inspect.ismodule(obj):
+            return obj.__file__
+        elif inspect.isclass(obj) or inspect.isfunction(obj):
+            return inspect.getfile(obj)
+        return None
+    except (TypeError, ValueError):
+        return None
+
+
+def normalize_path(path: str) -> str:
+    """Normalize a path for consistent representation.
+
+    Args:
+        path: The path to normalize
+
+    Returns:
+        The normalized path
+    """
+    return os.path.normpath(path)
+
+
+def is_same_path(path1: str, path2: str) -> bool:
+    """Check if two paths point to the same file.
+
+    Args:
+        path1: The first path
+        path2: The second path
+
+    Returns:
+        True if the paths point to the same file, False otherwise
+    """
+    return os.path.normpath(os.path.abspath(path1)) == os.path.normpath(
+        os.path.abspath(path2)
+    )
+
+
+def get_relative_path(path: str, base_path: str | None = None) -> str:
+    """Get a path relative to a base path.
+
+    Args:
+        path: The path to make relative
+        base_path: The base path (defaults to current working directory)
+
+    Returns:
+        The relative path
+    """
+    if base_path is None:
+        base_path = os.getcwd()
+
+    return os.path.relpath(path, base_path)
+
+
+def load_class_from_file(file_path: str, class_name: str) -> type | None:
+    """Load a class from a file.
+
+    Args:
+        file_path: The path to the file
+        class_name: The name of the class to load
+
+    Returns:
+        The loaded class, or None if it could not be loaded
+    """
+    try:
+        # Generate a unique module name to avoid conflicts
+        module_name = f"flock_dynamic_import_{hash(file_path)}"
+
+        # Create a spec for the module
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if not spec or not spec.loader:
+            return None
+
+        # Create and load the module
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+
+        # Get the class from the module
+        if not hasattr(module, class_name):
+            return None
+
+        return getattr(module, class_name)
+    except Exception:
+        return None
+
+
+def get_project_root() -> Path:
+    """Get the project root directory.
+
+    Returns:
+        The project root path
+    """
+    # Try to find the directory containing pyproject.toml or setup.py
+    current_dir = Path(os.getcwd())
+
+    # Walk up the directory tree looking for project markers
+    for path in [current_dir, *current_dir.parents]:
+        if (path / "pyproject.toml").exists() or (path / "setup.py").exists():
+            return path
+
+    # Default to current directory if no project markers found
+    return current_dir
+
+
+def component_path_to_file_path(component_path: str) -> str | None:
+    """Convert a component path (module.ClassName) to a file path.
+
+    Args:
+        component_path: The component path in the form module.ClassName
+
+    Returns:
+        The file path if it can be determined, None otherwise
+    """
+    try:
+        # Split into module path and class name
+        if "." not in component_path:
+            return None
+
+        module_path, class_name = component_path.rsplit(".", 1)
+
+        # Import the module
+        module = importlib.import_module(module_path)
+
+        # Get the file path
+        if hasattr(module, "__file__"):
+            return module.__file__
+
+        return None
+    except (ImportError, AttributeError):
+        return None
+
+
+def file_path_to_component_path(file_path: str, class_name: str) -> str | None:
+    """Convert a file path and class name to a component path (module.ClassName).
+
+    This is approximate and may not work in all cases, especially for non-standard
+    module structures.
+
+    Args:
+        file_path: The file path to the module
+        class_name: The name of the class
+
+    Returns:
+        The component path if it can be determined, None otherwise
+    """
+    try:
+        # Convert the file path to an absolute path
+        abs_path = os.path.abspath(file_path)
+
+        # Get the project root
+        root = get_project_root()
+
+        # Get the relative path from the project root
+        rel_path = os.path.relpath(abs_path, root)
+
+        # Convert to a module path
+        module_path = os.path.splitext(rel_path)[0].replace(os.sep, ".")
+
+        # Remove 'src.' prefix if present (common in Python projects)
+        if module_path.startswith("src."):
+            module_path = module_path[4:]
+
+        # Combine with the class name
+        return f"{module_path}.{class_name}"
+    except Exception:
+        return None
+
+
+def register_file_paths_in_registry(
+    component_paths: dict[str, str], registry: Any | None = None
+) -> bool:
+    """Register file paths in the registry.
+
+    Args:
+        component_paths: Dictionary mapping component paths to file paths
+        registry: The registry to register in (defaults to the global registry)
+
+    Returns:
+        True if all paths were registered, False otherwise
+    """
+    try:
+        # Get the global registry if none provided
+        if registry is None:
+            from flock.core.flock_registry import get_registry
+
+            registry = get_registry()
+
+        # Initialize component_file_paths if needed
+        if not hasattr(registry, "_component_file_paths"):
+            registry._component_file_paths = {}
+
+        # Register each path
+        for component_name, file_path in component_paths.items():
+            if component_name in registry._components:
+                registry._component_file_paths[component_name] = file_path
+
+        return True
+    except Exception:
+        return False