Merge pull request #414 from SylphAI-Inc/release_1.05a1

Release for version 1.05a1

Author: phi-jkim

adalflow/adalflow/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.0.4"
+__version__ = "1.0.5a1"
 
 from adalflow.core.component import (
     Component,

adalflow/adalflow/core/agent.py

@@ -244,21 +244,29 @@ def create_default_planner(
 
 
 class Agent(Component):
-    """
-    An agent is a high-level component that holds (1) a generator as task plannaer (calling tools) and (2) a tool manager to manage tools.
+    """A high-level agentic component that orchestrates AI planning and tool execution.
+
+    The Agent combines a Generator-based planner for task decomposition with a ToolManager
+    for function calling. It uses a ReAct (Reasoning and Acting) architecture to iteratively
+    plan steps and execute tools to solve complex tasks.
 
-    It comes with default prompt template that instructs LLM (1) agentic task description (2) template on adding definitions of tools
-    (3) arguments to fill in history.
+    The Agent comes with default prompt templates for agentic reasoning, automatic tool
+    definition integration, and step history tracking. It includes built-in helper tools:
+    - finish: Terminates execution with the final answer
+    - llm_tool: Fallback tool using LLM world knowledge for simple queries
 
-    Additionally, it comes with two helper tools:
-    1. finish: to finish the task
-    2. additional_llm_tool: to answer any input query with llm's world knowledge. Use me as a fallback tool or when the query is simple.
+    Architecture:
+        Agent contains two main components:
+        1. Planner (Generator): Plans and reasons about next actions using an LLM
+        2. ToolManager: Manages and executes available tools/functions
 
     Attributes:
-        name (str): Name of the agent
-        tool_manager (ToolManager): Stores and manages tools
-        generator (Generator): Handles text generation with a language model
-        the output_processors must return the type StepOutput
+        name (str): Unique identifier for the agent instance
+        tool_manager (ToolManager): Manages available tools and their execution
+        planner (Generator): LLM-based planner for task decomposition and reasoning
+        answer_data_type (Type): Expected type for the final answer output
+        max_steps (int): Maximum number of planning steps allowed
+        is_thinking_model (bool): Whether the underlying model supports chain-of-thought
     """
 
     def __init__(

adalflow/adalflow/core/generator.py

@@ -496,8 +496,8 @@ def _model_client_call(self, api_kwargs: Dict, use_cache: bool = False) -> Any:
             completion = self.model_client.call(
                 api_kwargs=api_kwargs, model_type=self.model_type
             )
-            # prepare cache
-            if use_cache:
+            # prepare cache - skip caching for streaming responses which contain unpickleable threading objects
+            if use_cache and not api_kwargs.get("stream", False):
                 self._save_cache(index_content, completion)
             return completion
         except Exception as e:
@@ -521,8 +521,8 @@ async def _async_model_client_call(
             completion = await self.model_client.acall(
                 api_kwargs=api_kwargs, model_type=self.model_type
             )
-            # save to cache
-            if use_cache:
+            # save to cache - skip caching for streaming responses which contain unpickleable threading objects
+            if use_cache and not api_kwargs.get("stream", False):
                 self._save_cache(index_content, completion)
             return completion
         except Exception as e:

adalflow/adalflow/core/runner.py

@@ -62,19 +62,32 @@
 
 
 class Runner(Component):
-    """A runner class that executes an Agent instance with multi-step execution.
-
-    It internally maintains a planner LLM and an executor and adds a LLM call to the executor as a tool for the planner.
-
-    The output to the planner agent  call is expected to be a Function object. The planner iterates through at most
-    max_steps unless the planner sets the action to "finish" then the planner returns the final response.
-
-    If the user optionally specifies the output_type then the Runner parses the Function object to the output_type.
+    """Executes Agent instances with multi-step iterative planning and tool execution.
+
+    The Runner orchestrates the execution of an Agent through multiple reasoning and action
+    cycles. It manages the step-by-step execution loop where the Agent's planner generates
+    Function calls that get executed by the ToolManager, with results fed back into the
+    planning context for the next iteration.
+
+    Execution Flow:
+        1. Initialize step history and prompt context
+        2. For each step (up to max_steps):
+           a. Call Agent's planner to get next Function
+           b. Execute the Function using ToolManager
+           c. Add step result to history
+           d. Check if Function is "finish" to terminate
+        3. Process final answer to expected output type
+
+    The Runner supports both synchronous and asynchronous execution modes, as well as
+    streaming execution with real-time event emission. It includes comprehensive tracing
+    and error handling throughout the execution pipeline.
 
     Attributes:
-        planner (Agent): The agent instance to execute
-        config (RunnerConfig): Configuration for the runner
-        max_steps (int): Maximum number of steps to execute
+        agent (Agent): The Agent instance to execute
+        max_steps (int): Maximum number of execution steps allowed
+        answer_data_type (Type): Expected type for final answer processing
+        step_history (List[StepOutput]): History of all execution steps
+        ctx (Optional[Dict]): Additional context passed to tools
     """
 
     def __init__(

adalflow/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "adalflow"
-version = "1.0.4"
+version = "1.0.5a1"
 description = "The Library to Build and Auto-optimize LLM Applications"
 authors = ["Li Yin <li@sylphai.com>"]
 readme = "README.md"

tutorials/v1_agent_runner/agent_runner.py

@@ -722,14 +722,14 @@ def run_example(example_name: str, example_func, *args, **kwargs):
     # Define all examples to run
     examples = [
         ("Synchronous ReAct Agent", run_react_agent_example),
-        # ("Primitive Type ReAct Agent", run_react_agent_primitive_type),
-        # ("Async ReAct Agent", lambda: asyncio.run(arun_react_agent_example())),
-        # ("Advanced ReAct Agent", run_advanced_react_agent),
+        ("Primitive Type ReAct Agent", run_react_agent_primitive_type),
+        ("Async ReAct Agent", lambda: asyncio.run(arun_react_agent_example())),
+        ("Advanced ReAct Agent", run_advanced_react_agent),
         (
             "Advanced Async ReAct Agent",
             lambda: asyncio.run(arun_advanced_react_agent()),
         ),
-        # ("No Structured Output Agent", no_structured_output_run_agent),
+        ("No Structured Output Agent", no_structured_output_run_agent),
         ("Pydantic Dataclass Agent", pydantic_dataclass_run_agent),
     ]
 

tutorials/v1_agent_runner/anthropic_streaming_tutorial.py

@@ -33,11 +33,14 @@
 from adalflow.core.base_data_class import DataClass
 from dataclasses import dataclass
 
-from adalflow.utils.lazy_import import setup_env
+from adalflow.utils import setup_env
 
 # Direct Anthropic API imports
 import anthropic
 
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
 
 setup_env()  # Comment out to prevent FileNotFoundError when .env doesn't exist
 
@@ -812,9 +815,8 @@ async def test_streaming():
                 print(f"   Event: {type(event).__name__}")
                 print(f"   Event content: {event}")
 
-            await streaming_result.wait_for_completion()
             print(f"   ✓ Final completion status: {streaming_result.is_complete}")
-            print(f"   ✓ Final result type: {type(streaming_result.final_result)}")
+            print(f"   ✓ Final answer type: {type(streaming_result.answer)}")
 
         asyncio.run(test_streaming())
 
@@ -851,11 +853,12 @@ async def test_streaming():
         )
 
         async def test_data_class_streaming():
-            # Wait for completion
-            await streaming_result.wait_for_completion()
+            # Consume stream events to completion
+            async for event in streaming_result.stream_events():
+                pass  # Process events if needed
 
             assert streaming_result.is_complete, "Should be complete"
-            assert streaming_result.final_result is not None, "Should have final result"
+            assert streaming_result.answer is not None, "Should have final answer"
 
             print("   ✓ Streaming completed")
             print("   ✓ Final result available")
@@ -1003,14 +1006,14 @@ async def test_complete_workflow():
                 print(f"   Event: {type(event).__name__}")
                 print(f"   Event content: {event}")
 
-            # Verify completion
+            # Verify completion - stream_events() automatically handles completion
             assert streaming_result.is_complete, "Workflow should be complete"
-            assert streaming_result.final_result is not None, "Should have final result"
+            assert streaming_result.answer is not None, "Should have final answer"
             assert len(events_received) > 0, "Should receive events"
 
             print(f"   ✓ Received {len(events_received)} events")
             print("   ✓ Workflow completed successfully")
-            print(f"   ✓ Final answer: {streaming_result.final_result.answer}")
+            print(f"   ✓ Final answer: {streaming_result.answer}")
 
         asyncio.run(test_complete_workflow())
 
@@ -1042,11 +1045,16 @@ async def test_error_handling():
             try:
                 async for event in streaming_result.stream_events():
                     pass
-                # If we get here, check if error was captured
-                if streaming_result.final_result and hasattr(
-                    streaming_result.final_result, "error"
+                # Check if error was captured - stream_events() handles completion
+                if (
+                    hasattr(streaming_result, "_exception")
+                    and streaming_result._exception
                 ):
-                    print("   ✓ Error properly captured in final result")
+                    print(
+                        f"   ✓ Error captured in streaming result: {streaming_result._exception}"
+                    )
+                elif streaming_result.answer is None:
+                    print("   ✓ No answer found, likely failed as expected")
                 else:
                     print("   ⚠ No error found, might have succeeded unexpectedly")
             except Exception as e:
@@ -1096,20 +1104,21 @@ async def compare_async_methods():
 
             astream_result = runner.astream(prompt_kwargs={"input_str": "Add 2 and 3"})
 
-            await astream_result.wait_for_completion()
+            # Consume stream events to completion
+            async for event in astream_result.stream_events():
+                print("THIS IS THE EVENT", event)
+                pass  # Process events if needed
 
             print("\nAsync Compare Agent Final Results:\n")
             print(f"acall result: {acall_result}")
-            print(f"astream result: {astream_result.final_result}")
+            print(f"astream result: {astream_result.answer}")
 
             # Both should complete successfully
             assert hasattr(acall_result, "answer"), "acall should have answer"
-            assert (
-                astream_result.final_result is not None
-            ), "astream should have final result"
+            assert astream_result.answer is not None, "astream should have final answer"
 
             print(f"   ✓ acall result type: {type(acall_result)}")
-            print(f"   ✓ astream result type: {type(astream_result.final_result)}")
+            print(f"   ✓ astream result answer type: {type(astream_result.answer)}")
 
         asyncio.run(compare_async_methods())