quantalogic 0.51.0__py3-none-any.whl → 0.52.1__py3-none-any.whl

quantalogic/tools/__init__.py

@@ -28,7 +28,7 @@ from .sequence_tool import SequenceTool
 from .serpapi_search_tool import SerpApiSearchTool
 from .sql_query_tool import SQLQueryTool
 from .task_complete_tool import TaskCompleteTool
-from .tool import Tool, ToolArgument
+from .tool import Tool, ToolArgument, create_tool
 from .unified_diff_tool import UnifiedDiffTool
 from .wikipedia_search_tool import WikipediaSearchTool
 from .write_file_tool import WriteFileTool
@@ -65,5 +65,6 @@ __all__ = [
     'ToolArgument',
     'UnifiedDiffTool',
     'WikipediaSearchTool',
-    'WriteFileTool'
+    'WriteFileTool',
+    "create_tool"
 ]

quantalogic/tools/tool.py

@@ -4,11 +4,16 @@ This module provides base classes and data models for creating configurable tool
 with type-validated arguments and execution methods.
 """
 
+import ast
 import asyncio  # Added for asynchronous support
-from typing import Any, Literal
+import inspect
+from typing import Any, Callable, Literal, TypeVar
 
+from docstring_parser import parse as parse_docstring
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+# Type variable for create_tool to preserve function signature
+F = TypeVar('F', bound=Callable[..., Any])
 
 class ToolArgument(BaseModel):
     """Represents an argument for a tool with validation and description.
@@ -204,7 +209,7 @@ class Tool(ToolDefinition):
             ]
         return []
 
-    def execute(self, **kwargs) -> str:
+    def execute(self, **kwargs: Any) -> str:
         """Execute the tool with provided arguments.
 
         If not implemented by a subclass, falls back to the asynchronous execute_async method.
@@ -221,7 +226,7 @@ class Tool(ToolDefinition):
             return asyncio.run(self.async_execute(**kwargs))
         raise NotImplementedError("This method should be implemented by subclasses.")
 
-    async def async_execute(self, **kwargs) -> str:
+    async def async_execute(self, **kwargs: Any) -> str:
         """Asynchronous version of execute.
 
         By default, runs the synchronous execute method in a separate thread using asyncio.to_thread.
@@ -253,6 +258,96 @@ class Tool(ToolDefinition):
         return {name: value for name, value in properties.items() if value is not None and name in argument_names}
 
 
+def create_tool(func: F) -> Tool:
+    """Create a Tool instance from a Python function using AST analysis.
+
+    Analyzes the function's source code to extract its name, docstring, and arguments,
+    then constructs a Tool subclass with appropriate execution logic.
+
+    Args:
+        func: The Python function (sync or async) to convert into a Tool.
+
+    Returns:
+        A Tool subclass instance configured based on the function.
+
+    Raises:
+        ValueError: If the input is not a valid function or lacks a function definition.
+    """
+    if not callable(func):
+        raise ValueError("Input must be a callable function")
+
+    # Get source code and parse with AST
+    try:
+        source = inspect.getsource(func).strip()
+        tree = ast.parse(source)
+    except (OSError, TypeError, SyntaxError) as e:
+        raise ValueError(f"Failed to parse function source: {e}")
+
+    # Ensure root node is a function definition
+    if not tree.body or not isinstance(tree.body[0], (ast.FunctionDef, ast.AsyncFunctionDef)):
+        raise ValueError("Source must define a single function")
+    func_def = tree.body[0]
+
+    # Extract metadata
+    name = func_def.name
+    docstring = ast.get_docstring(func_def) or ""
+    parsed_doc = parse_docstring(docstring)
+    description = parsed_doc.short_description or f"Tool generated from {name}"
+    param_docs = {p.arg_name: p.description for p in parsed_doc.params}
+    is_async = isinstance(func_def, ast.AsyncFunctionDef)
+
+    # Get type hints using typing module
+    from typing import get_type_hints
+    type_hints = get_type_hints(func)
+    type_map = {int: "int", str: "string", float: "float", bool: "boolean"}
+
+    # Process arguments
+    args = func_def.args
+    defaults = [None] * (len(args.args) - len(args.defaults)) + [
+        ast.unparse(d) if isinstance(d, ast.AST) else str(d) for d in args.defaults
+    ]
+    arguments: list[ToolArgument] = []
+
+    for i, arg in enumerate(args.args):
+        arg_name = arg.arg
+        default = defaults[i]
+        required = default is None
+
+        # Determine argument type
+        hint = type_hints.get(arg_name, str)  # Default to str if no hint
+        arg_type = type_map.get(hint, "string")  # Fallback to string for unmapped types
+
+        # Use docstring or default description
+        description = param_docs.get(arg_name, f"Argument {arg_name}")
+
+        # Create ToolArgument
+        arguments.append(ToolArgument(
+            name=arg_name,
+            arg_type=arg_type,
+            description=description,
+            required=required,
+            default=default,
+            example=default if default else None
+        ))
+
+    # Define Tool subclass
+    class GeneratedTool(Tool):
+        def __init__(self, *args: Any, **kwargs: Any):
+            super().__init__(*args, name=name, description=description, arguments=arguments, **kwargs)
+            self._func = func
+
+        if is_async:
+            async def async_execute(self, **kwargs: Any) -> str:
+                result = await self._func(**kwargs)
+                return str(result)
+        else:
+            def execute(self, **kwargs: Any) -> str:
+                result = self._func(**kwargs)
+                return str(result)
+
+    return GeneratedTool()
+
+
 if __name__ == "__main__":
     tool = Tool(name="my_tool", description="A simple tool", arguments=[ToolArgument(name="arg1", arg_type="string")])
     print(tool.to_markdown())
@@ -274,3 +369,34 @@ if __name__ == "__main__":
     )
     print(tool_with_fields_defined.to_markdown())
     print(tool_with_fields_defined.get_injectable_properties_in_execution())
+
+    # Test create_tool with synchronous function
+    def add(a: int, b: int = 0) -> int:
+        """Add two numbers.
+        
+        Args:
+            a: First number.
+            b: Second number (optional).
+        """
+        return a + b
+
+    # Test create_tool with asynchronous function
+    async def greet(name: str) -> str:
+        """Greet a person.
+        
+        Args:
+            name: Name of the person.
+        """
+        await asyncio.sleep(0.1)  # Simulate async work
+        return f"Hello, {name}"
+
+    # Create and test tools
+    sync_tool = create_tool(add)
+    print("\nSynchronous Tool:")
+    print(sync_tool.to_markdown())
+    print("Execution result:", sync_tool.execute(a=5, b=3))
+
+    async_tool = create_tool(greet)
+    print("\nAsynchronous Tool:")
+    print(async_tool.to_markdown())
+    print("Execution result:", asyncio.run(async_tool.async_execute(name="Alice")))

{quantalogic-0.51.0.dist-info → quantalogic-0.52.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: quantalogic
-Version: 0.51.0
+Version: 0.52.1
 Summary: QuantaLogic ReAct Agents
 Author: Raphaël MANSUY
 Author-email: raphael.mansuy@gmail.com
@@ -88,6 +88,8 @@ At [QuantaLogic](https://www.quantalogic.app), we spotted a black hole: amazing
 - [Quick Start](#quick-start)
 - [ReAct Framework: Dynamic Agents](#react-framework-dynamic-agents)
 - [Flow Module: Structured Workflows](#flow-module-structured-workflows)
+  - 📘 **[Workflow YAML DSL Specification](./quantalogic/flow/flow_yaml.md)**: Comprehensive guide to defining powerful, structured workflows using our Domain-Specific Language
+  - 📚 **[Flow YAML Documentation](https://quantalogic.github.io/quantalogic/flow/flow_yaml)**: Dive into the official documentation for a deeper understanding of Flow YAML and its applications
 - [ReAct vs. Flow: Pick Your Power](#react-vs-flow-pick-your-power)
 - [Using the CLI](#using-the-cli)
 - [Examples That Spark Joy](#examples-that-spark-joy)
@@ -357,7 +359,15 @@ Perfect for coding, debugging, or answering wild questions on the fly.
 
 ## Flow Module: Structured Workflows 
 
-The **Flow module** is your architect—building workflows that hum with precision. It’s all about nodes, transitions, and a steady rhythm, ideal for repeatable missions.
+The **Flow module** is your architect—building workflows that hum with precision. It's all about nodes, transitions, and a steady rhythm, ideal for repeatable missions.
+
+🔍 **Want to dive deeper?** Check out our comprehensive [Workflow YAML DSL Specification](./quantalogic/flow/flow_yaml.md), a detailed guide that walks you through defining powerful, structured workflows. From basic node configurations to complex transition logic, this documentation is your roadmap to mastering workflow design with QuantaLogic.
+
+📚 **For a deeper understanding of Flow YAML and its applications, please refer to the official [Flow YAML Documentation](https://quantalogic.github.io/quantalogic/flow/flow_yaml).**
+
+The Flow YAML documentation provides a comprehensive overview of the Flow YAML language, including its syntax, features, and best practices. It's a valuable resource for anyone looking to create complex workflows with QuantaLogic.
+
+Additionally, the Flow YAML documentation includes a number of examples and tutorials to help you get started with creating your own workflows. These examples cover a range of topics, from simple workflows to more complex scenarios, and are designed to help you understand how to use Flow YAML to create powerful and flexible workflows.
 
 ### The Building Blocks
 - **Nodes**: Tasks like functions or LLM calls. 
@@ -629,6 +639,83 @@ mypy quantalogic  # Check types
 ruff check quantalogic  # Lint it
 ```
 
+### Create Custom Tools
+The `create_tool()` function transforms any Python function into a reusable Tool:
+
+```python
+from quantalogic.tools import create_tool
+
+def weather_lookup(city: str, country: str = "US") -> dict:
+    """Retrieve current weather for a given location.
+    
+    Args:
+        city: Name of the city to look up
+        country: Two-letter country code (default: US)
+    
+    Returns:
+        Dictionary with weather information
+    """
+    # Implement weather lookup logic here
+    return {"temperature": 22, "condition": "Sunny"}
+
+# Convert the function to a Tool
+weather_tool = create_tool(weather_lookup)
+
+# Now you can use it as a Tool
+print(weather_tool.to_markdown())  # Generate tool documentation
+result = weather_tool.execute(city="New York")  # Execute as a tool
+```
+
+#### Using Custom Tools with ReAct Agent
+
+Here's how to integrate custom tools with a ReAct Agent:
+
+```python
+from quantalogic import Agent
+from quantalogic.tools import create_tool, PythonTool
+
+# Create a custom stock price lookup tool
+def get_stock_price(symbol: str) -> str:
+    """Get the current price of a stock by its ticker symbol.
+    
+    Args:
+        symbol: Stock ticker symbol (e.g., AAPL, MSFT)
+    
+    Returns:
+        Current stock price information
+    """
+    # In a real implementation, you would fetch from an API
+    prices = {"AAPL": 185.92, "MSFT": 425.27, "GOOGL": 175.43}
+    if symbol in prices:
+        return f"{symbol} is currently trading at ${prices[symbol]}"
+    return f"Could not find price for {symbol}"
+
+# Create an agent with standard and custom tools
+agent = Agent(
+    model_name="gpt-4o",
+    tools=[
+        PythonTool(),  # Standard Python execution tool
+        create_tool(get_stock_price)  # Custom stock price tool
+    ]
+)
+
+# The agent can now use both tools to solve tasks
+result = agent.solve_task(
+    "Write a Python function to calculate investment growth, "  
+    "then analyze Apple stock's current price"
+)
+
+print(result)
+```
+
+In this example, the agent can seamlessly use both the standard `PythonTool` and your custom stock price lookup tool to complete the task.
+
+Key features of `create_tool()`:
+- 🔧 Automatically converts functions to Tools
+- 📝 Extracts metadata from function signature and docstring
+- 🔍 Supports both synchronous and asynchronous functions
+- 🛠️ Generates tool documentation and validation
+
 ---
 
 ## Contributing 

{quantalogic-0.51.0.dist-info → quantalogic-0.52.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
 quantalogic/__init__.py,sha256=BcM0DKB86DijMFtht9YTBdWyzh81zU7E5fhNLFiP260,869
-quantalogic/agent.py,sha256=4XKUVAW4tnNwmdcwWbz9HjWe5CRWeouaC7Xlq-7CSHU,41129
+quantalogic/agent.py,sha256=8Zz0kzFcOVdZSQ2FraoWirk8dWrBCKILNGbF9oPXMpY,41163
 quantalogic/agent_config.py,sha256=fPyMfm77BzimyfyFkTzb2ZdyZtGlr2fq5aTRETu77Vs,8202
 quantalogic/agent_factory.py,sha256=LO0qsFtHxU7lcEi8dn-nDHhkh6Dl8Is6sP_3f1ap_Vg,6251
 quantalogic/coding_agent.py,sha256=A-firiPWQjMC56B329Ne606_v2GsoF5-nxcuz3rVbYM,5496
@@ -9,13 +9,15 @@ quantalogic/console_print_token.py,sha256=5IRVoPhwWZtSc4LpNoAsCQhCB_RnAW9chycGgy
 quantalogic/create_custom_agent.py,sha256=1ZMsbpQGHFueJJpfJIuYCWvR3LUsEtDYqDbr6OcwlWw,20850
 quantalogic/docs_cli.py,sha256=Ie6NwKQuxLKwVQ-cjhFMCttXeiHDjGhNY4hSmMtc0Qg,1664
 quantalogic/event_emitter.py,sha256=e_1r6hvx5GmW84iuRkoqcjpjRiYHBk4hzujd5ZoUC6U,16777
-quantalogic/flow/__init__.py,sha256=asLVwbDH6zVFhILschBOuZZWyKvMGdqhQbB1rd2RXHo,590
+quantalogic/flow/__init__.py,sha256=MD5FAdD6jnVnTPMIOmToKjFxHBQvLmOCT0VeaWhASBc,1295
 quantalogic/flow/flow.py,sha256=P4T6N6IDOHA5OKqoNjLIZ9BQ9Vk8LwhrqcYjz3wjMB8,25297
-quantalogic/flow/flow_extractor.py,sha256=4-q1gBBvSIova7DPTzr4x6e7Dg9SmueowPWqoeDHUwU,29926
-quantalogic/flow/flow_generator.py,sha256=rd-aJMngzJ3Jv8b7rkU6FlLRYPKBYTQ46dqsrzYjQFE,3987
-quantalogic/flow/flow_manager.py,sha256=622rikNGT0AVryWzhiEu15oTyZ8_HqIp_tOl2M6yTjE,20650
-quantalogic/flow/flow_manager_schema.py,sha256=5ytHEh9Qa31yKA4FPRh1lGJYOBGp33ag7crqsJexWG8,7288
-quantalogic/flow/flow_yaml.md,sha256=ZKhKW7Rp5czJWe99MnOHaXLs3U5OsgxUK6K8ezqnSzk,15776
+quantalogic/flow/flow_extractor.py,sha256=tkhisbnEhXXGk996tVU9_QNgB1rAW7z7yKtWxXG_G5Y,26804
+quantalogic/flow/flow_generator.py,sha256=FMEVVXOt3Q6PpTjcA3zO87IGgtvGIWaQEDfEZKMQ_xw,4219
+quantalogic/flow/flow_manager.py,sha256=2-HzQCzNGbrP4aMRCg3c1kvT9KBLfU470G-WhYfKWeo,20976
+quantalogic/flow/flow_manager_schema.py,sha256=07lAiefER0aWEA2tkBkWT7iEX9EOLRwP81m5UMahiQk,7249
+quantalogic/flow/flow_mermaid.py,sha256=iehCtKYP7mrVDjKewD2f_XUzxJK7xfan1ynSpuMrexw,10305
+quantalogic/flow/flow_validator.py,sha256=rawAfus7WMKt9Jfw1OD3qsB1CkCXDHU2cJl_gvSUgPs,15561
+quantalogic/flow/flow_yaml.md,sha256=J779AkqI2cfn0cb2rNmICnSW38RtK5UcpOnn6AAeOMY,15195
 quantalogic/generative_model.py,sha256=os30wdVRq3OsSf8M7TjoaGqJweL99UINQtSGCwoE91k,15913
 quantalogic/get_model_info.py,sha256=RgblwjjP7G97v_AzoGbXxXBIO082jVCRmvRwxnEpW_s,2991
 quantalogic/interactive_text_editor.py,sha256=CzefvRiLscFfOKBS4gmrI10Gn3SF_eS5zbiLVQ9Gugw,16334
@@ -47,7 +49,7 @@ quantalogic/server/templates/index.html,sha256=nDnXJoQEm1vXbhXtgaYk0G5VXj0wwzE6K
 quantalogic/task_file_reader.py,sha256=oPcB4vTxJ__Y8o7VVABIPOkVw3tGDMdQYwdK27PERlE,1440
 quantalogic/task_runner.py,sha256=c2QVGKZfHA0wZIBUvehpjMvtRaKZuhuYQerjIiCC9iY,10053
 quantalogic/tool_manager.py,sha256=vNA7aBKgdU3wpw_goom6i9rg_64pNZapNxvg4cUhhCI,6983
-quantalogic/tools/__init__.py,sha256=tW9Qx2E40OcgNhVBSXTmluSm9tU1rWoZ4EndHZ8uvGw,2242
+quantalogic/tools/__init__.py,sha256=lpfUu6S61dr4WYW4izUkpob7s5NLhkmmR5Zdi9iYrIc,2274
 quantalogic/tools/agent_tool.py,sha256=MXCXxWHRch7VK4UWhtRP1jeI8Np9Ne2CUGo8vm1oZiM,3064
 quantalogic/tools/composio/__init__.py,sha256=Yo9ygNx0qQILVhIfRgqpO8fgnCgp5WoZMd3Hm5D20GY,429
 quantalogic/tools/composio/composio.py,sha256=icVHA_Scr1pViBhahGGBGBRBl9JSB3hGSqpgQzAIUH8,17627
@@ -130,7 +132,7 @@ quantalogic/tools/sequence_tool.py,sha256=Hb2FSjWWACvXZX7rmJXPk5lnnnqaDeRTbhQQRt
 quantalogic/tools/serpapi_search_tool.py,sha256=sX-Noch77kGP2XiwislPNFyy3_4TH6TwMK6C81L3q9Y,5316
 quantalogic/tools/sql_query_tool.py,sha256=jEDZLlxOsB2bzsWlEqsqvTKiyovnRuk0XvgtwW7-WSQ,6055
 quantalogic/tools/task_complete_tool.py,sha256=L8tuyVoN07Q2hOsxx17JTW0C5Jd_N-C0i_0PtCUQUKU,929
-quantalogic/tools/tool.py,sha256=2XlveQf7NVuDlPz-IgE0gURye8rIp9iH3YhWhoOsnog,11232
+quantalogic/tools/tool.py,sha256=FLF4Y1nqjArVUYakD0w3WcDxkRJkbSBQzTG6Sp72Z4Q,15592
 quantalogic/tools/unified_diff_tool.py,sha256=o7OiYnCM5MjbPlQTpB2OmkMQRI9zjdToQmgVkhiTvOI,14148
 quantalogic/tools/utilities/__init__.py,sha256=M54fNYmXlTzG-nTnBVQamxSCuu8X4WzRM4bQQ-NvIC4,606
 quantalogic/tools/utilities/csv_processor_tool.py,sha256=Mu_EPVj6iYAclNaVX_vbkekxcNwPYwy7dW1SCY22EwY,9023
@@ -161,8 +163,8 @@ quantalogic/version_check.py,sha256=JyQFTNMDWtpHCLnN-BiakzB2cyXf6kUFsTjvmSruZi4,
 quantalogic/welcome_message.py,sha256=o4tHdgabNuIV9kbIDPgS3_2yzJhayK30oKad2UouYDc,3020
 quantalogic/xml_parser.py,sha256=AKuMdJC3QAX3Z_tErHVlZ-msjPemWaZUFiTwkHz76jg,11614
 quantalogic/xml_tool_parser.py,sha256=Vz4LEgDbelJynD1siLOVkJ3gLlfHsUk65_gCwbYJyGc,3784
-quantalogic-0.51.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-quantalogic-0.51.0.dist-info/METADATA,sha256=RZgwZd1kGVzEaJQFX-jt821N3p6T32gtyYum_TQ9qCE,24260
-quantalogic-0.51.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-quantalogic-0.51.0.dist-info/entry_points.txt,sha256=h74O_Q3qBRCrDR99qvwB4BpBGzASPUIjCfxHq6Qnups,183
-quantalogic-0.51.0.dist-info/RECORD,,
+quantalogic-0.52.1.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+quantalogic-0.52.1.dist-info/METADATA,sha256=XHeG9nuaPvNZ92KXj83W05hKR-62MKZIs88JiHqtx5E,28120
+quantalogic-0.52.1.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+quantalogic-0.52.1.dist-info/entry_points.txt,sha256=h74O_Q3qBRCrDR99qvwB4BpBGzASPUIjCfxHq6Qnups,183
+quantalogic-0.52.1.dist-info/RECORD,,