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

flock/core/mixin/dspy_integration.py

@@ -0,0 +1,197 @@
+"""Mixin class for integrating with the dspy library."""
+
+import sys
+from typing import Any, Literal
+
+from flock.core.logging.logging import get_logger
+from flock.core.util.input_resolver import split_top_level
+
+logger = get_logger("flock")
+
+AgentType = (
+    Literal["ReAct"] | Literal["Completion"] | Literal["ChainOfThought"] | None
+)
+
+
+class DSPyIntegrationMixin:
+    """Mixin class for integrating with the dspy library."""
+
+    def create_dspy_signature_class(
+        self, agent_name, description_spec, fields_spec
+    ) -> Any:
+        """Trying to create a dynamic class using dspy library."""
+        # ---------------------------
+        # 1. Parse the class specification.
+        # ---------------------------
+        import dspy
+
+        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:
+        import dspy
+
+        """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: Any,
+        agent_type_override: AgentType,
+    ) -> 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).
+        """
+        import dspy
+
+        dspy_solver = None
+
+        if agent_type_override:
+            if agent_type_override == "ChainOfThought":
+                dspy_solver = dspy.ChainOfThought(
+                    signature,
+                )
+            if agent_type_override == "ReAct":
+                dspy.ReAct(
+                    signature,
+                    tools=self.tools,
+                    max_iters=10,
+                )
+            if agent_type_override == "Completion":
+                dspy_solver = dspy.Predict(
+                    signature,
+                )
+        else:
+            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,118 @@
+"""Registry for storing and managing agents and tools with logging and tracing integration."""
+
+from collections.abc import Callable
+
+from opentelemetry import trace
+
+from flock.core.flock_agent import FlockAgent
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("registry")
+tracer = trace.get_tracer(__name__)
+
+
+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):
+        with tracer.start_as_current_span("Registry.__new__") as span:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+                cls._instance._initialize()
+                logger.info("Registry instance created")
+                span.set_attribute("instance.created", True)
+            return cls._instance
+
+    def _initialize(self):
+        with tracer.start_as_current_span("Registry._initialize"):
+            self._agents: list[FlockAgent] = []
+            self._tools: list[tuple[str, Callable]] = []
+            logger.info("Registry initialized", agents_count=0, tools_count=0)
+
+    def register_tool(self, tool_name: str, tool: Callable) -> None:
+        with tracer.start_as_current_span("Registry.register_tool") as span:
+            span.set_attribute("tool_name", tool_name)
+            try:
+                self._tools.append((tool_name, tool))
+                logger.info("Tool registered", tool_name=tool_name)
+            except Exception as e:
+                logger.error(
+                    "Error registering tool", tool_name=tool_name, error=str(e)
+                )
+                span.record_exception(e)
+                raise
+
+    def register_agent(self, agent: FlockAgent) -> None:
+        with tracer.start_as_current_span("Registry.register_agent") as span:
+            span.set_attribute("agent_name", agent.name)
+            try:
+                self._agents.append(agent)
+                logger.info("Agent registered", agent=agent.name)
+            except Exception as e:
+                logger.error(
+                    "Error registering agent", agent=agent.name, error=str(e)
+                )
+                span.record_exception(e)
+                raise
+
+    def get_agent(self, name: str) -> FlockAgent | None:
+        with tracer.start_as_current_span("Registry.get_agent") as span:
+            span.set_attribute("search_agent_name", name)
+            try:
+                for agent in self._agents:
+                    if agent.name == name:
+                        logger.info("Agent found", agent=name)
+                        span.set_attribute("found", True)
+                        return agent
+                logger.warning("Agent not found", agent=name)
+                span.set_attribute("found", False)
+                return None
+            except Exception as e:
+                logger.error("Error retrieving agent", agent=name, error=str(e))
+                span.record_exception(e)
+                raise
+
+    def get_tool(self, name: str) -> Callable | None:
+        with tracer.start_as_current_span("Registry.get_tool") as span:
+            span.set_attribute("search_tool_name", name)
+            try:
+                for tool_name, tool in self._tools:
+                    if tool_name == name:
+                        logger.info("Tool found", tool=name)
+                        span.set_attribute("found", True)
+                        return tool
+                logger.warning("Tool not found", tool=name)
+                span.set_attribute("found", False)
+                return None
+            except Exception as e:
+                logger.error("Error retrieving tool", tool=name, error=str(e))
+                span.record_exception(e)
+                raise
+
+    def get_tools(self, names: list[str] | None) -> list[Callable]:
+        with tracer.start_as_current_span("Registry.get_tools") as span:
+            span.set_attribute("search_tool_names", str(names))
+            try:
+                if not names:
+                    logger.info("No tool names provided")
+                    return []
+                tools = [self.get_tool(name) for name in names]
+                found_tools = [tool for tool in tools if tool is not None]
+                logger.info(
+                    "Tools retrieved", requested=names, found=len(found_tools)
+                )
+                span.set_attribute("found_tools_count", len(found_tools))
+                return found_tools
+            except Exception as e:
+                logger.error(
+                    "Error retrieving tools", names=str(names), error=str(e)
+                )
+                span.record_exception(e)
+                raise