quantalogic 0.59.3__py3-none-any.whl → 0.61.0__py3-none-any.whl

quantalogic/tools/tool.py

@@ -38,7 +38,6 @@ class ToolArgument(BaseModel):
     )
     example: str | None = Field(default=None, description="An example value to illustrate the argument's usage.")
 
-
 class ToolDefinition(BaseModel):
     """Base class for defining tool configurations without execution logic.
 
@@ -46,6 +45,7 @@ class ToolDefinition(BaseModel):
         name: Unique name of the tool.
         description: Brief description of the tool's functionality.
         arguments: List of arguments the tool accepts.
+        return_type: The return type of the tool's execution method. Defaults to "str".
         need_validation: Flag to indicate if tool requires validation.
     """
 
@@ -54,10 +54,15 @@ class ToolDefinition(BaseModel):
     name: str = Field(..., description="The unique name of the tool.")
     description: str = Field(..., description="A brief description of what the tool does.")
     arguments: list[ToolArgument] = Field(default_factory=list, description="A list of arguments the tool accepts.")
+    return_type: str = Field(default="str", description="The return type of the tool's execution method.")
     need_validation: bool = Field(
         default=False,
         description="When True, requires user confirmation before execution. Useful for tools that perform potentially destructive operations.",
     )
+    need_post_process: bool = Field(
+        default=True,
+        description="When True, requires user confirmation before execution. Useful for tools that perform potentially destructive operations.",
+    )
     need_variables: bool = Field(
         default=False,
         description="When True, provides access to the agent's variable store. Required for tools that need to interpolate variables (e.g., Jinja templates).",
@@ -81,6 +86,7 @@ class ToolDefinition(BaseModel):
             "name",
             "description",
             "arguments",
+            "return_type",
             "need_validation",
             "need_variables",
             "need_caller_context_memory",
@@ -119,10 +125,6 @@ class ToolDefinition(BaseModel):
             parameters = ""
             for arg in self.arguments:
                 # Skip if parameter name matches an object property with non-None value
-                # This enables automatic property injection during execution:
-                # When an object has a property matching an argument name,
-                # the agent will inject the property value at runtime,
-                # reducing manual input and improving flexibility
                 if properties_injectable.get(arg.name) is not None:
                     continue
 
@@ -180,6 +182,58 @@ class ToolDefinition(BaseModel):
         # For ToolDefinition, it returns an empty dict since it has no execution context yet
         return {}
 
+    def to_docstring(self) -> str:
+        """Convert the tool definition into a Google-style docstring with function signature.
+
+        Returns:
+            A string formatted as a valid Python docstring representing the tool's configuration,
+            including the function signature and return type.
+        """
+        # Construct the function signature
+        signature_parts = []
+        for arg in self.arguments:
+            # Base argument: name and type
+            arg_str = f"{arg.name}: {arg.arg_type}"
+            # Add default value if present
+            if arg.default is not None:
+                arg_str += f" = {arg.default}"
+            signature_parts.append(arg_str)
+        signature = f"def {self.name}({', '.join(signature_parts)}) -> {self.return_type}:"
+
+        # Start with the signature and description
+        docstring = f'"""\n{signature}\n\n{self.description}\n\n'
+        
+        # Add Arguments section if there are any
+        if self.arguments:
+            docstring += "Args:\n"
+            for arg in self.arguments:
+                # Base argument line: name and type
+                arg_line = f"    {arg.name} ({arg.arg_type})"
+                
+                # Add optional/required status and default/example if present
+                details = []
+                if not arg.required:
+                    details.append("optional")
+                if arg.default is not None:
+                    details.append(f"defaults to {arg.default}")
+                if arg.example is not None:
+                    details.append(f"e.g., {arg.example}")
+                if details:
+                    arg_line += f" [{', '.join(details)}]"
+                
+                # Add description if present
+                if arg.description:
+                    arg_line += f": {arg.description}"
+                
+                docstring += f"{arg_line}\n"
+        
+        # Add Returns section
+        docstring += f"Returns:\n    {self.return_type}: The result of the tool execution.\n"
+        
+        # Close the docstring
+        docstring += '"""'
+        
+        return docstring
 
 class Tool(ToolDefinition):
     """Extended class for tools with execution capabilities.
@@ -257,7 +311,6 @@ class Tool(ToolDefinition):
         properties = self.get_properties(exclude=["arguments"])
         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.
 
@@ -330,10 +383,14 @@ def create_tool(func: F) -> Tool:
             example=default if default else None
         ))
 
+    # Determine return type from type hints
+    return_type = type_hints.get("return", str)
+    return_type_str = type_map.get(return_type, "string")
+
     # Define Tool subclass
     class GeneratedTool(Tool):
         def __init__(self, *args: Any, **kwargs: Any):
-            super().__init__(*args, name=name, description=description, arguments=arguments, **kwargs)
+            super().__init__(*args, name=name, description=description, arguments=arguments, return_type=return_type_str, **kwargs)
             self._func = func
 
         if is_async:
@@ -347,28 +404,48 @@ def create_tool(func: F) -> Tool:
 
     return GeneratedTool()
 
-
 if __name__ == "__main__":
-    tool = Tool(name="my_tool", description="A simple tool", arguments=[ToolArgument(name="arg1", arg_type="string")])
+    # Basic tool with argument
+    tool = Tool(
+        name="my_tool",
+        description="A simple tool",
+        arguments=[ToolArgument(name="arg1", arg_type="string")]
+    )
+    print("Basic Tool Markdown:")
     print(tool.to_markdown())
+    print("Basic Tool Docstring:")
+    print(tool.to_docstring())
+    print()
 
+    # Tool with injectable field (undefined)
     class MyTool(Tool):
         field1: str | None = Field(default=None, description="Field 1 description")
 
     tool_with_fields = MyTool(
-        name="my_tool1", description="A simple tool", arguments=[ToolArgument(name="field1", arg_type="string")]
+        name="my_tool1",
+        description="A simple tool with a field",
+        arguments=[ToolArgument(name="field1", arg_type="string")]
     )
+    print("Tool with Undefined Field Markdown:")
     print(tool_with_fields.to_markdown())
-    print(tool_with_fields.get_injectable_properties_in_execution())
+    print("Injectable Properties (should be empty):", tool_with_fields.get_injectable_properties_in_execution())
+    print("Tool with Undefined Field Docstring:")
+    print(tool_with_fields.to_docstring())
+    print()
 
+    # Tool with defined injectable field
     tool_with_fields_defined = MyTool(
         name="my_tool2",
-        description="A simple tool2",
+        description="A simple tool with a defined field",
         field1="field1_value",
-        arguments=[ToolArgument(name="field1", arg_type="string")],
+        arguments=[ToolArgument(name="field1", arg_type="string")]
     )
+    print("Tool with Defined Field Markdown:")
     print(tool_with_fields_defined.to_markdown())
-    print(tool_with_fields_defined.get_injectable_properties_in_execution())
+    print("Injectable Properties (should include field1):", tool_with_fields_defined.get_injectable_properties_in_execution())
+    print("Tool with Defined Field Docstring:")
+    print(tool_with_fields_defined.to_docstring())
+    print()
 
     # Test create_tool with synchronous function
     def add(a: int, b: int = 0) -> int:
@@ -380,6 +457,14 @@ if __name__ == "__main__":
         """
         return a + b
 
+    sync_tool = create_tool(add)
+    print("Synchronous Tool Markdown:")
+    print(sync_tool.to_markdown())
+    print("Synchronous Tool Docstring:")
+    print(sync_tool.to_docstring())
+    print("Execution result:", sync_tool.execute(a=5, b=3))
+    print()
+
     # Test create_tool with asynchronous function
     async def greet(name: str) -> str:
         """Greet a person.
@@ -390,13 +475,26 @@ if __name__ == "__main__":
         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("Asynchronous Tool Markdown:")
     print(async_tool.to_markdown())
-    print("Execution result:", asyncio.run(async_tool.async_execute(name="Alice")))
+    print("Asynchronous Tool Docstring:")
+    print(async_tool.to_docstring())
+    print("Execution result:", asyncio.run(async_tool.async_execute(name="Alice")))
+    print()
+
+    # Comprehensive tool for to_docstring demonstration with custom return type
+    docstring_tool = Tool(
+        name="sample_tool",
+        description="A sample tool for testing docstring generation.",
+        arguments=[
+            ToolArgument(name="x", arg_type="int", description="The first number", required=True),
+            ToolArgument(name="y", arg_type="float", description="The second number", default="0.0", example="1.5"),
+            ToolArgument(name="verbose", arg_type="boolean", description="Print extra info", default="False")
+        ],
+        return_type="int"  # Custom return type
+    )
+    print("Comprehensive Tool Markdown:")
+    print(docstring_tool.to_markdown())
+    print("Comprehensive Tool Docstring with Custom Return Type:")
+    print(docstring_tool.to_docstring())

quantalogic/tools/utilities/__init__.py

@@ -11,6 +11,7 @@ from .csv_processor_tool import CSVProcessorTool
 from .download_file_tool import PrepareDownloadTool
 from .mermaid_validator_tool import MermaidValidatorTool
 from .vscode_tool import VSCodeServerTool
+from .llm_tool import OrientedLLMTool
 
 # Define __all__ to control what is imported with `from ... import *`
 __all__ = [
@@ -18,6 +19,7 @@ __all__ = [
     'PrepareDownloadTool',
     'MermaidValidatorTool',
     'VSCodeServerTool',
+    'OrientedLLMTool',
 ]
 
 # Optional: Add logging for import confirmation

quantalogic/tools/utilities/download_file_tool.py

@@ -20,7 +20,7 @@ class PrepareDownloadTool(Tool):
         "If it's a directory, it will be zipped. "
         "Returns an HTML link for downloading."
     )
-    need_validation: bool = True
+    need_validation: bool = False
     arguments: list = [
         ToolArgument(
             name="path",
@@ -106,10 +106,8 @@ class PrepareDownloadTool(Tool):
         )
         
         # Create the HTML link with embedded styles
-        html = f'''<a href="{url}" 
-            style="{style}" 
-            onmouseover="this.style.backgroundColor='#0066cc'; this.style.color='white';" 
-            onmouseout="this.style.backgroundColor='transparent'; this.style.color='#0066cc';" 
+        html = f'''Using this download functionnal download link : <a href="{url}" 
+            style="{style}"  
             download="{filename}">{text}</a>'''
             
         return html

quantalogic/tools/utilities/llm_tool.py

@@ -0,0 +1,283 @@
+"""Legal-oriented LLM Tool for generating answers using retrieved legal context."""
+
+import asyncio
+from typing import Callable, Dict, List, Optional, Union
+
+from loguru import logger
+from pydantic import ConfigDict, Field
+
+from quantalogic.console_print_token import console_print_token
+from quantalogic.event_emitter import EventEmitter
+from quantalogic.generative_model import GenerativeModel, Message
+from quantalogic.tools.tool import Tool, ToolArgument
+
+
+class OrientedLLMTool(Tool):
+    """Advanced LLM tool specialized for legal analysis and response generation."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
+
+    name: str = Field(default="legal_llm_tool")
+    description: str = Field(
+        default=(
+            "A specialized legal language model tool that generates expert legal analysis and responses. "
+            "Features:\n"
+            "- Legal expertise: Specialized in legal analysis and interpretation\n"
+            "- Context integration: Utilizes retrieved legal documents and precedents\n"
+            "- Multi-jurisdictional: Handles multiple legal systems and languages\n"
+            "- Citation support: Properly cites legal sources and precedents\n"
+            "\nCapabilities:\n"
+            "- Legal document analysis\n"
+            "- Statutory interpretation\n"
+            "- Case law analysis\n"
+            "- Regulatory compliance guidance"
+        )
+    )
+    arguments: list = Field(
+        default=[
+            ToolArgument(
+                name="role",
+                arg_type="string",
+                description="Legal specialization (e.g., 'commercial_law', 'environmental_law', 'constitutional_law')",
+                required=True,
+                default="general_legal_expert",
+            ),
+            ToolArgument(
+                name="legal_context",
+                arg_type="string",
+                description="Retrieved legal documents, precedents, and relevant context from RAG tool",
+                required=True,
+            ),
+            ToolArgument(
+                name="jurisdiction",
+                arg_type="string",
+                description="Relevant legal jurisdiction(s) for analysis",
+                required=True,
+                default="general",
+            ),
+            ToolArgument(
+                name="query_type",
+                arg_type="string",
+                description="Type of legal analysis needed (e.g., 'interpretation', 'compliance', 'comparison')",
+                required=True,
+                default="interpretation",
+            ),
+            ToolArgument(
+                name="prompt",
+                arg_type="string",
+                description="Specific legal question or analysis request",
+                required=True,
+            ),
+            ToolArgument(
+                name="temperature",
+                arg_type="float",
+                description="Response precision (0.0 for strict legal interpretation, 1.0 for creative analysis)",
+                required=False,
+                default="0.3",
+            ),
+        ]
+    )
+
+    model_name: str = Field(..., description="The name of the language model to use")
+    role: str = Field(default="general_legal_expert", description="The specific role or persona for the LLM")
+    jurisdiction: str = Field(default="general", description="The relevant jurisdiction for the LLM")
+    on_token: Callable | None = Field(default=None, exclude=True)
+    generative_model: GenerativeModel | None = Field(default=None, exclude=True)
+    event_emitter: EventEmitter | None = Field(default=None, exclude=True)
+
+    def __init__(
+        self,
+        model_name: str,
+        name: str = "legal_llm_tool",
+        role: str = "general_legal_expert",
+        jurisdiction: str = "general",
+        on_token: Optional[Callable] = None,
+        event_emitter: Optional[EventEmitter] = None,
+    ):
+        """Initialize the Legal LLM Tool.
+
+        Args:
+            model_name: Name of the language model
+            role: Legal specialization role
+            jurisdiction: Default jurisdiction
+            on_token: Optional callback for token streaming
+            event_emitter: Optional event emitter for streaming
+        """
+        super().__init__(
+            model_name=model_name,
+            name=name,
+            role=role,
+            jurisdiction=jurisdiction,
+            on_token=on_token,
+            event_emitter=event_emitter,
+        )
+        
+        self.model_name = model_name
+        self.role = role
+        self.jurisdiction = jurisdiction
+        self.on_token = on_token
+        self.event_emitter = event_emitter
+        self.generative_model = None
+        
+        # Initialize the model
+        self.model_post_init(None)
+
+    def model_post_init(self, __context):
+        """Initialize the generative model with legal-specific configuration."""
+        if self.generative_model is None:
+            self.generative_model = GenerativeModel(
+                model=self.model_name,
+                event_emitter=self.event_emitter
+            )
+            logger.debug(f"Initialized Legal LLM Tool with model: {self.model_name}")
+
+        if self.on_token is not None:
+            self.generative_model.event_emitter.on("stream_chunk", self.on_token)
+
+    def _build_legal_system_prompt(
+        self,
+        role: str,
+        jurisdiction: str,
+        query_type: str,
+        legal_context: Union[str, Dict, List]
+    ) -> str:
+        """Build a specialized legal system prompt.
+
+        Args:
+            role: Legal specialization role
+            jurisdiction: Relevant jurisdiction
+            query_type: Type of legal analysis
+            legal_context: Retrieved legal context from RAG
+
+        Returns:
+            Structured system prompt for legal analysis
+        """
+        # Format legal context if it's not a string
+        if not isinstance(legal_context, str):
+            legal_context = str(legal_context)
+
+        system_prompt = f"""You are an expert legal advisor specialized in {role}.
+Jurisdiction: {jurisdiction}
+Analysis Type: {query_type}
+
+Your task is to provide a well-reasoned legal analysis based on the following context:
+
+{legal_context}
+
+Guidelines:
+1. Base your analysis strictly on provided legal sources
+2. Cite specific articles, sections, and precedents
+3. Consider jurisdictional context and limitations
+4. Highlight any legal uncertainties or ambiguities
+5. Provide clear, actionable conclusions
+
+Format your response as follows:
+1. Legal Analysis
+2. Relevant Citations
+3. Key Considerations
+4. Conclusion
+
+Remember: If a legal point is not supported by the provided context, acknowledge the limitation."""
+
+        return system_prompt
+
+    async def async_execute(
+        self,
+        prompt: str,
+        legal_context: Union[str, Dict, List],
+        role: Optional[str] = None,
+        jurisdiction: Optional[str] = None,
+        query_type: str = "interpretation",
+        temperature: float = 0.3
+    ) -> str:
+        """Execute legal analysis asynchronously.
+
+        Args:
+            prompt: Legal question or analysis request
+            legal_context: Retrieved legal documents and context
+            role: Optional override for legal specialization
+            jurisdiction: Optional override for jurisdiction
+            query_type: Type of legal analysis needed
+            temperature: Response precision (0.0-1.0)
+
+        Returns:
+            Detailed legal analysis and response
+        """
+        try:
+            if not (0.0 <= temperature <= 1.0):
+                raise ValueError("Temperature must be between 0 and 1")
+
+            used_role = role or self.role
+            used_jurisdiction = jurisdiction or self.jurisdiction
+
+            system_prompt = self._build_legal_system_prompt(
+                used_role,
+                used_jurisdiction,
+                query_type,
+                legal_context
+            )
+
+            messages = [
+                Message(role="system", content=system_prompt),
+                Message(role="user", content=prompt)
+            ]
+
+            if self.generative_model:
+                self.generative_model.temperature = temperature
+                
+                is_streaming = self.on_token is not None
+                result = await self.generative_model.async_generate_with_history(
+                    messages_history=messages,
+                    prompt=prompt,
+                    streaming=is_streaming
+                )
+
+                if is_streaming:
+                    response = ""
+                    async for chunk in result:
+                        response += chunk
+                else:
+                    response = result.response
+
+                logger.info(f"Generated legal analysis for {query_type} query in {used_jurisdiction} jurisdiction")
+                return response
+            else:
+                raise ValueError("Generative model not initialized")
+
+        except Exception as e:
+            logger.error(f"Error in legal analysis: {str(e)}")
+            raise
+
+    def execute(self, *args, **kwargs) -> str:
+        """Synchronous wrapper for async_execute."""
+        return asyncio.run(self.async_execute(*args, **kwargs))
+
+
+if __name__ == "__main__":
+    # Example usage of OrientedLLMTool
+    tool = OrientedLLMTool(model_name="openrouter/openai/gpt-4o-mini")
+    legal_context = "Retrieved legal documents and context from RAG tool"
+    question = "What is the meaning of life?"
+    temperature = 0.7
+
+    # Synchronous execution
+    answer = tool.execute(prompt=question, legal_context=legal_context, temperature=temperature)
+    print("Synchronous Answer:")
+    print(answer)
+
+    # Asynchronous execution with streaming
+    pirate = OrientedLLMTool(
+        model_name="openrouter/openai/gpt-4o-mini", on_token=console_print_token
+    )
+    pirate_answer = asyncio.run(
+        pirate.async_execute(prompt=question, legal_context=legal_context, temperature=temperature)
+    )
+    print("\nAsynchronous Pirate Answer:")
+    print(f"Answer: {pirate_answer}")
+
+    # Display tool configuration in Markdown
+    custom_tool = OrientedLLMTool(
+        model_name="openrouter/openai/gpt-4o-mini", on_token=console_print_token
+    )
+    print("\nTool Configuration:")
+    print(custom_tool.to_markdown())