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

quantalogic/codeact/utils.py

@@ -0,0 +1,135 @@
+import ast
+import inspect
+from functools import wraps
+from typing import Any, Callable, Tuple
+
+from loguru import logger
+from lxml import etree
+
+
+def log_async_tool(verb: str):
+    """Decorator factory for consistent async tool logging."""
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            logger.info(f"Starting tool: {func.__name__}")
+            sig = inspect.signature(func)
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+            logger.info(f"{verb} {', '.join(f'{k}={v}' for k, v in bound_args.arguments.items())}")
+            result = await func(*args, **kwargs)
+            logger.info(f"Finished tool: {func.__name__}")
+            return result
+        return wrapper
+    return decorator
+
+
+def log_tool_method(func: Callable) -> Callable:
+    """Decorator for logging Tool class methods."""
+    @wraps(func)
+    async def wrapper(self, **kwargs):
+        logger.info(f"Starting tool: {self.name}")
+        try:
+            result = await func(self, **kwargs)
+            logger.info(f"Finished tool: {self.name}")
+            return result
+        except Exception as e:
+            logger.error(f"Tool {self.name} failed: {e}")
+            raise
+    return wrapper
+
+
+def validate_xml(xml_string: str) -> bool:
+    """Validate XML string."""
+    try:
+        etree.fromstring(xml_string)
+        return True
+    except etree.XMLSyntaxError as e:
+        logger.error(f"XML validation failed: {e}")
+        return False
+
+
+def validate_code(code: str) -> bool:
+    """Check if code has an async main() function."""
+    try:
+        tree = ast.parse(code)
+        return any(isinstance(node, ast.AsyncFunctionDef) and node.name == "main" 
+                  for node in ast.walk(tree))
+    except SyntaxError:
+        return False
+
+
+def format_xml_element(tag: str, value: Any, **attribs) -> etree.Element:
+    """Create an XML element with optional CDATA and attributes."""
+    elem = etree.Element(tag, **attribs)
+    elem.text = etree.CDATA(str(value)) if value is not None else None
+    return elem
+
+
+class XMLResultHandler:
+    """Utility class for handling XML formatting and parsing."""
+    @staticmethod
+    def format_execution_result(result) -> str:
+        """Format execution result as XML."""
+        root = etree.Element("ExecutionResult")
+        root.append(format_xml_element("Status", "Success" if not result.error else "Error"))
+        root.append(format_xml_element("Value", result.result or result.error))
+        root.append(format_xml_element("ExecutionTime", f"{result.execution_time:.2f} seconds"))
+
+        completed = result.result and result.result.startswith("Task completed:")
+        root.append(format_xml_element("Completed", str(completed).lower()))
+        
+        if completed:
+            final_answer = result.result[len("Task completed:"):].strip()
+            root.append(format_xml_element("FinalAnswer", final_answer))
+
+        if result.local_variables:
+            vars_elem = etree.SubElement(root, "Variables")
+            for k, v in result.local_variables.items():
+                if not callable(v) and not k.startswith("__"):
+                    vars_elem.append(format_xml_element("Variable", str(v)[:5000] + 
+                                                      ("... (truncated)" if len(str(v)) > 5000 else ""), 
+                                                      name=k))
+        return etree.tostring(root, pretty_print=True, encoding="unicode")
+
+    @staticmethod
+    def format_result_summary(result_xml: str) -> str:
+        """Format XML result into a readable summary."""
+        try:
+            root = etree.fromstring(result_xml)
+            lines = [
+                f"- Status: {root.findtext('Status', 'N/A')}",
+                f"- Value: {root.findtext('Value', 'N/A')}",
+                f"- Execution Time: {root.findtext('ExecutionTime', 'N/A')}",
+                f"- Completed: {root.findtext('Completed', 'N/A').capitalize()}"
+            ]
+            if final_answer := root.findtext("FinalAnswer"):
+                lines.append(f"- Final Answer: {final_answer}")
+
+            if (vars_elem := root.find("Variables")) is not None:
+                lines.append("- Variables:")
+                lines.extend(f"  - {var.get('name', 'unknown')}: {var.text.strip() or 'N/A'}" 
+                            for var in vars_elem.findall("Variable"))
+            return "\n".join(lines)
+        except etree.XMLSyntaxError:
+            logger.error(f"Failed to parse XML: {result_xml}")
+            return result_xml
+
+    @staticmethod
+    def parse_response(response: str) -> Tuple[str, str]:
+        """Parse XML response to extract thought and code."""
+        try:
+            root = etree.fromstring(response)
+            thought = root.findtext("Thought") or ""
+            code = root.findtext("Code") or ""
+            return thought, code
+        except etree.XMLSyntaxError as e:
+            raise ValueError(f"Failed to parse XML: {e}")
+
+    @staticmethod
+    def extract_result_value(result: str) -> str:
+        """Extract the value from the result XML."""
+        try:
+            return etree.fromstring(result).findtext("Value") or ""
+        except etree.XMLSyntaxError:
+            return ""

quantalogic/coding_agent.py

@@ -15,7 +15,7 @@ from quantalogic.tools import (
     ReadHTMLTool,
     ReplaceInFileTool,
     RipgrepTool,
-    SearchDefinitionNames,
+    SearchDefinitionNamesTool,
     TaskCompleteTool,
     WriteFileTool,
 )
@@ -71,7 +71,7 @@ def create_coding_agent(
         # Code navigation and search tools
         ListDirectoryTool(),  # Lists directory contents
         RipgrepTool(),  # Searches code with regex
-        SearchDefinitionNames(),  # Finds code definitions
+        SearchDefinitionNamesTool(),  # Finds code definitions
         # Specialized language model tools
         ReadFileTool(),
         ExecuteBashCommandTool(),

quantalogic/create_custom_agent.py

@@ -10,11 +10,15 @@ from quantalogic.console_print_token import console_print_token
 from quantalogic.event_emitter import EventEmitter
 from quantalogic.tools.tool import Tool
 
-# Configure loguru to output debug messages
+# Configure loguru to output only INFO and above
 logger.remove()  # Remove default handler
-logger.add(sink=lambda msg: print(msg, end=""), level="DEBUG")  # Add a new handler that prints to console
-
+logger.add(
+    sink=lambda msg: print(msg, end=""),
+    level="INFO",
+    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>"
+)
 
+# Helper function to import tool classes
 def _import_tool(module_path: str, class_name: str) -> Type[Tool]:
     """
     Import a tool class from a module path using standard Python imports.
@@ -78,6 +82,7 @@ TOOL_IMPORTS = {
     # File Tools
     "download_http_file": lambda: _import_tool("quantalogic.tools.utilities", "PrepareDownloadTool"),
     "write_file": lambda: _import_tool("quantalogic.tools.write_file_tool", "WriteFileTool"),
+    "file_tracker": lambda: _import_tool("quantalogic.tools.file_tracker_tool", "FileTrackerTool"),
     "edit_whole_content": lambda: _import_tool("quantalogic.tools", "EditWholeContentTool"),
     "read_file_block": lambda: _import_tool("quantalogic.tools", "ReadFileBlockTool"),
     "read_file": lambda: _import_tool("quantalogic.tools", "ReadFileTool"),
@@ -128,14 +133,15 @@ TOOL_IMPORTS = {
     # Product Hunt Tools
     "product_hunt_tool": lambda: _import_tool("quantalogic.tools.product_hunt", "ProductHuntTool"),
     
-    # RAG Tools
-    "rag_tool": lambda: _import_tool("quantalogic.tools.rag_tool", "RagTool"),
+    # RAG Tools 
+    "rag_tool_hf": lambda: _import_tool("quantalogic.tools.rag_tool", "RagToolHf"),
     
     # Utility Tools
     "task_complete": lambda: _import_tool("quantalogic.tools.task_complete_tool", "TaskCompleteTool"),
     "input_question": lambda: _import_tool("quantalogic.tools.utilities", "InputQuestionTool"),
     "markitdown": lambda: _import_tool("quantalogic.tools.utilities", "MarkitdownTool"),
-    "read_html": lambda: _import_tool("quantalogic.tools.utilities", "ReadHTMLTool"),
+    "read_html": lambda: _import_tool("quantalogic.tools.read_html_tool", "ReadHTMLTool"),
+    "oriented_llm_tool": lambda: _import_tool("quantalogic.tools.utilities", "OrientedLLMTool"),
     "presentation_llm": lambda: _import_tool("quantalogic.tools.presentation_tools", "PresentationLLMTool"),
     "sequence": lambda: _import_tool("quantalogic.tools.utilities", "SequenceTool"),
     "csv_processor": lambda: _import_tool("quantalogic.tools.utilities", "CSVProcessorTool"),
@@ -152,7 +158,8 @@ def create_custom_agent(
     max_tokens_working_memory: Optional[int] = None,
     specific_expertise: str = "",
     tools: Optional[list[dict[str, Any]]] = None,
-    memory: Optional[AgentMemory] = None
+    memory: Optional[AgentMemory] = None,
+    agent_mode: str = "react"
 ) -> Agent:
     """Create an agent with lazy-loaded tools and graceful error handling.
 
@@ -169,6 +176,8 @@ def create_custom_agent(
     Returns:
         Agent: Configured agent instance
     """
+    logger.info("Creating custom agent with model: {}".format(model_name))
+    logger.info("tools: {}".format(tools))
     # Create storage directory for RAG
     storage_dir = os.path.join(os.path.dirname(__file__), "storage", "rag")
     os.makedirs(storage_dir, exist_ok=True)
@@ -188,8 +197,9 @@ def create_custom_agent(
     tool_configs = {
         # LLM Tools with shared parameters
         "llm": lambda params: create_tool_instance(TOOL_IMPORTS["llm"](), **get_llm_params(params)),
+        "oriented_llm_tool": lambda params: create_tool_instance(TOOL_IMPORTS["oriented_llm_tool"](), **get_llm_params(params)),
         "llm_vision": lambda params: create_tool_instance(TOOL_IMPORTS["llm_vision"](),
-            model_name=params.get("vision_model_name") or vision_model_name,
+            model_name=params.get("vision_model_name") or "gpt-4-vision",
             on_token=console_print_token if not no_stream else None,
             event_emitter=event_emitter
         ) if vision_model_name else None,
@@ -203,6 +213,7 @@ def create_custom_agent(
         "download_http_file": lambda _: create_tool_instance(TOOL_IMPORTS["download_http_file"]()),
         "duck_duck_go_search": lambda _: create_tool_instance(TOOL_IMPORTS["duck_duck_go_search"]()),
         "write_file": lambda _: create_tool_instance(TOOL_IMPORTS["write_file"]()),
+        "file_tracker": lambda _: create_tool_instance(TOOL_IMPORTS["file_tracker"]()),
         "task_complete": lambda _: create_tool_instance(TOOL_IMPORTS["task_complete"]()),
         "edit_whole_content": lambda _: create_tool_instance(TOOL_IMPORTS["edit_whole_content"]()),
         "execute_bash_command": lambda _: create_tool_instance(TOOL_IMPORTS["execute_bash_command"]()),
@@ -296,11 +307,12 @@ def create_custom_agent(
         "nasa_apod_tool": lambda _: create_tool_instance(TOOL_IMPORTS["nasa_apod_tool"]()),
         "product_hunt_tool": lambda _: create_tool_instance(TOOL_IMPORTS["product_hunt_tool"]()),
         
-        # RAG tool
-        "rag_tool": lambda params: create_tool_instance(TOOL_IMPORTS["rag_tool"](),
-            vector_store=params.get("vector_store", "chroma"),
-            embedding_model=params.get("embedding_model", "openai"),
-            persist_dir=storage_dir,
+        # Multilingual RAG tool
+        "rag_tool_hf": lambda params: create_tool_instance(TOOL_IMPORTS["rag_tool_hf"](),
+            persist_dir=params.get("persist_dir", "./storage/multilingual_rag"),
+            use_ocr_for_pdfs=params.get("use_ocr_for_pdfs", False),
+            ocr_model=params.get("ocr_model", "openai/gpt-4o-mini"),
+            embed_model=params.get("embed_model", "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"),
             document_paths=params.get("document_paths", [])
         ),
         
@@ -357,26 +369,6 @@ def create_custom_agent(
             else:
                 logger.warning(f"Unknown tool type: {tool_type} - Skipping")
 
-    # Add download tool if any write tool is present
-    if has_write_tool:
-        try:
-            # Get the tool class first
-            download_tool_class = TOOL_IMPORTS["download_file_tool"]()
-            if download_tool_class:
-                # Create an instance with the name 'download'
-                download_tool = create_tool_instance(download_tool_class, name="download")
-                if download_tool:
-                    agent_tools.append(download_tool)
-                    logger.info("Added download tool automatically due to write tool presence")
-                else:
-                    logger.warning("Failed to instantiate download tool")
-            else:
-                logger.warning("Download tool class not found")
-        except ImportError as e:
-            logger.warning(f"Failed to load download tool: Required library missing - {str(e)}")
-        except Exception as e:
-            logger.error(f"Failed to add download tool: {str(e)}")
-
 
     # Create and return the agent
     try:
@@ -388,52 +380,8 @@ def create_custom_agent(
             max_tokens_working_memory=max_tokens_working_memory,
             specific_expertise=specific_expertise,
             memory=memory if memory else AgentMemory(),
+            agent_mode=agent_mode
         )
     except Exception as e:
         logger.error(f"Failed to create agent: {str(e)}")
         raise
-
-if __name__ == "__main__":
-    # Example usage
-    tools_config = [
-        {"type": "duck_duck_go_search", "parameters": {}},
-    ]
-    
-    agent = create_custom_agent(
-        model_name="openrouter/openai/gpt-4o-mini",
-        specific_expertise="General purpose assistant",
-        tools=tools_config
-    )
-    print(f"Created agent with {len(agent.tools.tool_names())} tools")
-    
-    # Display all tool names
-    print("Agent Tools:")
-    for tool_name in agent.tools.tool_names():
-        print(f"- {tool_name}")
-
-    # Set up event monitoring to track agent's lifecycle
-    # The event system provides:
-    # 1. Real-time observability into the agent's operations
-    # 2. Debugging and performance monitoring
-    # 3. Support for future analytics and optimization efforts
-    agent.event_emitter.on(
-        event=[
-            "task_complete",
-            "task_think_start",
-            "task_think_end",
-            "tool_execution_start",
-            "tool_execution_end",
-            "error_max_iterations_reached",
-            "memory_full",
-            "memory_compacted",
-            "memory_summary",
-        ],
-        listener=console_print_events,
-    )
-
-    # Enable token streaming for detailed output
-    agent.event_emitter.on(event=["stream_chunk"], listener=console_print_token)
-
-    # Solve task with streaming enabled
-    result = agent.solve_task("Who is the Prime Minister of France in 2025 ?", max_iterations=10, streaming=True)
-    print(result)

quantalogic/prompts/chat_system_prompt.j2

@@ -22,13 +22,17 @@ Tools must be called using the following XML format, with NO additional text:
 
 #### Examples of Correct Tool Usage
 
-**Example 1 - Search Tool:**
+**Example 1 - Duck Duck Go search tool:**
 ```xml
 <action>
-<duckduckgo_tool>
-  <query>search query text</query>
-  <max_results>5</max_results>  <!-- Always include max_results for search -->
-</duckduckgo_tool>
+<duckduckgosearch>
+  <query>machine learning</query>
+  <max_results>20</max_results>
+  <search_type>images</search_type>
+  <region>us-en</region>
+  <safesearch>moderate</safesearch>
+  <timelimit>d</timelimit>
+</duckduckgosearch>
 </action>
 ```
 
@@ -50,5 +54,4 @@ Tools must be called using the following XML format, with NO additional text:
 **Tools Available**: None
 {% endif %}
 
-Don't invent tools that are not listed.
-
+Don't invent tools that are not listed.

quantalogic/prompts/code_2_system_prompt.j2

@@ -0,0 +1,190 @@
+<agent_identity>
+You are QuantaLogic, an expert ReAct AI Agent implementing the OODA (Observe-Orient-Decide-Act) loop for powerful, efficient problem-solving.
+
+- Version: {{ version }}
+- Expertise: {{ expertise }}
+- Primary focus: Efficient task completion, robust planning, and adaptive execution
+</agent_identity>
+
+<language_settings>
+- Default working language: English
+- Use the language specified by the user in messages as the working language when explicitly provided
+- All thinking and responses must be in the working language
+- Natural language arguments in tool calls must be in the working language
+- Avoid using pure lists and bullet points format in any language
+</language_settings>
+
+<agent_loop>
+You are operating in an agent loop, iteratively completing tasks through the following structured steps:
+
+1. **Initial Thinking Phase**:
+   - Conduct a comprehensive analysis upon receiving a new task
+   - Break down the task into logical steps and create an execution plan
+   - Save the plan in `plan.md` for reference throughout task execution
+   - Include contingencies, fallback actions, and adaptive methods in the plan
+
+2. **Observe**:
+   - Gather essential data and contextual information when needed
+   - Reference the initial plan and identify any missing details
+   - Only perform additional observation steps if current data doesn't suffice
+
+3. **Orient**:
+   - Refer to the existing plan and analyze the context briefly
+   - Avoid rethinking unless task objectives or external conditions change significantly
+
+4. **Decide**:
+   - Select the most appropriate action based on the current step in the plan
+   - Focus decisions on task objectives while minimizing unnecessary interventions
+
+5. **Act**:
+   - Execute the decided action efficiently using tools
+   - Always update progress markers in the plan after completing a step
+
+6. **Reflect**:
+   - Evaluate action results against the plan
+   - Adjust the plan only if a significant deviation or new information arises
+
+7. **Iterate**:
+   - Loop through Observe, Orient, Decide, and Act phases
+   - Ensure one tool call per iteration, avoiding multiple simultaneous operations
+
+8. **Completion**:
+   - Submit results to the user via messages, attaching all relevant deliverables
+   - Enter standby mode when tasks are fully completed, waiting for new instructions
+</agent_loop>
+
+<cognitive_framework>
+Implement the OODA loop for problem-solving:
+1. 🔍 **OBSERVE**: Collect essential data if needed
+2. 🧭 **ORIENT**: Analyze context briefly, referring to the task plan
+3. 🎯 **DECIDE**: Choose the most effective action from the plan
+4. ⚡ **ACT**: Perform precise operations aligned with the task plan
+5. 🔄 **REFLECT**: Evaluate results and adjust the plan only if necessary
+6. ✅ **ADAPT**: Minimize thinking during execution unless conditions demand reevaluation
+</cognitive_framework>
+
+<planner_module>
+- Create an initial detailed execution plan (task decomposition, contingencies, metrics) upon receiving a task
+- Provide plans as numbered pseudocode, detailing execution steps
+- Include current step number, status, and rationales in planning updates
+- Save the plan as `plan.md`, updating only when the task objective or conditions change significantly
+- Ensure completion of all planned steps, reaching the task's final objective without unnecessary interruptions
+</planner_module>
+
+<knowledge_module>
+- Use the knowledge and memory module to access best practices, task-relevant knowledge, and references
+- Apply relevant knowledge during initial planning and action execution, continuously updating based on outcomes
+- Avoid redundant queries; leverage stored knowledge to enhance efficiency
+</knowledge_module>
+
+<response_schema>
+Mandatory three-block format:
+
+1. 🧠 **Analysis Block** (only when new thinking is needed):
+<thinking>
+  <!-- Concise cognitive processing using draft, emojis, and symbols -->
+  <context_analysis when="no_history">
+    • 📋 Task Decomposition: Key steps and dependencies
+    • 🎯 Success Metrics: Quantifiable outcomes
+    • 🛠️ Resources: Tools, data, variables
+    • ⚠️ Risks: Potential failures, mitigation strategies
+  </context_analysis>
+
+  <execution_analysis>
+    • 🔄 Last Operation: Result, impact
+    • 📊 Progress: Completed%, remaining%
+    • 💾 Variables: $var: brief content
+    • 📈 Metrics: Speed, quality, resource use
+  </execution_analysis>
+
+  <decision_matrix>
+    • 🎯 Next Action: Tool + rationale
+    • 📥 Parameters: Values + $var$
+    • 🔄 Fallback: Alternative approach
+    • ✅ Exit Criteria: Completion conditions
+  </decision_matrix>
+</thinking>
+
+2. 📊 **Plan Status Block** (default; includes updates only as needed):
+<plan_status>
+  • 📈 Progress: Step X of Y completed
+  • 🔄 Plan Updates: Modifications to the original plan
+  • 🎯 Next Step: Upcoming action
+</plan_status>
+
+3. ⚡ **Action Block**:
+<action>
+<tool_name>
+  <param1>value1</param1>
+  <param2>value2</param2>
+</tool_name>
+</action>
+</response_schema>
+
+<execution_guidelines>
+1. Prioritize achieving task objectives through data-driven decisions
+2. Create a robust initial task plan to minimize unnecessary iterations
+3. Optimize execution using feedback loops and adapt only as needed
+4. Validate each action's impact and maximize efficiency
+5. Focus on delivering complete, usable, high-quality results
+</execution_guidelines>
+
+<todo_rules>
+- Create and maintain `todo.md` as a checklist based on the task planning
+- Update progress markers in `todo.md` after completing each step
+- Rebuild `todo.md` when the task objective or plan changes significantly
+- Use it to track and ensure progress, verifying its completion at task end
+</todo_rules>
+
+<info_rules>
+- Prioritize information sources: authoritative data > web search > internal knowledge
+- Use dedicated tools for information gathering, avoiding redundant searches
+- Access multiple sources for cross-validation and deeper insights
+- Conduct searches systematically, processing entities or attributes step by step
+</info_rules>
+
+<file_rules>
+- Save intermediate results and organize information systematically in separate files
+- Use append mode for merging text files; ensure content continuity and format consistency
+- Maintain strict version control and follow writing rules for all saved content
+</file_rules>
+
+<writing_rules>
+- Write in engaging prose using varied sentence structures, avoiding lists unless explicitly requested
+- Provide detailed, comprehensive writing based on user requirements
+- Cite references actively, including URLs and source documentation
+- For lengthy documents, save sections individually before appending into a final compilation
+</writing_rules>
+
+<message_rules>
+- Communicate with users via messages, avoiding direct text responses
+- Notify users immediately of task updates, ensuring clarity in deliverables
+- Provide all relevant files as attachments, ensuring accessibility for users
+- Use messaging tools strategically to minimize interruptions
+</message_rules>
+
+<error_handling>
+- Proactively resolve tool-related issues using error messages and alternative methods
+- Report failure reasons to users if multiple approaches fail
+- Ensure reliability and adapt quickly to blockers
+</error_handling>
+
+<tool_use_rules>
+- Respond only via tool use (function calling), avoiding plain text responses
+- Verify tool availability and functionality explicitly; avoid fabricating non-existent tools
+- Ensure all tool calls align with the task plan and goals
+</tool_use_rules>
+
+Operational Parameters:
+- 🛠️ Tools: {{ tools }}
+- 🌐 Environment: {{ environment }}
+
+Input Protocol:
+Task Format: <task>task_description</task>
+
+Completion Format:
+<action>
+<task_complete>
+  <r>$final_output$</r>
+</task_complete>
+</action>