fastworkflow 2.15.6__py3-none-any.whl → 2.15.8__py3-none-any.whl

fastworkflow/utils/react.py

@@ -0,0 +1,242 @@
+import logging
+from typing import TYPE_CHECKING, Any, Callable, Literal
+
+from litellm import ContextWindowExceededError
+
+import dspy
+from dspy.adapters.types.tool import Tool
+from dspy.primitives.module import Module
+from dspy.signatures.signature import ensure_signature
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from dspy.signatures.signature import Signature
+
+
+class fastWorkflowReAct(Module):
+    def __init__(self, signature: type["Signature"], tools: list[Callable], max_iters: int = 10):
+        """
+        ReAct stands for "Reasoning and Acting," a popular paradigm for building tool-using agents.
+        In this approach, the language model is iteratively provided with a list of tools and has
+        to reason about the current situation. The model decides whether to call a tool to gather more
+        information or to finish the task based on its reasoning process. The DSPy version of ReAct is
+        generalized to work over any signature, thanks to signature polymorphism.
+
+        Args:
+            signature: The signature of the module, which defines the input and output of the react module.
+            tools (list[Callable]): A list of functions, callable objects, or `dspy.Tool` instances.
+            max_iters (Optional[int]): The maximum number of iterations to run. Defaults to 10.
+
+        Example:
+
+        ```python
+        def get_weather(city: str) -> str:
+            return f"The weather in {city} is sunny."
+
+        react = dspy.ReAct(signature="question->answer", tools=[get_weather])
+        pred = react(question="What is the weather in Tokyo?")
+        ```
+        """
+        super().__init__()
+        self.signature = signature = ensure_signature(signature)
+        self.max_iters = max_iters
+
+        tools = [t if isinstance(t, Tool) else Tool(t) for t in tools]
+        tools = {tool.name: tool for tool in tools}
+
+        inputs = ", ".join([f"`{k}`" for k in signature.input_fields.keys()])
+        outputs = ", ".join([f"`{k}`" for k in signature.output_fields.keys()])
+        instr = [f"{signature.instructions}\n"] if signature.instructions else []
+
+        instr.extend(
+            [
+                f"You are an Agent. In each episode, you will be given the fields {inputs} as input. And you can see your past trajectory so far.",
+                f"Your goal is to use one or more of the supplied tools to collect any necessary information for producing {outputs}.\n",
+                "To do this, you will interleave next_thought, next_tool_name, and next_tool_args in each turn, and also when finishing the task.",
+                "After each tool call, you receive a resulting observation, which gets appended to your trajectory.\n",
+                "When writing next_thought, you may reason about the current situation and plan for future steps.",
+                "When selecting the next_tool_name and its next_tool_args, the tool must be one of:\n",
+            ]
+        )
+
+        tools["finish"] = Tool(
+            func=lambda: "Completed.",
+            name="finish",
+            desc=f"Marks the task as complete. That is, signals that all information for producing the outputs, i.e. {outputs}, are now available to be extracted.",
+            args={},
+        )
+
+        for idx, tool in enumerate(tools.values()):
+            instr.append(f"({idx + 1}) {tool}")
+        instr.append("When providing `next_tool_args`, the value inside the field must be in JSON format")
+
+        react_signature = (
+            dspy.Signature({**signature.input_fields}, "\n".join(instr))
+            .append("trajectory", dspy.InputField(), type_=str)
+            .append("next_thought", dspy.OutputField(), type_=str)
+            .append("next_tool_name", dspy.OutputField(), type_=Literal[tuple(tools.keys())])
+            .append("next_tool_args", dspy.OutputField(), type_=dict[str, Any])
+        )
+
+        fallback_signature = dspy.Signature(
+            {**signature.input_fields, **signature.output_fields},
+            signature.instructions,
+        ).append("trajectory", dspy.InputField(), type_=str)
+
+        self.tools = tools
+        self.react = dspy.Predict(react_signature)
+        self.extract = dspy.ChainOfThought(fallback_signature)
+
+        self.inputs = {}
+        self.current_trajectory = {}
+
+    def _format_trajectory(self, trajectory: dict[str, Any]):
+        adapter = dspy.settings.adapter or dspy.ChatAdapter()
+        trajectory_signature = dspy.Signature(f"{', '.join(trajectory.keys())} -> x")
+        return adapter.format_user_message_content(trajectory_signature, trajectory)
+
+    def forward(self, **input_args):
+        self.inputs = input_args
+
+        trajectory = {}
+        max_iters = input_args.pop("max_iters", self.max_iters)
+        for idx in range(max_iters):
+            try:
+                pred = self._call_with_potential_trajectory_truncation(self.react, trajectory, **input_args)
+            except ValueError as err:
+                logger.warning(f"Ending the trajectory: Agent failed to select a valid tool: {_fmt_exc(err)}")
+                break
+
+            trajectory[f"thought_{idx}"] = pred.next_thought
+            trajectory[f"tool_name_{idx}"] = pred.next_tool_name
+            trajectory[f"tool_args_{idx}"] = pred.next_tool_args
+
+            self.current_trajectory[f"action_{idx}"] = f'{pred.next_tool_name}: {pred.next_tool_args}'
+
+            try:
+                trajectory[f"observation_{idx}"] = self.tools[pred.next_tool_name](**pred.next_tool_args)
+            except Exception as err:
+                trajectory[f"observation_{idx}"] = f"Execution error in {pred.next_tool_name}: {_fmt_exc(err)}"
+
+            if pred.next_tool_name == "finish":
+                break
+
+        extract = self._call_with_potential_trajectory_truncation(self.extract, trajectory, **input_args)
+        return dspy.Prediction(trajectory=trajectory, **extract)
+
+    async def aforward(self, **input_args):
+        trajectory = {}
+        max_iters = input_args.pop("max_iters", self.max_iters)
+        for idx in range(max_iters):
+            try:
+                pred = await self._async_call_with_potential_trajectory_truncation(self.react, trajectory, **input_args)
+            except ValueError as err:
+                logger.warning(f"Ending the trajectory: Agent failed to select a valid tool: {_fmt_exc(err)}")
+                break
+
+            trajectory[f"thought_{idx}"] = pred.next_thought
+            trajectory[f"tool_name_{idx}"] = pred.next_tool_name
+            trajectory[f"tool_args_{idx}"] = pred.next_tool_args
+
+            try:
+                trajectory[f"observation_{idx}"] = await self.tools[pred.next_tool_name].acall(**pred.next_tool_args)
+            except Exception as err:
+                trajectory[f"observation_{idx}"] = f"Execution error in {pred.next_tool_name}: {_fmt_exc(err)}"
+
+            if pred.next_tool_name == "finish":
+                break
+
+        extract = await self._async_call_with_potential_trajectory_truncation(self.extract, trajectory, **input_args)
+        return dspy.Prediction(trajectory=trajectory, **extract)
+
+    def _call_with_potential_trajectory_truncation(self, module, trajectory, **input_args):
+        for _ in range(3):
+            try:
+                return module(
+                    **input_args,
+                    trajectory=self._format_trajectory(trajectory),
+                )
+            except ContextWindowExceededError:
+                logger.warning("Trajectory exceeded the context window, truncating the oldest tool call information.")
+                trajectory = self.truncate_trajectory(trajectory)
+
+    async def _async_call_with_potential_trajectory_truncation(self, module, trajectory, **input_args):
+        for _ in range(3):
+            try:
+                return await module.acall(
+                    **input_args,
+                    trajectory=self._format_trajectory(trajectory),
+                )
+            except ContextWindowExceededError:
+                logger.warning("Trajectory exceeded the context window, truncating the oldest tool call information.")
+                trajectory = self.truncate_trajectory(trajectory)
+
+    def truncate_trajectory(self, trajectory):
+        """Truncates the trajectory so that it fits in the context window.
+
+        Users can override this method to implement their own truncation logic.
+        """
+        keys = list(trajectory.keys())
+        if len(keys) < 4:
+            # Every tool call has 4 keys: thought, tool_name, tool_args, and observation.
+            raise ValueError(
+                "The trajectory is too long so your prompt exceeded the context window, but the trajectory cannot be "
+                "truncated because it only has one tool call."
+            )
+
+        for key in keys[:4]:
+            trajectory.pop(key)
+
+        return trajectory
+
+
+def _fmt_exc(err: BaseException, *, limit: int = 5) -> str:
+    """
+    Return a one-string traceback summary.
+    * `limit` - how many stack frames to keep (from the innermost outwards).
+    """
+
+    import traceback
+
+    return "\n" + "".join(traceback.format_exception(type(err), err, err.__traceback__, limit=limit)).strip()
+
+
+"""
+Thoughts and Planned Improvements for dspy.ReAct.
+
+TOPIC 01: How Trajectories are Formatted, or rather when they are formatted.
+
+Right now, both sub-modules are invoked with a `trajectory` argument, which is a string formatted in `forward`. Though
+the formatter uses a general adapter.format_fields, the tracing of DSPy only sees the string, not the formatting logic.
+
+What this means is that, in demonstrations, even if the user adjusts the adapter for a fixed program, the demos' format
+will not update accordingly, but the inference-time trajectories will.
+
+One way to fix this is to support `format=fn` in the dspy.InputField() for "trajectory" in the signatures. But this
+means that care must be taken that the adapter is accessed at `forward` runtime, not signature definition time.
+
+Another potential fix is to more natively support a "variadic" input field, where the input is a list of dictionaries,
+or a big dictionary, and have each adapter format it accordingly.
+
+Trajectories also affect meta-programming modules that view the trace later. It's inefficient O(n^2) to view the
+trace of every module repeating the prefix.
+
+
+TOPIC 03: Simplifying ReAct's __init__ by moving modular logic to the Tool class.
+    * Handling exceptions and error messages.
+    * More cleanly defining the "finish" tool, perhaps as a runtime-defined function?
+
+
+TOPIC 04: Default behavior when the trajectory gets too long.
+
+
+TOPIC 05: Adding more structure around how the instruction is formatted.
+    * Concretely, it's now a string, so an optimizer can and does rewrite it freely.
+    * An alternative would be to add more structure, such that a certain template is fixed but values are variable?
+
+
+TOPIC 06: Idiomatically allowing tools that maintain state across iterations, but not across different `forward` calls.
+    * So the tool would be newly initialized at the start of each `forward` call, but maintain state across iterations.
+    * This is pretty useful for allowing the agent to keep notes or count certain things, etc.
+"""

fastworkflow/utils/signatures.py

@@ -285,8 +285,24 @@ Today's date is {today}.
                 trainset=trainset
             )
 
+            def basic_checks(args, pred):
+                for field_name in field_names:
+                    # return 0 if it extracts an example value instead of correct value | None
+                    extracted_param_value = getattr(pred, field_name)
+                    examples = model_class.model_fields[field_name].examples
+                    if extracted_param_value in examples:
+                        return 0.0
+                return 1.0
+
+            # Create a refined module that tries up to 3 times
+            best_of_3 = dspy.BestOfN(
+                module=compiled_model, 
+                N=3, 
+                reward_fn=basic_checks, 
+                threshold=1.0)
+
             try:
-                dspy_result = compiled_model(command=self.command)
+                dspy_result = best_of_3(command=self.command)
                 for field_name in field_names:
                     default = model_class.model_fields[field_name].default
                     param_dict[field_name] = getattr(dspy_result, field_name, default)
@@ -428,27 +444,14 @@ Today's date is {today}.
                 if hasattr(type(cmd_parameters).model_fields.get(missing_field), "json_schema_extra") and type(cmd_parameters).model_fields.get(missing_field).json_schema_extra:
                     is_available_from = type(cmd_parameters).model_fields.get(missing_field).json_schema_extra.get("available_from")
                 if is_available_from:
-                    message += f"abort and use the {' or '.join(is_available_from)} command(s) to get {missing_field} information. OR...\n"
+                    msg_prefix = "abort and "
+                    if "run_as_agent" in app_workflow.context:
+                        msg_prefix = ""
+                    message += f"{msg_prefix}use the {' or '.join(is_available_from)} command(s) to get {missing_field} information. OR...\n"
 
         if invalid_fields:
             message += f"{INVALID_INFORMATION_ERRMSG}" + ", ".join(invalid_fields) + "\n"
 
-        with suppress(Exception):
-            graph_path = os.path.join(app_workflow.folderpath, "command_dependency_graph.json")
-            suggestions_texts: list[str] = []
-            for field in missing_fields:
-                plans = get_dependency_suggestions(graph_path, subject_command_name, field, min_weight=0.7, max_depth=3)
-                if plans:
-                    # Format a concise plan: main command and any immediate sub-steps
-                    top = plans[0]
-                    def format_plan(p):
-                        if not p.get('sub_plans'):
-                            return p['command']
-                        return p['command'] + " -> " + " -> ".join(sp['command'] for sp in p['sub_plans'])
-                    suggestions_texts.append(f"To get '{field}', try: {format_plan(top)}")
-            if suggestions_texts:
-                message += "\n" + "\n".join(suggestions_texts) + "\n"
-
         for field, suggestions in all_suggestions.items():
             if suggestions:
                 is_format_instruction = any(("format" in str(s).lower() or "pattern" in str(s).lower()) for s in suggestions)
@@ -468,6 +471,7 @@ Today's date is {today}.
         if combined_fields:
             combined_fields_str = ", ".join(combined_fields)
             message += f"\nProvide corrected parameter values in the exact order specified below, separated by commas:\n{combined_fields_str}"
-            message += "\nFor parameter values that include a comma, provide separately from other values, and one at a time."
+            if "run_as_agent" not in app_workflow.context:
+                message += "\nFor parameter values that include a comma, provide separately from other values, and one at a time."
 
         return (False, message, all_suggestions)