flock-core 0.1.2__py3-none-any.whl → 0.2.1__py3-none-any.whl

flock/core/mixin/dspy_integration.py

@@ -0,0 +1,171 @@
+"""Mixin class for integrating with the dspy library."""
+
+import sys
+from typing import Any
+
+import dspy
+
+from flock.core.logging.logging import get_logger
+from flock.core.util.input_resolver import split_top_level
+
+logger = get_logger("flock")
+
+
+class DSPyIntegrationMixin:
+    """Mixin class for integrating with the dspy library."""
+
+    def create_dspy_signature_class(
+        self, agent_name, description_spec, fields_spec
+    ) -> dspy.Signature:
+        """Trying to create a dynamic class using dspy library."""
+        # ---------------------------
+        # 1. Parse the class specification.
+        # ---------------------------
+        base_class = dspy.Signature
+
+        # Start building the class dictionary with a docstring and annotations dict.
+        class_dict = {"__doc__": description_spec, "__annotations__": {}}
+
+        # ---------------------------
+        # 2. Split the fields specification into inputs and outputs.
+        # ---------------------------
+        if "->" in fields_spec:
+            inputs_spec, outputs_spec = fields_spec.split("->", 1)
+        else:
+            inputs_spec, outputs_spec = fields_spec, ""
+
+        # ---------------------------
+        # 3. Draw the rest of the owl.
+        # ---------------------------
+        def parse_field(field_str):
+            """Parser.
+
+            Parse a field of the form:
+                <name> [ : <type> ] [ | <desc> ]
+            Returns a tuple: (name, field_type, desc)
+            """
+            field_str = field_str.strip()
+            if not field_str:
+                return None
+
+            parts = field_str.split("|", 1)
+            main_part = parts[0].strip()  # contains name and (optionally) type
+            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
+
+            # Evaluate the type. Since type can be any valid expression (including custom types),
+            # we use eval. (Be cautious if using eval with untrusted input.)
+            try:
+                # TODO: We have to find a way to avoid using eval here.
+                # This is a security risk, as it allows arbitrary code execution.
+
+                try:
+                    field_type = eval(type_str, sys.modules[__name__].__dict__)
+                except Exception:
+                    field_type = eval(
+                        type_str, sys.modules["__main__"].__dict__
+                    )
+
+            except Exception:
+                # If evaluation fails, default to str.
+                field_type = str
+
+            return name, field_type, desc
+
+        def process_fields(fields_string, field_kind):
+            """Process a comma-separated list of field definitions.
+
+            field_kind: "input" or "output" determines which Field constructor to use.
+            """
+            if not fields_string.strip():
+                return
+
+            # Split on commas.
+            for field in split_top_level(fields_string):
+                if field.strip():
+                    parsed = parse_field(field)
+                    if not parsed:
+                        continue
+                    name, field_type, desc = parsed
+                    class_dict["__annotations__"][name] = field_type
+
+                    # Use the proper Field constructor.
+                    if field_kind == "input":
+                        if desc is not None:
+                            class_dict[name] = dspy.InputField(desc=desc)
+                        else:
+                            class_dict[name] = dspy.InputField()
+                    elif field_kind == "output":
+                        if desc is not None:
+                            class_dict[name] = dspy.OutputField(desc=desc)
+                        else:
+                            class_dict[name] = dspy.OutputField()
+                    else:
+                        raise ValueError("Unknown field kind: " + field_kind)
+
+        # Process input fields (to be used with my.InputField)
+        process_fields(inputs_spec, "input")
+        # Process output fields (to be used with my.OutputField)
+        process_fields(outputs_spec, "output")
+
+        return type("dspy_" + agent_name, (base_class,), class_dict)
+
+    def _configure_language_model(self) -> None:
+        """Initialize and configure the language model using dspy."""
+        lm = dspy.LM(self.model, cache=self.use_cache)
+        dspy.configure(lm=lm)
+
+    def _select_task(
+        self,
+        signature: dspy.Signature,
+    ) -> Any:
+        """Select and instantiate the appropriate task based on tool availability.
+
+        Args:
+            prompt: The detailed prompt string.
+            input_desc: Dictionary of input key descriptions.
+            output_desc: Dictionary of output key descriptions.
+
+        Returns:
+            An instance of a dspy task (either ReAct or Predict).
+        """
+        dspy_solver = None
+        if self.tools:
+            dspy_solver = dspy.ReAct(
+                signature,
+                tools=self.tools,
+                max_iters=10,
+            )
+        else:
+            dspy_solver = dspy.Predict(
+                signature,
+            )
+
+        return dspy_solver
+
+    def _process_result(
+        self, result: Any, inputs: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Convert the result to a dictionary and add the inputs for an unified result object.
+
+        Args:
+            result: The raw result from the dspy task.
+            inputs: The original inputs provided to the agent.
+
+        Returns:
+            A dictionary containing the processed output.
+        """
+        try:
+            result = result.toDict()
+            for key in inputs:
+                result.setdefault(key, inputs.get(key))
+        except Exception as conv_error:
+            logger.warning(
+                f"Warning: Failed to convert result to dict in agent '{self.name}': {conv_error}"
+            )
+        return result

flock/core/mixin/prompt_parser.py

@@ -0,0 +1,125 @@
+"""A mixin class for parsing agent prompts and building clean signatures for DSPy."""
+
+# DEPRECATED! This mixin is no longer used in the current version of Flock. It was used to parse agent prompts and build clean signatures for DSPy.
+# TODO: DELETE THIS FILE!
+
+from flock.core.util.input_resolver import split_top_level
+
+
+class PromptParserMixin:
+    """A mixin class for parsing agent prompts and building clean signatures for DSPy."""
+
+    def _parse_key_descriptions(self, keys_str: str) -> list[tuple[str, str]]:
+        """Parse a comma-separated string into a list of (key, description) tuples.
+
+        This function processes a configuration string that defines one or more keys, where each key may
+        include a type hint and an optional human-readable description. The expected format for each key is:
+
+            key: type_hint | description
+
+        If the pipe symbol ("|") is absent, the description is set to an empty string.
+
+        The splitting is performed using split_top_level() so that commas inside type hints are preserved.
+
+        For example, given:
+            "query: str | The search query, context: dict | The full conversation context"
+        it returns:
+            [("query", "The search query"), ("context", "The full conversation context")]
+
+        Args:
+            keys_str (str): A comma-separated string of key definitions.
+
+        Returns:
+            List[Tuple[str, str]]: A list of (key, description) tuples.
+        """
+        key_descs = []
+        for part in split_top_level(keys_str):
+            if not part:
+                continue
+            if "|" in part:
+                key_type_part, desc = part.split("|", 1)
+                desc = desc.strip()
+            else:
+                key_type_part = part
+                desc = ""
+            key = key_type_part.split(":", 1)[0].strip()
+            key_descs.append((key, desc))
+        return key_descs
+
+    def _build_clean_signature(self, keys_str: str) -> str:
+        """Build a clean signature string from the configuration string by removing the description parts.
+
+        Given a string like:
+            "query: str | The search query, context: dict | The full conversation context"
+        this method returns:
+            "query: str, context: dict"
+
+        This function uses split_top_level() to avoid splitting on commas that are inside type hints.
+
+        Args:
+            keys_str (str): The configuration string containing keys, type hints, and optional descriptions.
+
+        Returns:
+            str: A clean signature string with only keys and type hints.
+        """
+        parts = []
+        for part in split_top_level(keys_str):
+            if not part:
+                continue
+            if "|" in part:
+                clean_part = part.split("|", 1)[0].strip()
+            else:
+                clean_part = part.strip()
+            parts.append(clean_part)
+        return ", ".join(parts)
+
+    def _build_descriptions(self) -> tuple[dict[str, str], dict[str, str]]:
+        """Build dictionaries of input and output descriptions from the agent's configuration.
+
+        Returns:
+            A tuple containing:
+            - input_desc: A dictionary mapping each input key (without type hints) to its description.
+            - output_desc: A dictionary mapping each output key (without type hints) to its description.
+        """
+        input_desc: dict[str, str] = {}
+        if self.input:
+            for key, desc in self._parse_key_descriptions(self.input):
+                input_desc[key] = desc
+
+        output_desc: dict[str, str] = {}
+        if self.output:
+            for key, desc in self._parse_key_descriptions(self.output):
+                output_desc[key] = desc
+
+        return input_desc, output_desc
+
+    def _build_prompt(
+        self, input_desc: dict[str, str], output_desc: dict[str, str]
+    ) -> str:
+        """Build a clean signature prompt from the agent's configuration.
+
+        This method uses the original input and output strings (removing the description parts)
+        to create a signature string that is passed to DSPy. For example, if:
+        - self.input is "query: str | The search query, context: dict | The full conversation context"
+        - self.output is "result: str | The result"
+        then the prompt will be:
+        "query: str, context: dict -> result: str"
+
+        **Note:** The descriptive metadata is preserved in the dictionaries obtained from _build_descriptions,
+        which are passed separately to DSPy.
+
+        Args:
+            input_desc: Dictionary of input key descriptions (for metadata only).
+            output_desc: Dictionary of output key descriptions (for metadata only).
+
+        Returns:
+            A clean signature string for DSPy.
+        """
+        clean_input = (
+            self._build_clean_signature(self.input) if self.input else ""
+        )
+        clean_output = (
+            self._build_clean_signature(self.output) if self.output else ""
+        )
+        # Combine the clean input and output signatures using "->"
+        return f"{clean_input} -> {clean_output}"

flock/core/registry/agent_registry.py

@@ -0,0 +1,103 @@
+"""Registry for storing and managing agents and tools."""
+
+from collections.abc import Callable
+
+from flock.core.flock_agent import FlockAgent
+
+
+class Registry:
+    """Registry for storing and managing agents and tools.
+
+    This singleton class maintains a centralized registry of agents and tools,
+    which is particularly important for Temporal workflows where only basic Python
+    types can be passed between activities.
+    """
+
+    _instance = None
+
+    def __new__(cls):
+        """Singleton pattern implementation."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialize()
+        return cls._instance
+
+    def _initialize(self):
+        """Initialize the registry's storage."""
+        self._agents: list[FlockAgent] = []
+        self._tools: list[tuple[str, Callable]] = []
+
+    def register_tool(self, tool_name: str, tool: Callable) -> None:
+        """Register a tool with the registry.
+
+        Args:
+            tool_name: The name to register the tool under
+            tool: The tool function to register
+        """
+        try:
+            self._tools.append((tool_name, tool))
+        except Exception:
+            raise
+
+    def register_agent(self, agent: FlockAgent) -> None:
+        """Register an agent with the registry.
+
+        Args:
+            agent: The agent instance to register
+        """
+        try:
+            self._agents.append(agent)
+        except Exception:
+            raise
+
+    def get_agent(self, name: str) -> FlockAgent | None:
+        """Retrieve an agent by name.
+
+        Args:
+            name: The name of the agent to retrieve
+
+        Returns:
+            The agent instance if found, None otherwise
+        """
+        try:
+            for agent in self._agents:
+                if agent.name == name:
+                    return agent
+            return None
+        except Exception:
+            raise
+
+    def get_tool(self, name: str) -> Callable | None:
+        """Retrieve a tool by name.
+
+        Args:
+            name: The name of the tool to retrieve
+
+        Returns:
+            The tool function if found, None otherwise
+        """
+        try:
+            for tool_name, tool in self._tools:
+                if tool_name == name:
+                    return tool
+            return None
+        except Exception:
+            raise
+
+    def get_tools(self, names: list[str] | None) -> list[Callable]:
+        """Retrieve multiple tools by name.
+
+        Args:
+            names: List of tool names to retrieve
+
+        Returns:
+            List of found tool functions (may be empty if none found)
+        """
+        try:
+            if not names:
+                return []
+
+            tools = [self.get_tool(name) for name in names]
+            return [tool for tool in tools if tool is not None]
+        except Exception:
+            raise