flock-core 0.5.0b16__py3-none-any.whl → 0.5.0b18__py3-none-any.whl

flock/core/mixin/dspy_integration.py

@@ -1,5 +1,10 @@
 # src/flock/core/mixin/dspy_integration.py
-"""Mixin class for integrating with the dspy library."""
+"""Mixin class for integrating with the dspy library.
+
+This mixin centralizes Flock ↔ DSPy interop. It intentionally
+delegates more to DSPy’s native builders (Signature, settings.context,
+modules) to reduce custom glue and stay aligned with DSPy updates.
+"""
 
 import ast
 import re  # Import re for parsing
@@ -145,114 +150,70 @@ def _resolve_type_string(type_str: str) -> type:
 class DSPyIntegrationMixin:
     """Mixin class for integrating with the dspy library."""
 
-    def create_dspy_signature_class(
-        self, agent_name, description_spec, fields_spec
-    ) -> Any:
-        """Creates a dynamic DSPy Signature class from string specifications,
-        resolving types using the registry.
+    def create_dspy_signature_class(self, agent_name: str, description_spec: str, fields_spec: str) -> Any:
+        """Create a DSPy Signature using DSPy's native builder.
+
+        We support the Flock spec format: "field: type | description, ... -> ...".
+        This converts to the dict-based make_signature format with
+        InputField/OutputField and resolved Python types.
         """
         try:
             import dspy
-        except ImportError:
-            logger.error(
-                "DSPy library is not installed. Cannot create DSPy signature. "
-                "Install with: pip install dspy-ai"
-            )
-            raise ImportError("DSPy is required for this functionality.")
-
-        base_class = dspy.Signature
-        class_dict = {"__doc__": description_spec, "__annotations__": {}}
+        except ImportError as exc:
+            logger.error("DSPy is not installed. Install with: pip install dspy-ai")
+            raise
 
+        # Split input/output part
         if "->" in fields_spec:
             inputs_spec, outputs_spec = fields_spec.split("->", 1)
         else:
-            inputs_spec, outputs_spec = (
-                fields_spec,
-                "",
-            )  # Assume only inputs if no '->'
+            inputs_spec, outputs_spec = fields_spec, ""
 
-        def parse_field(field_str):
-            """Parses 'name: type_str | description' using _resolve_type_string."""
+        def parse_field(field_str: str) -> tuple[str, type, str | None] | None:
             field_str = field_str.strip()
             if not field_str:
                 return None
-
             parts = field_str.split("|", 1)
             main_part = parts[0].strip()
             desc = parts[1].strip() if len(parts) > 1 else None
-
             if ":" in main_part:
                 name, type_str = [s.strip() for s in main_part.split(":", 1)]
             else:
-                name = main_part
-                type_str = "str"  # Default type
-
+                name, type_str = main_part, "str"
             try:
-                field_type = _resolve_type_string(type_str)
-            except Exception as e:  # Catch resolution errors
-                logger.error(
-                    f"Failed to resolve type '{type_str}' for field '{name}': {e}. Defaulting to str."
+                py_type = _resolve_type_string(type_str)
+            except Exception as e:
+                logger.warning(
+                    f"Type resolution failed for '{type_str}' in field '{name}': {e}. Falling back to str."
                 )
-                field_type = str
-
-            return name, field_type, desc
-
-        def process_fields(fields_string, field_kind):
-            """Process fields and add to class_dict."""
-            if not fields_string or not fields_string.strip():
-                return
-
-            split_fields = split_top_level(fields_string)
-            for field in split_fields:
-                if field.strip():
-                    parsed = parse_field(field)
-                    if not parsed:
-                        continue
-                    name, field_type, desc = parsed
-                    class_dict["__annotations__"][name] = (
-                        field_type  # Use resolved type
-                    )
-
-                    FieldClass = (
-                        dspy.InputField
-                        if field_kind == "input"
-                        else dspy.OutputField
-                    )
-                    # DSPy Fields use 'desc' for description
-                    class_dict[name] = (
-                        FieldClass(desc=desc)
-                        if desc is not None
-                        else FieldClass()
-                    )
+                py_type = str
+            return name, py_type, desc
+
+        def to_field_tuples(spec: str, kind: str) -> dict[str, tuple[type, Any]]:
+            mapping: dict[str, tuple[type, Any]] = {}
+            if not spec.strip():
+                return mapping
+            for raw in split_top_level(spec):
+                parsed = parse_field(raw)
+                if not parsed:
+                    continue
+                fname, ftype, fdesc = parsed
+                FieldClass = dspy.InputField if kind == "input" else dspy.OutputField
+                finfo = FieldClass(desc=fdesc) if fdesc is not None else FieldClass()
+                mapping[fname] = (ftype, finfo)
+            return mapping
 
         try:
-            process_fields(inputs_spec, "input")
-            process_fields(outputs_spec, "output")
-        except Exception as e:
-            logger.error(
-                f"Error processing fields for DSPy signature '{agent_name}': {e}",
-                exc_info=True,
-            )
-            raise ValueError(
-                f"Could not process fields for signature: {e}"
-            ) from e
-
-        # Create and return the dynamic class
-        try:
-            DynamicSignature = type(
-                "dspy_" + agent_name, (base_class,), class_dict
-            )
-            logger.info(
-                f"Successfully created DSPy Signature: {DynamicSignature.__name__} "
-                f"with fields: {DynamicSignature.__annotations__}"
-            )
-            return DynamicSignature
-        except Exception as e:
-            logger.error(
-                f"Failed to create dynamic type 'dspy_{agent_name}': {e}",
-                exc_info=True,
-            )
-            raise TypeError(f"Could not create DSPy signature type: {e}") from e
+            fields: dict[str, tuple[type, Any]] = {
+                **to_field_tuples(inputs_spec, "input"),
+                **to_field_tuples(outputs_spec, "output"),
+            }
+            sig = dspy.Signature(fields, description_spec or None, signature_name=f"dspy_{agent_name}")
+            logger.info("Created DSPy Signature %s", sig.__name__)
+            return sig
+        except Exception as e:  # pragma: no cover - defensive
+            logger.error("Failed to create DSPy Signature for %s: %s", agent_name, e, exc_info=True)
+            raise
 
     def _configure_language_model(
         self,
@@ -275,34 +236,28 @@ class DSPyIntegrationMixin:
         try:
             import dspy
         except ImportError:
-            logger.error(
-                "DSPy library is not installed. Cannot configure language model."
-            )
-            return  # Or raise
+            logger.error("DSPy is not installed; cannot configure LM.")
+            return
 
+        # Build an LM instance for per-call usage; prefer settings.context over global configure.
         try:
-            # Ensure 'cache' parameter is handled correctly (might not exist on dspy.LM directly)
-            # DSPy handles caching globally or via specific optimizers typically.
-            # We'll configure the LM without explicit cache control here.
             lm_instance = dspy.LM(
                 model=model,
                 temperature=temperature,
                 max_tokens=max_tokens,
                 cache=use_cache,
-                # Add other relevant parameters if needed, e.g., API keys via dspy.settings
             )
-            dspy.settings.configure(lm=lm_instance)
+            # Do not call settings.configure() here to avoid cross-task/thread conflicts.
+            # Callers should pass this LM via dspy.settings.context(lm=...) or program.acall(lm=...)
+            dspy.settings  # touch to ensure settings is importable
             logger.info(
-                f"DSPy LM configured with model: {model}, temp: {temperature}, max_tokens: {max_tokens}"
+                "Prepared DSPy LM (defer install to settings.context): model=%s temp=%s max_tokens=%s",
+                model,
+                temperature,
+                max_tokens,
             )
-            # Note: DSPy caching is usually configured globally, e.g., dspy.settings.configure(cache=...)
-            # or handled by optimizers. Setting `cache=use_cache` on dspy.LM might not be standard.
         except Exception as e:
-            logger.error(
-                f"Failed to configure DSPy language model '{model}': {e}",
-                exc_info=True,
-            )
-            # We need to raise this exception, otherwise Flock will trundle on until it needs dspy.settings.lm and can't find it.
+            logger.error("Failed to prepare DSPy LM '%s': %s", model, e, exc_info=True)
             raise
 
     def _select_task(
@@ -349,9 +304,17 @@ class DSPyIntegrationMixin:
 
         # Determine type if not overridden
         if not selected_type:
-            selected_type = (
-                "ReAct" if processed_tools or processed_mcp_tools else "Predict"
-            )  # Default logic
+            selected_type = "ReAct" if processed_tools or processed_mcp_tools else "Predict"
+
+        # Normalize common aliases/casing
+        sel = selected_type.lower() if isinstance(selected_type, str) else selected_type
+        if isinstance(sel, str):
+            if sel in {"completion", "predict"}:
+                sel = "predict"
+            elif sel in {"react"}:
+                sel = "react"
+            elif sel in {"chainofthought", "cot", "chain_of_thought"}:
+                sel = "chain_of_thought"
 
         logger.debug(
             f"Selecting DSPy program type: {selected_type} (Tools provided: {bool(processed_tools)}) (MCP Tools: {bool(processed_mcp_tools)}"
@@ -368,15 +331,15 @@ class DSPyIntegrationMixin:
             merged_tools = merged_tools + processed_mcp_tools
 
         try:
-            if selected_type == "ChainOfThought":
+            if sel == "chain_of_thought":
                 dspy_program = dspy.ChainOfThought(signature, **kwargs)
-            elif selected_type == "ReAct":
+            elif sel == "react":
                 if not kwargs:
                     kwargs = {"max_iters": max_tool_calls}
                 dspy_program = dspy.ReAct(
                     signature, tools=merged_tools or [], **kwargs
                 )
-            elif selected_type == "Predict":  # Default or explicitly Completion
+            elif sel == "predict":
                 dspy_program = dspy.Predict(signature)
             else:  # Fallback or handle unknown type
                 logger.warning(
@@ -395,51 +358,46 @@ class DSPyIntegrationMixin:
             )
             raise RuntimeError(f"Could not create DSPy program: {e}") from e
 
-    def _process_result(
-        self, result: Any, inputs: dict[str, Any]
-    ) -> tuple[dict[str, Any], float, list]:
-        """Convert the DSPy result object to a dictionary."""
-        import dspy
+    def _process_result(self, result: Any, inputs: dict[str, Any]) -> tuple[dict[str, Any], float, list]:
+        """Convert a DSPy Prediction or mapping to a plain dict and attach LM history.
+
+        Returns (result_dict, cost_placeholder, lm_history). The cost is set to 0.0;
+        use token usage trackers elsewhere for accurate accounting.
+        """
+        try:
+            import dspy
+        except ImportError:
+            dspy = None
 
         if result is None:
             logger.warning("DSPy program returned None result.")
-            return {}
+            return {}, 0.0, []
+
         try:
-            # DSPy Prediction objects often behave like dicts or have .keys() / items()
-            if hasattr(result, "items") and callable(result.items):
-                output_dict = dict(result.items())
-            elif hasattr(result, "__dict__"):  # Fallback for other object types
-                output_dict = {
-                    k: v
-                    for k, v in result.__dict__.items()
-                    if not k.startswith("_")
-                }
+            # Best-effort extraction from DSPy Prediction
+            if dspy and isinstance(result, dspy.Prediction):
+                output_dict = dict(result.items(include_dspy=False))
+            elif isinstance(result, dict):
+                output_dict = result
+            elif hasattr(result, "items") and callable(result.items):
+                try:
+                    output_dict = dict(result.items())
+                except Exception:
+                    output_dict = {"raw_result": str(result)}
             else:
-                # If it's already a dict (less common for DSPy results directly)
-                if isinstance(result, dict):
-                    output_dict = result
-                else:  # Final fallback
-                    logger.warning(
-                        f"Could not reliably convert DSPy result of type {type(result)} to dict. Returning as is."
-                    )
-                    output_dict = {"raw_result": result}
+                output_dict = {"raw_result": str(result)}
 
-            logger.debug(f"Processed DSPy result to dict: {output_dict}")
-            # Optionally merge inputs back if desired (can make result dict large)
             final_result = {**inputs, **output_dict}
 
-            lm = dspy.settings.get("lm")
-            cost = sum([x["cost"] for x in lm.history if x["cost"] is not None])
-            lm_history = lm.history
+            lm_history = []
+            try:
+                if dspy and dspy.settings.lm is not None and hasattr(dspy.settings.lm, "history"):
+                    lm_history = dspy.settings.lm.history
+            except Exception:
+                lm_history = []
 
-            return final_result, cost, lm_history
+            return final_result, 0.0, lm_history
 
-        except Exception as conv_error:
-            logger.error(
-                f"Failed to process DSPy result into dictionary: {conv_error}",
-                exc_info=True,
-            )
-            return {
-                "error": "Failed to process result",
-                "raw_result": str(result),
-            }
+        except Exception as conv_error:  # pragma: no cover - defensive
+            logger.error("Failed to process DSPy result into dictionary: %s", conv_error, exc_info=True)
+            return {"error": "Failed to process result", "raw_result": str(result)}, 0.0, []

flock/core/orchestration/flock_execution.py

@@ -124,6 +124,13 @@ class FlockExecution:
 
             # Setup execution context and input
             run_input = input if input is not None else self.flock._start_input
+            # Accept Pydantic BaseModel instances as input by converting to dict
+            try:
+                from pydantic import BaseModel as _BM
+                if not isinstance(run_input, dict) and isinstance(run_input, _BM):
+                    run_input = run_input.model_dump(exclude_none=True)  # type: ignore[attr-defined]
+            except Exception:
+                pass
             effective_run_id = run_id or f"flockrun_{uuid.uuid4().hex[:8]}"
 
             # Set span attributes

flock/core/orchestration/flock_initialization.py

@@ -31,6 +31,10 @@ class FlockInitialization:
         servers: list["FlockMCPServer"] | None = None,
     ) -> None:
         """Handle all initialization side effects and setup."""
+        # Workaround: newer litellm logging tries to import proxy dependencies (apscheduler)
+        # via cold storage logging even for non-proxy usage. Avoid hard dependency by
+        # pre-stubbing the `litellm.proxy.proxy_server` module with a minimal object.
+        self._patch_litellm_proxy_imports()
         # Register passed servers first (agents may depend on them)
         if servers:
             self._register_servers(servers)
@@ -64,6 +68,26 @@ class FlockInitialization:
             enable_temporal=self.flock.enable_temporal,
         )
 
+    def _patch_litellm_proxy_imports(self) -> None:
+        """Stub litellm proxy_server to avoid optional proxy deps when not used.
+
+        Some litellm versions import `litellm.proxy.proxy_server` during standard logging
+        to read `general_settings`, which pulls in optional dependencies like `apscheduler`.
+        We provide a stub so imports succeed but cold storage remains disabled.
+        """
+        try:
+            import sys
+            import types
+
+            if "litellm.proxy.proxy_server" not in sys.modules:
+                stub = types.ModuleType("litellm.proxy.proxy_server")
+                # Minimal surface that cold_storage_handler accesses
+                setattr(stub, "general_settings", {})
+                sys.modules["litellm.proxy.proxy_server"] = stub
+        except Exception as e:
+            # Safe to ignore; worst case litellm will log a warning
+            logger.debug(f"Failed to stub litellm proxy_server: {e}")
+
     def _register_servers(self, servers: list["FlockMCPServer"]) -> None:
         """Register servers with the Flock instance."""
         from flock.core.mcp.flock_mcp_server import (

flock/core/serialization/serialization_utils.py

@@ -76,12 +76,14 @@ def _format_type_to_string(type_hint: type) -> str:
     elif hasattr(type_hint, "__name__"):
         # Handle custom types registered in registry (get preferred name)
         registry = get_registry()
-        for (
-            name,
-            reg_type,
-        ) in registry._types.items():  # Access internal for lookup
-            if reg_type == type_hint:
-                return name  # Return registered name
+        try:
+            # Prefer explicit type registration names when available
+            for name, reg_type in registry.types.get_all_types().items():
+                if reg_type == type_hint:
+                    return name
+        except Exception:
+            # Defensive: if registry helper is unavailable, fall back below
+            pass
         return type_hint.__name__  # Fallback to class name if not registered
     else:
         # Fallback for complex types or types not handled above
@@ -245,22 +247,20 @@ def serialize_item(item: Any) -> Any:
         return {key: serialize_item(value) for key, value in item.items()}
     elif isinstance(item, Sequence) and not isinstance(item, str):
         return [serialize_item(sub_item) for sub_item in item]
-    elif isinstance(
-        item, type
-    ):  # Handle type objects themselves (e.g. if stored directly)
-        type_name = registry.get_component_type_name(
-            item
-        )  # Check components first
+    elif isinstance(item, type):  # Handle type objects themselves (e.g. if stored directly)
+        # Prefer registered component/type names when possible
+        type_name = registry.get_component_type_name(item)
         if type_name:
             return {"__component_ref__": type_name}
-        type_name = registry._get_path_string(
-            item
-        )  # Check regular types/classes by path
-        if type_name:
-            return {"__type_ref__": type_name}
-        logger.warning(
-            f"Could not serialize type object {item}, storing as string."
-        )
+        # Fall back to module-qualified path for general types
+        try:
+            module = getattr(item, "__module__", None)
+            name = getattr(item, "__name__", None)
+            if module and name:
+                return {"__type_ref__": f"{module}.{name}"}
+        except Exception:
+            pass
+        logger.warning(f"Could not serialize type object {item}, storing as string.")
         return str(item)
     elif isinstance(item, Enum):
         return item.value

flock/workflow/agent_execution_activity.py

@@ -23,7 +23,7 @@ registry = get_registry()  # Get registry instance once
 
 
 @activity.defn
-async def execute_single_agent(agent_name: str, context: FlockContext) -> dict:
+async def execute_single_agent(agent_name: str, context_dict: dict) -> dict:
     """Executes a single specified agent and returns its result.
 
     Args:
@@ -47,7 +47,8 @@ async def execute_single_agent(agent_name: str, context: FlockContext) -> dict:
             # Raise error for Temporal to potentially retry/fail the activity
             raise ValueError(f"Agent '{agent_name}' not found in registry.")
 
-        # Set agent's context reference (transient, for this execution)
+        # Rehydrate context from dict and set on agent (transient for this execution)
+        context = FlockContext.from_dict(context_dict)
         agent.context = context
 
         # Ensure model is set (using context value if needed)
@@ -66,13 +67,39 @@ async def execute_single_agent(agent_name: str, context: FlockContext) -> dict:
         # agent.resolve_callables(context=context)
 
         # Resolve inputs for this specific agent run
-        previous_agent_name = (
-            context.get_last_agent_name()
-        )  # Relies on context method
+        previous_agent_name = context.get_last_agent_name()  # May be None on first agent
+        prev_def = (
+            context.get_agent_definition(previous_agent_name)
+            if previous_agent_name
+            else None
+        )
+        prev_out_spec = (
+            (prev_def.agent_data.get("output_spec") if isinstance(prev_def, type(prev_def)) else None)
+            if prev_def and isinstance(prev_def.agent_data, dict)
+            else None
+        )
+        prev_cfg = (
+            prev_def.agent_data.get("config")
+            if prev_def and isinstance(prev_def.agent_data, dict)
+            else {}
+        )
+        prev_strategy = (
+            prev_cfg.get("handoff_strategy") if isinstance(prev_cfg, dict) else None
+        ) or "static"
+        prev_map = (
+            prev_cfg.get("handoff_map") if isinstance(prev_cfg, dict) else None
+        ) or {}
         logger.debug(
             f"Resolving inputs for {agent_name} with previous agent {previous_agent_name}"
         )
-        agent_inputs = resolve_inputs(agent.input, context, previous_agent_name)
+        agent_inputs = resolve_inputs(
+            agent.input,
+            context,
+            previous_agent_name or "",
+            prev_out_spec or "",
+            prev_strategy,
+            prev_map,
+        )
         span.add_event(
             "resolved inputs", attributes={"inputs": str(agent_inputs)}
         )
@@ -96,6 +123,8 @@ async def execute_single_agent(agent_name: str, context: FlockContext) -> dict:
                 error=str(e),
                 exc_info=True,
             )
+            # Debug aid: ensure exception prints even if logger is muted in environment
+            print(f"[agent_activity] Single agent execution failed for {agent_name}: {e!r}")
             span.record_exception(e)
             # Re-raise the exception for Temporal to handle based on retry policy
             raise
@@ -103,22 +132,11 @@ async def execute_single_agent(agent_name: str, context: FlockContext) -> dict:
 
 @activity.defn
 async def determine_next_agent(
-    current_agent_name: str, result: dict, context: FlockContext
-) -> dict | None:
-    """Determines the next agent using the current agent's handoff router.
-
-    Args:
-        current_agent_name: The name of the agent that just ran.
-        result: The result produced by the current agent.
-        context: The current FlockContext.
-
-    Returns:
-        A dictionary representing the HandOffRequest (serialized via model_dump),
-        or None if no handoff occurs or router doesn't specify a next agent.
+    current_agent_name: str, result: dict, context_dict: dict
+) -> str | None:
+    """Determine the next agent using the agent's routing component.
 
-    Raises:
-        ValueError: If the current agent cannot be found.
-        Exception: Propagates exceptions from router execution for Temporal retries.
+    Returns the next agent's name or None if the workflow should terminate.
     """
     with tracer.start_as_current_span("determine_next_agent") as span:
         span.set_attribute("agent.name", current_agent_name)
@@ -145,75 +163,30 @@ async def determine_next_agent(
             agent=agent.name,
         )
         try:
-            # Execute the routing logic
-            handoff_data: (
-                HandOffRequest | Callable
-            ) = await agent.router.route(agent, result, context)
-
-            # Handle callable handoff functions - This is complex in distributed systems.
-            # Consider if this pattern should be supported or if routing should always
-            # return serializable data directly. Executing arbitrary code from context
-            # within an activity can have side effects and security implications.
-            # Assuming for now it MUST return HandOffRequest or structure convertible to it.
-            if callable(handoff_data):
-                logger.warning(
-                    "Callable handoff detected - executing function.",
-                    agent=agent.name,
-                )
-                # Ensure context is available if the callable needs it
-                try:
-                    handoff_data = handoff_data(
-                        context, result
-                    )  # Potential side effects
-                    if not isinstance(handoff_data, HandOffRequest):
-                        logger.error(
-                            "Handoff function did not return a HandOffRequest object.",
-                            agent=agent.name,
-                        )
-                        raise TypeError(
-                            "Handoff function must return a HandOffRequest object."
-                        )
-                except Exception as e:
-                    logger.error(
-                        "Handoff function execution failed",
-                        agent=agent.name,
-                        error=str(e),
-                        exc_info=True,
-                    )
-                    span.record_exception(e)
-                    raise  # Propagate error
-
-            # Ensure we have a HandOffRequest object after potentially calling function
-            if not isinstance(handoff_data, HandOffRequest):
-                logger.error(
-                    "Router returned unexpected type",
-                    type=type(handoff_data).__name__,
-                    agent=agent.name,
-                )
-                raise TypeError(
-                    f"Router for agent '{agent.name}' did not return a HandOffRequest object."
-                )
-
-            # Ensure agent instance is converted to name for serialization across boundaries
-            if isinstance(handoff_data.next_agent, FlockAgent):
-                handoff_data.next_agent = handoff_data.next_agent.name
-
-            # If router logic determines no further agent, return None
-            if not handoff_data.next_agent:
+            # Execute routing logic on the router component (unified architecture)
+            context = FlockContext.from_dict(context_dict)
+            next_val = await agent.router.determine_next_step(agent, result, context)
+
+            # Convert to a simple agent name if needed
+            if isinstance(next_val, FlockAgent):
+                next_name = next_val.name
+            elif isinstance(next_val, str):
+                next_name = next_val
+            else:
+                next_name = None
+
+            if not next_name:
                 logger.info("Router determined no next agent", agent=agent.name)
                 span.add_event("no_next_agent_from_router")
                 return None
 
             logger.info(
-                "Handoff determined",
-                next_agent=handoff_data.next_agent,
+                "Next agent determined",
+                next_agent=next_name,
                 agent=agent.name,
             )
-            span.set_attribute("next_agent", handoff_data.next_agent)
-            # Return the serializable HandOffRequest data using Pydantic's export method
-            return handoff_data.model_dump(
-                mode="json"
-            )  # Ensure JSON-serializable
+            span.set_attribute("next_agent", next_name)
+            return next_name
 
         except Exception as e:
             # Catch potential errors during routing execution
@@ -223,6 +196,7 @@ async def determine_next_agent(
                 error=str(e),
                 exc_info=True,
             )
+            print(f"[agent_activity] Router execution failed for {agent.name}: {e!r}")
             span.record_exception(e)
             # Let Temporal handle the activity failure based on retry policy
             raise