refactor: decompose monolithic app into modular architecture

- Split monolithic app.py into organized modules (tools/, agents/, etc.)
- Separate configuration from implementation in config.py
- Implement proper error handling for API calls
- Create specialized agent modules with clean factory pattern
- Maintain app.py as entry point for HuggingFace compatibility
- Improve code reusability and maintainability

agents/__init__.py

@@ -0,0 +1,3 @@
+"""
+Agent definitions for lyrics search and analysis components.
+"""

agents/analysis_agent.py

@@ -0,0 +1,46 @@
+"""
+Analysis agent for interpreting song lyrics and providing deeper context.
+"""
+
+from smolagents import CodeAgent, VisitWebpageTool
+from loguru import logger
+
+from config import AGENT_CONFIG, load_prompt_templates
+from tools.search_tools import ThrottledDuckDuckGoSearchTool
+from tools.analysis_tools import analyze_lyrics_tool
+
+
+def create_analysis_agent(model):
+    """
+    Create an agent specialized in analyzing and interpreting song lyrics.
+    
+    Args:
+        model: The LLM model to use with this agent
+        
+    Returns:
+        A configured CodeAgent for lyrics analysis
+    """
+    # Get configuration values
+    config = AGENT_CONFIG['analysis_agent']
+    prompt_templates = load_prompt_templates()
+    
+    # Create the throttled search tool
+    throttled_search_tool = ThrottledDuckDuckGoSearchTool(
+        min_delay=3.0, 
+        max_delay=7.0
+    )
+    
+    # Create and return the agent
+    agent = CodeAgent(
+        model=model,
+        tools=[throttled_search_tool, VisitWebpageTool(), analyze_lyrics_tool],
+        name="lyrics_analysis_agent",
+        description=config['description'],
+        additional_authorized_imports=["numpy", "bs4"],
+        max_steps=config['max_steps'],
+        verbosity_level=config['verbosity_level'],
+        prompt_templates=prompt_templates
+    )
+    
+    logger.info("Analysis agent created successfully")
+    return agent

agents/manager_agent.py

@@ -0,0 +1,46 @@
+"""
+Manager agent for coordinating the lyrics search and analysis process.
+"""
+
+from smolagents import CodeAgent, FinalAnswerTool
+from loguru import logger
+
+from config import AGENT_CONFIG, load_prompt_templates
+from agents.web_agent import create_web_agent
+from agents.analysis_agent import create_analysis_agent
+
+
+def create_manager_agent(model):
+    """
+    Create a manager agent that coordinates the web and analysis agents.
+    
+    Args:
+        model: The LLM model to use with this agent
+        
+    Returns:
+        A configured CodeAgent manager for coordinating other agents
+    """
+    # Get configuration values
+    config = AGENT_CONFIG['manager_agent']
+    prompt_templates = load_prompt_templates()
+    
+    # Create sub-agents
+    web_agent = create_web_agent(model)
+    analysis_agent = create_analysis_agent(model)
+    
+    # Create and return the manager agent
+    agent = CodeAgent(
+        model=model,
+        tools=[FinalAnswerTool()],
+        name="manager_agent",
+        description=config['description'],
+        managed_agents=[web_agent, analysis_agent],
+        additional_authorized_imports=["json"],
+        planning_interval=config['planning_interval'],
+        verbosity_level=config['verbosity_level'],
+        max_steps=config['max_steps'],
+        prompt_templates=prompt_templates
+    )
+    
+    logger.info("Manager agent created successfully")
+    return agent

agents/web_agent.py

@@ -0,0 +1,45 @@
+"""
+Web agent for finding and extracting song lyrics from online sources.
+"""
+
+from smolagents import CodeAgent, VisitWebpageTool
+from loguru import logger
+
+from config import AGENT_CONFIG, load_prompt_templates
+from tools.search_tools import ThrottledDuckDuckGoSearchTool
+
+
+def create_web_agent(model):
+    """
+    Create an agent specialized in web browsing and lyrics extraction.
+    
+    Args:
+        model: The LLM model to use with this agent
+        
+    Returns:
+        A configured CodeAgent for web searches
+    """
+    # Get configuration values
+    config = AGENT_CONFIG['web_agent']
+    prompt_templates = load_prompt_templates()
+    
+    # Create the throttled search tool
+    throttled_search_tool = ThrottledDuckDuckGoSearchTool(
+        min_delay=3.0, 
+        max_delay=7.0
+    )
+    
+    # Create and return the agent
+    agent = CodeAgent(
+        model=model,
+        tools=[throttled_search_tool, VisitWebpageTool()],
+        name="lyrics_search_agent",
+        description=config['description'],
+        additional_authorized_imports=["numpy", "bs4"],
+        max_steps=config['max_steps'],
+        verbosity_level=config['verbosity_level'],
+        prompt_templates=prompt_templates
+    )
+    
+    logger.info("Web agent (lyrics search) created successfully")
+    return agent

api_utils.py

@@ -0,0 +1,70 @@
+"""
+Utilities for making API calls with retry logic and error handling.
+"""
+
+import time
+import random
+import traceback
+from loguru import logger
+from litellm import completion
+
+def make_api_call_with_retry(model: str, prompt: str) -> str:
+    """
+    Makes an API call with a retry mechanism for error handling.
+
+    Args:
+        model: The model identifier to use.
+        prompt: The prompt text to send to the model.
+
+    Returns:
+        The response from the model as a string.
+    """
+    max_attempts = 20
+    base_delay = 10
+    max_delay = 60
+    attempt = 0
+    last_exception = None
+    
+    while attempt < max_attempts:
+        try:
+            # Add a small random delay to prevent simultaneous requests
+            jitter = random.uniform(0.1, 1.0)
+            time.sleep(jitter)
+            
+            # If this is a retry attempt, add exponential backoff delay
+            if attempt > 0:
+                delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
+                time.sleep(delay)
+            
+            response = completion(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                num_retries=2,  # Built-in retry mechanism of LiteLLM
+            )
+
+            # Try to extract the content from the response
+            try:
+                analysis_result = response.choices[0].message.content.strip()
+                return analysis_result
+            except (AttributeError, KeyError, IndexError):
+                try:
+                    analysis_result = response["choices"][0]["message"]["content"].strip()
+                    return analysis_result
+                except (AttributeError, KeyError, IndexError):
+                    # If we couldn't extract the content, return an error
+                    raise ValueError("Failed to extract content from response")
+                    
+        except (ConnectionError, TimeoutError) as e:
+            last_exception = e
+            logger.warning("API call failed (attempt {}/{}) for model {}: {}. Retrying...", attempt+1, max_attempts, model, str(e))
+            attempt += 1
+            continue
+        except Exception as e:
+            logger.error("Unexpected error: {}", str(e))
+            logger.error(traceback.format_exc())
+            raise  # For other exceptions, we don't retry
+    
+    # If all attempts failed, re-raise the last exception
+    if last_exception:
+        logger.error("All {} attempts failed. Last error: {}", max_attempts, str(last_exception))
+        raise last_exception

app.py

@@ -1,225 +1,49 @@
-import os
-import time
-import random
-import yaml
-import traceback
-from loguru import logger
-from Gradio_UI import GradioUI
-from litellm import completion
-from smolagents import (
-    CodeAgent,
-    DuckDuckGoSearchTool,
-    FinalAnswerTool,
-    LiteLLMModel,
-    VisitWebpageTool,
-    tool,
-    Tool,
-)
-
-# Setting up logging with loguru - only terminal output
-logger.remove()  # Remove default handlers
-logger.add(
-    lambda msg: print(msg, end=""), 
-    level="INFO", 
-    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{message}</cyan>")
-
-# API key configuration
-os.environ["GEMINI_API_KEY"] = os.getenv("GEMINI_API_KEY")
-
-
-class LyricsSearchTool(Tool):
-    """
-    Uses web search to find song lyrics based on song title and artist name
-
-    The search query should include the song title and artist name. The tool
-    will return the lyrics of the song if found.
-
-    Parameters
-    ----------
-    query : str
-        The search query for finding song lyrics. Should include song title and artist name.
-
-    Returns
-    -------
-    str
-        The lyrics of the song if found, otherwise an empty string.
-    """
-    name = "lyrics_search_tool"
-    description = "Uses web search to find song lyrics based on song title and artist name"
-    inputs = {
-        "query": {
-            "type": "string",
-            "description": "The search query for finding song lyrics. Should include song title and artist name.",
-        }
-    }
-    output_type = "string"
-
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-
-    def forward(self, query: str) -> str:
-        assert isinstance(query, str), "Your search query must be a string"
-        # TODO: Implement lyrics search functionality
-        return "Lyrics search not implemented yet"
-
-with open("prompts.yaml", 'r') as stream:
-    prompt_templates = yaml.safe_load(stream)
-
-@tool
-def analyze_lyrics_tool(song_title: str, artist: str, lyrics: str) -> str:
-    """
-    Performs a deep analysis of the musical track, given its metadata.
-
-    Args:
-        song_title: Title of the song or music track.
-        artist: The name of the artist.
-        lyrics: The lyrics of the song.
-
-    Returns:
-        A summary of the song's meaning in English.
-    """
+#!/usr/bin/env python3
+"""
+Lyrics Analyzer Agent - Main Entry Point
 
-    prompt = f"""You are an expert in songs and their meanings. 
-    Summarize the meaning of {song_title} by {artist} and identify 
-    key themes based on the lyrics: 
-    {lyrics}. 
+This module serves as the entry point for the Lyrics Analyzer application, which
+uses a system of specialized agents to search for and analyze song lyrics.  
+"""
 
-    Include deep idea and vibes analysis with explanations 
-    based on references to the exact lines.
-    """
-
-    # If the USE_ANTHROPIC environment variable is defined, use the Claude model
-    if os.getenv("USE_ANTHROPIC", "false").lower() == "true":
-        model_to_use = "claude-3-haiku-20240307"
-        logger.info("Using Anthropic model: {} for lyrics analysis", model_to_use)
-    else:
-        model_to_use = "gemini/gemini-2.0-flash"
-        logger.info("Using Gemini model: {} for lyrics analysis", model_to_use)
+from loguru import logger
+from Gradio_UI import GradioUI
+from smolagents import LiteLLMModel
 
-    # Use the function with retry mechanism
-    logger.info("Analyzing lyrics for song: '{}' by '{}'", song_title, artist)
-    return _make_api_call_with_retry(model_to_use, prompt)
+from config import setup_logger, load_api_keys, get_model_id, GRADIO_CONFIG
+from agents.manager_agent import create_manager_agent
 
 
-# Function with manual implementation of retry mechanism
-def _make_api_call_with_retry(model: str, prompt: str) -> str:
+def main():
     """
-    Makes an API call with a retry mechanism for error handling.
-
-    Args:
-        model: The model identifier to use.
-        prompt: The prompt text to send to the model.
-
-    Returns:
-        The response from the model as a string.
+    Main function to initialize and run the Lyrics Analyzer Agent.
+    
+    This function sets up logging, loads API keys, initializes the LLM model,
+    and starts the Gradio UI server with the manager agent.
     """
-    max_attempts = 20
-    base_delay = 10
-    max_delay = 60
-    attempt = 0
-    last_exception = None
+    # Setup logger and API keys
+    setup_logger()
+    load_api_keys()
     
-    while attempt < max_attempts:
-        try:
-            # Add a small random delay to prevent simultaneous requests
-            jitter = random.uniform(0.1, 1.0)
-            time.sleep(jitter)
-            
-            # If this is a retry attempt, add exponential backoff delay
-            if attempt > 0:
-                delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
-                time.sleep(delay)
-            
-            response = completion(
-                model=model,
-                messages=[{"role": "user", "content": prompt}],
-                num_retries=2,  # Built-in retry mechanism of LiteLLM
-            )
-
-            # Try to extract the content from the response
-            try:
-                analysis_result = response.choices[0].message.content.strip()
-                return analysis_result
-            except (AttributeError, KeyError, IndexError):
-                try:
-                    analysis_result = response["choices"][0]["message"]["content"].strip()
-                    return analysis_result
-                except (AttributeError, KeyError, IndexError):
-                    # If we couldn't extract the content, return an error
-                    raise ValueError("Failed to extract content from response")
-                    
-        except (ConnectionError, TimeoutError) as e:
-            last_exception = e
-            logger.warning("API call failed (attempt {}/{}) for model {}: {}. Retrying...", attempt+1, max_attempts, model, str(e))
-            attempt += 1
-            continue
-        except Exception as e:
-            logger.error("Unexpected error: {}", str(e))
-            logger.error(traceback.format_exc())
-            raise  # For other exceptions, we don't retry
+    # Initialize the LLM model based on configuration
+    model_id = get_model_id()
+    logger.info(f"Initializing with model: {model_id}")
+    model = LiteLLMModel(model_id=model_id)
     
-    # If all attempts failed, re-raise the last exception
-    if last_exception:
-        logger.error("All {} attempts failed. Last error: {}", max_attempts, str(last_exception))
-        raise last_exception
-
-
-# TODO: use DuckDuckGoSearchTool to find related information
-# for explanation in case the LLM itself is not confident or doesn't know
-
-# Check if we need to use Anthropic for local testing
-use_anthropic = os.getenv("USE_ANTHROPIC", "false").lower() == "true"
-
-# Configure Anthropic API key if needed
-if use_anthropic:
-    os.environ["ANTHROPIC_API_KEY"] = os.getenv("ANTHROPIC_API_KEY")
-    model = LiteLLMModel(model_id="claude-3-haiku-20240307")
-    logger.info("Using Anthropic Claude model for local testing")
-else:
-    model = LiteLLMModel(model_id="gemini/gemini-2.0-flash")
-    logger.info("Using Gemini model as default")
-
-web_agent = CodeAgent(
-    model=model,
-    tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
-    name="lyrics_search_agent",
-    description="Browses the web to find original full lyrics and scrape them. Excels at building effective search queries",
-    additional_authorized_imports=["numpy", "bs4"],
-    max_steps=50,
-    verbosity_level=2,
-    prompt_templates=prompt_templates
-)
-
-
-analysis_agent = CodeAgent(
-    model=model,
-    tools=[DuckDuckGoSearchTool(), VisitWebpageTool(), analyze_lyrics_tool],
-    name="lyrics_analysis_agent",
-    description="You are a Song Analysis Expert with deep knowledge of music theory, lyrical interpretation, cultural contexts, and music history. Your role is to analyze song lyrics to uncover their deeper meaning, artistic significance, and historical context.",
-    additional_authorized_imports=["numpy", "bs4"],
-    max_steps=5,
-    verbosity_level=2,
-    prompt_templates=prompt_templates
-)
-
-
-# When using the DuckDuckGoSearchTool, clearly indicate when information comes from external research versus your own knowledge base.
-manager_agent = CodeAgent(
-    model=model,
-    tools=[FinalAnswerTool()],
-    name="manager_agent",
-    description="Manages the search process and coordinates the search and analysis of song lyrics.",
-    managed_agents=[web_agent, analysis_agent],
-    additional_authorized_imports=["json"],
-    planning_interval=5,
-    verbosity_level=2,
-    max_steps=15,
-    prompt_templates=prompt_templates
-)
-
-logger.info("Initializing Gradio UI and launching server")
-GradioUI(manager_agent).launch(
-    debug=True, share=True, 
-    server_name="127.0.0.1",  server_port=3000
-)
-logger.success("Server started successfully")
+    # Create the manager agent which will create and manage the other agents
+    manager_agent = create_manager_agent(model)
+    
+    # Start the Gradio UI server
+    logger.info("Initializing Gradio UI and launching server")
+    GradioUI(manager_agent).launch(
+        debug=GRADIO_CONFIG['debug'], 
+        share=GRADIO_CONFIG['share'],
+        server_name=GRADIO_CONFIG['server_name'], 
+        server_port=GRADIO_CONFIG['server_port']
+    )
+    logger.success("Server started successfully")
+
+
+# Run the application when executed directly
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,86 @@
+"""
+Configuration parameters for the Lyrics Analyzer Agent.
+
+This module separates configuration from implementation,
+making it easier to modify settings without changing code.
+"""
+
+import os
+import yaml
+from loguru import logger
+
+# Logger configuration
+def setup_logger():
+    """Configure loguru logger with custom formatting."""
+    logger.remove()  # Remove default handlers
+    logger.add(
+        lambda msg: print(msg, end=""), 
+        level="INFO", 
+        format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{message}</cyan>"
+    )
+
+# API configuration
+def load_api_keys():
+    """Load API keys from environment variables."""
+    # Gemini API is the default
+    os.environ["GEMINI_API_KEY"] = os.getenv("GEMINI_API_KEY")
+    
+    # Anthropic API for local testing
+    if use_anthropic():
+        os.environ["ANTHROPIC_API_KEY"] = os.getenv("ANTHROPIC_API_KEY")
+
+# Default model configuration
+def use_anthropic():
+    """Check if we should use Anthropic instead of Gemini."""
+    return os.getenv("USE_ANTHROPIC", "false").lower() == "true"
+
+def get_model_id():
+    """Get the appropriate model ID based on configuration."""
+    if use_anthropic():
+        return "claude-3-haiku-20240307"
+    else:
+        return "gemini/gemini-2.0-flash"
+
+# Load prompts from YAML
+def load_prompt_templates():
+    """Load prompt templates from YAML file."""
+    try:
+        with open("prompts.yaml", 'r') as stream:
+            return yaml.safe_load(stream)
+    except (FileNotFoundError, yaml.YAMLError) as e:
+        logger.error(f"Error loading prompts.yaml: {e}")
+        return {}  # Return empty dict to avoid breaking the application
+
+# Tool configuration
+SEARCH_TOOL_CONFIG = {
+    "min_delay": 3.0,
+    "max_delay": 7.0
+}
+
+# Agent configuration
+AGENT_CONFIG = {
+    "web_agent": {
+        "max_steps": 50,
+        "verbosity_level": 2,
+        "description": "Browses the web to find original full lyrics and scrape them. Excels at building effective search queries"
+    },
+    "analysis_agent": {
+        "max_steps": 5,
+        "verbosity_level": 2,
+        "description": "You are a Song Analysis Expert with deep knowledge of music theory, lyrical interpretation, cultural contexts, and music history. Your role is to analyze song lyrics to uncover their deeper meaning, artistic significance, and historical context."
+    },
+    "manager_agent": {
+        "max_steps": 15,
+        "verbosity_level": 2,
+        "planning_interval": 5,
+        "description": "Manages the search process and coordinates the search and analysis of song lyrics."
+    }
+}
+
+# Gradio UI configuration
+GRADIO_CONFIG = {
+    "debug": True,
+    "share": True,
+    "server_name": "127.0.0.1",
+    "server_port": 3000
+}

tools/__init__.py

@@ -0,0 +1,3 @@
+"""
+Tools for interacting with search engines and analyzing song lyrics.
+"""

tools/analysis_tools.py

@@ -0,0 +1,44 @@
+"""
+Analysis tools for understanding and interpreting song lyrics.
+"""
+
+import os
+from loguru import logger
+from smolagents import tool
+
+from api_utils import make_api_call_with_retry
+
+@tool
+def analyze_lyrics_tool(song_title: str, artist: str, lyrics: str) -> str:
+    """
+    Performs a deep analysis of the musical track, given its metadata.
+
+    Args:
+        song_title: Title of the song or music track.
+        artist: The name of the artist.
+        lyrics: The lyrics of the song.
+
+    Returns:
+        A summary of the song's meaning in English.
+    """
+
+    prompt = f"""You are an expert in songs and their meanings. 
+    Summarize the meaning of {song_title} by {artist} and identify 
+    key themes based on the lyrics: 
+    {lyrics}. 
+
+    Include deep idea and vibes analysis with explanations 
+    based on references to the exact lines.
+    """
+
+    # Determine which model to use based on configuration
+    if os.getenv("USE_ANTHROPIC", "false").lower() == "true":
+        model_to_use = "claude-3-haiku-20240307"
+        logger.info("Using Anthropic model: {} for lyrics analysis", model_to_use)
+    else:
+        model_to_use = "gemini/gemini-2.0-flash"
+        logger.info("Using Gemini model: {} for lyrics analysis", model_to_use)
+
+    # Use the function with retry mechanism
+    logger.info("Analyzing lyrics for song: '{}' by '{}'", song_title, artist)
+    return make_api_call_with_retry(model_to_use, prompt)

tools/search_tools.py

@@ -0,0 +1,95 @@
+"""
+Search tools for finding song lyrics and related information.
+"""
+
+import time
+import random
+from typing import Dict, List, Any
+from loguru import logger
+from smolagents import DuckDuckGoSearchTool, Tool
+
+class ThrottledDuckDuckGoSearchTool(DuckDuckGoSearchTool):
+    """
+    A wrapper around DuckDuckGoSearchTool that adds a delay between requests
+    to avoid rate limiting issues.
+    
+    This tool implements a delay mechanism to prevent hitting DuckDuckGo's rate limits.
+    Each search request will be followed by a random delay within the specified range.
+    """
+    
+    def __init__(self, min_delay: float = 2.0, max_delay: float = 5.0, **kwargs):
+        """
+        Initialize the throttled search tool with delay parameters.
+        
+        Args:
+            min_delay: Minimum delay in seconds between requests (default: 2.0)
+            max_delay: Maximum delay in seconds between requests (default: 5.0)
+            **kwargs: Additional arguments to pass to DuckDuckGoSearchTool
+        """
+        super().__init__(**kwargs)
+        self.min_delay = min_delay
+        self.max_delay = max_delay
+        self.name = "search"  # Keep the same name as the parent class
+        logger.info(f"Initialized ThrottledDuckDuckGoSearchTool with delay range: {min_delay}-{max_delay}s")
+    
+    def forward(self, query: str) -> List[Dict[str, Any]]:
+        """
+        Execute a search with a delay to avoid rate limiting.
+        
+        Args:
+            query: The search query string
+            
+        Returns:
+            List of search results
+        """
+        # Add a random delay before the search to avoid rate limiting
+        delay = random.uniform(self.min_delay, self.max_delay)
+        logger.info(f"Throttling DuckDuckGo search for {delay:.2f} seconds before query: '{query}'")
+        time.sleep(delay)
+        
+        # Call the parent class implementation
+        try:
+            results = super().forward(query)
+            # Add another delay after the search to ensure spacing between requests
+            time.sleep(random.uniform(self.min_delay / 2, self.max_delay / 2))
+            return results
+        except Exception as e:
+            logger.error(f"Error in DuckDuckGo search: {str(e)}")
+            # Return empty results on error to allow the agent to continue
+            return [{"title": "Search error", "href": "", "body": f"Error performing search: {str(e)}"}]
+
+
+class LyricsSearchTool(Tool):
+    """
+    Uses web search to find song lyrics based on song title and artist name
+
+    The search query should include the song title and artist name. The tool
+    will return the lyrics of the song if found.
+
+    Parameters
+    ----------
+    query : str
+        The search query for finding song lyrics. Should include song title and artist name.
+
+    Returns
+    -------
+    str
+        The lyrics of the song if found, otherwise an empty string.
+    """
+    name = "lyrics_search_tool"
+    description = "Uses web search to find song lyrics based on song title and artist name"
+    inputs = {
+        "query": {
+            "type": "string",
+            "description": "The search query for finding song lyrics. Should include song title and artist name.",
+        }
+    }
+    output_type = "string"
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+    def forward(self, query: str) -> str:
+        assert isinstance(query, str), "Your search query must be a string"
+        # TODO: Implement lyrics search functionality
+        return "Lyrics search not implemented yet"