Sync local Space with Hub

.gitignore

@@ -0,0 +1,3 @@
+__pycache__
+logs/
+data

README.md

@@ -1,14 +1,14 @@
 ---
 title: ODR
 emoji: 🏆
-colorFrom: purple
-colorTo: green
+colorFrom: yellow
+colorTo: purple
 sdk: gradio
-sdk_version: 5.23.1
+sdk_version: 5.14.0
 app_file: app.py
 pinned: false
 license: apache-2.0
-short_description: OpenAI's Deep Research, but open. Forked m-ric repo!
+short_description: OpenAI's Deep Research, but open
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -1,44 +1,131 @@
 #!/usr/bin/env python
 # coding=utf-8
 # Copyright 2024 The Footscray Coding Collective. All rights reserved.
+"""
+Financial Research Agent: Advanced Market Analysis and Data Access
+
+This script implements a comprehensive financial research agent capable of performing market analysis,
+retrieving financial data, and providing interactive research capabilities through either a GUI or
+command-line interface.
+
+The agent leverages the Smolagents framework to create an autonomous system that can:
+1. Access and analyze real-time market data through Alpha Vantage API integration
+2. Process financial documents and extract relevant information
+3. Perform web searches and analyze webpage content
+4. Create visualizations of financial data
+5. Generate comprehensive financial analysis reports
+6. Handle user uploads of various document types
+
+Key Components:
+-------------
+- ModelManager: Handles loading and configuration of various LLM models
+- ToolRegistry: Manages initialization and organization of tools available to the agent
+- GradioUI: Provides a user-friendly interface with responsive design for desktop/mobile
+- A robust set of financial tools for retrieving stock data, financial statements, and market sentiment
+- Web browsing capabilities with text extraction and analysis
+- Document processing for PDFs, spreadsheets, and other common file formats
+- Visualization tools for creating charts and graphs from financial data
+
+Usage:
+-----
+Run in UI mode (default):
+   python app.py
+
+Run in headless mode with a specific query:
+   python app.py --mode headless --query "Analyze Tesla's financial performance for 2023"
+
+Configuration:
+------------
+The script uses environment variables for API keys and other configuration settings.
+Required environment variables:
+- ALPHA_VANTAGE_API_KEY: For accessing financial data APIs
+- HF_TOKEN: For accessing Hugging Face models (optional)
+
+The agent also maintains detailed logs in the logs/ directory for debugging and auditing.
+
+Dependencies:
+-----------
+- smolagents: Core framework for agent capabilities
+- gradio: For the web interface
+- Alpha Vantage API integration: For financial data
+- Various data processing libraries: For handling and analyzing financial information
+
+Technical Notes:
+--------------
+- The agent runs with a configurable number of maximum steps (default: 20)
+- Planning occurs at regular intervals (default: every 4 steps)
+- The agent has access to a curated list of authorized Python imports for security
+- All file uploads are validated for type and size before processing
+
+Created by the Footscray Coding Collective
+Copyright 2024, All rights reserved
+"""
+import contextlib
+import datetime
+import logging
 import mimetypes
 import os
 import re
 import shutil
-from typing import Optional
+from typing import Any, Dict, Generator, List, Optional, Tuple
 
+# Typer for CLI functionality
+import typer
+
+# Telemetry imports (optional)
+with contextlib.suppress(ImportError):
+    from openinference.instrumentation.smolagents import SmolagentsInstrumentor
+    from phoenix.otel import register
+
+    # Initialize telemetry for observability and tracing
+    register()
+    SmolagentsInstrumentor().instrument()
+
+# third-party
 import gradio as gr
+import pytz
 from dotenv import load_dotenv
 from huggingface_hub import login
+from rich.console import Console
+from rich.logging import RichHandler
+from smolagents import FinalAnswerTool  # smolagents
+from smolagents import (CodeAgent, GoogleSearchTool, HfApiModel, LiteLLMModel,
+                        OpenAIServerModel, Tool, TransformersModel)
+from smolagents.agent_types import AgentText
+from smolagents.gradio_ui import (handle_agent_output_types,
+                                  pull_messages_from_step)
+
+# local
+from scripts.finance_tools import (DataVisualizationTool,
+                                   FinancialCalculatorTool, TrendAnalysisTool,
+                                   get_balance_sheet_data, get_cash_flow_data,
+                                   get_company_overview_data,
+                                   get_earnings_data,
+                                   get_income_statement_data,
+                                   get_market_news_sentiment,
+                                   get_stock_quote_data, get_time_series_daily,
+                                   search_symbols)
 from scripts.flux_lora_tool import FluxLoRATool
 from scripts.text_cleaner_tool import TextCleanerTool
 from scripts.text_inspector_tool import TextInspectorTool
-from scripts.text_web_browser import (
-    ArchiveSearchTool,
-    FinderTool,
-    FindNextTool,
-    PageDownTool,
-    PageUpTool,
-    SimpleTextBrowser,
-    VisitTool,
-)
+from scripts.text_web_browser import (ArchiveSearchTool, DownloadTool,
+                                      FinderTool, FindNextTool, PageDownTool,
+                                      PageUpTool, SimpleTextBrowser, VisitTool)
+from scripts.time_tools import get_temporal_context
 from scripts.visual_qa import visualizer
-from smolagents import (
-    CodeAgent,
-    GoogleSearchTool,
-    HfApiModel,
-    LiteLLMModel,
-    OpenAIServerModel,
-    Tool,
-    TransformersModel,
+
+# Initialize console and app
+console = Console()
+app = typer.Typer(
+    help="Financial Research Agent - Access market data and analysis through a CLI or UI",
+    add_completion=False,
 )
-from smolagents.agent_types import AgentAudio, AgentImage, AgentText
-from smolagents.gradio_ui import handle_agent_output_types, pull_messages_from_step
 
 # ------------------------ Configuration and Setup ------------------------
 # Constants and configurations
 AUTHORIZED_IMPORTS = [
     "requests",  # Web requests (fetching data from the internet)
+    "pytz",  # Timezone handling
     "zipfile",  # Working with ZIP archives
     "pandas",  # Data manipulation and analysis (DataFrames)
     "numpy",  # Numerical computing (arrays, linear algebra)
@@ -48,7 +135,7 @@ AUTHORIZED_IMPORTS = [
     "pubchempy",  # Accessing PubChem chemical database
     "yaml",
     "xml",  # XML processing
-    "yahoo_finance",  # Fetching stock data
+    "yahoo_finance",  # Fetching stock datauv 
     "Bio",  # Bioinformatics tools (e.g., sequence analysis)
     "sklearn",  # Scikit-learn for machine learning
     "scipy",  # Scientific computing (stats, optimization)
@@ -74,7 +161,7 @@ AUTHORIZED_IMPORTS = [
     "time",  # Measuring time
     "tempfile",  # Creating temporary files and directories
     # Data Visualization (if needed) - Consider security implications carefully
-    "matplotlib",  # Plotting library (basic charts)
+    "matplotlib.plt",  # Plotting library
     "seaborn",  # Statistical data visualization (more advanced)
     # Web Scraping (more specific/controlled) - Consider ethical implications
     "lxml",  # Faster XML/HTML processing (alternative to bs4)
@@ -85,6 +172,7 @@ AUTHORIZED_IMPORTS = [
     "schedule",  # Allow the agent to schedule tasks
     "uuid",
     "base64",
+    "smolagents",  # smolagents package to be able to create smolagents tools
 ]
 
 USER_AGENT = (
@@ -93,7 +181,7 @@ USER_AGENT = (
 )
 BROWSER_CONFIG = {
     "viewport_size": 1024 * 5,
-    "downloads_folder": "downloads_folder",
+    "downloads_folder": "data/downloads_folder",
     "request_kwargs": {
         "headers": {"User-Agent": USER_AGENT},
         "timeout": 300,
@@ -103,7 +191,6 @@ BROWSER_CONFIG = {
 
 CUSTOM_ROLE_CONVERSIONS = {"tool-call": "assistant", "tool-response": "user"}
 
-
 ALLOWED_FILE_TYPES = [
     "application/pdf",
     "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -121,23 +208,108 @@ ALLOWED_FILE_TYPES = [
 ]
 
 
-def setup_environment():
-    """Initialize environment variables and authentication."""
+# Set up logging configuration
+def setup_logging() -> Tuple[str, logging.Logger]:
+    """
+    Configure logging with structured output and file storage.
+
+    The function creates logs directory and timestamped log filename, sets up
+    logging with Rich integration and creates and returns logger.
+
+    Returns:
+        Tuple containing the log file path and configured logger
+    """
+    # Create logs directory
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    logs_dir = os.path.join(current_dir, "logs")
+    os.makedirs(logs_dir, exist_ok=True)
+
+    # Generate timestamped log filename
+    melbourne_timezone = pytz.timezone("Australia/Melbourne")
+    log_filename = f'smolagents_{datetime.datetime.now(melbourne_timezone).strftime("%Y%m%d_%H%M%S")}.log'
+    log_file = os.path.join(logs_dir, log_filename)
+
+    # Set up logging with Rich integration
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        handlers=[
+            RichHandler(rich_tracebacks=True, show_time=True),
+            logging.FileHandler(log_file),
+        ],
+    )
+
+    # Create and return logger
+    logger = logging.getLogger(__name__)
+    return log_file, logger
+
+
+LOG_FILE, logger = setup_logging()
+
+
+def setup_environment() -> None:
+    """Initialize environment variables and authentication.
+
+    This function ensures that required environment variables are set and
+    attempts to authenticate with Hugging Face and Alpha Vantage services.
+    """
     load_dotenv(override=True)
+
+    # Check Hugging Face token
     if os.getenv("HF_TOKEN"):  # Check if token is actually set
         login(os.getenv("HF_TOKEN"))
-        print("HF_TOKEN (last 10 characters):", os.getenv("HF_TOKEN")[-10:])
+        console.print("HF_TOKEN loaded successfully")
     else:
-        print("HF_TOKEN not found in environment variables.")
+        console.print(
+            "[yellow]HF_TOKEN not found in environment variables. "
+            "Some features may not work properly.[/yellow]"
+        )
+
+    # Check Alpha Vantage API key
+    try:
+        # Ensure Alpha Vantage API key is available
+        api_key = os.getenv("ALPHA_VANTAGE_API_KEY")
+        if not api_key:
+            console.print(
+                "[yellow]⚠️ Warning: ALPHA_VANTAGE_API_KEY not found. "
+                "Finance tools may not work properly.[/yellow]"
+            )
+        else:
+            console.print("[green]✓ ALPHA_VANTAGE_API_KEY loaded successfully[/green]")
+    except Exception as e:
+        console.print(f"[red]Error checking ALPHA_VANTAGE_API_KEY: {e}[/red]")
 
 
 # ------------------------ Model and Tool Management ------------------------
 class ModelManager:
-    """Manages model loading and initialization."""
+    """Manages model loading and initialization.
+
+    This class provides a static method to load the specified model with the
+    appropriate configuration. It supports the following inference types:
+        - hf_api: Use the Hugging Face API to load the model.
+        - hf_api_provider: Use the Hugging Face API to load the model with the
+            'together' provider.
+        - litellm: Load the LiteLLM model with the specified model ID.
+        - openai: Load the OpenAI model with the specified model ID and API key.
+        - transformers: Load the Hugging Face transformers model with the
+            specified model ID and configuration.
+    """
 
     @staticmethod
     def load_model(chosen_inference: str, model_id: str, key_manager=None):
-        """Load the specified model with appropriate configuration."""
+        """Load the specified model with appropriate configuration.
+
+        Args:
+            chosen_inference (str): The inference type to use.
+            model_id (str): The model ID to load.
+            key_manager (Optional[KeyManager]): The key manager to use for
+                loading the model. Required for OpenAI models.
+
+        Raises:
+            ValueError: If the chosen inference type is invalid.
+            Exception: If an error occurs while loading the model.
+        """
         try:
             if chosen_inference == "hf_api":
                 return HfApiModel(model_id=model_id)
@@ -156,7 +328,7 @@ class ModelManager:
                     model_id=model_id, api_key=key_manager.get_key("openai_api_key")
                 )
 
-            elif chosen_inference == "transformers":
+            if chosen_inference == "transformers":
                 return TransformersModel(
                     model_id="HuggingFaceTB/SmolLM2-1.7B-Instruct",
                     device_map="auto",
@@ -167,41 +339,114 @@ class ModelManager:
                 raise ValueError(f"Invalid inference type: {chosen_inference}")
 
         except Exception as e:
-            print(f"✗ Couldn't load model: {e}")
+            console.print(f"[red]✗ Couldn't load model: {e}[/red]")
             raise
 
 
+# ------------------------ Tool Registration ------------------------
 class ToolRegistry:
-    """Manages tool initialization and organization."""
+    """Manages tool initialization and organization using Zhou Protocol priorities."""
 
     @staticmethod
-    def load_web_tools(model, browser, text_limit=20000):
-        """Initialize and return web-related tools."""
+    def load_information_tools(model, text_limit=30000):
+        """
+        Initialize and return information analysis tools.
+
+        This method creates tools for analyzing text from documents, and other sources.
+        The information tools should be prioritized first in the agent's toolset.
+
+        Args:
+            model: Language model to use for analysis
+            text_limit: Maximum character length for text summaries
+
+        Returns:
+            List of information analysis tools
+        """
         return [
-            GoogleSearchTool(provider="serper"),
-            VisitTool(browser),
-            PageUpTool(browser),
-            PageDownTool(browser),
-            FinderTool(browser),
-            FindNextTool(browser),
-            ArchiveSearchTool(browser),
             TextInspectorTool(model, text_limit),
         ]
 
     @staticmethod
-    def load_document_tools():
+    def load_utility_tools():
         """
-        Initialize and return document processing, i.e. sanitisation and indexing, tools.
+        Initialize and return utility tools for text cleaning and normalization.
+
         Returns:
-            List of document tools
+            List of utility tools
         """
         return [
             TextCleanerTool(),
         ]
 
+    @staticmethod
+    def load_time_tools():
+        """
+        Initialize and return time-related tools.
+
+        Returns:
+            List of time-related tools
+        """
+        return [get_temporal_context]
+
+    @staticmethod
+    def load_finance_tools():
+        """
+        Initialize and return financial analysis tools.
+
+        Returns:
+            List of financial tools in priority order
+        """
+        return [
+            # Analysis tools first (higher priority)
+            DataVisualizationTool(),
+            FinancialCalculatorTool(),
+            TrendAnalysisTool(),
+            # Data retrieval tools next
+            search_symbols,
+            get_stock_quote_data,
+            get_company_overview_data,
+            get_earnings_data,
+            get_income_statement_data,
+            get_balance_sheet_data,
+            get_cash_flow_data,
+            get_time_series_daily,
+            get_market_news_sentiment,
+        ]
+
+    @staticmethod
+    def load_web_tools(browser, text_limit=20000):
+        """
+        Initialize and return web interaction tools.
+
+        Args:
+            browser: Browser instance for web navigation
+            text_limit: Maximum character length for text processing
+
+        Returns:
+            List of web tools in priority order
+        """
+        return [
+            # Search tools first
+            GoogleSearchTool(provider="serper"),
+            # Navigation tools next
+            VisitTool(browser),
+            DownloadTool(browser),
+            # Page interaction tools last
+            PageUpTool(browser),
+            PageDownTool(browser),
+            FinderTool(browser),
+            FindNextTool(browser),
+            ArchiveSearchTool(browser),
+        ]
+
     @staticmethod
     def load_image_generation_tools():
-        """Initialize and return image generation tools."""
+        """
+        Initialize and return image generation tools.
+
+        Returns:
+            Image generation tool or fallback
+        """
         try:
             return Tool.from_space(
                 space_id="xkerser/FLUX.1-dev",
@@ -209,95 +454,219 @@ class ToolRegistry:
                 description="Generates high-quality AgentImage using the FLUX.1-dev model based on text prompts.",
             )
         except Exception as e:
-            print(f"✗ Couldn't initialize image generation tool: {e}")
-        return FluxLoRATool
+            console.print(
+                f"[yellow]✗ Couldn't initialize image generation tool: {e}[/yellow]"
+            )
+            return FluxLoRATool()
+
+    @staticmethod
+    def load_final_answer_tool():
+        """
+        Return the final answer tool for providing conclusive responses.
+
+        Returns:
+            List containing the final answer tool
+        """
+        return [FinalAnswerTool()]
 
 
-# ------------------------ Agent Creation and Execution ------------------------
-def create_agent():
+def create_agent(model_id: str = "openrouter/google/gemini-2.0-flash-001"):
     """
-    Creates a fresh agent instance with properly configured tools.
+    Create a fresh agent instance with properly configured tools.
+
+    This function creates a CodeAgent with tools organized by the Zhou Protocol
+    priority system, ensuring the most relevant tools are considered first.
+
+    Args:
+        model_id: The ID of the model to use for the agent
+
     Returns:
-        CodeAgent: Configured agent ready for use
+        A configured CodeAgent instance
+
     Raises:
-        ValueError: If tool validation fails
         RuntimeError: If agent creation fails
     """
     try:
-        # Initialize model
-        model = LiteLLMModel(
-            custom_role_conversions=CUSTOM_ROLE_CONVERSIONS,
-            model_id="openrouter/google/gemini-2.0-flash-001",
-        )
+        # Initialize model with fallback system
+        model = _load_model_with_fallback(model_id)
 
         # Initialize tools
         text_limit = 30000
         browser = SimpleTextBrowser(**BROWSER_CONFIG)
 
-        # Collect all tools in a single list
-        web_tools = ToolRegistry.load_web_tools(model, browser, text_limit)
-        doc_tools = ToolRegistry.load_document_tools()  # New document tools
+        # Collect all tools with proper Zhou Protocol prioritization
+        information_tools = ToolRegistry.load_information_tools(model, text_limit)
+        utility_tools = ToolRegistry.load_utility_tools()
+        finance_tools = ToolRegistry.load_finance_tools()
+        web_tools = ToolRegistry.load_web_tools(browser)
+        time_tools = ToolRegistry.load_time_tools()
         image_generator = ToolRegistry.load_image_generation_tools()
-
-        # Combine all tools into a single list
-        all_tools = [visualizer] + web_tools + doc_tools + [image_generator]
+        final_answer = ToolRegistry.load_final_answer_tool()
+
+        # Combine all tools with information tools prioritized first
+        all_tools = (
+            information_tools  # Critical information extraction (highest priority)
+            + utility_tools  # General utility functions
+            + finance_tools  # Financial analysis capabilities
+            + web_tools  # Web search and navigation
+            + time_tools  # Time context tools
+            + [visualizer]  # Image analysis
+            + [image_generator]  # Image generation
+            + final_answer  # Task completion (always last)
+        )
 
         # Validate tools before creating agent
-        for tool in all_tools:
-            if not isinstance(tool, Tool):
-                raise ValueError(
-                    f"Invalid tool type: {type(tool)}. "
-                    f"All tools must be instances of Tool class."
-                )
+        _validate_tools(all_tools)
 
         return CodeAgent(
             model=model,
             tools=all_tools,
-            max_steps=12,
+            max_steps=20,
             verbosity_level=2,
             additional_authorized_imports=AUTHORIZED_IMPORTS,
-            planning_interval=2,
+            planning_interval=4,
+            description="""
+        This agent assists with comprehensive research and financial analysis. It first analyzes
+        any provided documents or text, then leverages specialized financial tools and web search
+        capabilities to provide thorough insights.
+        
+        QUERY COMPREHENSION FRAMEWORK
+        Before answering any complex question, apply the Zhou Comprehension Pattern:
+        1. **Initial Parse**: What is literally being asked?
+        2. **Intent Detection**: What is the user actually trying to accomplish?
+        3. **Knowledge Assessment**: What information is needed to address this properly?
+        4. **Tool Selection**: Which tools provide the most direct path to a solution?
+        5. **Execution Planning**: What sequence of operations will yield the best result?
+        
+        CLARIFICATION CHECKLIST
+        When faced with ambiguous queries, the agent should systematically clarify:
+        * **Scope**: "How comprehensive should this analysis be?"
+        * **Format**: "What form would you like the results in?"
+        * **Technical Level**: "Should I explain technical details or focus on practical applications?"
+        * **Time Horizon**: "Are you interested in historical data, current status, or future projections?"
+        * **Priority**: "Which aspect of this question is most important to you?"
+        """.strip(),
         )
-    except (ValueError, RuntimeError) as e:
-        print(f"Failed to create agent: {e}")
+    except Exception as e:
+        console.print(f"[red]✗ Agent creation failed: {e}[/red]")
         raise RuntimeError(f"Agent creation failed: {e}")
 
 
+def _load_model_with_fallback(model_id: str) -> Any:
+    """
+    Attempt to load the specified model with fallbacks if it fails.
+
+    Args:
+        model_id: Primary model ID to try loading
+
+    Returns:
+        Loaded model instance
+
+    Raises:
+        RuntimeError: If all model loading attempts fail
+    """
+    # Fallback model chain from most capable to most reliable
+    fallback_models = [
+        model_id,  # Try the requested model first
+        "openrouter/anthropic/claude-3.7-sonnet",
+        "openai/gpt-4o-mini",
+        "anthropic/claude-3.7-sonnet",
+        "HuggingFaceTB/SmolLM2-1.7B-Instruct",  # Last resort local option
+    ]
+
+    last_error = None
+    for model in fallback_models:
+        try:
+            return LiteLLMModel(
+                custom_role_conversions=CUSTOM_ROLE_CONVERSIONS,
+                model_id=model,
+            )
+        except Exception as e:
+            last_error = e
+            console.print(f"[yellow]Failed to load model {model}: {e}[/yellow]")
+
+    # If we get here, all models failed
+    raise RuntimeError(f"All model loading attempts failed. Last error: {last_error}")
+
+
+def _validate_tools(tools):
+    """
+    Validate that all tools are proper Tool instances.
+
+    Args:
+        tools: List of tools to validate
+
+    Raises:
+        ValueError: If any tool is not a Tool instance
+    """
+    for tool in tools:
+        if not isinstance(tool, Tool):
+            raise ValueError(
+                f"Invalid tool type: {type(tool)}. "
+                f"All tools must be instances of Tool class."
+            )
+
+
+# ------------------------ Gradio UI Components ------------------------
+
+
 def stream_to_gradio(
     agent,
     task: str,
     reset_agent_memory: bool = False,
     additional_args: Optional[dict] = None,
 ):
-    """Runs an agent with the given task and streams messages as Gradio ChatMessages."""
-    for step_log in agent.run(
-        task, stream=True, reset=reset_agent_memory, additional_args=additional_args
-    ):
-        for message in pull_messages_from_step(step_log):
-            yield message
+    """Streams agent responses with improved status indicators."""
+    try:
+        # Initial processing indicator
+        yield gr.ChatMessage(role="assistant", content="⏳ Processing your request...")
+
+        # Track what we've yielded to replace the processing indicator
+        first_message_yielded = False
+
+        for step_log in agent.run(
+            task, stream=True, reset=reset_agent_memory, additional_args=additional_args
+        ):
+            # The key fix: pull_messages_from_step is a generator function that yields messages
+            # We need to iterate through each yielded message
+            for message in pull_messages_from_step(step_log):
+                if not first_message_yielded:
+                    # Replace the initial "Processing" message
+                    first_message_yielded = True
+                    message.content = message.content.replace(
+                        "⏳ Processing your request...", ""
+                    )
 
-    # Process final answer : Use a more comprehensive media output
-    final_answer = step_log  # Last log is the run's final_answer
-    final_answer = handle_agent_output_types(final_answer)
+                # Check what type of operation is being performed based on the metadata or content
+                # Instead of trying to access a 'status' attribute that doesn't exist
+                content_lower = (
+                    message.content.lower() if hasattr(message, "content") else ""
+                )
 
-    if isinstance(final_answer, AgentText):
-        yield gr.ChatMessage(
-            role="assistant",
-            content=f"**Final answer:**\n{final_answer.to_string()}\n",
-        )
-    if isinstance(final_answer, AgentImage):
-        yield gr.ChatMessage(
-            role="assistant",
-            content={"image": final_answer.to_string(), "type": "file"},
-        )  # Send as Gradio-compatible file object:
-    if isinstance(final_answer, AgentAudio):
+                if "document analysis" in content_lower:
+                    message.content = f"📄 **Document Analysis:** {message.content}"
+                elif "search" in content_lower:
+                    message.content = f"🔍 **Search:** {message.content}"
+
+                yield message
+
+        # Final answer with enhanced formatting
+        final_answer = handle_agent_output_types(step_log)
+
+        if isinstance(final_answer, AgentText):
+            yield gr.ChatMessage(
+                role="assistant",
+                content=f"✅ **Final Answer:**\n\n{final_answer.to_string()}",
+            )
+        else:
+            yield gr.ChatMessage(
+                role="assistant", content=f"✅ **Final Answer:** {str(final_answer)}"
+            )
+
+    except Exception as e:
         yield gr.ChatMessage(
             role="assistant",
-            content={"audio": final_answer.to_string(), "type": "file"},
-        )  # Send as Gradio-compatible file object
-    else:
-        yield gr.ChatMessage(
-            role="assistant", content=f"**Final answer:** {str(final_answer)}"
+            content=f"❌ **Error:** {str(e)}\n\nPlease try again with a different query.",
         )
 
 
@@ -313,20 +682,37 @@ class GradioUI:
             if not os.path.exists(file_upload_folder):
                 os.mkdir(file_upload_folder)
 
-    def interact_with_agent(self, prompt, messages, session_state):
-        """Main interaction handler with the agent."""
+    def interact_with_agent(
+        self,
+        prompt: str,
+        messages: List[gr.ChatMessage],
+        session_state: Dict[str, Any],
+    ) -> Generator[List[gr.ChatMessage], None, None]:
+        """Main interaction handler with the agent.
+
+        Args:
+            prompt: The user's input prompt
+            messages: The list of messages so far (including the user's prompt)
+            session_state: The current state of the user's session
+
+        Yields:
+            A list of messages after each step (including the user's prompt)
+        """
 
         # Get or create session-specific agent
         if "agent" not in session_state:
-            session_state["agent"] = create_agent()
+            model_id = session_state.get(
+                "model_id", "openrouter/google/gemini-2.0-flash-001"
+            )
+            session_state["agent"] = create_agent(model_id)
 
         # Adding monitoring
         try:
             # Log the existence of agent memory
             has_memory = hasattr(session_state["agent"], "memory")
-            print(f"Agent has memory: {has_memory}")
+            console.print(f"Agent has memory: {has_memory}")
             if has_memory:
-                print(f"Memory type: {type(session_state['agent'].memory)}")
+                console.print(f"Memory type: {type(session_state['agent'].memory)}")
 
             messages.append(gr.ChatMessage(role="user", content=prompt))
             yield messages
@@ -339,7 +725,7 @@ class GradioUI:
             yield messages  # Yield messages one last time
 
         except Exception as e:
-            print(f"Error in interaction: {str(e)}")
+            console.print(f"[red]Error in interaction: {str(e)}[/red]")
             raise
 
     def upload_file(
@@ -448,7 +834,7 @@ class GradioUI:
             @gr.render()
             def layout(request: gr.Request):
                 device = self.detect_device(request)
-                print(f"device - {device}")
+                console.print(f"device - {device}")
                 # Render layout with sidebar
                 if device == "Desktop":
                     return self._create_desktop_layout()
@@ -464,7 +850,7 @@ class GradioUI:
             with gr.Sidebar():
                 gr.Markdown(
                     """#OpenDeepResearch - 3theSmolagents!
-                Model_id: google/gemini-2.0-flash-001"""
+                Model_id: deepseek/deepseek-r1"""
                 )
                 with gr.Group():
                     gr.Markdown("**What's on your mind mate?**", container=True)
@@ -635,18 +1021,75 @@ class GradioUI:
         )
 
 
-# ------------------------ Execution ------------------------
-def main():
-    """Main entry point for the application."""
-    # Initialize environment
+# ------------------------ CLI Command ------------------------
+@app.command()
+def run(
+    mode: str = typer.Option(
+        "ui",
+        "--mode",
+        "-m",
+        help="Operating mode: 'ui' for Gradio interface or 'headless' for CLI mode",
+    ),
+    model_id: str = typer.Option(
+        "openrouter/google/gemini-2.0-flash-001",
+        "--model",
+        help="Model ID to use for the agent",
+    ),
+    query: Optional[str] = typer.Option(
+        None, "--query", "-q", help="Query to execute (required in headless mode)"
+    ),
+):
+    """
+    Run the financial research agent in either UI or headless mode.
+
+    In UI mode, launches a Gradio interface for interactive use.
+    In headless mode, processes a single query and outputs the result to the console.
+    """
+    # Setup environment variables
     setup_environment()
 
-    # Ensure downloads folder exists
-    os.makedirs(f"./{BROWSER_CONFIG['downloads_folder']}", exist_ok=True)
+    # Validate inputs for headless mode
+    if mode == "headless" and not query:
+        console.print("[red]Error: query parameter is required in headless mode[/red]")
+        raise typer.Exit(code=1)
+
+    # Create agent with specified model ID
+    console.print(f"[bold]Initializing agent with model:[/bold] {model_id}")
+
+    # Execute in appropriate mode
+    if mode == "ui":
+        console.print(
+            "[bold green]Starting UI mode with Gradio interface...[/bold green]"
+        )
+
+        # Ensure downloads folder exists
+        os.makedirs(f"./{BROWSER_CONFIG['downloads_folder']}", exist_ok=True)
+
+        # Launch UI
+        GradioUI(file_upload_folder="data/uploaded_files").launch()
+
+    elif mode == "headless":
+        console.print(f"[bold]Processing query in headless mode:[/bold] {query}")
+
+        # Create agent for headless mode
+        agent = create_agent(model_id)
 
-    # Launch UI
-    GradioUI(file_upload_folder="uploaded_files").launch()
+        # Show a simple spinner during processing
+        with console.status("[bold green]Processing query...[/bold green]"):
+            result = agent.run(query)
+
+        # Display the results
+        console.print("\n[bold green]Results:[/bold green]")
+        console.print(result)
+
+    else:
+        console.print(
+            f"[red]Error: Invalid mode '{mode}'. Use 'ui' or 'headless'[/red]"
+        )
+        raise typer.Exit(code=1)
 
 
+# ------------------------ Main Entry Point ------------------------
 if __name__ == "__main__":
-    main()
+    # Use the typer app as the entry point
+    app()

requirements.txt

@@ -1,13 +1,9 @@
+smolagents[litellm, telemetry]
 anthropic>=0.37.1
 beautifulsoup4>=4.12.3
-Bio
-chess
-clean-text[gpl]
 datasets>=2.21.0
 google_search_results>=2.4.2
 huggingface_hub>=0.23.4
-llama-index
-llama-index-embeddings-huggingface
 mammoth>=1.8.0
 markdownify>=0.13.1
 numexpr>=2.10.1
@@ -19,25 +15,26 @@ pathvalidate>=3.2.1
 pdfminer>=20191125
 pdfminer.six>=20240706
 Pillow>=11.0.0
-pubchempy
 puremagic>=1.28
-pydub
-PyPDF2
+pypdf>=5.1.0
 python-dotenv>=1.0.1
 python_pptx>=1.0.2
-python-pptx
 Requests>=2.32.3
-scikit-learn
-scikit-learn
-scipy
 serpapi>=0.1.5
-smolagents[gradio, langchain, litellm, telemetry]
-SpeechRecognition
-sympy
+tqdm>=4.66.4
 torch>=2.2.2
 torchvision>=0.17.2
-tqdm>=4.66.4
-tqdm
 transformers>=4.46.0
-xlrd
 youtube_transcript_api>=0.6.2
+chess
+sympy
+pubchempy
+Bio
+scikit-learn
+scipy
+pydub
+PyPDF2
+python-pptx
+torch
+xlrd
+SpeechRecognition

scripts/cookies.py

@@ -1,6 +1,5 @@
 from requests.cookies import RequestsCookieJar
 
-
 COOKIES_LIST = [
     {
         "domain": ".youtube.com",
@@ -712,4 +711,6 @@ COOKIES = RequestsCookieJar()
 
 # Add cookies to the jar
 for cookie in COOKIES_LIST:
-    COOKIES.set(cookie["name"], cookie["value"], domain=cookie["domain"], path=cookie["path"])
+    COOKIES.set(
+        cookie["name"], cookie["value"], domain=cookie["domain"], path=cookie["path"]
+    )

scripts/finance_tools.py

@@ -0,0 +1,987 @@
+#!/usr/bin/env python
+# coding=utf-8
+# Copyright 2024 The Footscray Coding Collective. All rights reserved.
+"""
+Financial Data and Analysis Tools
+--------------------------------------
+A comprehensive suite of tools for retrieving financial market data through the Alpha Vantage API.
+These tools enable accessing real-time stock quotes, company fundamentals, financial statements,
+price history, market news, and sentiment analysis with proper error handling and caching.
+
+The Alpha Vantage tools follow the Zhou Protocol for financial data retrieval:
+- Singleton pattern for API client management
+- Comprehensive error handling with failed request tracking
+- In-memory request caching to minimize API usage
+- Detailed docstrings with usage examples
+
+Key Financial Tools:
+- search_symbols: Find ticker symbols for companies by keywords
+- get_stock_quote_data: Real-time stock quote information
+- get_company_overview_data: Company profiles and fundamentals
+- get_earnings_data: Quarterly and annual earnings information
+- get_income_statement_data: Income statement analysis
+- get_balance_sheet_data: Balance sheet information
+- get_cash_flow_data: Cash flow statement analysis
+- get_time_series_daily: Historical price and volume data
+- get_market_news_sentiment: News and sentiment analysis
+
+Financial Analysis Tools:
+- FinancialCalculatorTool: Calculate financial metrics (growth rates, margins, CAGR)
+- DataVisualizationTool: Generate visual representations of financial data
+- TrendAnalysisTool: Perform year-over-year trend analysis on financial metrics
+"""
+
+import io
+import logging
+import os
+import traceback
+from typing import Any, Dict, Optional, Set
+
+# Third-party imports in alphabetical order with dotenv first
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ImportError:
+    pass
+
+import matplotlib.pyplot as plt  # Plot the chart
+import pandas as pd  # Store dataframe
+import requests
+from smolagents import Tool, tool
+
+
+class AlphaVantageClient:
+    """Centralized client for Alpha Vantage API requests with caching and error handling."""
+
+    def __init__(self):
+        """Initialize the client with empty caches."""
+        self._api_key: Optional[str] = None
+        self._failed_requests: Set[str] = set()
+        self._data_cache: Dict[str, Dict[str, Any]] = {}
+
+    def get_api_key(self) -> str:
+        """
+        Get Alpha Vantage API key from environment or cache.
+
+        Returns:
+            API key string or error message
+        """
+        if self._api_key:
+            return self._api_key
+
+        api_key = os.getenv("ALPHA_VANTAGE_API_KEY")
+        if not api_key:
+            return "Error: No API key found. Set ALPHA_VANTAGE_API_KEY in your environment."
+
+        self._api_key = api_key
+        return api_key
+
+    def make_request(self, function: str, symbol: str, **params: Any) -> Dict[str, Any]:
+        """
+        Make a request to Alpha Vantage API with error handling and caching.
+
+        Args:
+            function (str): API function name
+            symbol (str): Stock symbol
+            **params (Any): Additional parameters for the request, excluding 'function' and 'symbol'
+
+        Returns:
+            Dict[str, Any]: Raw JSON response data
+        """
+        # Validate params
+        if "function" in params or "symbol" in params:
+            raise ValueError("function and symbol should not be included in params")
+
+        # Generate cache key
+        cache_key = f"{function}:{symbol}:{hash(frozenset(params.items()))}"
+
+        # Return cached data if available
+        if cache_key in self._data_cache:
+            return self._data_cache[cache_key]
+
+        # Check if this request has failed before
+        if cache_key in self._failed_requests:
+            return {
+                "Error": f"Previously failed request for {symbol} with function {function}"
+            }
+
+        # Get API key
+        api_key = self.get_api_key()
+        if api_key.startswith("Error:"):
+            return {"Error Message": api_key}
+
+        # Build request URL and parameters
+        url = "https://www.alphavantage.co/query"
+        request_params = {
+            "function": function,
+            "symbol": symbol,
+            "apikey": api_key,
+            **params,
+        }
+
+        try:
+            # Make request with timeout for responsiveness
+            response = requests.get(url, params=request_params, timeout=10)
+            response.raise_for_status()
+            data = response.json()
+
+            # Check for API errors
+            if "Error Message" in data or "Information" in data or not data:
+                self._failed_requests.add(cache_key)
+                return data
+
+            # Cache successful response
+            self._data_cache[cache_key] = data
+            return data
+
+        except requests.RequestException as e:
+            error_data = {"Error Message": f"API request failed: {str(e)}"}
+            self._failed_requests.add(cache_key)
+            return error_data
+        except ValueError as e:
+            error_data = {"Error Message": f"Failed to parse response: {str(e)}"}
+            self._failed_requests.add(cache_key)
+            return error_data
+
+    def clear_cache(
+        self, function: Optional[str] = None, symbol: Optional[str] = None
+    ) -> None:
+        """
+        Clear the data cache, optionally filtering by function and/or symbol.
+
+        Args:
+            function: Optional function name to filter cache entries
+            symbol: Optional symbol to filter cache entries
+        """
+        if not function and not symbol:
+            self._data_cache.clear()
+            return
+
+        keys_to_remove = []
+        for key in self._data_cache:
+            parts = key.split(":")
+            if function and parts[0] != function:
+                continue
+            if symbol and parts[1] != symbol:
+                continue
+            keys_to_remove.append(key)
+
+        for key in keys_to_remove:
+            del self._data_cache[key]
+
+
+# Create a singleton instance of the client
+_client = AlphaVantageClient()
+
+
+@tool
+def get_stock_quote_data(symbol: str) -> Dict[str, Any]:
+    """
+    Retrieve raw real-time stock quote information from Alpha Vantage.
+
+    This tool fetches current market data for a specified stock ticker,
+    returning the raw data for custom processing and analysis.
+
+    Args:
+        symbol: The stock ticker symbol (e.g., 'AAPL', 'MSFT', 'IBM')
+
+    Returns:
+        Raw JSON data containing:
+        - Global Quote object with price, volume, and trading information
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get raw quote data
+        data = get_stock_quote_data("MSFT")
+
+        # Extract price
+        if "Global Quote" in data:
+            quote = data["Global Quote"]
+            price = float(quote.get("05. price", 0))
+            change = float(quote.get("09. change", 0))
+            print(f"MSFT: ${price:.2f} ({change:+.2f})")
+        ```
+    """
+    return _client.make_request("GLOBAL_QUOTE", symbol)
+
+
+@tool
+def get_company_overview_data(symbol: str) -> Dict[str, Any]:
+    """
+    Retrieve raw company information and metrics from Alpha Vantage.
+
+    This tool provides comprehensive information about a company, returning
+    raw data for custom analysis and presentation.
+
+    Args:
+        symbol: The stock ticker symbol (e.g., 'AAPL', 'MSFT', 'IBM')
+
+    Returns:
+        Raw JSON data containing:
+        - Company profile (name, sector, industry)
+        - Financial metrics (market cap, P/E ratio, etc.)
+        - Performance indicators (ROE, ROA, etc.)
+        - Company description
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get company data
+        data = get_company_overview_data("AAPL")
+
+        # Create custom analysis
+        if "Sector" in data:
+            sector = data.get("Sector")
+            market_cap = float(data.get("MarketCapitalization", 0))
+            pe_ratio = float(data.get("PERatio", 0))
+
+            print(f"AAPL is in the {sector} sector")
+            print(f"Market Cap: ${market_cap/1e9:.2f}B")
+            print(f"P/E Ratio: {pe_ratio:.2f}")
+        ```
+    """
+    return _client.make_request("OVERVIEW", symbol)
+
+
+@tool
+def get_earnings_data(symbol: str) -> Dict[str, Any]:
+    """
+    Retrieve raw earnings data for a company from Alpha Vantage.
+
+    This tool fetches quarterly and annual earnings data, returning
+    raw information for custom analysis and trend evaluation.
+
+    Args:
+        symbol: The stock ticker symbol (e.g., 'AAPL', 'MSFT', 'IBM')
+
+    Returns:
+        Raw JSON data containing:
+        - quarterlyEarnings array with fiscal dates, reported EPS, and surprises
+        - annualEarnings array with yearly EPS figures
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get earnings data
+        data = get_earnings_data("MSFT")
+
+        # Analyze earnings surprises
+        if "quarterlyEarnings" in data:
+            quarterly = data["quarterlyEarnings"]
+
+            # Calculate average earnings surprise percentage
+            surprises = [float(q.get("surprisePercentage", 0)) for q in quarterly[:4]]
+            avg_surprise = sum(surprises) / len(surprises)
+
+            print(f"Average earnings surprise (last 4Q): {avg_surprise:.2f}%")
+
+            # Find biggest positive surprise
+            max_surprise = max(surprises)
+            print(f"Largest positive surprise: {max_surprise:.2f}%")
+        ```
+    """
+    return _client.make_request("EARNINGS", symbol)
+
+
+@tool
+def get_income_statement_data(symbol: str) -> Dict[str, Any]:
+    """
+    Retrieve raw income statement data for a company from Alpha Vantage.
+
+    This tool fetches annual and quarterly income statements, returning
+    raw financial data for custom analysis and profit trend evaluation.
+
+    Args:
+        symbol: The stock ticker symbol (e.g., 'AAPL', 'MSFT', 'IBM')
+
+    Returns:
+        Raw JSON data containing:
+        - annualReports array with yearly income statements
+        - quarterlyReports array with quarterly income statements
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get income statement data
+        data = get_income_statement_data("AAPL")
+
+        # Analyze profitability trends
+        if "annualReports" in data and len(data["annualReports"]) >= 3:
+            reports = data["annualReports"][:3]  # Last 3 years
+
+            # Extract revenue and profit
+            revenues = [float(r.get("totalRevenue", 0)) for r in reports]
+            net_incomes = [float(r.get("netIncome", 0)) for r in reports]
+
+            # Calculate profit margins
+            margins = [ni/rev*100 if rev else 0 for ni, rev in zip(net_incomes, revenues)]
+
+            for i, margin in enumerate(margins):
+                year = reports[i].get("fiscalDateEnding", "Unknown")
+                print(f"{year}: Profit margin = {margin:.2f}%")
+        ```
+    """
+    return _client.make_request("INCOME_STATEMENT", symbol)
+
+
+@tool
+def get_balance_sheet_data(symbol: str) -> Dict[str, Any]:
+    """
+    Retrieve raw balance sheet data for a company from Alpha Vantage.
+
+    This tool fetches annual and quarterly balance sheets, returning
+    raw financial data for custom analysis of a company's financial position.
+
+    Args:
+        symbol: The stock ticker symbol (e.g., 'AAPL', 'MSFT', 'IBM')
+
+    Returns:
+        Raw JSON data containing:
+        - annualReports array with yearly balance sheets
+        - quarterlyReports array with quarterly balance sheets
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get balance sheet data
+        data = get_balance_sheet_data("MSFT")
+
+        # Calculate debt-to-equity ratio
+        if "annualReports" in data and data["annualReports"]:
+            latest = data["annualReports"][0]
+
+            total_debt = float(latest.get("shortTermDebt", 0)) + float(latest.get("longTermDebt", 0))
+            equity = float(latest.get("totalShareholderEquity", 0))
+
+            if equity:
+                debt_to_equity = total_debt / equity
+                print(f"Debt-to-Equity Ratio: {debt_to_equity:.2f}")
+
+            # Calculate current ratio
+            current_assets = float(latest.get("totalCurrentAssets", 0))
+            current_liabilities = float(latest.get("totalCurrentLiabilities", 0))
+
+            if current_liabilities:
+                current_ratio = current_assets / current_liabilities
+                print(f"Current Ratio: {current_ratio:.2f}")
+        ```
+    """
+    return _client.make_request("BALANCE_SHEET", symbol)
+
+
+@tool
+def get_cash_flow_data(symbol: str) -> Dict[str, Any]:
+    """
+    Retrieve raw cash flow statement data for a company from Alpha Vantage.
+
+    This tool fetches annual and quarterly cash flow statements, returning
+    raw financial data for analyzing a company's cash generation and usage.
+
+    Args:
+        symbol: The stock ticker symbol (e.g., 'AAPL', 'MSFT', 'IBM')
+
+    Returns:
+        Raw JSON data containing:
+        - annualReports array with yearly cash flow statements
+        - quarterlyReports array with quarterly cash flow statements
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get cash flow data
+        data = get_cash_flow_data("AMZN")
+
+        # Analyze free cash flow
+        if "annualReports" in data and data["annualReports"]:
+            reports = data["annualReports"][:3]  # Last 3 years
+
+            for report in reports:
+                year = report.get("fiscalDateEnding", "Unknown")
+                operating_cf = float(report.get("operatingCashflow", 0))
+                capex = float(report.get("capitalExpenditures", 0))
+
+                # Free cash flow = Operating cash flow - Capital expenditures
+                free_cf = operating_cf - abs(capex)
+
+                print(f"{year}: Free Cash Flow = ${free_cf/1e9:.2f}B")
+        ```
+    """
+    return _client.make_request("CASH_FLOW", symbol)
+
+
+@tool
+def get_time_series_daily(symbol: str, outputsize: str = "compact") -> Dict[str, Any]:
+    """
+    Retrieve daily time series stock price data from Alpha Vantage.
+
+    This tool fetches historical daily OHLCV (Open, High, Low, Close, Volume) data
+    for specified ticker symbols, supporting both compact (100 data points) and
+    full (20+ years) history.
+
+    Args:
+        symbol: The stock ticker symbol (e.g., 'AAPL', 'MSFT', 'IBM')
+        outputsize: Data size, either 'compact' (last 100 points) or 'full' (20+ years)
+
+    Returns:
+        Raw JSON data containing:
+        - "Meta Data" object with information about the data series
+        - "Time Series (Daily)" object with date-keyed OHLCV data points
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get daily prices (compact = last 100 days)
+        data = get_time_series_daily("TSLA")
+
+        # Calculate moving averages
+        if "Time Series (Daily)" in data:
+            time_series = data["Time Series (Daily)"]
+            dates = sorted(time_series.keys())
+
+            # Extract closing prices
+            prices = [float(time_series[date]["4. close"]) for date in dates]
+
+            # Calculate 20-day moving average
+            if len(prices) >= 20:
+                ma_20 = sum(prices[-20:]) / 20
+                print(f"20-day Moving Average: ${ma_20:.2f}")
+
+                # Get latest price
+                latest_price = prices[-1]
+                print(f"Latest price: ${latest_price:.2f}")
+
+                # Compare to moving average
+                diff_pct = (latest_price / ma_20 - 1) * 100
+                print(f"Price is {diff_pct:+.2f}% from 20-day MA")
+        ```
+    """
+    return _client.make_request("TIME_SERIES_DAILY", symbol, outputsize=outputsize)
+
+
+# Ensure that the default value IS specified
+@tool
+def search_symbols(keywords: str) -> Dict[str, Any]:
+    """
+    [FINANCIAL DISCOVERY] Search for stock symbols matching the provided keywords.
+
+    WHEN TO USE: ALWAYS use this tool FIRST when you don't know the exact stock symbol for a company.
+
+    This tool helps find relevant ticker symbols when you don't know the exact symbol,
+    matching companies by name, description, or partial symbols.
+
+    Args:
+        keywords: Search term (e.g., 'microsoft', 'tech', 'MSFT')
+
+    Returns:
+        Raw JSON data containing:
+        - bestMatches array with matching companies (symbol, name, type, region)
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Search for companies related to "electric vehicles"
+        results = search_symbols("electric vehicles")
+
+        # Print matched symbols and names
+        if "bestMatches" in results:
+            matches = results["bestMatches"]
+
+            print(f"Found {len(matches)} matches:")
+            for match in matches:
+                symbol = match.get("1. symbol", "")
+                name = match.get("2. name", "")
+                market = match.get("4. region", "")
+
+                print(f"{symbol} - {name} ({market})")
+        ```
+    """
+    return _client.make_request("SYMBOL_SEARCH", "", keywords=keywords)
+
+
+@tool
+def clear_api_cache() -> str:
+    """
+    Clear all cached API data to force fresh requests.
+
+    Returns:
+        Confirmation message
+    """
+    _client._data_cache.clear()
+    return "API cache cleared successfully."
+
+
+@tool
+def get_market_news_sentiment(
+    tickers: Optional[str] = None,
+    topics: Optional[str] = None,
+    time_from: Optional[str] = None,
+    time_to: Optional[str] = None,
+    sort: str = "LATEST",
+    limit: int = 50,
+) -> Dict[str, Any]:
+    """
+    Retrieve market news and sentiment data from Alpha Vantage.
+
+    This tool fetches live and historical market news with sentiment analysis from premier
+    news outlets worldwide, covering stocks, cryptocurrencies, forex, and various market topics.
+
+    Args:
+        tickers: Optional comma-separated list of symbols (e.g., 'AAPL,MSFT' or 'COIN,CRYPTO:BTC,FOREX:USD')
+        topics: Optional comma-separated list of news topics (e.g., 'technology,ipo')
+                Available topics: blockchain, earnings, ipo, mergers_and_acquisitions, financial_markets,
+                economy_fiscal, economy_monetary, economy_macro, energy_transportation, finance,
+                life_sciences, manufacturing, real_estate, retail_wholesale, technology
+        time_from: Optional start time in YYYYMMDDTHHMM format (e.g., '20220410T0130')
+        time_to: Optional end time in YYYYMMDDTHHMM format
+        sort: Sorting order - 'LATEST' (default), 'EARLIEST', or 'RELEVANCE'
+        limit: Maximum number of results to return (default: 50, max: 1000)
+
+    Returns:
+        Raw JSON data containing:
+        - feed: Array of news articles with title, summary, url, time_published, authors, and more
+        - sentiment scores for each article (if available)
+        - Error information if the request failed
+
+    Example:
+        ```python
+        # Get latest news about Apple
+        apple_news = get_market_news_sentiment(tickers="AAPL")
+
+        # Get news articles at the intersection of technology and IPOs
+        tech_ipo_news = get_market_news_sentiment(topics="technology,ipo")
+
+        # Get Bitcoin news from a specific time period
+        btc_news = get_market_news_sentiment(
+            tickers="CRYPTO:BTC",
+            time_from="20230101T0000",
+            time_to="20230201T0000"
+        )
+
+        # Process the sentiment data
+        if "feed" in apple_news:
+            for article in apple_news["feed"]:
+                title = article.get("title", "No title")
+                sentiment = article.get("overall_sentiment_score", "N/A")
+                print(f"Article: {title} | Sentiment: {sentiment}")
+        ```
+    """
+    params = {
+        "function": "NEWS_SENTIMENT",
+    }
+
+    # Add optional parameters
+    if tickers:
+        params["tickers"] = tickers
+    if topics:
+        params["topics"] = topics
+    if time_from:
+        params["time_from"] = time_from
+    if time_to:
+        params["time_to"] = time_to
+    if sort:
+        params["sort"] = sort
+    if limit:
+        params["limit"] = limit
+
+    return _client.make_request("NEWS_SENTIMENT", "", **params)
+
+
+"""Example functions to be used in the tools and called by the agent"""
+
+
+class FinancialCalculatorTool(Tool):
+    """
+    Performs various financial calculations, given structured data from a table.
+    Useful for calculating growth rates, financial ratios, and other key metrics.
+    The tool can directly perform calculations on the data for numerical answers.
+    """
+
+    name = "financial_calculator"
+    description = """
+    Performs various financial calculations, given structured data from a table.
+    Useful for calculating growth rates, financial ratios, and other key metrics.
+    The tool can directly perform calculations on the data for numerical answers.
+
+    Input:
+        - `data` (str): A string representing table data (e.g., CSV, markdown table).
+        - `calculation_type` (str): The type of calculation to perform, such as 'growth_rate', 'profit_margin', 'debt_to_equity'.
+        - `year1`, `year2`, `metric` (str): Parameters for "growth", e.g., "2020", "2021", "Revenue".
+        - `year`, `revenue`, `netIncome`(str): Parameters for 'Profit_Margin', e.g. "2023", "10000", "1000".
+        - `year`, `totalDebt`, `totalEquity` (str): Parameters for 'Debt_To_Equity', e.g. "2023", "5000", "10000".
+        - `startYear`, `endYear`, `metric"(str): Parametes for "CAGR", e.g. "2020", "2025", "Revenue"
+
+    Output:
+        - `calculation_result` (str): The result of the financial calculation as a string, to two decimals points.
+                                     This ensures the agent can understand and utilize the output effectively.
+    """
+
+    inputs = {
+        "data": {
+            "type": "string",
+            "description": "A string representing table data. Must be in CSV format with a header row.",
+        },
+        "calculation_type": {
+            "type": "string",
+            "description": "The type of calculation to perform.  Must be one of the following exactly: 'growth_rate', 'profit_margin', 'debt_to_equity', 'CAGR'.",
+        },
+        "year1": {
+            "type": "string",
+            "description": "Year 1 for growth rate calculation, as a string.",
+            "nullable": True,
+        },
+        "metric": {
+            "type": "string",
+            "description": "Valid CSV Header to compare, for growth. MUST correspond to the appropriate header in dataset.",
+            "nullable": True,
+        },
+        "year2": {
+            "type": "string",
+            "description": "Year 2 for growth rate calculation, as a string. Make sure that is a valid CSV Header.",
+            "nullable": True,
+        },
+        "revenue": {
+            "type": "string",
+            "description": "Revenue for the fiscal year profit calculation (as a string).",
+            "nullable": True,
+        },
+        "netIncome": {
+            "type": "string",
+            "description": "Must be Valid Valid Net income for the fiscal year profit margin calculation, in string format",
+            "nullable": True,
+        },
+        "endYear": {
+            "type": "string",
+            "description": "Year 2 string for the CAGR function",
+            "nullable": True,
+        },
+        "year": {
+            "type": "string",
+            "description": "Valid Year",
+            "nullable": True,
+        },
+        "startYear": {
+            "type": "string",
+            "description": "Year 1,  string for the CAGR function",
+            "nullable": True,
+        },
+        "totalAssets": {
+            "type": "string",
+            "description": "The Total assets data in string format",
+            "nullable": True,
+        },
+        "totalDebt": {
+            "type": "string",
+            "description": "The total debt data in string.",
+            "nullable": True,
+        },
+        "totalEquity": {
+            "type": "string",
+            "description": "The Total Shareholders Equity in string format",
+            "nullable": True,
+        },
+    }
+    output_type = "string"
+
+    def forward(
+        self,
+        data: str,  # A string representing the data. Must be a valid CSV
+        calculation_type: str,  # type of calculation you'd like to do with the data
+        year1: Optional[str] = None,  # Year1, all string types
+        metric: Optional[str] = None,  # metric, all string types
+        year2: Optional[str] = None,  # Year2, all string types
+        revenue: Optional[str] = None,  # Revenue, all string types
+        netIncome: Optional[str] = None,  # Net income, all string types
+        endYear: Optional[str] = None,  # Year 2 string for the CAGR function
+        year: Optional[str] = None,  # Valid Year
+        startYear: Optional[str] = None,  # Year 1,  string for the CAGR function
+        totalAssets: Optional[str] = None,  # The Total assets data in string format
+        totalDebt: Optional[str] = None,  # The total debt data in string.
+        totalEquity: Optional[
+            str
+        ] = None,  # The Total Shareholders Equity in string format
+    ) -> str:
+        """
+        Performs the specified financial calculation.
+        Args:
+            data: A string representing the dat. Must be a valid CSV
+            calculation_type: type of calculation you'd like to do with the data
+            year1: Year1, all string types
+            year2: Year2, all string types
+            metric: metric, all string types
+
+        Returns:
+            A string representing the result of the calculation. If an error occurs, the string will start with "Error: "
+        """
+        try:
+            df = pd.read_csv(io.StringIO(data))
+        except Exception as e:
+            return f"Error reading data: {e}. Ensure that the input provided is a valid csv, AND has headers (no comments or empty rows)."
+
+        try:
+            if calculation_type == "growth_rate":
+                if not (year1 and year2 and metric):
+                    return "Error: Missing year1, year2, or metric for growth_rate calculation."
+
+                value1 = df.loc[df["Year"] == year1][metric].values[0]
+                value2 = df.loc[df["Year"] == year2][metric].values[0]
+
+                growth_rate = ((value2 - value1) / value1) * 100
+                return f"{growth_rate:.2f}%"
+
+            elif calculation_type == "profit_margin":
+                if not year or not revenue or not netIncome:
+                    return "Error: Missing year for profit_margin calculation"
+
+                # revenue = df.loc[df['Year'] == year]['Revenue'].values[0]  # Replace with your actual data columns
+                # net_income = df.loc[df['Year'] == year]['Net Income'].values[0] # This can also be EBIT or operating profit or whatever
+
+                profit_margin = (float(netIncome) / float(revenue)) * 100
+                return f"{profit_margin:.2f}%"
+
+            elif calculation_type == "debt_to_equity":
+                if not year or not totalDebt or not totalEquity:
+                    return "Error: Missing year for debt_to_equity calculation"
+
+                # total_debt = df.loc[df['Year'] == year]['Total Debt'].values[0] # Could be short term or long term
+                # total_equity = df.loc[df['Year'] == year]['Total Equity'].values[0] # Could be share holders equity?
+
+                debt_to_equity = float(totalDebt) / float(totalEquity)
+                return f"{debt_to_equity:.2f}"
+            elif calculation_type == "CAGR":
+
+                if not (startYear and endYear and metric):
+                    return "Error: Missing startYear, endYear, or metric for CAGR calculation."
+
+                try:  # Make the CSV valid
+                    start_value = float(
+                        df[df["Year"] == startYear][metric].values[0]
+                    )  # float(start_value) #df[df.columns[1]] #["Start Value"].values[0]
+                    end_value = float(
+                        df[df["Year"] == endYear][metric].values[0]
+                    )  # float(end_value) # float(raw[0]) #df[df.columns[1]] #["End Value"].values[0]# CSV
+                except Exception as exception:
+                    return f"start value {df[df['Year'] == startYear][metric].values[0]}  endvalue {df[df['Year'] == endYear][metric].values[0]}. start and end values are not valid headers! Ensure CSV Headers are there, and they're valid. OriginalException{exception}"
+                try:  # check to confirm the calculations work by converting them to float
+                    n = int(endYear) - int(startYear)
+                    cagr = (end_value / start_value) ** (1 / n) - 1
+                    return f"{cagr:.2f}"  # f"EndValue {endYear2:.2f} Startvalue {startYear2:.2f}"
+                except Exception:
+                    return f"start year {startYear} end year {endYear}  Startvalue {start_value} end value {end_value}. Year calcs invalid! Invalid CSV"
+
+            else:
+                return f"Error: Unsupported Calculation Type: {calculation_type}.  Consider growth_rate, profit_margin, debt_to_equity, CAGR."
+        except Exception as e:
+            return f"Error performing calculation: {e}"
+
+
+class DataVisualizationTool(Tool):
+    """
+    Generates visualizations (charts, graphs) from structured data to help identify trends.
+    Be thoughtful about the data AND type of graph: they must match.
+    You CANNOT import things other than csv, so make sure to follow the instructions.
+    """
+
+    name = "data_visualization"
+    description = """
+    Generates visualizations (charts, graphs) from structured data to help identify trends. Be thoughtful about the data AND type of graph: they must match. You CANNOT import things other than csv, so make sure to follow the instructions.
+
+    Input:
+        - `data` (str): A valid CSV string, that represents values to graph: MUST start with a HEADER row, then be followed by valid csv syntax
+        - `chart_type` (str): The type of chart/graph to generate, MUST be one of: 'line', 'bar', 'scatter'.
+        - `x_axis_label` (str): Label for the x axis.  If unsure, set as "years"
+        - `y_axis_label` (str): Label for the y axis.  If unsure, set as "net income"
+
+    Output:
+        - `plot_string` (str): A verbal description of the plot, especially its overall trend. A short trend is sufficient.
+
+    """
+    inputs = {
+        "data": {
+            "type": "string",
+            "description": "CSV data representing a time series: Start this with headers followed by values!!",
+        },
+        "chart_type": {
+            "type": "string",
+            "description": "Type of chart to generate (e.g., MUST be one of 'line', 'bar', 'scatter').",
+        },
+        "x_axis_label": {
+            "type": "string",
+            "description": "Label of x-axis, such as 'years' or 'quarters'",
+        },
+        "y_axis_label": {
+            "type": "string",
+            "description": "Label of y-axis, such as 'net income' or 'revenue'",
+        },
+    }
+    output_type = "string"
+
+    def forward(
+        self, data: str, chart_type: str, x_axis_label: str, y_axis_label: str
+    ) -> str:
+        """
+        Perform chart visuals
+
+        Args:
+            data (str): string CSV in the correct format
+            chart_type (str): one of scatter, line, bar
+            x_axis_label (str): label
+            y_axis_label (str): label
+
+        Returns:
+            str: A verbal description of the plot, especially its overall trend.
+        """
+        if not data:
+            return "Error: No data provided."
+        if not chart_type:
+            return "Error: No chart."
+        if not x_axis_label:
+            return "Error: No x-axis label provided."
+        if not y_axis_label:
+            return "Error: No y-axis label provided."
+        try:
+            df = pd.read_csv(io.StringIO(data))
+        except Exception as e:
+            return f"Problem building data {data}: {e}"
+        if len(df.columns) < 2:
+            return "Error: Data must have at least two columns."
+        try:
+            plt.figure(figsize=(10, 6))  # Adjust the figure size for better readability
+            if chart_type == "line":
+                plt.xlabel(x_axis_label)
+                plt.ylabel(y_axis_label)
+                plt.plot(
+                    df[df.columns[0]], df[df.columns[1]]
+                )  # [df.columns[0]], df[df.columns[1]]
+            elif chart_type == "bar":
+                plt.ylabel(y_axis_label)
+                plt.xlabel(x_axis_label)
+                plt.bar(df[df.columns[0]], df[df.columns[1]])  # .values[0]
+            elif chart_type == "scatter":
+                plt.ylabel(y_axis_label)
+                plt.xlabel(x_axis_label)
+                plt.scatter(df[df.columns[0]], df[df.columns[1]])  # .values[0]
+            else:
+                raise ValueError(f"Unsupported chart type: {chart_type}")
+            chart_summary = f"Chart generated, which shows the {chart_type} of {df.columns[1]} with respect to {df.columns[0]}. "
+            plt.title(y_axis_label + " vs. " + x_axis_label)  # What we're graphing
+            #   plt.text(80000000000, 80000000000, chart_summary) # Show the chart summary
+            plt.show()  # actually show the chart to the user, as above shows matplotlib backend
+            return chart_summary
+        except Exception as e:
+            return f"Problem with chart plotting: {e}"  # chart_type = None
+
+
+class TrendAnalysisTool(Tool):
+    """
+    You can retrieve year over year increase percentages for a specific category by setting the category.
+    Please provide a valid CSV. MAKE SURE headers = columns, and that is in the correct format.
+    """
+
+    name = "trend_analysis"
+    description = """
+    You can retrieve year over year increase percentages for a specific category by setting the category. Please provide a valid CSV. MAKE SURE headers = columns, and that is in the correct format.
+    """
+    inputs = {
+        "data": {
+            "type": "string",
+            "description": "A string representing the data (e.g., CSV format) - MUST HAVE HEADERS. MUST specify all colums",
+        },
+        "category": {
+            "type": "string",
+            "description": "The category we want to compare, such as revenue. Check to know WHAT the name is!!",
+        },
+    }
+    output_type = "string"
+
+    def forward(self, data: str, category: str) -> str:
+        """Make year over year increases for a given csv
+        Args:
+            data: all the data
+            category: the category we want to compare, such as revenue
+        """
+        try:
+            df = pd.read_csv(io.StringIO(data))
+        except Exception as e:
+            return f"Error reading data: {e}. Ensure valid CSV, and headers are present: {e}!!"
+        try:
+            df["YoY Change"] = df[category].pct_change() * 100
+            df["YoY Change"] = df["YoY Change"].map("{:.2f}%".format)
+            change_description = df.to_string()  #
+            return change_description
+        except Exception as e:
+            return f"Error with trend analysis: {e}. Check the name or data!!"
+
+
+# ###########################
+# # Example loading the tools:
+# ###########################
+
+# # def load_finance_tools():
+# #     finance_tools = [
+# #         get_stock_quote_data,
+# #         get_company_overview_data,
+# #         get_earnings_data,
+# #         get_income_statement_data,
+# #         get_balance_sheet_data,
+# #         get_cash_flow_data,
+# #         get_time_series_daily,
+# #         search_symbols,
+# #         DataVisualizationTool(),
+# #         FinancialCalculatorTool(),
+# #         TrendAnalysisTool()
+# #     ]
+# #     return finance_tools
+
+
+def load_finance_tools():
+    """Initialize and return finance tools for data retrieval and analysis.
+    You MUST put all the correct tools in here, or it will not run.
+    """
+
+    finance_tools = []
+    # finance_tools_names = [] # was getting errors on loading
+
+    def safe_tool_load(tool_func, tool_name):
+        """Helper to safely load and append a finance tool."""
+        try:
+            finance_tools.append(tool_func)
+            # finance_tools_names.append(tool_func.__name__) # was getting errors on loading
+            logging.info(f"Loaded {tool_name} tool successfully")
+        except Exception as e:
+            logging.error(f"Failed to load tool {tool_name}: {e}")
+            logging.error(traceback.format_exc())  # Print the stack trace
+
+    # Financial calculation tools first
+    safe_tool_load(DataVisualizationTool(), "DataVisualizationTool")
+    safe_tool_load(FinancialCalculatorTool(), "FinancialCalculatorTool")
+    safe_tool_load(TrendAnalysisTool(), "TrendAnalysisTool")
+    # Raw data retrieval tools last
+    safe_tool_load(get_stock_quote_data, "get_stock_quote_data")
+    safe_tool_load(get_company_overview_data, "get_company_overview_data")
+    safe_tool_load(get_earnings_data, "get_earnings_data")
+    safe_tool_load(get_income_statement_data, "get_income_statement_data")
+    safe_tool_load(get_balance_sheet_data, "get_balance_sheet_data")
+    safe_tool_load(get_cash_flow_data, "get_cash_flow_data")
+    safe_tool_load(get_time_series_daily, "get_time_series_daily")
+    safe_tool_load(search_symbols, "search_symbols")
+    safe_tool_load(get_market_news_sentiment, "get_market_news_sentiment")
+
+    return finance_tools
+
+
+__all__ = [
+    "get_stock_quote_data",
+    "get_company_overview_data",
+    "get_earnings_data",
+    "get_income_statement_data",
+    "get_balance_sheet_data",
+    "get_cash_flow_data",
+    "get_time_series_daily",
+    "search_symbols",
+    "get_market_news_sentiment",
+    "DataVisualizationTool",
+    "FinancialCalculatorTool",
+    "TrendAnalysisTool",
+]

scripts/flux_lora_tool.py

@@ -12,30 +12,28 @@ Usage:
     agent = CodeAgent(tools=[flux_tool], ...)
 """
 
+import logging
 import os
-import uuid
 import tempfile
-import logging
-from typing import Dict, Any, Optional, List, Union, Tuple
+import uuid
 from dataclasses import dataclass
-import contextlib
-from pathlib import Path
+from typing import Any, Dict, Optional
 
 # Third-party
 import requests
-from PIL import Image
 from gradio_client import Client
-
-# Smolagents
+from PIL import Image
 from smolagents import Tool
 
 # -----------------------------------------------------------------------------
 # CONSTANTS AND TYPE DEFINITIONS
 # -----------------------------------------------------------------------------
 
+
 @dataclass
 class LoRAModelInfo:
     """Value object representing LoRA model information."""
+
     name: str
     description: Optional[str] = None
     example_image_url: Optional[str] = None
@@ -44,6 +42,7 @@ class LoRAModelInfo:
 @dataclass
 class ImageGenerationResult:
     """Value object representing a generated image result."""
+
     image_path: str
     seed: int
     metadata: Optional[Dict[str, Any]] = None
@@ -53,14 +52,15 @@ class ImageGenerationResult:
 # CORE TOOL IMPLEMENTATION
 # -----------------------------------------------------------------------------
 
+
 class FluxLoRATool(Tool):
     """
     Tool for generating images using FLUX-LoRA-DLC API.
-    
+
     This tool implements the Zhou Protocol integration patterns to provide
     a clean, efficient interface for image generation using LoRA models.
     """
-    
+
     name = "flux_lora_generator"
     description = """
     Generates high-quality images using FLUX-LoRA models.
@@ -68,74 +68,74 @@ class FluxLoRATool(Tool):
     """
     inputs = {
         "prompt": {
-            "type": "string", 
-            "description": "Detailed description of the desired image."
+            "type": "string",
+            "description": "Detailed description of the desired image.",
         },
         "image_input": {
-            "type": "string", 
+            "type": "string",
             "description": "Optional URL or file path to input image for img2img generation.",
-            "optional": True
+            "optional": True,
         },
         "image_strength": {
             "type": "float",
             "description": "Strength of input image influence (0.0-1.0), where 1.0 maintains more of original image.",
             "optional": True,
-            "default": 0.75
+            "default": 0.75,
         },
         "cfg_scale": {
             "type": "float",
             "description": "Guidance scale for prompt adherence (1.0-30.0).",
             "optional": True,
-            "default": 3.5
+            "default": 3.5,
         },
         "steps": {
             "type": "integer",
             "description": "Number of sampling steps (10-100).",
             "optional": True,
-            "default": 28
+            "default": 28,
         },
         "seed": {
             "type": "integer",
             "description": "Random seed for reproducibility. Use -1 for random seed.",
             "optional": True,
-            "default": -1
+            "default": -1,
         },
         "width": {
             "type": "integer",
             "description": "Image width in pixels.",
             "optional": True,
-            "default": 1024
+            "default": 1024,
         },
         "height": {
             "type": "integer",
             "description": "Image height in pixels.",
             "optional": True,
-            "default": 1024
+            "default": 1024,
         },
         "lora_scale": {
             "type": "float",
             "description": "LoRA influence scale (0.0-1.0).",
             "optional": True,
-            "default": 0.95
+            "default": 0.95,
         },
         "custom_lora": {
             "type": "string",
             "description": "Custom LoRA model to use. Leave empty for default.",
-            "optional": True
-        }
+            "optional": True,
+        },
     }
     output_type = "string"
-    
+
     def __init__(
-        self, 
+        self,
         api_url: str = "xkerser/FLUX-LoRA-DLC",
         image_save_dir: Optional[str] = None,
         connection_timeout: int = 60,
-        verbose: bool = False
+        verbose: bool = False,
     ):
         """
         Initialize the FLUX-LoRA Tool with Zhou Protocol connection patterns.
-        
+
         Args:
             api_url: URL or endpoint ID for the FLUX-LoRA-DLC API
             image_save_dir: Directory to save generated images (created if doesn't exist)
@@ -143,66 +143,67 @@ class FluxLoRATool(Tool):
             verbose: Enable detailed logging
         """
         super().__init__()
-        
+
         # Initialize logging
         self.logger = logging.getLogger("flux_lora_tool")
         self.logger.setLevel(logging.DEBUG if verbose else logging.INFO)
-        
+
         # Set up client and storage directories
         self.api_url = api_url
         self.connection_timeout = connection_timeout
         self._client = None  # Lazy initialization
-        
+
         # Set up image storage directory
-        self.image_save_dir = image_save_dir or os.path.join(tempfile.gettempdir(), "flux_lora_images")
+        self.image_save_dir = image_save_dir or os.path.join(
+            tempfile.gettempdir(), "flux_lora_images"
+        )
         os.makedirs(self.image_save_dir, exist_ok=True)
-        self.logger.info(f"FluxLoRATool initialized. Images will be saved to: {self.image_save_dir}")
-    
+        self.logger.info(
+            f"FluxLoRATool initialized. Images will be saved to: {self.image_save_dir}"
+        )
+
     @property
     def client(self) -> Client:
         """
         Get or initialize the Gradio client with proper connection handling.
-        
+
         Returns:
             Initialized Gradio client
-        
+
         Raises:
             ConnectionError: If client initialization fails
         """
         if self._client is None:
             try:
-                self._client = Client(
-                    self.api_url,
-                    timeout=self.connection_timeout
-                )
+                self._client = Client(self.api_url, timeout=self.connection_timeout)
                 self.logger.debug(f"Gradio client initialized for: {self.api_url}")
             except Exception as e:
                 error_msg = f"Failed to initialize FLUX-LoRA client: {str(e)}"
                 self.logger.error(error_msg)
                 raise ConnectionError(error_msg) from e
-        
+
         return self._client
-    
+
     def _validate_inputs(self, **kwargs) -> Dict[str, Any]:
         """
         Validate and normalize input parameters with Zhou Protocol validation patterns.
-        
+
         Args:
             **kwargs: Input parameters
-            
+
         Returns:
             Validated and normalized parameters
-            
+
         Raises:
             ValueError: If input validation fails
         """
         validated = {}
-        
+
         # Required parameter: prompt
         if not kwargs.get("prompt"):
             raise ValueError("Prompt is required for image generation")
         validated["prompt"] = kwargs["prompt"]
-        
+
         # Image input handling
         if "image_input" in kwargs and kwargs["image_input"]:
             input_image = kwargs["image_input"]
@@ -215,7 +216,7 @@ class FluxLoRATool(Tool):
                 if not os.path.exists(input_image):
                     raise ValueError(f"Image file not found: {input_image}")
                 validated["image_input"] = input_image
-        
+
         # Numeric parameter validation with constraints
         numeric_params = {
             "image_strength": {"min": 0.0, "max": 1.0, "default": 0.75},
@@ -223,13 +224,13 @@ class FluxLoRATool(Tool):
             "steps": {"min": 10, "max": 100, "default": 28},
             "width": {"min": 128, "max": 2048, "default": 1024},
             "height": {"min": 128, "max": 2048, "default": 1024},
-            "lora_scale": {"min": 0.0, "max": 1.0, "default": 0.95}
+            "lora_scale": {"min": 0.0, "max": 1.0, "default": 0.95},
         }
-        
+
         for param, constraints in numeric_params.items():
             if param in kwargs and kwargs[param] is not None:
                 value = kwargs[param]
-                
+
                 # Type conversion if needed
                 if param in ["steps", "width", "height"]:
                     try:
@@ -241,17 +242,17 @@ class FluxLoRATool(Tool):
                         value = float(value)
                     except (ValueError, TypeError):
                         raise ValueError(f"Parameter '{param}' must be a number")
-                
+
                 # Range validation
                 if value < constraints["min"] or value > constraints["max"]:
                     raise ValueError(
                         f"Parameter '{param}' must be between {constraints['min']} and {constraints['max']}"
                     )
-                
+
                 validated[param] = value
             else:
                 validated[param] = constraints["default"]
-        
+
         # Special handling for seed
         if "seed" in kwargs and kwargs["seed"] is not None:
             try:
@@ -264,6 +265,7 @@ class FluxLoRATool(Tool):
                         self.logger.warning(f"Failed to get random seed from API: {e}")
                         # Fallback to Python's random
                         import random
+
                         seed = random.randint(0, 2**32 - 1)
                 validated["seed"] = seed
             except (ValueError, TypeError):
@@ -271,57 +273,56 @@ class FluxLoRATool(Tool):
         else:
             # Default to random seed
             validated["seed"] = self._get_random_seed()
-        
+
         # Custom LoRA handling
         if "custom_lora" in kwargs and kwargs["custom_lora"]:
             validated["custom_lora"] = kwargs["custom_lora"]
-        
+
         return validated
-    
+
     def _download_image(self, url: str) -> str:
         """
         Download image from URL and save to local file.
-        
+
         Args:
             url: Image URL
-            
+
         Returns:
             Local file path
-            
+
         Raises:
             ConnectionError: If download fails
         """
         try:
             response = requests.get(url, stream=True, timeout=30)
             response.raise_for_status()
-            
+
             # Generate temporary file path
             file_ext = self._guess_extension(response.headers.get("Content-Type", ""))
             temp_path = os.path.join(
-                self.image_save_dir, 
-                f"input_{uuid.uuid4().hex}{file_ext}"
+                self.image_save_dir, f"input_{uuid.uuid4().hex}{file_ext}"
             )
-            
+
             # Save image
             with open(temp_path, "wb") as f:
                 for chunk in response.iter_content(chunk_size=8192):
                     f.write(chunk)
-            
+
             self.logger.debug(f"Downloaded image from {url} to {temp_path}")
             return temp_path
-            
+
         except Exception as e:
             error_msg = f"Failed to download image from {url}: {str(e)}"
             self.logger.error(error_msg)
             raise ConnectionError(error_msg) from e
-    
+
     def _guess_extension(self, content_type: str) -> str:
         """
         Guess file extension from content type.
-        
+
         Args:
             content_type: HTTP Content-Type header
-            
+
         Returns:
             File extension (with dot)
         """
@@ -336,14 +337,14 @@ class FluxLoRATool(Tool):
             return ".gif"
         else:
             return ".png"  # Default to PNG
-    
+
     def _get_random_seed(self) -> int:
         """
         Get a random seed from the API.
-        
+
         Returns:
             Random seed value
-            
+
         Raises:
             RuntimeError: If random seed retrieval fails
         """
@@ -357,14 +358,14 @@ class FluxLoRATool(Tool):
             # Just log and re-raise as we have fallback in the validation method
             self.logger.warning(f"Failed to get random seed: {e}")
             raise
-    
+
     def _handle_custom_lora(self, custom_lora: Optional[str]) -> None:
         """
         Add or remove custom LoRA model.
-        
+
         Args:
             custom_lora: Custom LoRA model string
-            
+
         Raises:
             RuntimeError: If LoRA handling fails
         """
@@ -381,15 +382,14 @@ class FluxLoRATool(Tool):
             # Add custom LoRA
             try:
                 self.client.predict(
-                    custom_lora=custom_lora,
-                    api_name="/add_custom_lora"
+                    custom_lora=custom_lora, api_name="/add_custom_lora"
                 )
                 self.logger.debug(f"Added custom LoRA: {custom_lora}")
             except Exception as e:
                 error_msg = f"Failed to add custom LoRA '{custom_lora}': {str(e)}"
                 self.logger.error(error_msg)
                 raise RuntimeError(error_msg) from e
-    
+
     def forward(
         self,
         prompt: str,
@@ -401,11 +401,11 @@ class FluxLoRATool(Tool):
         width: Optional[int] = None,
         height: Optional[int] = None,
         lora_scale: Optional[float] = None,
-        custom_lora: Optional[str] = None
+        custom_lora: Optional[str] = None,
     ) -> str:
         """
         Generate an image with FLUX-LoRA.
-        
+
         Args:
             prompt: Text description of the desired image
             image_input: Optional path or URL to input image for img2img
@@ -417,10 +417,10 @@ class FluxLoRATool(Tool):
             height: Image height in pixels (128-2048)
             lora_scale: LoRA influence scale (0.0-1.0)
             custom_lora: Custom LoRA model to use
-            
+
         Returns:
             Formatted string with image generation results
-            
+
         Raises:
             ValueError: If input validation fails
             ConnectionError: If API communication fails
@@ -438,12 +438,12 @@ class FluxLoRATool(Tool):
                 width=width,
                 height=height,
                 lora_scale=lora_scale,
-                custom_lora=custom_lora
+                custom_lora=custom_lora,
             )
             self.logger.debug(f"Validated parameters: {params}")
         except ValueError as e:
             return f"Parameter validation failed: {str(e)}"
-        
+
         # Step 2: Handle custom LoRA if specified
         if "custom_lora" in params:
             try:
@@ -451,15 +451,16 @@ class FluxLoRATool(Tool):
                 self._handle_custom_lora(custom_lora_value)
             except RuntimeError as e:
                 return f"Custom LoRA setup failed: {str(e)}"
-        
+
         # Step 3: Generate image
         try:
             # Prepare image input if provided
             img_param = None
             if "image_input" in params and params["image_input"]:
                 from gradio_client import handle_file
+
                 img_param = handle_file(params.pop("image_input"))
-            
+
             # Call the API
             generation_args = {
                 "prompt": params["prompt"],
@@ -472,27 +473,23 @@ class FluxLoRATool(Tool):
                 "height": params["height"],
                 "lora_scale": params["lora_scale"],
             }
-            
+
             # Add image input if available
             if img_param:
                 generation_args["image_input"] = img_param
-            
+
             self.logger.info(f"Generating image with params: {generation_args}")
-            result = self.client.predict(
-                api_name="/run_lora",
-                **generation_args
-            )
-            
+            result = self.client.predict(api_name="/run_lora", **generation_args)
+
             # Process result
             if isinstance(result, tuple) and len(result) >= 2:
                 image_path, actual_seed = result[0], result[1]
-                
+
                 # Save image to our directory
                 try:
                     output_path = self._save_image(image_path)
                     image_result = ImageGenerationResult(
-                        image_path=output_path,
-                        seed=int(actual_seed)
+                        image_path=output_path, seed=int(actual_seed)
                     )
                     return self._format_result(image_result, params["prompt"])
                 except Exception as e:
@@ -500,69 +497,69 @@ class FluxLoRATool(Tool):
                     return f"Image generated but failed to save: {str(e)}"
             else:
                 raise ValueError(f"Unexpected API response format: {result}")
-                
+
         except Exception as e:
             error_msg = f"Image generation failed: {str(e)}"
             self.logger.error(error_msg)
             return error_msg
-    
+
     def _save_image(self, image_path: str) -> str:
         """
         Save generated image to specified directory.
-        
+
         Args:
             image_path: Path to generated image from API
-            
+
         Returns:
             Path to saved image
-            
+
         Raises:
             IOError: If image saving fails
         """
         try:
             # Load the image
             img = Image.open(image_path)
-            
+
             # Generate timestamp-based filename
             timestamp = uuid.uuid4().hex[:8]
             output_filename = f"flux_lora_{timestamp}.png"
             output_path = os.path.join(self.image_save_dir, output_filename)
-            
+
             # Save to our directory
             img.save(output_path)
             self.logger.debug(f"Saved image to {output_path}")
-            
+
             return output_path
-            
+
         except Exception as e:
             error_msg = f"Failed to save image: {str(e)}"
             self.logger.error(error_msg)
             raise IOError(error_msg) from e
-    
+
     def _format_result(self, result: ImageGenerationResult, prompt: str) -> str:
         """
         Format the image generation result as a string.
-        
+
         Args:
             result: Image generation result
             prompt: Original prompt
-            
+
         Returns:
             Formatted string with generation details
         """
         lines = [
-            f"📷 Image generated successfully!",
+            "📷 Image generated successfully!",
             f"🖼️ Image saved to: {result.image_path}",
             f"🌱 Seed used: {result.seed}",
             f"📝 Original prompt: {prompt}",
         ]
-        
+
         # Add metadata if available
         if result.metadata:
             lines.append("📊 Additional metadata:")
             for key, value in result.metadata.items():
                 lines.append(f"   - {key}: {value}")
-        
+
         return "\n".join(lines)
 
 
@@ -570,17 +567,18 @@ class FluxLoRATool(Tool):
 # UTILITY FUNCTIONS
 # -----------------------------------------------------------------------------
 
+
 def download_image(url: str, output_dir: Optional[str] = None) -> str:
     """
     Standalone utility to download an image from a URL.
-    
+
     Args:
         url: Image URL
         output_dir: Directory to save image (created if doesn't exist)
-        
+
     Returns:
         Path to downloaded image
-        
+
     Raises:
         ValueError: If URL is invalid
         ConnectionError: If download fails
@@ -588,31 +586,30 @@ def download_image(url: str, output_dir: Optional[str] = None) -> str:
     """
     if not url.startswith(("http://", "https://")):
         raise ValueError(f"Invalid URL: {url}")
-    
+
     # Setup output directory
     if output_dir is None:
         output_dir = os.path.join(tempfile.gettempdir(), "flux_lora_images")
     os.makedirs(output_dir, exist_ok=True)
-    
+
     try:
         # Download image
         response = requests.get(url, stream=True, timeout=30)
         response.raise_for_status()
-        
+
         # Determine file extension
         content_type = response.headers.get("Content-Type", "")
         ext = ".jpg" if "jpeg" in content_type.lower() else ".png"
-        
+
         # Save image
         output_path = os.path.join(output_dir, f"download_{uuid.uuid4().hex}{ext}")
         with open(output_path, "wb") as f:
             for chunk in response.iter_content(chunk_size=8192):
                 f.write(chunk)
-        
+
         return output_path
-        
+
     except requests.RequestException as e:
         raise ConnectionError(f"Failed to download image: {str(e)}")
     except IOError as e:
         raise IOError(f"Failed to save image: {str(e)}")
-        

scripts/frontmatter_tool.py

@@ -1,402 +0,0 @@
-"""
-Frontmatter Generator Tool for Smolagents
-
-This tool helps generate consistent YAML frontmatter for documents,
-useful for RAG systems, static site generators, and document organization.
-Integrates with TextInspectorTool and MarkdownConverter for a complete
-document processing pipeline.
-"""
-
-import re
-import yaml
-import json
-from datetime import datetime
-from typing import Dict, List, Optional, Any, Union
-from smolagents import Tool
-
-
-class FrontmatterGeneratorTool(Tool):
-    """Tool for generating and manipulating YAML frontmatter in documents."""
-
-    name = "frontmatter_generator"
-    description = """
-    Generates or extracts YAML frontmatter for documents. Frontmatter provides structured 
-    metadata for documents including title, author, date, description, and tags.
-    Useful for document organization, RAG systems, and static site generators.
-    Works with content from the inspect_file_as_text tool to add metadata to documents.
-    """
-
-    inputs = {
-        "content": {
-            "type": "string",
-            "description": "Document content (with or without existing frontmatter)",
-        },
-        "title": {"type": "string", "description": "Document title", "nullable": True},
-        "author": {
-            "type": "string",
-            "description": "Document author(s)",
-            "nullable": True,
-        },
-        "date": {
-            "type": "string",
-            "description": "Document date in YYYY-MM-DD format (defaults to today if not provided)",
-            "nullable": True,
-        },
-        "date_format": {
-            "type": "string",
-            "description": "Format string for the document date (e.g., '%Y-%m-%d', '%d/%m/%Y'). Defaults to '%Y-%m-%d'",
-            "nullable": True,
-            "default": "%Y-%m-%d",
-        },
-        "description": {
-            "type": "string",
-            "description": "Brief description of the document",
-            "nullable": True,
-        },
-        "tags": {
-            "type": "string",
-            "description": "Comma-separated list of tags",
-            "nullable": True,
-        },
-        "additional_fields": {
-            "type": "string",
-            "description": "JSON string with additional frontmatter fields",
-            "nullable": True,
-        },
-        "mode": {
-            "type": "string",
-            "description": "Operation mode: 'generate' (create new), 'extract' (get existing), 'update' (modify existing), or 'strip' (remove)",
-            "default": "generate",
-        },
-    }
-    output_type = "string"
-
-    # Regular expression to detect and extract YAML frontmatter
-    FRONTMATTER_PATTERN = r"^---\s*\n(.*?)\n---\s*\n"
-
-    def forward(
-        self,
-        content: str,
-        title: Optional[str] = None,
-        author: Optional[str] = None,
-        date: Optional[str] = None,
-        date_format: Optional[str] = "%Y-%m-%d",
-        description: Optional[str] = None,
-        tags: Optional[str] = None,
-        additional_fields: Optional[str] = None,
-        mode: str = "generate",
-    ) -> str:
-        """
-        Process document content based on specified mode.
-
-        Args:
-            content: Document content with or without frontmatter
-            title: Document title
-            author: Document author(s)
-            date: Document date (YYYY-MM-DD)
-            date_format: strftime format string
-            description: Brief document description
-            tags: Comma-separated list of tags
-            additional_fields: JSON string with additional fields
-            mode: Operation mode (generate, extract, update, strip)
-
-        Returns:
-            Processed document or extracted frontmatter
-        """
-        # Validate inputs
-        if not isinstance(content, str):
-            return "Error: Content must be a string"
-        if title and not isinstance(title, str):
-            return "Error: Title must be a string"
-        if author and not isinstance(author, str):
-            return "Error: Author must be a string"
-        if date and not isinstance(date, str):
-            return "Error: Date must be a string"
-        if description and not isinstance(description, str):
-            return "Error: Description must be a string"
-        if tags and not isinstance(tags, str):
-            return "Error: Tags must be a string"
-        if additional_fields and not isinstance(additional_fields, str):
-            return "Error: Additional_fields must be a string"
-        if not isinstance(mode, str):
-            return "Error: Mode must be a string"
-
-        # Validate mode
-        valid_modes = ["generate", "extract", "update", "strip"]
-        if mode not in valid_modes:
-            return f"Error: Invalid mode '{mode}'. Valid options are: {', '.join(valid_modes)}"
-
-        # Handle empty content
-        if not content or not content.strip():
-            if mode == "generate":
-                # We can still generate frontmatter from provided fields
-                content = ""
-            else:
-                return "Error: Empty content provided"
-
-        # Special handling for TextInspectorTool output
-        if content.startswith("Document content:"):
-            content = content[len("Document content:"):].strip()
-        
-        # Process based on mode
-        try:
-            if mode == "extract":
-                return self._extract_frontmatter(content)
-            elif mode == "strip":
-                return self._strip_frontmatter(content)
-            elif mode == "update":
-                return self._update_frontmatter(
-                    content,
-                    title,
-                    author,
-                    date,
-                    description,
-                    tags,
-                    additional_fields,
-                    date_format,
-                )
-            else:  # generate
-                return self._generate_frontmatter(
-                    content,
-                    title,
-                    author,
-                    date,
-                    description,
-                    tags,
-                    additional_fields,
-                    date_format,
-                )
-        except Exception as e:
-            return f"Error processing frontmatter: {str(e)}"
-
-    def _extract_frontmatter(self, content: str) -> str:
-        """Extract and return existing frontmatter as formatted YAML."""
-        match = re.search(self.FRONTMATTER_PATTERN, content, re.DOTALL)
-        if not match:
-            return "No frontmatter found in the document"
-
-        try:
-            yaml_content = match.group(1)
-            # Parse and reformat for consistency
-            frontmatter_dict = yaml.safe_load(yaml_content)
-            return f"Extracted frontmatter:\n\n```yaml\n{yaml.dump(frontmatter_dict, sort_keys=False, default_flow_style=False)}```"
-        except yaml.YAMLError:
-            return "Found frontmatter but failed to parse it as valid YAML"
-
-    def _strip_frontmatter(self, content: str) -> str:
-        """Remove frontmatter from document and return clean content."""
-        result = re.sub(self.FRONTMATTER_PATTERN, "", content, count=1, flags=re.DOTALL)
-
-        # Check if anything was actually removed
-        if result == content:
-            return "No frontmatter found to strip. Content unchanged."
-
-        return result.strip()
-
-    def _parse_additional_fields(self, additional_fields: str) -> Dict[str, Any]:
-        """Parse the additional_fields JSON string into a dictionary."""
-        if not additional_fields:
-            return {}
-
-        try:
-            return json.loads(additional_fields)
-        except json.JSONDecodeError:
-            raise ValueError("additional_fields must be a valid JSON string")
-
-    def _infer_title_from_content(self, content: str) -> Optional[str]:
-        """Attempt to infer document title from content."""
-        # Try to find the first heading
-        heading_match = re.search(r"^#\s+(.+)$", content, re.MULTILINE)
-        if heading_match:
-            return heading_match.group(1).strip()
-
-        # Try to find the first non-empty line
-        lines = content.split("\n")
-        for line in lines:
-            if line.strip():
-                # Limit to a reasonable title length
-                return line.strip()[:100]
-
-        return None
-
-    def _parse_tags(self, tags_string: str) -> List[str]:
-        """Parse comma-separated tags into a list."""
-        if not tags_string:
-            return []
-
-        # Split by comma and clean each tag
-        tag_list = [tag.strip() for tag in tags_string.split(",")]
-        # Remove any empty tags
-        return [tag for tag in tag_list if tag]
-
-    def _parse_flexible_date(
-        self, date_str: str, date_format: Optional[str] = None
-    ) -> str:
-        """
-        Try to parse dates in various formats and convert to YYYY-MM-DD.
-
-        Args:
-            date_str: The date string to parse
-            date_format: Optional preferred format to try first
-
-        Returns:
-            Formatted date as string (YYYY-MM-DD by default)
-        """
-        if not date_str:
-            return datetime.now().strftime("%Y-%m-%d")
-
-        # If a specific format is provided, try it first
-        if date_format:
-            try:
-                parsed_date = datetime.strptime(date_str, date_format)
-                return parsed_date.strftime("%Y-%m-%d")
-            except ValueError:
-                # If it fails, continue with other formats
-                pass
-
-        # Common formats to try
-        formats = [
-            "%Y-%m-%d",  # 2013-03-13
-            "%d %B %Y",  # 13 March 2013
-            "%B %Y",  # September 2013
-            "%Y",  # 1958
-            "%d/%m/%Y",  # 13/03/2013
-            "%m/%d/%Y",  # 03/13/2013
-            "%d-%m-%Y",  # 13-03-2013
-            "%m-%d-%Y",  # 03-13-2013
-            "%Y/%m/%d",  # 2013/03/13
-        ]
-
-        for fmt in formats:
-            try:
-                parsed_date = datetime.strptime(date_str, fmt)
-                return parsed_date.strftime("%Y-%m-%d")
-            except ValueError:
-                continue
-
-        # If no format matched, return the original string
-        return date_str
-
-    def _update_frontmatter(
-        self,
-        content: str,
-        title: Optional[str] = None,
-        author: Optional[str] = None,
-        date: Optional[str] = None,
-        description: Optional[str] = None,
-        tags: Optional[str] = None,
-        additional_fields: Optional[str] = None,
-        date_format: Optional[str] = None,
-    ) -> str:
-        """Update existing frontmatter with new values."""
-        # Check if frontmatter exists
-        match = re.search(self.FRONTMATTER_PATTERN, content, re.DOTALL)
-        if not match:
-            # If no frontmatter exists, generate new one
-            return self._generate_frontmatter(
-                content,
-                title,
-                author,
-                date,
-                description,
-                tags,
-                additional_fields,
-                date_format,
-            )
-
-        # Parse existing frontmatter
-        yaml_content = match.group(1)
-        try:
-            frontmatter_dict = yaml.safe_load(yaml_content) or {}
-        except yaml.YAMLError:
-            frontmatter_dict = {}
-
-        # Update with new values if provided
-        if title:
-            frontmatter_dict["title"] = title
-        if author:
-            frontmatter_dict["author"] = author
-        if date:
-            # Try to parse the date with the flexible parser
-            frontmatter_dict["date"] = self._parse_flexible_date(date, date_format)
-        if description:
-            frontmatter_dict["description"] = description
-        if tags:
-            frontmatter_dict["tags"] = self._parse_tags(tags)
-
-        # Add additional fields
-        if additional_fields:
-            additional_dict = self._parse_additional_fields(additional_fields)
-            frontmatter_dict.update(additional_dict)
-
-        # Generate new frontmatter
-        new_frontmatter = yaml.dump(
-            frontmatter_dict, sort_keys=False, default_flow_style=False
-        )
-        new_frontmatter = f"---\n{new_frontmatter}---\n\n"
-
-        # Replace old frontmatter with new one
-        return re.sub(
-            self.FRONTMATTER_PATTERN, new_frontmatter, content, count=1, flags=re.DOTALL
-        )
-
-    def _generate_frontmatter(
-        self,
-        content: str,
-        title: Optional[str] = None,
-        author: Optional[str] = None,
-        date: Optional[str] = None,
-        description: Optional[str] = None,
-        tags: Optional[str] = None,
-        additional_fields: Optional[str] = None,
-        date_format: Optional[str] = None,
-    ) -> str:
-        """Generate new frontmatter and prepend to content."""
-        # Strip any existing frontmatter
-        clean_content = (
-            self._strip_frontmatter(content) if isinstance(content, str) else ""
-        )
-
-        # Build frontmatter dictionary
-        frontmatter_dict = {}
-
-        # Try to infer title if not provided
-        if title:
-            frontmatter_dict["title"] = title
-        else:
-            inferred_title = self._infer_title_from_content(clean_content)
-            if inferred_title:
-                frontmatter_dict["title"] = inferred_title
-
-        # Add other fields if provided
-        if author:
-            frontmatter_dict["author"] = author
-
-        # Process date with flexible parser
-        if date:
-            frontmatter_dict["date"] = self._parse_flexible_date(date, date_format)
-        else:
-            # Use current date with provided format or default
-            format_to_use = date_format or "%Y-%m-%d"
-            frontmatter_dict["date"] = datetime.now().strftime(format_to_use)
-
-        if description:
-            frontmatter_dict["description"] = description
-
-        if tags:
-            frontmatter_dict["tags"] = self._parse_tags(tags)
-
-        # Add additional fields
-        if additional_fields:
-            additional_dict = self._parse_additional_fields(additional_fields)
-            frontmatter_dict.update(additional_dict)
-
-        # Generate YAML frontmatter
-        frontmatter_yaml = yaml.dump(
-            frontmatter_dict, sort_keys=False, default_flow_style=False
-        )
-        frontmatter = f"---\n{frontmatter_yaml}---\n\n"
-
-        # Combine frontmatter with content
-        return frontmatter + clean_content
-        

scripts/gaia_scorer.py

@@ -1,124 +0,0 @@
-import re
-import string
-import warnings
-
-
-def normalize_number_str(number_str: str) -> float:
-    # we replace these common units and commas to allow
-    # conversion to float
-    for char in ["$", "%", ","]:
-        number_str = number_str.replace(char, "")
-    try:
-        return float(number_str)
-    except ValueError:
-        print(f"String {number_str} cannot be normalized to number str.")
-        return float("inf")
-
-
-def split_string(
-    s: str,
-    char_list: list[str] = [",", ";"],
-) -> list[str]:
-    pattern = f"[{''.join(char_list)}]"
-    return re.split(pattern, s)
-
-
-def is_float(element: any) -> bool:
-    try:
-        float(element)
-        return True
-    except ValueError:
-        return False
-
-
-def question_scorer(
-    model_answer: str,
-    ground_truth: str,
-) -> bool:
-    # if gt is a number
-    if is_float(ground_truth):
-        normalized_answer = normalize_number_str(str(model_answer))
-        return normalized_answer == float(ground_truth)
-
-    # if gt is a list
-    elif any(char in ground_truth for char in [",", ";"]):
-        # question with the fish: normalization removes punct
-
-        gt_elems = split_string(ground_truth)
-        ma_elems = split_string(model_answer)
-
-        # check length is the same
-        if len(gt_elems) != len(ma_elems):
-            warnings.warn("Answer lists have different lengths, returning False.", UserWarning)
-            return False
-
-        # compare each element as float or str
-        comparisons = []
-        for ma_elem, gt_elem in zip(ma_elems, gt_elems):
-            if is_float(gt_elem):
-                normalized_ma_elem = normalize_number_str(ma_elem)
-                comparisons.append(normalized_ma_elem == float(gt_elem))
-            else:
-                # we do not remove punct since comparisons can include punct
-                comparisons.append(
-                    normalize_str(ma_elem, remove_punct=False) == normalize_str(gt_elem, remove_punct=False)
-                )
-        return all(comparisons)
-
-    # if gt is a str
-    else:
-        return normalize_str(model_answer) == normalize_str(ground_truth)
-
-
-def check_prediction_contains_answer_letters_in_order(prediction, true_answer):
-    prediction = prediction.lower()
-    true_answer = true_answer.lower()
-    if len(prediction) > len(true_answer) * 3:
-        return False
-    i = 0
-    for letter in true_answer:
-        if letter in prediction[i:]:
-            i += prediction[i:].index(letter)
-        else:
-            return False
-    return True
-
-
-def check_close_call(prediction, true_answer, is_correct):
-    if is_correct:
-        return True
-    else:
-        if is_float(true_answer):
-            return is_correct
-        else:
-            if (
-                check_prediction_contains_answer_letters_in_order(str(prediction), str(true_answer))
-                and len(str(true_answer)) * 0.5 <= len(str(prediction)) <= len(str(true_answer)) * 2
-            ):
-                print(f"Close call: {prediction} vs {true_answer}")
-                return True
-            else:
-                return False
-
-
-def normalize_str(input_str, remove_punct=True) -> str:
-    """
-    Normalize a string by:
-    - Removing all white spaces
-    - Optionally removing punctuation (if remove_punct is True)
-    - Converting to lowercase
-    Parameters:
-    - input_str: str, the string to normalize
-    - remove_punct: bool, whether to remove punctuation (default: True)
-    Returns:
-    - str, the normalized string
-    """
-    # Remove all white spaces. Required e.g for seagull vs. sea gull
-    no_spaces = re.sub(r"\s", "", input_str)
-
-    # Remove punctuation, if specified.
-    if remove_punct:
-        translator = str.maketrans("", "", string.punctuation)
-        return no_spaces.lower().translate(translator)
-    else:
-        return no_spaces.lower()

scripts/mdconvert.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+# coding=utf-8
 # This is copied from Magentic-one's great repo: https://github.com/microsoft/autogen/blob/v0.4.4/python/packages/autogen-magentic-one/src/autogen_magentic_one/markdown_browser/mdconvert.py
 # Thanks to Microsoft researchers for open-sourcing this!
 # type: ignore
@@ -22,7 +24,6 @@ import pandas as pd
 import pdfminer
 import pdfminer.high_level
 import pptx
-
 # File-format detection
 import puremagic
 import pydub
@@ -86,7 +87,11 @@ class _CustomMarkdownify(markdownify.MarkdownConverter):
         if self.options["default_title"] and not title:
             title = href
         title_part = ' "%s"' % title.replace('"', r"\"") if title else ""
-        return "%s[%s](%s%s)%s" % (prefix, text, href, title_part, suffix) if href else text
+        return (
+            "%s[%s](%s%s)%s" % (prefix, text, href, title_part, suffix)
+            if href
+            else text
+        )
 
     def convert_img(self, el: Any, text: str, convert_as_inline: bool) -> str:
         """Same as usual converter, but removes data URIs"""
@@ -95,7 +100,10 @@ class _CustomMarkdownify(markdownify.MarkdownConverter):
         src = el.attrs.get("src", None) or ""
         title = el.attrs.get("title", None) or ""
         title_part = ' "%s"' % title.replace('"', r"\"") if title else ""
-        if convert_as_inline and el.parent.name not in self.options["keep_inline_images_in"]:
+        if (
+            convert_as_inline
+            and el.parent.name not in self.options["keep_inline_images_in"]
+        ):
             return alt
 
         # Remove dataURIs
@@ -119,16 +127,22 @@ class DocumentConverterResult:
 class DocumentConverter:
     """Abstract superclass of all DocumentConverters."""
 
-    def convert(self, local_path: str, **kwargs: Any) -> Union[None, DocumentConverterResult]:
+    def convert(
+        self, local_path: str, **kwargs: Any
+    ) -> Union[None, DocumentConverterResult]:
         raise NotImplementedError()
 
 
 class PlainTextConverter(DocumentConverter):
     """Anything with content type text/plain"""
 
-    def convert(self, local_path: str, **kwargs: Any) -> Union[None, DocumentConverterResult]:
+    def convert(
+        self, local_path: str, **kwargs: Any
+    ) -> Union[None, DocumentConverterResult]:
         # Guess the content type from any file extension that might be around
-        content_type, _ = mimetypes.guess_type("__placeholder" + kwargs.get("file_extension", ""))
+        content_type, _ = mimetypes.guess_type(
+            "__placeholder" + kwargs.get("file_extension", "")
+        )
 
         # Only accept text files
         if content_type is None:
@@ -148,7 +162,9 @@ class PlainTextConverter(DocumentConverter):
 class HtmlConverter(DocumentConverter):
     """Anything with content type text/html"""
 
-    def convert(self, local_path: str, **kwargs: Any) -> Union[None, DocumentConverterResult]:
+    def convert(
+        self, local_path: str, **kwargs: Any
+    ) -> Union[None, DocumentConverterResult]:
         # Bail if not html
         extension = kwargs.get("file_extension", "")
         if extension.lower() not in [".html", ".htm"]:
@@ -181,14 +197,17 @@ class HtmlConverter(DocumentConverter):
         assert isinstance(webpage_text, str)
 
         return DocumentConverterResult(
-            title=None if soup.title is None else soup.title.string, text_content=webpage_text
+            title=None if soup.title is None else soup.title.string,
+            text_content=webpage_text,
         )
 
 
 class WikipediaConverter(DocumentConverter):
     """Handle Wikipedia pages separately, focusing only on the main document content."""
 
-    def convert(self, local_path: str, **kwargs: Any) -> Union[None, DocumentConverterResult]:
+    def convert(
+        self, local_path: str, **kwargs: Any
+    ) -> Union[None, DocumentConverterResult]:
         # Bail if not Wikipedia
         extension = kwargs.get("file_extension", "")
         if extension.lower() not in [".html", ".htm"]:
@@ -220,7 +239,9 @@ class WikipediaConverter(DocumentConverter):
                 assert isinstance(main_title, str)
 
             # Convert the page
-            webpage_text = f"# {main_title}\n\n" + _CustomMarkdownify().convert_soup(body_elm)
+            webpage_text = f"# {main_title}\n\n" + _CustomMarkdownify().convert_soup(
+                body_elm
+            )
         else:
             webpage_text = _CustomMarkdownify().convert_soup(soup)
 
@@ -233,7 +254,9 @@ class WikipediaConverter(DocumentConverter):
 class YouTubeConverter(DocumentConverter):
     """Handle YouTube specially, focusing on the video title, description, and transcript."""
 
-    def convert(self, local_path: str, **kwargs: Any) -> Union[None, DocumentConverterResult]:
+    def convert(
+        self, local_path: str, **kwargs: Any
+    ) -> Union[None, DocumentConverterResult]:
         # Bail if not YouTube
         extension = kwargs.get("file_extension", "")
         if extension.lower() not in [".html", ".htm"]:
@@ -327,7 +350,12 @@ class YouTubeConverter(DocumentConverter):
             text_content=webpage_text,
         )
 
-    def _get(self, metadata: Dict[str, str], keys: List[str], default: Union[str, None] = None) -> Union[str, None]:
+    def _get(
+        self,
+        metadata: Dict[str, str],
+        keys: List[str],
+        default: Union[str, None] = None,
+    ) -> Union[str, None]:
         for k in keys:
             if k in metadata:
                 return metadata[k]
@@ -444,7 +472,13 @@ class PptxConverter(HtmlConverter):
 
                     # A placeholder name
                     filename = re.sub(r"\W", "", shape.name) + ".jpg"
-                    md_content += "\n![" + (alt_text if alt_text else shape.name) + "](" + filename + ")\n"
+                    md_content += (
+                        "\n!["
+                        + (alt_text if alt_text else shape.name)
+                        + "]("
+                        + filename
+                        + ")\n"
+                    )
 
                 # Tables
                 if self._is_table(shape):
@@ -460,7 +494,9 @@ class PptxConverter(HtmlConverter):
                         html_table += "</tr>"
                         first_row = False
                     html_table += "</table></body></html>"
-                    md_content += "\n" + self._convert(html_table).text_content.strip() + "\n"
+                    md_content += (
+                        "\n" + self._convert(html_table).text_content.strip() + "\n"
+                    )
 
                 # Text areas
                 elif shape.has_text_frame:
@@ -508,7 +544,9 @@ class MediaConverter(DocumentConverter):
             return None
         else:
             try:
-                result = subprocess.run([exiftool, "-json", local_path], capture_output=True, text=True).stdout
+                result = subprocess.run(
+                    [exiftool, "-json", local_path], capture_output=True, text=True
+                ).stdout
                 return json.loads(result)[0]
             except Exception:
                 return None
@@ -548,9 +586,13 @@ class WavConverter(MediaConverter):
         # Transcribe
         try:
             transcript = self._transcribe_audio(local_path)
-            md_content += "\n\n### Audio Transcript:\n" + ("[No speech detected]" if transcript == "" else transcript)
+            md_content += "\n\n### Audio Transcript:\n" + (
+                "[No speech detected]" if transcript == "" else transcript
+            )
         except Exception:
-            md_content += "\n\n### Audio Transcript:\nError. Could not transcribe this audio."
+            md_content += (
+                "\n\n### Audio Transcript:\nError. Could not transcribe this audio."
+            )
 
         return DocumentConverterResult(
             title=None,
@@ -612,7 +654,9 @@ class Mp3Converter(WavConverter):
                     "[No speech detected]" if transcript == "" else transcript
                 )
             except Exception:
-                md_content += "\n\n### Audio Transcript:\nError. Could not transcribe this audio."
+                md_content += (
+                    "\n\n### Audio Transcript:\nError. Could not transcribe this audio."
+                )
 
         finally:
             os.unlink(temp_path)
@@ -662,7 +706,11 @@ class ImageConverter(MediaConverter):
             md_content += (
                 "\n# Description:\n"
                 + self._get_mlm_description(
-                    local_path, extension, mlm_client, mlm_model, prompt=kwargs.get("mlm_prompt")
+                    local_path,
+                    extension,
+                    mlm_client,
+                    mlm_model,
+                    prompt=kwargs.get("mlm_prompt"),
                 ).strip()
                 + "\n"
             )
@@ -759,7 +807,11 @@ class MarkdownConverter:
 
         # Local path or url
         if isinstance(source, str):
-            if source.startswith("http://") or source.startswith("https://") or source.startswith("file://"):
+            if (
+                source.startswith("http://")
+                or source.startswith("https://")
+                or source.startswith("file://")
+            ):
                 return self.convert_url(source, **kwargs)
             else:
                 return self.convert_local(source, **kwargs)
@@ -767,7 +819,9 @@ class MarkdownConverter:
         elif isinstance(source, requests.Response):
             return self.convert_response(source, **kwargs)
 
-    def convert_local(self, path: str, **kwargs: Any) -> DocumentConverterResult:  # TODO: deal with kwargs
+    def convert_local(
+        self, path: str, **kwargs: Any
+    ) -> DocumentConverterResult:  # TODO: deal with kwargs
         # Prepare a list of extensions to try (in order of priority)
         ext = kwargs.get("file_extension")
         extensions = [ext] if ext is not None else []
@@ -781,7 +835,9 @@ class MarkdownConverter:
         return self._convert(path, extensions, **kwargs)
 
     # TODO what should stream's type be?
-    def convert_stream(self, stream: Any, **kwargs: Any) -> DocumentConverterResult:  # TODO: deal with kwargs
+    def convert_stream(
+        self, stream: Any, **kwargs: Any
+    ) -> DocumentConverterResult:  # TODO: deal with kwargs
         # Prepare a list of extensions to try (in order of priority)
         ext = kwargs.get("file_extension")
         extensions = [ext] if ext is not None else []
@@ -814,10 +870,14 @@ class MarkdownConverter:
 
         return result
 
-    def convert_url(self, url: str, **kwargs: Any) -> DocumentConverterResult:  # TODO: fix kwargs type
+    def convert_url(
+        self, url: str, **kwargs: Any
+    ) -> DocumentConverterResult:  # TODO: fix kwargs type
         # Send a HTTP request to the URL
         user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36 Edg/119.0.0.0"
-        response = self._requests_session.get(url, stream=True, headers={"User-Agent": user_agent})
+        response = self._requests_session.get(
+            url, stream=True, headers={"User-Agent": user_agent}
+        )
         response.raise_for_status()
         return self.convert_response(response, **kwargs)
 
@@ -871,7 +931,9 @@ class MarkdownConverter:
 
         return result
 
-    def _convert(self, local_path: str, extensions: List[Union[str, None]], **kwargs) -> DocumentConverterResult:
+    def _convert(
+        self, local_path: str, extensions: List[Union[str, None]], **kwargs
+    ) -> DocumentConverterResult:
         error_trace = ""
         for ext in extensions + [None]:  # Try last with no extension
             for converter in self._page_converters:
@@ -899,7 +961,9 @@ class MarkdownConverter:
 
                 if res is not None:
                     # Normalize the content
-                    res.text_content = "\n".join([line.rstrip() for line in re.split(r"\r?\n", res.text_content)])
+                    res.text_content = "\n".join(
+                        [line.rstrip() for line in re.split(r"\r?\n", res.text_content)]
+                    )
                     res.text_content = re.sub(r"\n{3,}", "\n\n", res.text_content)
 
                     # Todo

scripts/reformulator.py

@@ -1,86 +0,0 @@
-# Shamelessly stolen from Microsoft Autogen team: thanks to them for this great resource!
-# https://github.com/microsoft/autogen/blob/gaia_multiagent_v01_march_1st/autogen/browser_utils.py
-import copy
-
-from smolagents.models import MessageRole, Model
-
-
-def prepare_response(original_task: str, inner_messages, reformulation_model: Model) -> str:
-    messages = [
-        {
-            "role": MessageRole.SYSTEM,
-            "content": [
-                {
-                    "type": "text",
-                    "text": f"""Earlier you were asked the following:
-
-{original_task}
-
-Your team then worked diligently to address that request. Read below a transcript of that conversation:""",
-                }
-            ],
-        }
-    ]
-
-    # The first message just repeats the question, so remove it
-    # if len(inner_messages) > 1:
-    #    del inner_messages[0]
-
-    # copy them to this context
-    try:
-        for message in inner_messages:
-            if not message.get("content"):
-                continue
-            message = copy.deepcopy(message)
-            message["role"] = MessageRole.USER
-            messages.append(message)
-    except Exception:
-        messages += [{"role": MessageRole.ASSISTANT, "content": str(inner_messages)}]
-
-    # ask for the final answer
-    messages.append(
-        {
-            "role": MessageRole.USER,
-            "content": [
-                {
-                    "type": "text",
-                    "text": f"""
-Read the above conversation and output a FINAL ANSWER to the question. The question is repeated here for convenience:
-
-{original_task}
-
-To output the final answer, use the following template: FINAL ANSWER: [YOUR FINAL ANSWER]
-Your FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings.
-ADDITIONALLY, your FINAL ANSWER MUST adhere to any formatting instructions specified in the original question (e.g., alphabetization, sequencing, units, rounding, decimal places, etc.)
-If you are asked for a number, express it numerically (i.e., with digits rather than words), don't use commas, and DO NOT INCLUDE UNITS such as $ or USD or percent signs unless specified otherwise.
-If you are asked for a string, don't use articles or abbreviations (e.g. for cities), unless specified otherwise. Don't output any final sentence punctuation such as '.', '!', or '?'.
-If you are asked for a comma separated list, apply the above rules depending on whether the elements are numbers or strings.
-If you are unable to determine the final answer, output 'FINAL ANSWER: Unable to determine'
-""",
-                }
-            ],
-        }
-    )
-
-    response = reformulation_model(messages).content
-
-    final_answer = response.split("FINAL ANSWER: ")[-1].strip()
-    print("> Reformulated answer: ", final_answer)
-
-    #     if "unable to determine" in final_answer.lower():
-    #         messages.append({"role": MessageRole.ASSISTANT, "content": response })
-    #         messages.append({"role": MessageRole.USER, "content": [{"type": "text", "text": """
-    # I understand that a definitive answer could not be determined. Please make a well-informed EDUCATED GUESS based on the conversation.
-
-    # To output the educated guess, use the following template: EDUCATED GUESS: [YOUR EDUCATED GUESS]
-    # Your EDUCATED GUESS should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. DO NOT OUTPUT 'I don't know', 'Unable to determine', etc.
-    # ADDITIONALLY, your EDUCATED GUESS MUST adhere to any formatting instructions specified in the original question (e.g., alphabetization, sequencing, units, rounding, decimal places, etc.)
-    # If you are asked for a number, express it numerically (i.e., with digits rather than words), don't use commas, and don't include units such as $ or percent signs unless specified otherwise.
-    # If you are asked for a string, don't use articles or abbreviations (e.g. cit for cities), unless specified otherwise. Don't output any final sentence punctuation such as '.', '!', or '?'.
-    # If you are asked for a comma separated list, apply the above rules depending on whether the elements are numbers or strings.
-    # """.strip()}]})
-
-    #         response = model(messages).content
-    #         print("\n>>>Making an educated guess.\n", response)
-    #         final_answer = response.split("EDUCATED GUESS: ")[-1].strip()
-    return final_answer

scripts/run_agents.py

@@ -1,87 +0,0 @@
-import json
-import os
-import shutil
-import textwrap
-from pathlib import Path
-
-# import tqdm.asyncio
-from smolagents.utils import AgentError
-
-
-def serialize_agent_error(obj):
-    if isinstance(obj, AgentError):
-        return {"error_type": obj.__class__.__name__, "message": obj.message}
-    else:
-        return str(obj)
-
-
-def get_image_description(file_name: str, question: str, visual_inspection_tool) -> str:
-    prompt = f"""Write a caption of 5 sentences for this image. Pay special attention to any details that might be useful for someone answering the following question:
-{question}. But do not try to answer the question directly!
-Do not add any information that is not present in the image."""
-    return visual_inspection_tool(image_path=file_name, question=prompt)
-
-
-def get_document_description(file_path: str, question: str, document_inspection_tool) -> str:
-    prompt = f"""Write a caption of 5 sentences for this document. Pay special attention to any details that might be useful for someone answering the following question:
-{question}. But do not try to answer the question directly!
-Do not add any information that is not present in the document."""
-    return document_inspection_tool.forward_initial_exam_mode(file_path=file_path, question=prompt)
-
-
-def get_single_file_description(file_path: str, question: str, visual_inspection_tool, document_inspection_tool):
-    file_extension = file_path.split(".")[-1]
-    if file_extension in ["png", "jpg", "jpeg"]:
-        file_description = f" - Attached image: {file_path}"
-        file_description += (
-            f"\n     -> Image description: {get_image_description(file_path, question, visual_inspection_tool)}"
-        )
-        return file_description
-    elif file_extension in ["pdf", "xls", "xlsx", "docx", "doc", "xml"]:
-        file_description = f" - Attached document: {file_path}"
-        image_path = file_path.split(".")[0] + ".png"
-        if os.path.exists(image_path):
-            description = get_image_description(image_path, question, visual_inspection_tool)
-        else:
-            description = get_document_description(file_path, question, document_inspection_tool)
-        file_description += f"\n     -> File description: {description}"
-        return file_description
-    elif file_extension in ["mp3", "m4a", "wav"]:
-        return f" - Attached audio: {file_path}"
-    else:
-        return f" - Attached file: {file_path}"
-
-
-def get_zip_description(file_path: str, question: str, visual_inspection_tool, document_inspection_tool):
-    folder_path = file_path.replace(".zip", "")
-    os.makedirs(folder_path, exist_ok=True)
-    shutil.unpack_archive(file_path, folder_path)
-
-    prompt_use_files = ""
-    for root, dirs, files in os.walk(folder_path):
-        for file in files:
-            file_path = os.path.join(root, file)
-            prompt_use_files += "\n" + textwrap.indent(
-                get_single_file_description(file_path, question, visual_inspection_tool, document_inspection_tool),
-                prefix="    ",
-            )
-    return prompt_use_files
-
-
-def get_tasks_to_run(data, total: int, base_filename: Path, tasks_ids: list[int]):
-    f = base_filename.parent / f"{base_filename.stem}_answers.jsonl"
-    done = set()
-    if f.exists():
-        with open(f, encoding="utf-8") as fh:
-            done = {json.loads(line)["task_id"] for line in fh if line.strip()}
-
-    tasks = []
-    for i in range(total):
-        task_id = int(data[i]["task_id"])
-        if task_id not in done:
-            if tasks_ids is not None:
-                if task_id in tasks_ids:
-                    tasks.append(data[i])
-            else:
-                tasks.append(data[i])
-    return tasks

scripts/text_cleaner_tool.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python
+# coding=utf-8
+# Copyright 2025 The Footscray Coding Collective. All rights reserved.
 """
 Text cleaning tool for smolagents.
 
@@ -7,32 +10,26 @@ text content with handling for various text transformation options.
 
 # Standard library imports
 import logging
-from typing import Dict, Any, Optional
+from typing import Any, Dict, Optional
 
 # Third-party imports
+from cleantext import clean
 from smolagents import Tool
 
-# Try to import cleantext - handle gracefully if not installed
-try:
-    from cleantext import clean
-
-    CLEANTEXT_AVAILABLE = True
-except ImportError:
-    CLEANTEXT_AVAILABLE = False
-
 # Configure module logger
 logger = logging.getLogger(__name__)
 
 
 # pylint: disable=too-few-public-methods
 class TextCleanerTool(Tool):
-    """A simplified text cleaner tool that avoids typing issues."""
+    """A simple text cleaner tool."""
 
     name = "clean_text"
-    description = (
-        "Cleans and normalizes text using the cleantext library. "
-        "Transforms messy user-generated content into normalized text."
-    )
+    description = """This tool can be used to process messy user-generated content into
+    normalized text. It handles a variety of text transformation options,
+    such as fixing unicode errors, transliterating to closest ASCII,
+    lowercasing text, normalizing line breaks, removing punctuation,
+    replacing numbers with a token, and more."""
     inputs = {
         "text": {"type": "string", "description": "The input text to clean"},
         "options": {
@@ -76,7 +73,7 @@ class TextCleanerTool(Tool):
         `clean-text` uses ftfy, unidecode and numerous hand-crafted rules,
         i.e., RegEx.
 
-        Example API:
+        Usage of the cleantext API:
         clean("some input",
             fix_unicode=True,          # fix various unicode errors
             to_ascii=True,             # transliterate to closest ASCII
@@ -110,14 +107,6 @@ class TextCleanerTool(Tool):
                 logger.error("Failed to convert input to string: %s", e)
                 return f"Error: Could not process input of type {type(text)}"
 
-        # Check if cleantext is available
-        if not CLEANTEXT_AVAILABLE:
-            logger.error(
-                "cleantext package not installed. "
-                "Install with: pip install clean-text"
-            )
-            return "Error: Required dependency 'clean-text' is not installed."
-
         # Default replacement tokens
         replacements = {
             "replace_with_url": "<URL>",
@@ -159,3 +148,6 @@ class TextCleanerTool(Tool):
         except (ValueError, TypeError, AttributeError) as e:
             logger.error("Error cleaning text: %s", e)
             return f"Error during text cleaning: {str(e)}"
+
+
+__all__ = ["TextCleanerTool"]

scripts/text_inspector_tool.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+# coding=utf-8
 from typing import Optional
 
 from smolagents import Tool
@@ -7,10 +9,24 @@ from .mdconvert import MarkdownConverter
 
 
 class TextInspectorTool(Tool):
-    name = "inspect_file_as_text"
+    """
+    Tool for converting various file types to text and answering questions about their contents.
+
+    Supported file types include:
+    - Text documents (.txt, .md)
+    - Web documents (.html, .htm)
+    - Office documents (.docx, .xlsx, .pptx)
+    - Audio files (.wav, .mp3, .flac)
+    - PDF documents (.pdf)
+
+    Images are not supported and should be processed with a visualizer tool instead.
+    """
+
+    name = "view_file"
     description = """
-You cannot load files yourself: instead call this tool to read a file as markdown text and ask questions about it.
-This tool handles the following file extensions: [".html", ".htm", ".xlsx", ".pptx", ".wav", ".mp3", ".flac", ".pdf", ".docx"], and all other types of text files. IT DOES NOT HANDLE IMAGES."""
+    You cannot load files yourself: instead call this tool to read a file as markdown text and ask questions about it.
+    This tool handles the following file extensions: [".html", ".htm", ".md", ".txt", ".xlsx", ".pptx", ".wav", ".mp3", ".flac", ".pdf", ".docx"], and all other types of text files. IT DOES NOT HANDLE IMAGES.
+    """
 
     inputs = {
         "file_path": {
@@ -27,15 +43,23 @@ This tool handles the following file extensions: [".html", ".htm", ".xlsx", ".pp
     md_converter = MarkdownConverter()
 
     def __init__(self, model: Model, text_limit: int):
+        """
+        Initialize the TextInspectorTool with a model to use for generating text and a limit for the amount of text to generate.
+        """
         super().__init__()
         self.model = model
         self.text_limit = text_limit
 
     def forward_initial_exam_mode(self, file_path, question):
+        """
+        This is used for generating code for the initial exam, and is not used for the final exam.
+        """
         result = self.md_converter.convert(file_path)
 
-        if file_path[-4:] in [".png", ".jpg"]:
-            raise Exception("Cannot use inspect_file_as_text tool with images: use visualizer instead!")
+        if file_path[-4:] in [".png", ".jpg", ".webp"]:
+            raise Exception(
+                "Cannot use inspect_file_as_text tool with images: use visualizer instead!"
+            )
 
         if ".zip" in file_path:
             return result.text_content
@@ -73,11 +97,28 @@ This tool handles the following file extensions: [".html", ".htm", ".xlsx", ".pp
         ]
         return self.model(messages).content
 
-    def forward(self, file_path, question: Optional[str] = None) -> str:
+    def forward(self, file_path: str, question: Optional[str] = None) -> str:
+        """
+        Process a file and optionally answer a question about its contents.
+
+        Args:
+            file_path: Path to the file to be processed. Must be a supported file type.
+            question: Optional question to answer about the file contents.
+                    If None, returns the raw file content.
+
+        Returns:
+            Either the raw file content if no question is provided, or the model's
+            response to the question based on the file contents.
+
+        Raises:
+            Exception: If the file is an image file or has an unsupported format.
+        """
         result = self.md_converter.convert(file_path)
 
         if file_path[-4:] in [".png", ".jpg"]:
-            raise Exception("Cannot use inspect_file_as_text tool with images: use visualizer instead!")
+            raise Exception(
+                "Cannot use inspect_file_as_text tool with images: use visualizer instead!"
+            )
 
         if ".zip" in file_path:
             return result.text_content
@@ -120,3 +161,6 @@ This tool handles the following file extensions: [".html", ".htm", ".xlsx", ".pp
             },
         ]
         return self.model(messages).content
+
+
+__all__ = ["TextInspectorTool"]

scripts/text_web_browser.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python
+# coding=utf-8
+# TODO: REMOVE REDUNDANT SERPAPI CODE AND IMPORT/EXTEND DEFAULT GoogleSearchTool FROM SMOLAGENTS
 # Shamelessly stolen from Microsoft Autogen team: thanks to them for this great resource!
 # https://github.com/microsoft/autogen/blob/gaia_multiagent_v01_march_1st/autogen/browser_utils.py
 import mimetypes
@@ -12,11 +15,11 @@ from urllib.parse import unquote, urljoin, urlparse
 import pathvalidate
 import requests
 from serpapi import GoogleSearch
-
 from smolagents import Tool
 
 from .cookies import COOKIES
-from .mdconvert import FileConversionException, MarkdownConverter, UnsupportedFormatException
+from .mdconvert import (FileConversionException, MarkdownConverter,
+                        UnsupportedFormatException)
 
 
 class SimpleTextBrowser:
@@ -45,7 +48,9 @@ class SimpleTextBrowser:
         self._page_content: str = ""
 
         self._find_on_page_query: Union[str, None] = None
-        self._find_on_page_last_result: Union[int, None] = None  # Location of the last result
+        self._find_on_page_last_result: Union[int, None] = (
+            None  # Location of the last result
+        )
 
     @property
     def address(self) -> str:
@@ -60,7 +65,9 @@ class SimpleTextBrowser:
         if uri_or_path == "about:blank":
             self._set_page_content("")
         elif uri_or_path.startswith("google:"):
-            self._serpapi_search(uri_or_path[len("google:") :].strip(), filter_year=filter_year)
+            self._serpapi_search(
+                uri_or_path[len("google:") :].strip(), filter_year=filter_year
+            )
         else:
             if (
                 not uri_or_path.startswith("http:")
@@ -97,7 +104,9 @@ class SimpleTextBrowser:
             self.viewport_current_page = len(self.viewport_pages) - 1
 
     def page_down(self) -> None:
-        self.viewport_current_page = min(self.viewport_current_page + 1, len(self.viewport_pages) - 1)
+        self.viewport_current_page = min(
+            self.viewport_current_page + 1, len(self.viewport_pages) - 1
+        )
 
     def page_up(self) -> None:
         self.viewport_current_page = max(self.viewport_current_page - 1, 0)
@@ -107,7 +116,10 @@ class SimpleTextBrowser:
 
         # Did we get here via a previous find_on_page search with the same query?
         # If so, map to find_next
-        if query == self._find_on_page_query and self.viewport_current_page == self._find_on_page_last_result:
+        if (
+            query == self._find_on_page_query
+            and self.viewport_current_page == self._find_on_page_last_result
+        ):
             return self.find_next()
 
         # Ok it's a new search start from the current viewport
@@ -135,7 +147,9 @@ class SimpleTextBrowser:
             if starting_viewport >= len(self.viewport_pages):
                 starting_viewport = 0
 
-        viewport_match = self._find_next_viewport(self._find_on_page_query, starting_viewport)
+        viewport_match = self._find_next_viewport(
+            self._find_on_page_query, starting_viewport
+        )
         if viewport_match is None:
             self._find_on_page_last_result = None
             return None
@@ -144,7 +158,9 @@ class SimpleTextBrowser:
             self._find_on_page_last_result = viewport_match
             return self.viewport
 
-    def _find_next_viewport(self, query: str, starting_viewport: int) -> Union[int, None]:
+    def _find_next_viewport(
+        self, query: str, starting_viewport: int
+    ) -> Union[int, None]:
         """Search for matches between the starting viewport looping when reaching the end."""
 
         if query is None:
@@ -153,7 +169,9 @@ class SimpleTextBrowser:
         # Normalize the query, and convert to a regular expression
         nquery = re.sub(r"\*", "__STAR__", query)
         nquery = " " + (" ".join(re.split(r"\W+", nquery))).strip() + " "
-        nquery = nquery.replace(" __STAR__ ", "__STAR__ ")  # Merge isolated stars with prior word
+        nquery = nquery.replace(
+            " __STAR__ ", "__STAR__ "
+        )  # Merge isolated stars with prior word
         nquery = nquery.replace("__STAR__", ".*").lower()
 
         if nquery.strip() == "":
@@ -196,7 +214,9 @@ class SimpleTextBrowser:
         while start_idx < len(self._page_content):
             end_idx = min(start_idx + self.viewport_size, len(self._page_content))  # type: ignore[operator]
             # Adjust to end on a space
-            while end_idx < len(self._page_content) and self._page_content[end_idx - 1] not in [" ", "\t", "\r", "\n"]:
+            while end_idx < len(self._page_content) and self._page_content[
+                end_idx - 1
+            ] not in [" ", "\t", "\r", "\n"]:
                 end_idx += 1
             self.viewport_pages.append((start_idx, end_idx))
             start_idx = end_idx
@@ -211,15 +231,21 @@ class SimpleTextBrowser:
             "api_key": self.serpapi_key,
         }
         if filter_year is not None:
-            params["tbs"] = f"cdr:1,cd_min:01/01/{filter_year},cd_max:12/31/{filter_year}"
+            params["tbs"] = (
+                f"cdr:1,cd_min:01/01/{filter_year},cd_max:12/31/{filter_year}"
+            )
 
         search = GoogleSearch(params)
         results = search.get_dict()
         self.page_title = f"{query} - Search"
         if "organic_results" not in results.keys():
-            raise Exception(f"No results found for query: '{query}'. Use a less specific query.")
+            raise Exception(
+                f"No results found for query: '{query}'. Use a less specific query."
+            )
         if len(results["organic_results"]) == 0:
-            year_filter_message = f" with filter year={filter_year}" if filter_year is not None else ""
+            year_filter_message = (
+                f" with filter year={filter_year}" if filter_year is not None else ""
+            )
             self._set_page_content(
                 f"No results found for '{query}'{year_filter_message}. Try with a more general query, or remove the year filter."
             )
@@ -250,7 +276,9 @@ class SimpleTextBrowser:
 
                 redacted_version = f"{idx}. [{page['title']}]({page['link']}){date_published}{source}\n{_prev_visit(page['link'])}{snippet}"
 
-                redacted_version = redacted_version.replace("Your browser can't play this video.", "")
+                redacted_version = redacted_version.replace(
+                    "Your browser can't play this video.", ""
+                )
                 web_snippets.append(redacted_version)
 
         content = (
@@ -270,7 +298,11 @@ class SimpleTextBrowser:
                 self._set_page_content(res.text_content)
             else:
                 # Prepare the request parameters
-                request_kwargs = self.request_kwargs.copy() if self.request_kwargs is not None else {}
+                request_kwargs = (
+                    self.request_kwargs.copy()
+                    if self.request_kwargs is not None
+                    else {}
+                )
                 request_kwargs["stream"] = True
 
                 # Send a HTTP request to the URL
@@ -291,15 +323,21 @@ class SimpleTextBrowser:
                     fname = None
                     download_path = None
                     try:
-                        fname = pathvalidate.sanitize_filename(os.path.basename(urlparse(url).path)).strip()
-                        download_path = os.path.abspath(os.path.join(self.downloads_folder, fname))
+                        fname = pathvalidate.sanitize_filename(
+                            os.path.basename(urlparse(url).path)
+                        ).strip()
+                        download_path = os.path.abspath(
+                            os.path.join(self.downloads_folder, fname)
+                        )
 
                         suffix = 0
                         while os.path.exists(download_path) and suffix < 1000:
                             suffix += 1
                             base, ext = os.path.splitext(fname)
                             new_fname = f"{base}__{suffix}{ext}"
-                            download_path = os.path.abspath(os.path.join(self.downloads_folder, new_fname))
+                            download_path = os.path.abspath(
+                                os.path.join(self.downloads_folder, new_fname)
+                            )
 
                     except NameError:
                         pass
@@ -310,7 +348,9 @@ class SimpleTextBrowser:
                         if extension is None:
                             extension = ".download"
                         fname = str(uuid.uuid4()) + extension
-                        download_path = os.path.abspath(os.path.join(self.downloads_folder, fname))
+                        download_path = os.path.abspath(
+                            os.path.join(self.downloads_folder, fname)
+                        )
 
                     # Open a file for writing
                     with open(download_path, "wb") as fh:
@@ -324,11 +364,15 @@ class SimpleTextBrowser:
         except UnsupportedFormatException as e:
             print(e)
             self.page_title = ("Download complete.",)
-            self._set_page_content(f"# Download complete\n\nSaved file to '{download_path}'")
+            self._set_page_content(
+                f"# Download complete\n\nSaved file to '{download_path}'"
+            )
         except FileConversionException as e:
             print(e)
             self.page_title = ("Download complete.",)
-            self._set_page_content(f"# Download complete\n\nSaved file to '{download_path}'")
+            self._set_page_content(
+                f"# Download complete\n\nSaved file to '{download_path}'"
+            )
         except FileNotFoundError:
             self.page_title = "Error 404"
             self._set_page_content(f"## Error 404\n\nFile not found: {download_path}")
@@ -341,10 +385,14 @@ class SimpleTextBrowser:
                 if content_type is not None and "text/html" in content_type.lower():
                     res = self._mdconvert.convert(response)
                     self.page_title = f"Error {response.status_code}"
-                    self._set_page_content(f"## Error {response.status_code}\n\n{res.text_content}")
+                    self._set_page_content(
+                        f"## Error {response.status_code}\n\n{res.text_content}"
+                    )
                 else:
                     text = ""
-                    for chunk in response.iter_content(chunk_size=512, decode_unicode=True):
+                    for chunk in response.iter_content(
+                        chunk_size=512, decode_unicode=True
+                    ):
                         text += chunk
                     self.page_title = f"Error {response.status_code}"
                     self._set_page_content(f"## Error {response.status_code}\n\n{text}")
@@ -366,14 +414,18 @@ class SimpleTextBrowser:
                 header += f"You previously visited this page {round(time.time() - self.history[i][1])} seconds ago.\n"
                 break
 
-        header += f"Viewport position: Showing page {current_page + 1} of {total_pages}.\n"
+        header += (
+            f"Viewport position: Showing page {current_page + 1} of {total_pages}.\n"
+        )
         return (header, self.viewport)
 
 
 class SearchInformationTool(Tool):
     name = "web_search"
     description = "Perform a web search query (think a google search) and returns the search results."
-    inputs = {"query": {"type": "string", "description": "The web search query to perform."}}
+    inputs = {
+        "query": {"type": "string", "description": "The web search query to perform."}
+    }
     inputs["filter_year"] = {
         "type": "string",
         "description": "[Optional parameter]: filter the search results to only include pages from a specific year. For example, '2020' will only include pages from 2020. Make sure to use this parameter if you're trying to search for articles from a specific date!",
@@ -394,7 +446,12 @@ class SearchInformationTool(Tool):
 class VisitTool(Tool):
     name = "visit_page"
     description = "Visit a webpage at a given URL and return its text. Given a url to a YouTube video, this returns the transcript."
-    inputs = {"url": {"type": "string", "description": "The relative or absolute url of the webapge to visit."}}
+    inputs = {
+        "url": {
+            "type": "string",
+            "description": "The relative or absolute url of the webapge to visit.",
+        }
+    }
     output_type = "string"
 
     def __init__(self, browser):
@@ -413,7 +470,12 @@ class DownloadTool(Tool):
 Download a file at a given URL. The file should be of this format: [".xlsx", ".pptx", ".wav", ".mp3", ".png", ".docx"]
 After using this tool, for further inspection of this page you should return the download path to your manager via final_answer, and they will be able to inspect it.
 DO NOT use this tool for .pdf or .txt or .htm files: for these types of files use visit_page with the file url instead."""
-    inputs = {"url": {"type": "string", "description": "The relative or absolute url of the file to be downloaded."}}
+    inputs = {
+        "url": {
+            "type": "string",
+            "description": "The relative or absolute url of the file to be downloaded.",
+        }
+    }
     output_type = "string"
 
     def __init__(self, browser):
@@ -435,7 +497,9 @@ DO NOT use this tool for .pdf or .txt or .htm files: for these types of files us
             f.write(response.content)
 
         if "pdf" in extension or "txt" in extension or "htm" in extension:
-            raise Exception("Do not use this tool for pdf or txt or html files: use visit_page instead.")
+            raise Exception(
+                "Do not use this tool for pdf or txt or html files: use visit_page instead."
+            )
 
         return f"File was downloaded and saved under path {new_path}."
 
@@ -461,15 +525,23 @@ class ArchiveSearchTool(Tool):
         archive_url = no_timestamp_url + f"&timestamp={date}"
         response = requests.get(archive_url).json()
         response_notimestamp = requests.get(no_timestamp_url).json()
-        if "archived_snapshots" in response and "closest" in response["archived_snapshots"]:
+        if (
+            "archived_snapshots" in response
+            and "closest" in response["archived_snapshots"]
+        ):
             closest = response["archived_snapshots"]["closest"]
             print("Archive found!", closest)
 
-        elif "archived_snapshots" in response_notimestamp and "closest" in response_notimestamp["archived_snapshots"]:
+        elif (
+            "archived_snapshots" in response_notimestamp
+            and "closest" in response_notimestamp["archived_snapshots"]
+        ):
             closest = response_notimestamp["archived_snapshots"]["closest"]
             print("Archive found!", closest)
         else:
-            raise Exception(f"Your {url=} was not archived on Wayback Machine, try a different url.")
+            raise Exception(
+                f"Your {url=} was not archived on Wayback Machine, try a different url."
+            )
         target_url = closest["url"]
         self.browser.visit_page(target_url)
         header, content = self.browser._state()
@@ -499,9 +571,7 @@ class PageUpTool(Tool):
 
 class PageDownTool(Tool):
     name = "page_down"
-    description = (
-        "Scroll the viewport DOWN one page-length in the current webpage and return the new viewport content."
-    )
+    description = "Scroll the viewport DOWN one page-length in the current webpage and return the new viewport content."
     inputs = {}
     output_type = "string"
 
@@ -558,6 +628,20 @@ class FindNextTool(Tool):
         header, content = self.browser._state()
 
         if find_result is None:
-            return header.strip() + "\n=======================\nThe search string was not found on this page."
+            return (
+                header.strip()
+                + "\n=======================\nThe search string was not found on this page."
+            )
         else:
             return header.strip() + "\n=======================\n" + content
+
+
+__all__ = [
+    "DownloadTool",
+    "VisitTool",
+    "PageUpTool",
+    "PageDownTool",
+    "FinderTool",
+    "FindNextTool",
+    "ArchiveSearchTool",
+]

scripts/time_tools.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python
+# coding=utf-8
+# Copyright 2024 The Footscray Coding Collective. All rights reserved.
+from datetime import datetime
+from typing import Optional
+
+import pytz
+from smolagents import tool
+
+
+@tool
+def get_temporal_context(
+    timezone_str: str = "US/Eastern", market: str = "US", date_str: Optional[str] = None
+) -> str:
+    """
+    Provides a concise overview of the current temporal context, including date, time, and market status.
+
+    Args:
+        timezone_str: The timezone to display time in (default: US/Eastern)
+        market: Market identifier (US, EU, ASIA) (default: US)
+        date_str: Date in YYYY-MM-DD format (optional, defaults to current date if not provided)
+
+    Returns:
+        A formatted string containing the current date, time, year, trading day status, and market hours status.
+    """
+
+    try:
+        # Get current time information using pytz
+        try:
+            tz = pytz.timezone(timezone_str)
+        except pytz.exceptions.UnknownTimeZoneError:
+            return f"Error: Unknown timezone '{timezone_str}'. Try using standard timezone names like 'US/Eastern'."
+
+        now = datetime.now(tz)
+        current_date = now.strftime("%Y-%m-%d")
+        current_time = now.strftime("%H:%M:%S")
+        current_year = now.year
+        weekday_name = now.strftime("%A")
+        time_info = f"""Current Time Information:
+- Date: {current_date} ({weekday_name})
+- Time: {current_time} ({timezone_str})
+- Year: {current_year}
+"""
+
+        # Get Market hours Information
+        if market == "US":
+            # Convert time to US/Eastern for US market check
+            eastern_tz = pytz.timezone("US/Eastern")
+            eastern_now = now.astimezone(eastern_tz)
+
+            is_weekday_us = eastern_now.weekday() < 5
+            us_minutes = eastern_now.hour * 60 + eastern_now.minute
+            us_market_open = 9 * 60 + 30  # 9:30 AM ET
+            us_market_close = 16 * 60  # 4:00 PM ET
+
+            if is_weekday_us and us_market_open <= us_minutes < us_market_close:
+                market_status = "Open"
+            else:
+                market_status = "Closed"
+
+            market_hours_info = f"US Markets (NYSE, NASDAQ): {market_status}"
+
+        elif market == "EU":
+            # Convert time to London for EU market check
+            london_tz = pytz.timezone("Europe/London")
+            london_now = now.astimezone(london_tz)
+
+            is_weekday_eu = london_now.weekday() < 5
+            eu_minutes = london_now.hour * 60 + london_now.minute
+            eu_market_open = 8 * 60  # 8:00 AM London
+            eu_market_close = 16 * 60 + 30  # 4:30 PM London
+
+            if is_weekday_eu and eu_market_open <= eu_minutes < eu_market_close:
+                market_status = "Open"
+            else:
+                market_status = "Closed"
+
+            market_hours_info = f"European Markets (LSE, Euronext): {market_status}"
+
+        elif market == "ASIA":
+            # Convert time to Tokyo for Asian market check
+            tokyo_tz = pytz.timezone("Asia/Tokyo")
+            tokyo_now = now.astimezone(tokyo_tz)
+
+            is_weekday_tokyo = tokyo_now.weekday() < 5
+            tokyo_minutes = tokyo_now.hour * 60 + tokyo_now.minute
+            tokyo_morning_open = 9 * 60  # 9:00 AM Tokyo
+            tokyo_morning_close = 11 * 60 + 30  # 11:30 AM Tokyo
+            tokyo_afternoon_open = 12 * 60 + 30  # 12:30 PM Tokyo
+            tokyo_afternoon_close = 15 * 60  # 3:00 PM Tokyo
+
+            is_tokyo_session = (
+                tokyo_morning_open <= tokyo_minutes < tokyo_morning_close
+            ) or (tokyo_afternoon_open <= tokyo_minutes < tokyo_afternoon_close)
+
+            if is_weekday_tokyo and is_tokyo_session:
+                market_status = "Open"
+            else:
+                market_status = "Closed"
+
+            market_hours_info = (
+                "Asian Markets (Tokyo Stock Exchange, Shanghai Stock Exchange, "
+                f"Australian Securities Exchange): {market_status}"
+            )
+
+        else:
+            return f"Error: Invalid market '{market}'. Supported markets are 'US', 'EU', and 'ASIA'."
+
+        # Get Trading Day Information
+        if date_str:
+            try:
+                date_obj = datetime.strptime(date_str, "%Y-%m-%d")
+                # Apply timezone to date_obj
+                date_obj = tz.localize(date_obj)
+            except ValueError:
+                return (
+                    f"Error: Invalid date format '{date_str}'. Use YYYY-MM-DD format."
+                )
+        else:
+            date_obj = now
+            date_str = now.strftime("%Y-%m-%d")
+
+        is_weekend = date_obj.weekday() > 4
+        trading_day = "No" if is_weekend else "Yes"
+        trading_info = f"Trading Day: {trading_day}"
+
+        # Combine all information
+        final_result = f"""{time_info}
+{market_hours_info}
+- {trading_info}
+"""
+
+        return final_result
+
+    except Exception as e:
+        return f"Error retrieving temporal context: {str(e)}"
+
+
+__all__ = ["get_temporal_context"]

scripts/visual_qa.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+# coding=utf-8
 import base64
 import json
 import mimetypes
@@ -10,10 +12,8 @@ import requests
 from dotenv import load_dotenv
 from huggingface_hub import InferenceClient
 from PIL import Image
-from transformers import AutoProcessor
-
 from smolagents import Tool, tool
-
+from transformers import AutoProcessor
 
 load_dotenv(override=True)
 
@@ -31,7 +31,9 @@ def process_images_and_text(image_path, query, client):
         },
     ]
 
-    prompt_with_template = idefics_processor.apply_chat_template(messages, add_generation_prompt=True)
+    prompt_with_template = idefics_processor.apply_chat_template(
+        messages, add_generation_prompt=True
+    )
 
     # load images from local directory
 
@@ -42,7 +44,9 @@ def process_images_and_text(image_path, query, client):
 
         # Convert the image to a base64 string
         buffer = BytesIO()
-        image.save(buffer, format="JPEG")  # Use the appropriate format (e.g., JPEG, PNG)
+        image.save(
+            buffer, format="JPEG"
+        )  # Use the appropriate format (e.g., JPEG, PNG)
         base64_image = base64.b64encode(buffer.getvalue()).decode("utf-8")
 
         # add string formatting required by the endpoint
@@ -51,7 +55,9 @@ def process_images_and_text(image_path, query, client):
         return image_string
 
     image_string = encode_local_image(image_path)
-    prompt_with_images = prompt_with_template.replace("<image>", "![]({}) ").format(image_string)
+    prompt_with_images = prompt_with_template.replace("<image>", "![]({}) ").format(
+        image_string
+    )
 
     payload = {
         "inputs": prompt_with_images,
@@ -95,7 +101,10 @@ def encode_image(image_path):
         return base64.b64encode(image_file.read()).decode("utf-8")
 
 
-headers = {"Content-Type": "application/json", "Authorization": f"Bearer {os.getenv('OPENAI_API_KEY')}"}
+headers = {
+    "Content-Type": "application/json",
+    "Authorization": f"Bearer {os.getenv('OPENAI_API_KEY')}",
+}
 
 
 def resize_image(image_path):
@@ -115,7 +124,11 @@ class VisualQATool(Tool):
             "description": "The path to the image on which to answer the question",
             "type": "string",
         },
-        "question": {"description": "the question to answer", "type": "string", "nullable": True},
+        "question": {
+            "description": "the question to answer",
+            "type": "string",
+            "nullable": True,
+        },
     }
     output_type = "string"
     # try use the same model with two different endpoints
@@ -136,9 +149,7 @@ class VisualQATool(Tool):
                 output = process_images_and_text(new_image_path, question, self.client)
 
         if add_note:
-            output = (
-                f"You did not provide a particular question, so here is a detailed caption for the image: {output}"
-            )
+            output = f"You did not provide a particular question, so here is a detailed caption for the image: {output}"
 
         return output
 
@@ -156,7 +167,9 @@ def visualizer(image_path: str, question: Optional[str] = None) -> str:
         add_note = True
         question = "Please write a detailed caption for this image."
     if not isinstance(image_path, str):
-        raise Exception("You should provide at least `image_path` string argument to this tool!")
+        raise Exception(
+            "You should provide at least `image_path` string argument to this tool!"
+        )
 
     mime_type, _ = mimetypes.guess_type(image_path)
     base64_image = encode_image(image_path)
@@ -168,13 +181,18 @@ def visualizer(image_path: str, question: Optional[str] = None) -> str:
                 "role": "user",
                 "content": [
                     {"type": "text", "text": "what is in this image" + question},
-                    {"type": "image_url", "image_url": {"url": f"data:{mime_type};base64,{base64_image}"}},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:{mime_type};base64,{base64_image}"},
+                    },
                 ],
             }
         ],
         "max_tokens": 1000,
     }
-    response = requests.post("https://openrouter.ai/api/v1", headers=headers, json=payload)
+    response = requests.post(
+        "https://openrouter.ai/api/v1", headers=headers, json=payload
+    )
     try:
         output = response.json()["choices"][0]["message"]["content"]
     except Exception:
@@ -184,5 +202,5 @@ def visualizer(image_path: str, question: Optional[str] = None) -> str:
         output = f"You did not provide a particular question, so here is a detailed caption for the image: {output}"
 
     # TO DO: write to yaml or chromadb -> HF Dataset in due course...
-    
+
     return output