flock-core 0.5.0b28__py3-none-any.whl → 0.5.56b0__py3-none-any.whl

flock/core/util/hydrator.py

@@ -1,309 +0,0 @@
-# src/flock/core/util/hydrator.py (Revised - Simpler)
-
-import asyncio
-import json
-from typing import (
-    Any,
-    TypeVar,
-    get_type_hints,
-)
-
-from pydantic import BaseModel
-
-# Import necessary Flock components
-from flock.core import Flock, FlockFactory
-from flock.core.logging.logging import get_logger
-
-# Import helper to format type hints back to strings
-from flock.core.serialization.serialization_utils import _format_type_to_string
-
-logger = get_logger("hydrator")
-T = TypeVar("T", bound=BaseModel)
-
-
-def flockclass(model: str = "openai/gpt-4o", agent_description: str | None = None):
-    """Decorator to add a .hydrate() method to a Pydantic class.
-    Leverages a dynamic Flock agent to fill missing (None) fields.
-
-    Args:
-        model: The default LLM model identifier to use for hydration.
-        agent_description: An optional description for the dynamically created agent.
-    """
-
-    def decorator(cls: type[T]) -> type[T]:
-        if not issubclass(cls, BaseModel):
-            raise TypeError(
-                "@flockclass can only decorate Pydantic BaseModel subclasses."
-            )
-
-        # Store metadata on the class
-        setattr(cls, "__flock_model__", model)
-        setattr(cls, "__flock_agent_description__", agent_description)
-
-        # --- Attach the async hydrate method directly ---
-        async def hydrate_async(self) -> T:
-            """Hydrates the object by filling None fields using a dynamic Flock agent.
-            Uses existing non-None fields as input context.
-            Returns the hydrated object (self).
-            """
-            class_name = self.__class__.__name__
-            logger.info(f"Starting hydration for instance of {class_name}")
-
-            # Get field information
-            all_fields, type_hints = _get_model_fields(self, class_name)
-            if all_fields is None or type_hints is None:
-                return self  # Return early if field introspection failed
-
-            # Identify existing and missing fields
-            existing_data, missing_fields = _identify_fields(self, all_fields)
-
-            if not missing_fields:
-                logger.info(f"No fields to hydrate for {class_name} instance.")
-                return self
-
-            logger.debug(f"{class_name}: Fields to hydrate: {missing_fields}")
-            logger.debug(
-                f"{class_name}: Existing data for context: {json.dumps(existing_data, default=str)}"
-            )
-
-            # Create agent signatures
-            input_str, output_str, input_parts = _build_agent_signatures(
-                existing_data,
-                missing_fields,
-                type_hints,
-                all_fields,
-                class_name,
-            )
-
-            # Create and run agent
-            result = await _run_hydration_agent(
-                self,
-                input_str,
-                output_str,
-                input_parts,
-                existing_data,
-                class_name,
-            )
-            if result is None:
-                return self  # Return early if agent run failed
-
-            # Update object fields with results
-            _update_fields_with_results(self, result, missing_fields, class_name)
-
-            return self
-
-        # --- Attach the sync hydrate method directly ---
-        def hydrate(self) -> T:
-            """Synchronous wrapper for the async hydrate method."""
-            try:
-                # Try to get the current running loop
-                loop = asyncio.get_running_loop()
-
-                # If we reach here, there is a running loop
-                if loop.is_running():
-                    # This runs the coroutine in the existing loop from a different thread
-                    import concurrent.futures
-
-                    with concurrent.futures.ThreadPoolExecutor() as executor:
-                        future = executor.submit(asyncio.run, hydrate_async(self))
-                        return future.result()
-                else:
-                    # There's a loop but it's not running
-                    return loop.run_until_complete(hydrate_async(self))
-
-            except RuntimeError:  # No running loop
-                # If no loop is running, create a new one and run our coroutine
-                return asyncio.run(hydrate_async(self))
-
-        # Attach the methods to the class
-        setattr(cls, "hydrate_async", hydrate_async)
-        setattr(cls, "hydrate", hydrate)
-        setattr(cls, "hydrate_sync", hydrate)  # Alias for backward compatibility
-
-        logger.debug(f"Attached hydrate methods to class {cls.__name__}")
-        return cls
-
-    return decorator
-
-
-def _get_model_fields(
-    obj: BaseModel, class_name: str
-) -> tuple[dict | None, dict | None]:
-    """Extracts field information from a Pydantic model, handling v1/v2 compatibility."""
-    try:
-        if hasattr(obj, "model_fields"):  # Pydantic v2
-            all_fields = obj.model_fields
-            type_hints = {name: field.annotation for name, field in all_fields.items()}
-        else:  # Pydantic v1 fallback
-            type_hints = get_type_hints(obj.__class__)
-            all_fields = getattr(obj, "__fields__", {name: None for name in type_hints})
-        return all_fields, type_hints
-    except Exception as e:
-        logger.error(
-            f"Could not get fields/type hints for {class_name}: {e}",
-            exc_info=True,
-        )
-        return None, None
-
-
-def _identify_fields(
-    obj: BaseModel, all_fields: dict
-) -> tuple[dict[str, Any], list[str]]:
-    """Identifies existing (non-None) and missing fields in the object."""
-    existing_data: dict[str, Any] = {}
-    missing_fields: list[str] = []
-
-    for field_name in all_fields:
-        if hasattr(obj, field_name):  # Check if attribute exists
-            value = getattr(obj, field_name)
-            if value is not None:
-                existing_data[field_name] = value
-            else:
-                missing_fields.append(field_name)
-
-    return existing_data, missing_fields
-
-
-def _build_agent_signatures(
-    existing_data: dict[str, Any],
-    missing_fields: list[str],
-    type_hints: dict,
-    all_fields: dict,
-    class_name: str,
-) -> tuple[str, str, list]:
-    """Builds input and output signatures for the dynamic agent."""
-    # Input signature based on existing data
-    input_parts = []
-    for name in existing_data:
-        field_type = type_hints.get(name, Any)
-        type_str = _format_type_to_string(field_type)
-        field_info = all_fields.get(name)
-        field_desc = getattr(field_info, "description", "")
-        if field_desc:
-            input_parts.append(f"{name}: {type_str} | {field_desc}")
-        else:
-            input_parts.append(f"{name}: {type_str}")
-
-    input_str = (
-        ", ".join(input_parts)
-        if input_parts
-        else "context_info: dict | Optional context if no fields have values"
-    )
-
-    # Output signature based on missing fields
-    output_parts = []
-    for name in missing_fields:
-        field_type = type_hints.get(name, Any)
-        type_str = _format_type_to_string(field_type)
-        field_info = all_fields.get(name)
-        field_desc = getattr(field_info, "description", "")
-        if field_desc:
-            output_parts.append(f"{name}: {type_str} | {field_desc}")
-        else:
-            output_parts.append(f"{name}: {type_str}")
-
-    output_str = ", ".join(output_parts)
-
-    return input_str, output_str, input_parts
-
-
-async def _run_hydration_agent(
-    obj: BaseModel,
-    input_str: str,
-    output_str: str,
-    input_parts: list,
-    existing_data: dict[str, Any],
-    class_name: str,
-) -> dict[str, Any] | None:
-    """Creates and runs a dynamic Flock agent to hydrate the object."""
-    # Agent configuration
-    agent_name = f"hydrator_{class_name}_{id(obj)}"
-    description = (
-        getattr(obj, "__flock_agent_description__", None)
-        or f"Agent that completes missing data for a {class_name} object."
-    )
-    hydration_model = getattr(obj, "__flock_model__", "openai/gpt-4o")
-
-    logger.debug(f"Creating dynamic agent '{agent_name}' for {class_name}")
-    logger.debug(f"  Input Schema: {input_str}")
-    logger.debug(f"  Output Schema: {output_str}")
-
-    try:
-        # Create agent
-        dynamic_agent = FlockFactory.create_default_agent(
-            name=agent_name,
-            description=description,
-            input=input_str,
-            output=output_str,
-            model=hydration_model,
-            no_output=True,
-            use_cache=False,
-        )
-
-        # Create temporary Flock
-        temp_flock = Flock(
-            name=f"temp_hydrator_flock_{agent_name}",
-            model=hydration_model,
-            show_flock_banner=False,
-        )
-        temp_flock.add_agent(dynamic_agent)
-
-        # Prepare input data
-        agent_input_data = (
-            existing_data
-            if input_parts
-            else {"context_info": {"object_type": class_name}}
-        )
-
-        logger.info(f"Running hydration agent '{agent_name}' for {class_name}...")
-
-        # Run agent
-        result = await temp_flock.run_async(
-            agent=agent_name,
-            input=agent_input_data,
-            box_result=False,
-        )
-        logger.info(f"Hydration agent returned for {class_name}: {list(result.keys())}")
-
-        return result
-
-    except Exception as e:
-        logger.error(
-            f"Hydration agent creation or run failed for {class_name}: {e}",
-            exc_info=True,
-        )
-        return None
-
-
-def _update_fields_with_results(
-    obj: BaseModel,
-    result: dict[str, Any],
-    missing_fields: list[str],
-    class_name: str,
-) -> None:
-    """Updates object fields with results from the hydration agent."""
-    updated_count = 0
-    for field_name in missing_fields:
-        if field_name in result:
-            try:
-                setattr(obj, field_name, result[field_name])
-                logger.debug(
-                    f"Hydrated field '{field_name}' in {class_name} with value: {getattr(obj, field_name)}"
-                )
-                updated_count += 1
-            except Exception as e:
-                logger.warning(
-                    f"Failed to set hydrated value for '{field_name}' in {class_name}: {e}. Value received: {result[field_name]}"
-                )
-        else:
-            logger.warning(
-                f"Hydration result missing expected field for {class_name}: '{field_name}'"
-            )
-
-    logger.info(
-        f"Hydration complete for {class_name}. Updated {updated_count}/{len(missing_fields)} fields."
-    )
-
-
-# Ensure helper functions are available
-# from flock.core.serialization.serialization_utils import _format_type_to_string

flock/core/util/input_resolver.py

@@ -1,164 +0,0 @@
-"""Utility functions for resolving input keys to their corresponding values."""
-
-from flock.core.context.context import FlockContext
-from flock.core.util.splitter import split_top_level
-
-
-def get_callable_members(obj):
-    """Extract all callable (methods/functions) members from a module or class.
-    Returns a list of callable objects.
-    """
-    import inspect
-
-    # Get all members of the object
-    members = inspect.getmembers(obj)
-
-    # Filter for callable members that don't start with underscore (to exclude private/special methods)
-    callables = [
-        member[1]
-        for member in members
-        if inspect.isroutine(member[1]) and not member[0].startswith("_")
-    ]
-
-    return callables
-
-
-def _parse_keys(keys: list[str]) -> list[str]:
-    """Split a comma‐separated string and strip any type annotations.
-
-    For example, "a, b: list[str]" becomes ["a", "b"].
-    """
-    res_keys = []
-    for key in keys:
-        if "|" in key:
-            key = key.split("|")[0].strip()
-        if ":" in key:
-            key = key.split(":")[0].strip()
-        res_keys.append(key)
-    return res_keys
-
-
-def top_level_to_keys(s: str) -> list[str]:
-    """Convert a top-level comma-separated string to a list of keys."""
-    top_level_split = split_top_level(s)
-    return _parse_keys(top_level_split)
-
-
-def resolve_inputs(
-    input_spec: str,
-    context: FlockContext,
-    previous_agent_name: str,
-    previous_agent_output:str,
-    previous_agent_handoff_strategy:str,
-    previous_agent_handoff_map:dict[str, str]
-) -> dict:
-    """Build a dictionary of inputs based on the input specification string and the provided context.
-
-    The lookup rules are:
-      - "context" (case-insensitive): returns the entire context.
-      - "context.property": returns an attribute from the context.
-      - "def.agent_name": returns the agent definition for the given agent.
-      - "agent_name": returns the most up2date record from the given agent's history.
-      - "agent_name.property": returns the value of a property from the state variable keyed by "agent_name.property".
-      - "property": searches the history for the most recent value of a property.
-      - Otherwise, if no matching value is found, fallback to the FLOCK_INITIAL_INPUT.
-
-    -> Recommendations:
-        - prefix your agent variables with the agent name or a short handle to avoid conflicts.
-        eg. agent name: "idea_agent", variable: "ia_idea" (ia = idea agent)
-        - or set hand off mode to strict to avoid conflicts.
-        with strict mode, the agent will only accept inputs from the previous agent.
-        
-
-    Strategy for passing data to the next agent.
-
-    Example:
-    ReviewAgent.next_agent = SummaryAgent
-    ReviewAgent(output = "text:str, keywords:list[str], rating:int")
-    SummaryAgent(input = "text:str, title:str")
-
-    'append' means the difference in signature is appended to the next agent's input signature.
-    SummaryAgent(input = "text:str, title:str, keywords:list[str], rating:int")
-
-    'override' means the target agent's signature is getting overriden.
-    SummaryAgent(input = "text:str, keywords:list[str], rating:int")
-
-    'static' means the the target agent's signature is not changed at all.
-    If source agent has no output fields that match the target agent's input,
-    there will be no data passed to the next agent.
-    SummaryAgent(input = "text:str, title:str")
-
-    'map' means the source agent's output is mapped to the target agent's input
-    based on 'handoff_map' configuration.
-
-    Args:
-        input_spec: Comma-separated input keys (e.g., "query" or "agent_name.property").
-        context: A FlockContext instance.
-
-    Returns:
-        A dictionary mapping each input key to its resolved value.
-    """
-    split_input = split_top_level(input_spec)
-    keys = _parse_keys(split_input)
-    inputs = {}
-
-    def _normalize_empty_string(val):
-        """Treat empty string inputs as None to match None semantics.
-
-        This aligns behavior so passing "" behaves like passing None
-        for agent input properties.
-        """
-        if isinstance(val, str) and val == "":
-            return None
-        return val
-
-    for key in keys:
-        split_key = key.split(".")
-
-        # Case 1: A single key
-        if len(split_key) == 1:
-            # Special keyword: "context"
-            if key.lower() == "context":
-                inputs[key] = context
-                continue
-
-            # Try to get a historic record for an agent (if any)
-            historic_records = context.get_agent_history(key)
-            if historic_records:
-                # You may choose to pass the entire record or just its data.
-                inputs[key] = historic_records[0].data
-                continue
-
-            # Fallback to the most recent value in the state
-            historic_value = context.get_most_recent_value(key)
-            if historic_value is not None:
-                inputs[key] = _normalize_empty_string(historic_value)
-                continue
-
-            # Fallback to the initial input
-            var_value = context.get_variable(key)
-            if var_value is not None:
-                inputs[key] = _normalize_empty_string(var_value)
-                continue
-
-            inputs[key] = _normalize_empty_string(context.get_variable("flock." + key))
-
-        # Case 2: A compound key (e.g., "agent_name.property" or "context.property")
-        elif len(split_key) == 2:
-            entity_name, property_name = split_key
-
-            if entity_name.lower() == "context":
-                # Try to fetch the attribute from the context
-                inputs[key] = _normalize_empty_string(getattr(context, property_name, None))
-                continue
-
-            if entity_name.lower() == "def":
-                # Return the agent definition for the given property name
-                inputs[key] = _normalize_empty_string(context.get_agent_definition(property_name))
-                continue
-
-            # Otherwise, attempt to look up a state variable with the key "entity_name.property_name"
-            inputs[key] = _normalize_empty_string(context.get_variable(f"{entity_name}.{property_name}"))
-            continue
-
-    return inputs

flock/core/util/loader.py

@@ -1,59 +0,0 @@
-# src/flock/core/loader.py
-"""Provides functionality to load Flock instances from files."""
-
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-# Use TYPE_CHECKING to avoid runtime circular import if Flock imports this module indirectly
-if TYPE_CHECKING:
-    from flock.core.flock import Flock
-
-# Import locally within the function to ensure Serializable methods are available
-# from .serialization.serializable import Serializable # Serializable defines the file methods
-
-# Cloudpickle check needs to be top-level
-try:
-    import cloudpickle
-
-    PICKLE_AVAILABLE = True
-except ImportError:
-    PICKLE_AVAILABLE = False
-
-
-def load_flock_from_file(file_path: str) -> "Flock":
-    """Load a Flock instance from various file formats (detects type)."""
-    # Import Flock locally within the function to avoid circular dependency at module level
-    from flock.core.flock import Flock
-
-    p = Path(file_path)
-    if not p.exists():
-        raise FileNotFoundError(f"Flock file not found: {file_path}")
-
-    try:
-        if p.suffix.lower() in [".yaml", ".yml"]:
-            return Flock.from_yaml_file(p)
-        elif p.suffix.lower() == ".json":
-            # Assuming from_json is available via Serializable or directly on Flock
-            return Flock.from_json(p.read_text())
-        elif p.suffix.lower() == ".msgpack":
-            # Assuming from_msgpack_file is available via Serializable or directly on Flock
-            return Flock.from_msgpack_file(p)
-        elif p.suffix.lower() == ".pkl":
-            if PICKLE_AVAILABLE:
-                # Assuming from_pickle_file is available via Serializable or directly on Flock
-                return Flock.from_pickle_file(p)
-            else:
-                raise RuntimeError(
-                    "Cannot load Pickle file: cloudpickle not installed."
-                )
-        else:
-            raise ValueError(f"Unsupported file extension: {p.suffix}")
-    except Exception as e:
-        # Add specific error logging if helpful
-        from flock.core.logging.logging import get_logger
-
-        logger = get_logger("loader")
-        logger.error(
-            f"Error loading Flock from {file_path}: {e}", exc_info=True
-        )
-        raise  # Re-raise the original exception