feat: Add Text Story module with iMessage-style chat video generation

modules/bar_race/__init__.py

@@ -1,35 +0,0 @@
-"""
-Bar Race Module
-Intelligent Bar Chart Race Video Generator.
-
-Architecture:
-- Brain: LLM Planner (Gemini)
-- Scout: Data Fetcher (APIs + Scraping)
-- Surgeon: Data Cleaner
-- Artist: Image Processor
-- Director: Video Generator
-
-100% standalone - no dependency on other modules.
-"""
-import logging
-from fastapi import FastAPI
-
-logger = logging.getLogger(__name__)
-
-# Module metadata for auto-discovery
-MODULE_NAME = "bar_race"
-MODULE_PREFIX = "/api/bar-race"
-MODULE_DESCRIPTION = "Bar Chart Race Video Generator"
-
-_app = None
-
-
-def register(app: FastAPI, config=None):
-    """Register Bar Race module routes"""
-    global _app
-    _app = app
-    
-    from .router import router
-    app.include_router(router, prefix="/api/bar-race", tags=["Bar Race"])
-    
-    logger.info("Bar Race module registered at /api/bar-race")

modules/bar_race/assets/fonts/.gitkeep

@@ -1 +0,0 @@
-# Custom fonts for video rendering

modules/bar_race/assets/images/.gitkeep

@@ -1 +0,0 @@
-# Entity images will be downloaded here during video generation

modules/bar_race/assets/music/.gitkeep

@@ -1,3 +0,0 @@
-# Optional background music files
-# Supported formats: .mp3, .wav, .m4a, .ogg
-# Music will be automatically added if files exist here

modules/bar_race/deep_researcher/__init__.py

@@ -1,13 +0,0 @@
-"""Deep Researcher Module - LangGraph-based web research agent"""
-
-from .graph import graph
-from .state import SummaryState, SummaryStateInput, SummaryStateOutput
-from .configuration import Configuration
-
-__all__ = [
-    "graph",
-    "SummaryState",
-    "SummaryStateInput", 
-    "SummaryStateOutput",
-    "Configuration",
-]

modules/bar_race/deep_researcher/configuration.py

@@ -1,81 +0,0 @@
-import os
-from enum import Enum
-from pydantic import BaseModel, Field
-from typing import Any, Optional, Literal
-
-from langchain_core.runnables import RunnableConfig
-
-
-class SearchAPI(Enum):
-    PERPLEXITY = "perplexity"
-    TAVILY = "tavily"
-    DUCKDUCKGO = "duckduckgo"
-    # SEARXNG removed - requires langchain-community
-
-
-class Configuration(BaseModel):
-    """The configurable fields for the research assistant."""
-
-    max_web_research_loops: int = Field(
-        default=3,
-        title="Research Depth",
-        description="Number of research iterations to perform",
-    )
-    local_llm: str = Field(
-        default="llama3.2",
-        title="LLM Model Name",
-        description="Name of the LLM model to use",
-    )
-    llm_provider: Literal["ollama", "lmstudio"] = Field(
-        default="ollama",
-        title="LLM Provider",
-        description="Provider for the LLM (Ollama or LMStudio)",
-    )
-    search_api: Literal["perplexity", "tavily", "duckduckgo"] = Field(
-        default="tavily", title="Search API", description="Web search API to use"
-    )
-    fetch_full_page: bool = Field(
-        default=True,
-        title="Fetch Full Page",
-        description="Include the full page content in the search results",
-    )
-    ollama_base_url: str = Field(
-        default="http://localhost:11434/",
-        title="Ollama Base URL",
-        description="Base URL for Ollama API",
-    )
-    lmstudio_base_url: str = Field(
-        default="http://localhost:1234/v1",
-        title="LMStudio Base URL",
-        description="Base URL for LMStudio OpenAI-compatible API",
-    )
-    strip_thinking_tokens: bool = Field(
-        default=True,
-        title="Strip Thinking Tokens",
-        description="Whether to strip <think> tokens from model responses",
-    )
-    use_tool_calling: bool = Field(
-        default=False,
-        title="Use Tool Calling",
-        description="Use tool calling instead of JSON mode for structured output",
-    )
-
-    @classmethod
-    def from_runnable_config(
-        cls, config: Optional[RunnableConfig] = None
-    ) -> "Configuration":
-        """Create a Configuration instance from a RunnableConfig."""
-        configurable = (
-            config["configurable"] if config and "configurable" in config else {}
-        )
-
-        # Get raw values from environment or config
-        raw_values: dict[str, Any] = {
-            name: os.environ.get(name.upper(), configurable.get(name))
-            for name in cls.model_fields.keys()
-        }
-
-        # Filter out None values
-        values = {k: v for k, v in raw_values.items() if v is not None}
-
-        return cls(**values)

modules/bar_race/deep_researcher/graph.py

@@ -1,456 +0,0 @@
-import json
-import os
-
-from pydantic import BaseModel, Field
-from typing_extensions import Literal
-
-from langchain_core.messages import HumanMessage, SystemMessage
-from langchain_core.runnables import RunnableConfig
-from langchain_core.tools import tool
-from langchain_google_genai import ChatGoogleGenerativeAI
-from langgraph.graph import START, END, StateGraph
-
-from .configuration import Configuration, SearchAPI
-from .utils import (
-    deduplicate_and_format_sources,
-    tavily_search,
-    format_sources,
-    perplexity_search,
-    duckduckgo_search,
-    strip_thinking_tokens,
-    get_config_value,
-)
-from .state import (
-    SummaryState,
-    SummaryStateInput,
-    SummaryStateOutput,
-)
-from .prompts import (
-    query_writer_instructions,
-    summarizer_instructions,
-    reflection_instructions,
-    get_current_date,
-    json_mode_query_instructions,
-    tool_calling_query_instructions,
-    json_mode_reflection_instructions,
-    tool_calling_reflection_instructions,
-)
-from .rate_limiter import gemini_rate_limiter
-
-# Constants
-MAX_TOKENS_PER_SOURCE = 1000
-CHARS_PER_TOKEN = 4
-
-
-def convert_messages_for_gemma(messages: list) -> list:
-    """
-    Convert SystemMessage to HumanMessage for Gemma model compatibility.
-    
-    Gemma models don't support 'developer instructions' (SystemMessage) through
-    the LangChain interface. This function converts all SystemMessages to 
-    HumanMessages with a clear instruction prefix.
-    
-    Args:
-        messages: List of LangChain messages
-        
-    Returns:
-        List of messages with SystemMessages converted to HumanMessages
-    """
-    converted = []
-    for msg in messages:
-        if isinstance(msg, SystemMessage):
-            # Convert SystemMessage to HumanMessage with instruction prefix
-            converted.append(HumanMessage(
-                content=f"[INSTRUCTIONS]\n{msg.content}\n[/INSTRUCTIONS]"
-            ))
-        else:
-            converted.append(msg)
-    return converted
-
-def generate_search_query_with_structured_output(
-    configurable: Configuration,
-    messages: list,
-    tool_class,
-    fallback_query: str,
-    tool_query_field: str,
-    json_query_field: str,
-):
-    """Helper function to generate search queries using either tool calling or JSON mode.
-    
-    Args:
-        configurable: Configuration object
-        messages: List of messages to send to LLM
-        tool_class: Tool class for tool calling mode
-        fallback_query: Fallback search query if extraction fails
-        tool_query_field: Field name in tool args containing the query
-        json_query_field: Field name in JSON response containing the query
-        
-    Returns:
-        Dictionary with "search_query" key
-    """
-    # Convert messages for Gemma compatibility (no SystemMessage)
-    messages = convert_messages_for_gemma(messages)
-    
-    if configurable.use_tool_calling:
-        llm = get_llm(configurable).bind_tools([tool_class])
-        gemini_rate_limiter.acquire()  # Rate limit before API call
-        result = llm.invoke(messages)
-
-        if not result.tool_calls:
-            return {"search_query": fallback_query}
-        
-        try:
-            tool_data = result.tool_calls[0]["args"]
-            search_query = tool_data.get(tool_query_field)
-            return {"search_query": search_query}
-        except (IndexError, KeyError):
-            return {"search_query": fallback_query}
-    
-    else:
-        # Use JSON mode
-        llm = get_llm(configurable)
-        gemini_rate_limiter.acquire()  # Rate limit before API call
-        result = llm.invoke(messages)
-        print(f"result: {result}")
-        content = result.content
-
-        try:
-            parsed_json = json.loads(content)
-            search_query = parsed_json.get(json_query_field)
-            if not search_query:
-                return {"search_query": fallback_query}
-            return {"search_query": search_query}
-        except (json.JSONDecodeError, KeyError):
-            if configurable.strip_thinking_tokens:
-                content = strip_thinking_tokens(content)
-            return {"search_query": fallback_query}
-
-def get_llm(configurable: Configuration):
-    """Helper function to initialize LLM based on configuration.
-
-    Uses Gemini API for all operations.
-
-    Args:
-        configurable: Configuration object containing LLM settings
-
-    Returns:
-        Configured LLM instance
-    """
-    # Use Gemini for all providers
-    # Using gemma-3-27b-it for higher rate limits (30 req/min vs 10 req/min)
-    return ChatGoogleGenerativeAI(
-        model=os.getenv("GEMINI_MODEL", "gemma-3-27b-it"),
-        google_api_key=os.getenv("GEMINI_API_KEY"),
-        temperature=0,
-    )
-
-# Nodes
-def generate_query(state: SummaryState, config: RunnableConfig):
-    """LangGraph node that generates a search query based on the research topic.
-
-    Uses an LLM to create an optimized search query for web research based on
-    the user's research topic. Supports both LMStudio and Ollama as LLM providers.
-
-    Args:
-        state: Current graph state containing the research topic
-        config: Configuration for the runnable, including LLM provider settings
-
-    Returns:
-        Dictionary with state update, including search_query key containing the generated query
-    """
-
-    # Format the prompt
-    current_date = get_current_date()
-    formatted_prompt = query_writer_instructions.format(
-        current_date=current_date, research_topic=state.research_topic
-    )
-
-    # Generate a query
-    configurable = Configuration.from_runnable_config(config)
-
-    @tool
-    class Query(BaseModel):
-        """
-        This tool is used to generate a query for web search.
-        """
-
-        query: str = Field(description="The actual search query string")
-        rationale: str = Field(
-            description="Brief explanation of why this query is relevant"
-        )
-
-    messages = [
-        SystemMessage(
-            content=formatted_prompt + (
-                tool_calling_query_instructions if configurable.use_tool_calling 
-                else json_mode_query_instructions
-            )
-        ),
-        HumanMessage(content="Generate a query for web search:"),
-    ]
-
-    return generate_search_query_with_structured_output(
-        configurable=configurable,
-        messages=messages,
-        tool_class=Query,
-        fallback_query=f"Tell me more about {state.research_topic}",
-        tool_query_field="query",
-        json_query_field="query",
-    )
-
-
-def web_research(state: SummaryState, config: RunnableConfig):
-    """LangGraph node that performs web research using the generated search query.
-
-    Executes a web search using the configured search API (tavily, perplexity,
-    duckduckgo, or searxng) and formats the results for further processing.
-
-    Args:
-        state: Current graph state containing the search query and research loop count
-        config: Configuration for the runnable, including search API settings
-
-    Returns:
-        Dictionary with state update, including sources_gathered, research_loop_count, and web_research_results
-    """
-
-    # Configure
-    configurable = Configuration.from_runnable_config(config)
-
-    # Get the search API
-    search_api = get_config_value(configurable.search_api)
-
-    # Search the web
-    if search_api == "tavily":
-        search_results = tavily_search(
-            state.search_query,
-            fetch_full_page=configurable.fetch_full_page,
-            max_results=1,
-        )
-        search_str = deduplicate_and_format_sources(
-            search_results,
-            max_tokens_per_source=MAX_TOKENS_PER_SOURCE,
-            fetch_full_page=configurable.fetch_full_page,
-        )
-    elif search_api == "perplexity":
-        search_results = perplexity_search(
-            state.search_query, state.research_loop_count
-        )
-        search_str = deduplicate_and_format_sources(
-            search_results,
-            max_tokens_per_source=MAX_TOKENS_PER_SOURCE,
-            fetch_full_page=configurable.fetch_full_page,
-        )
-    elif search_api == "duckduckgo":
-        search_results = duckduckgo_search(
-            state.search_query,
-            max_results=3,
-            fetch_full_page=configurable.fetch_full_page,
-        )
-        search_str = deduplicate_and_format_sources(
-            search_results,
-            max_tokens_per_source=MAX_TOKENS_PER_SOURCE,
-            fetch_full_page=configurable.fetch_full_page,
-        )
-    # Note: searxng removed - use tavily or duckduckgo instead
-    else:
-        raise ValueError(f"Unsupported search API: {configurable.search_api}")
-
-    return {
-        "sources_gathered": [format_sources(search_results)],
-        "research_loop_count": state.research_loop_count + 1,
-        "web_research_results": [search_str],
-    }
-
-
-def summarize_sources(state: SummaryState, config: RunnableConfig):
-    """LangGraph node that summarizes web research results.
-
-    Uses an LLM to create or update a running summary based on the newest web research
-    results, integrating them with any existing summary.
-
-    Args:
-        state: Current graph state containing research topic, running summary,
-              and web research results
-        config: Configuration for the runnable, including LLM provider settings
-
-    Returns:
-        Dictionary with state update, including running_summary key containing the updated summary
-    """
-
-    # Existing summary
-    existing_summary = state.running_summary
-
-    # Most recent web research
-    most_recent_web_research = state.web_research_results[-1]
-
-    # Build the human message
-    if existing_summary:
-        human_message_content = (
-            f"<Existing Summary> \n {existing_summary} \n <Existing Summary>\n\n"
-            f"<New Context> \n {most_recent_web_research} \n <New Context>"
-            f"Update the Existing Summary with the New Context on this topic: \n <User Input> \n {state.research_topic} \n <User Input>\n\n"
-        )
-    else:
-        human_message_content = (
-            f"<Context> \n {most_recent_web_research} \n <Context>"
-            f"Create a Summary using the Context on this topic: \n <User Input> \n {state.research_topic} \n <User Input>\n\n"
-        )
-
-    # Run the LLM
-    configurable = Configuration.from_runnable_config(config)
-
-    # Use Gemini via get_llm helper
-    llm = get_llm(configurable)
-
-    # Build messages and convert for Gemma compatibility
-    messages = convert_messages_for_gemma([
-        SystemMessage(content=summarizer_instructions),
-        HumanMessage(content=human_message_content),
-    ])
-    
-    gemini_rate_limiter.acquire()  # Rate limit before API call
-    result = llm.invoke(messages)
-
-    # Strip thinking tokens if configured
-    running_summary = result.content
-    if configurable.strip_thinking_tokens:
-        running_summary = strip_thinking_tokens(running_summary)
-
-    return {"running_summary": running_summary}
-
-
-def reflect_on_summary(state: SummaryState, config: RunnableConfig):
-    """LangGraph node that identifies knowledge gaps and generates follow-up queries.
-
-    Analyzes the current summary to identify areas for further research and generates
-    a new search query to address those gaps. Uses structured output to extract
-    the follow-up query in JSON format.
-
-    Args:
-        state: Current graph state containing the running summary and research topic
-        config: Configuration for the runnable, including LLM provider settings
-
-    Returns:
-        Dictionary with state update, including search_query key containing the generated follow-up query
-    """
-
-    # Generate a query
-    configurable = Configuration.from_runnable_config(config)
-    formatted_prompt = reflection_instructions.format(
-        research_topic=state.research_topic
-    )
-
-    @tool
-    class FollowUpQuery(BaseModel):
-        """
-        This tool is used to generate a follow-up query to address a knowledge gap.
-        """
-
-        follow_up_query: str = Field(
-            description="Write a specific question to address this gap"
-        )
-        knowledge_gap: str = Field(
-            description="Describe what information is missing or needs clarification"
-        )
-
-    messages = [
-        SystemMessage(
-            content=formatted_prompt + (
-                tool_calling_reflection_instructions if configurable.use_tool_calling 
-                else json_mode_reflection_instructions
-            )
-        ),
-        HumanMessage(
-            content=f"Reflect on our existing knowledge: \n === \n {state.running_summary}, \n === \n And now identify a knowledge gap and generate a follow-up web search query:"
-        ),
-    ]
-
-    return generate_search_query_with_structured_output(
-        configurable=configurable,
-        messages=messages,
-        tool_class=FollowUpQuery,
-        fallback_query=f"Tell me more about {state.research_topic}",
-        tool_query_field="follow_up_query",
-        json_query_field="follow_up_query",
-    )
-
-
-def finalize_summary(state: SummaryState):
-    """LangGraph node that finalizes the research summary.
-
-    Prepares the final output by deduplicating and formatting sources, then
-    combining them with the running summary to create a well-structured
-    research report with proper citations.
-
-    Args:
-        state: Current graph state containing the running summary and sources gathered
-
-    Returns:
-        Dictionary with state update, including running_summary key containing the formatted final summary with sources
-    """
-
-    # Deduplicate sources before joining
-    seen_sources = set()
-    unique_sources = []
-
-    for source in state.sources_gathered:
-        # Split the source into lines and process each individually
-        for line in source.split("\n"):
-            # Only process non-empty lines
-            if line.strip() and line not in seen_sources:
-                seen_sources.add(line)
-                unique_sources.append(line)
-
-    # Join the deduplicated sources
-    all_sources = "\n".join(unique_sources)
-    state.running_summary = (
-        f"## Summary\n{state.running_summary}\n\n ### Sources:\n{all_sources}"
-    )
-    return {"running_summary": state.running_summary}
-
-
-def route_research(
-    state: SummaryState, config: RunnableConfig
-) -> Literal["finalize_summary", "web_research"]:
-    """LangGraph routing function that determines the next step in the research flow.
-
-    Controls the research loop by deciding whether to continue gathering information
-    or to finalize the summary based on the configured maximum number of research loops.
-
-    Args:
-        state: Current graph state containing the research loop count
-        config: Configuration for the runnable, including max_web_research_loops setting
-
-    Returns:
-        String literal indicating the next node to visit ("web_research" or "finalize_summary")
-    """
-
-    configurable = Configuration.from_runnable_config(config)
-    if state.research_loop_count <= configurable.max_web_research_loops:
-        return "web_research"
-    else:
-        return "finalize_summary"
-
-
-# Add nodes and edges
-builder = StateGraph(
-    SummaryState,
-    input=SummaryStateInput,
-    output=SummaryStateOutput,
-    config_schema=Configuration,
-)
-builder.add_node("generate_query", generate_query)
-builder.add_node("web_research", web_research)
-builder.add_node("summarize_sources", summarize_sources)
-builder.add_node("reflect_on_summary", reflect_on_summary)
-builder.add_node("finalize_summary", finalize_summary)
-
-# Add edges
-builder.add_edge(START, "generate_query")
-builder.add_edge("generate_query", "web_research")
-builder.add_edge("web_research", "summarize_sources")
-builder.add_edge("summarize_sources", "reflect_on_summary")
-builder.add_conditional_edges("reflect_on_summary", route_research)
-builder.add_edge("finalize_summary", END)
-
-graph = builder.compile()

modules/bar_race/deep_researcher/prompts.py

@@ -1,112 +0,0 @@
-from datetime import datetime
-
-
-# Get current date in a readable format
-def get_current_date():
-    return datetime.now().strftime("%B %d, %Y")
-
-
-query_writer_instructions = """Your goal is to generate a targeted web search query.
-
-<CONTEXT>
-Current date: {current_date}
-Please ensure your queries account for the most current information available as of this date.
-</CONTEXT>
-
-<TOPIC>
-{research_topic}
-</TOPIC>
-
-<EXAMPLE>
-Example output:
-{{
-    "query": "machine learning transformer architecture explained",
-    "rationale": "Understanding the fundamental structure of transformer models"
-}}
-</EXAMPLE>"""
-
-json_mode_query_instructions = """<FORMAT>
-Format your response as a JSON object with ALL three of these exact keys:
-- "query": The actual search query string
-- "rationale": Brief explanation of why this query is relevant
-</FORMAT>
-
-Provide your response in JSON format:"""
-
-tool_calling_query_instructions = """<INSTRUCTIONS   >
-Call the Query tool to format your response with the following keys:
-   - "query": The actual search query string
-   - "rationale": Brief explanation of why this query is relevant
-</INSTRUCTIONS>
-
-Call the Query Tool to generate a query for this request:"""
-
-summarizer_instructions = """
-<GOAL>
-Generate a high-quality summary of the provided context.
-</GOAL>
-
-<REQUIREMENTS>
-When creating a NEW summary:
-1. Highlight the most relevant information related to the user topic from the search results
-2. Ensure a coherent flow of information
-
-When EXTENDING an existing summary:                                                                                                                 
-1. Read the existing summary and new search results carefully.                                                    
-2. Compare the new information with the existing summary.                                                         
-3. For each piece of new information:                                                                             
-    a. If it's related to existing points, integrate it into the relevant paragraph.                               
-    b. If it's entirely new but relevant, add a new paragraph with a smooth transition.                            
-    c. If it's not relevant to the user topic, skip it.                                                            
-4. Ensure all additions are relevant to the user's topic.                                                         
-5. Verify that your final output differs from the input summary.                                                                                                                                                            
-< /REQUIREMENTS >
-
-< FORMATTING >
-- Start directly with the updated summary, without preamble or titles. Do not use XML tags in the output.  
-< /FORMATTING >
-
-<Task>
-Think carefully about the provided Context first. Then generate a summary of the context to address the User Input.
-</Task>
-"""
-
-reflection_instructions = """You are an expert research assistant analyzing a summary about {research_topic}.
-
-<GOAL>
-1. Identify knowledge gaps or areas that need deeper exploration
-2. Generate a follow-up question that would help expand your understanding
-3. Focus on technical details, implementation specifics, or emerging trends that weren't fully covered
-</GOAL>
-
-<REQUIREMENTS>
-Ensure the follow-up question is self-contained and includes necessary context for web search.
-</REQUIREMENTS>"""
-
-json_mode_reflection_instructions = """<FORMAT>
-Format your response as a JSON object with these exact keys:
-- knowledge_gap: Describe what information is missing or needs clarification
-- follow_up_query: Write a specific question to address this gap
-</FORMAT>
-
-<Task>
-Reflect carefully on the Summary to identify knowledge gaps and produce a follow-up query. Then, produce your output following this JSON format:
-{{
-    "knowledge_gap": "The summary lacks information about performance metrics and benchmarks",
-    "follow_up_query": "What are typical performance benchmarks and metrics used to evaluate [specific technology]?"
-}}
-</Task>
-
-Provide your analysis in JSON format:"""
-
-tool_calling_reflection_instructions = """<INSTRUCTIONS>
-Call the FollowUpQuery tool to format your response with the following keys:
-- follow_up_query: Write a specific question to address this gap
-- knowledge_gap: Describe what information is missing or needs clarification
-</INSTRUCTIONS>
-
-<Task>
-Reflect carefully on the Summary to identify knowledge gaps and produce a follow-up query.
-</Task>
-
-Call the FollowUpQuery Tool to generate a reflection for this request:"""

modules/bar_race/deep_researcher/rate_limiter.py

@@ -1,120 +0,0 @@
-"""
-Rate Limiter for Gemini API calls.
-
-Gemma-3-27b-it has a limit of 30 requests per minute.
-This module ensures we don't exceed that limit.
-"""
-
-import time
-import threading
-import logging
-from collections import deque
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-class RateLimiter:
-    """
-    Thread-safe rate limiter for API calls.
-    
-    Ensures no more than `max_requests` are made within `time_window` seconds.
-    """
-    
-    def __init__(self, max_requests: int = 29, time_window: int = 62):
-        """
-        Initialize the rate limiter.
-        
-        Args:
-            max_requests: Maximum requests allowed in the time window (default 29)
-            time_window: Time window in seconds (default 60)
-        """
-        self.max_requests = max_requests
-        self.time_window = time_window
-        self.requests: deque = deque()
-        self.lock = threading.Lock()
-    
-    def wait_if_needed(self) -> float:
-        """
-        Wait if we've exceeded the rate limit.
-        
-        Returns:
-            Time waited in seconds (0 if no wait needed)
-        """
-        with self.lock:
-            now = time.time()
-            
-            # Remove old requests outside the time window
-            while self.requests and self.requests[0] < now - self.time_window:
-                self.requests.popleft()
-            
-            # Check if we need to wait
-            if len(self.requests) >= self.max_requests:
-                # Wait until oldest request exits the window
-                wait_time = self.requests[0] + self.time_window - now + 0.1  # +0.1s buffer
-                
-                if wait_time > 0:
-                    logger.info(f"RateLimiter: Waiting {wait_time:.1f}s to avoid rate limit...")
-                    self.lock.release()  # Release lock while waiting
-                    time.sleep(wait_time)
-                    self.lock.acquire()  # Re-acquire lock
-                    
-                    # Clean up old requests after waiting
-                    now = time.time()
-                    while self.requests and self.requests[0] < now - self.time_window:
-                        self.requests.popleft()
-                    
-                    return wait_time
-            
-            return 0.0
-    
-    def record_request(self):
-        """Record that a request was made."""
-        with self.lock:
-            self.requests.append(time.time())
-    
-    def acquire(self) -> float:
-        """
-        Acquire permission to make a request.
-        
-        This is the main method to call before making an API request.
-        It will wait if necessary and record the request.
-        
-        Returns:
-            Time waited in seconds
-        """
-        wait_time = self.wait_if_needed()
-        self.record_request()
-        return wait_time
-    
-    @property
-    def current_count(self) -> int:
-        """Get current request count in the time window."""
-        with self.lock:
-            now = time.time()
-            # Remove old requests
-            while self.requests and self.requests[0] < now - self.time_window:
-                self.requests.popleft()
-            return len(self.requests)
-
-
-# Global rate limiter instance for Gemini API
-# 29 requests per 62 seconds to stay safely under the 30/min limit
-gemini_rate_limiter = RateLimiter(max_requests=29, time_window=62)
-
-
-def rate_limited_call(func):
-    """
-    Decorator to rate limit function calls.
-    
-    Usage:
-        @rate_limited_call
-        def my_api_call():
-            ...
-    """
-    def wrapper(*args, **kwargs):
-        wait_time = gemini_rate_limiter.acquire()
-        if wait_time > 0:
-            logger.info(f"RateLimiter: Waited {wait_time:.1f}s before API call")
-        return func(*args, **kwargs)
-    return wrapper

modules/bar_race/deep_researcher/state.py

@@ -1,25 +0,0 @@
-import operator
-from dataclasses import dataclass, field
-from typing_extensions import Annotated
-
-
-# Note: kw_only=True removed for Python 3.9 compatibility
-@dataclass
-class SummaryState:
-    research_topic: str = field(default=None)  # Report topic
-    search_query: str = field(default=None)  # Search query
-    web_research_results: Annotated[list, operator.add] = field(default_factory=list)
-    sources_gathered: Annotated[list, operator.add] = field(default_factory=list)
-    research_loop_count: int = field(default=0)  # Research loop count
-    running_summary: str = field(default=None)  # Final report
-
-
-@dataclass
-class SummaryStateInput:
-    research_topic: str = field(default=None)  # Report topic
-
-
-@dataclass
-class SummaryStateOutput:
-    running_summary: str = field(default=None)  # Final report
-

modules/bar_race/deep_researcher/utils.py

@@ -1,333 +0,0 @@
-import os
-import httpx
-import requests
-from typing import Dict, Any, List, Union, Optional
-
-from markdownify import markdownify
-from langsmith import traceable
-from tavily import TavilyClient
-from duckduckgo_search import DDGS
-
-# Note: SearxSearchWrapper removed to avoid langchain-community dependency
-# We use Tavily and DuckDuckGo for search instead
-
-# Constants
-CHARS_PER_TOKEN = 4
-
-
-def get_config_value(value: Any) -> str:
-    """
-    Convert configuration values to string format, handling both string and enum types.
-
-    Args:
-        value (Any): The configuration value to process. Can be a string or an Enum.
-
-    Returns:
-        str: The string representation of the value.
-
-    Examples:
-        >>> get_config_value("tavily")
-        'tavily'
-        >>> get_config_value(SearchAPI.TAVILY)
-        'tavily'
-    """
-    return value if isinstance(value, str) else value.value
-
-
-def strip_thinking_tokens(text: str) -> str:
-    """
-    Remove <think> and </think> tags and their content from the text.
-
-    Iteratively removes all occurrences of content enclosed in thinking tokens.
-
-    Args:
-        text (str): The text to process
-
-    Returns:
-        str: The text with thinking tokens and their content removed
-    """
-    while "<think>" in text and "</think>" in text:
-        start = text.find("<think>")
-        end = text.find("</think>") + len("</think>")
-        text = text[:start] + text[end:]
-    return text
-
-
-def deduplicate_and_format_sources(
-    search_response: Union[Dict[str, Any], List[Dict[str, Any]]],
-    max_tokens_per_source: int,
-    fetch_full_page: bool = False,
-) -> str:
-    """
-    Format and deduplicate search responses from various search APIs.
-
-    Takes either a single search response or list of responses from search APIs,
-    deduplicates them by URL, and formats them into a structured string.
-
-    Args:
-        search_response (Union[Dict[str, Any], List[Dict[str, Any]]]): Either:
-            - A dict with a 'results' key containing a list of search results
-            - A list of dicts, each containing search results
-        max_tokens_per_source (int): Maximum number of tokens to include for each source's content
-        fetch_full_page (bool, optional): Whether to include the full page content. Defaults to False.
-
-    Returns:
-        str: Formatted string with deduplicated sources
-
-    Raises:
-        ValueError: If input is neither a dict with 'results' key nor a list of search results
-    """
-    # Convert input to list of results
-    if isinstance(search_response, dict):
-        sources_list = search_response["results"]
-    elif isinstance(search_response, list):
-        sources_list = []
-        for response in search_response:
-            if isinstance(response, dict) and "results" in response:
-                sources_list.extend(response["results"])
-            else:
-                sources_list.extend(response)
-    else:
-        raise ValueError(
-            "Input must be either a dict with 'results' or a list of search results"
-        )
-
-    # Deduplicate by URL
-    unique_sources = {}
-    for source in sources_list:
-        if source["url"] not in unique_sources:
-            unique_sources[source["url"]] = source
-
-    # Format output
-    formatted_text = "Sources:\n\n"
-    for i, source in enumerate(unique_sources.values(), 1):
-        formatted_text += f"Source: {source['title']}\n===\n"
-        formatted_text += f"URL: {source['url']}\n===\n"
-        formatted_text += (
-            f"Most relevant content from source: {source['content']}\n===\n"
-        )
-        if fetch_full_page:
-            # Using rough estimate of characters per token
-            char_limit = max_tokens_per_source * CHARS_PER_TOKEN
-            # Handle None raw_content
-            raw_content = source.get("raw_content", "")
-            if raw_content is None:
-                raw_content = ""
-                print(f"Warning: No raw_content found for source {source['url']}")
-            if len(raw_content) > char_limit:
-                raw_content = raw_content[:char_limit] + "... [truncated]"
-            formatted_text += f"Full source content limited to {max_tokens_per_source} tokens: {raw_content}\n\n"
-
-    return formatted_text.strip()
-
-
-def format_sources(search_results: Dict[str, Any]) -> str:
-    """
-    Format search results into a bullet-point list of sources with URLs.
-
-    Creates a simple bulleted list of search results with title and URL for each source.
-
-    Args:
-        search_results (Dict[str, Any]): Search response containing a 'results' key with
-                                        a list of search result objects
-
-    Returns:
-        str: Formatted string with sources as bullet points in the format "* title : url"
-    """
-    return "\n".join(
-        f"* {source['title']} : {source['url']}" for source in search_results["results"]
-    )
-
-
-def fetch_raw_content(url: str) -> Optional[str]:
-    """
-    Fetch HTML content from a URL and convert it to markdown format.
-
-    Uses a 10-second timeout to avoid hanging on slow sites or large pages.
-
-    Args:
-        url (str): The URL to fetch content from
-
-    Returns:
-        Optional[str]: The fetched content converted to markdown if successful,
-                      None if any error occurs during fetching or conversion
-    """
-    try:
-        # Create a client with reasonable timeout
-        with httpx.Client(timeout=10.0) as client:
-            response = client.get(url)
-            response.raise_for_status()
-            return markdownify(response.text)
-    except Exception as e:
-        print(f"Warning: Failed to fetch full page content for {url}: {str(e)}")
-        return None
-
-
-@traceable
-def duckduckgo_search(
-    query: str, max_results: int = 3, fetch_full_page: bool = False
-) -> Dict[str, List[Dict[str, Any]]]:
-    """
-    Search the web using DuckDuckGo and return formatted results.
-
-    Uses the DDGS library to perform web searches through DuckDuckGo.
-
-    Args:
-        query (str): The search query to execute
-        max_results (int, optional): Maximum number of results to return. Defaults to 3.
-        fetch_full_page (bool, optional): Whether to fetch full page content from result URLs.
-                                         Defaults to False.
-    Returns:
-        Dict[str, List[Dict[str, Any]]]: Search response containing:
-            - results (list): List of search result dictionaries, each containing:
-                - title (str): Title of the search result
-                - url (str): URL of the search result
-                - content (str): Snippet/summary of the content
-                - raw_content (str or None): Full page content if fetch_full_page is True,
-                                            otherwise same as content
-    """
-    try:
-        with DDGS() as ddgs:
-            results = []
-            search_results = list(ddgs.text(query, max_results=max_results))
-
-            for r in search_results:
-                url = r.get("href")
-                title = r.get("title")
-                content = r.get("body")
-
-                if not all([url, title, content]):
-                    print(f"Warning: Incomplete result from DuckDuckGo: {r}")
-                    continue
-
-                raw_content = content
-                if fetch_full_page:
-                    raw_content = fetch_raw_content(url)
-
-                # Add result to list
-                result = {
-                    "title": title,
-                    "url": url,
-                    "content": content,
-                    "raw_content": raw_content,
-                }
-                results.append(result)
-
-            return {"results": results}
-    except Exception as e:
-        print(f"Error in DuckDuckGo search: {str(e)}")
-        print(f"Full error details: {type(e).__name__}")
-        return {"results": []}
-
-
-@traceable
-def tavily_search(
-    query: str, fetch_full_page: bool = True, max_results: int = 3
-) -> Dict[str, List[Dict[str, Any]]]:
-    """
-    Search the web using the Tavily API and return formatted results.
-
-    Uses the TavilyClient to perform searches. Tavily API key must be configured
-    in the environment.
-
-    Args:
-        query (str): The search query to execute
-        fetch_full_page (bool, optional): Whether to include raw content from sources.
-                                         Defaults to True.
-        max_results (int, optional): Maximum number of results to return. Defaults to 3.
-
-    Returns:
-        Dict[str, List[Dict[str, Any]]]: Search response containing:
-            - results (list): List of search result dictionaries, each containing:
-                - title (str): Title of the search result
-                - url (str): URL of the search result
-                - content (str): Snippet/summary of the content
-                - raw_content (str or None): Full content of the page if available and
-                                            fetch_full_page is True
-    """
-
-    tavily_client = TavilyClient()
-    return tavily_client.search(
-        query, max_results=max_results, include_raw_content=fetch_full_page
-    )
-
-
-@traceable
-def perplexity_search(
-    query: str, perplexity_search_loop_count: int = 0
-) -> Dict[str, Any]:
-    """
-    Search the web using the Perplexity API and return formatted results.
-
-    Uses the Perplexity API to perform searches with the 'sonar-pro' model.
-    Requires a PERPLEXITY_API_KEY environment variable to be set.
-
-    Args:
-        query (str): The search query to execute
-        perplexity_search_loop_count (int, optional): The loop step for perplexity search
-                                                     (used for source labeling). Defaults to 0.
-
-    Returns:
-        Dict[str, Any]: Search response containing:
-            - results (list): List of search result dictionaries, each containing:
-                - title (str): Title of the search result (includes search counter)
-                - url (str): URL of the citation source
-                - content (str): Content of the response or reference to main content
-                - raw_content (str or None): Full content for the first source, None for additional
-                                            citation sources
-
-    Raises:
-        requests.exceptions.HTTPError: If the API request fails
-    """
-
-    headers = {
-        "accept": "application/json",
-        "content-type": "application/json",
-        "Authorization": f"Bearer {os.getenv('PERPLEXITY_API_KEY')}",
-    }
-
-    payload = {
-        "model": "sonar-pro",
-        "messages": [
-            {
-                "role": "system",
-                "content": "Search the web and provide factual information with sources.",
-            },
-            {"role": "user", "content": query},
-        ],
-    }
-
-    response = requests.post(
-        "https://api.perplexity.ai/chat/completions", headers=headers, json=payload
-    )
-    response.raise_for_status()  # Raise exception for bad status codes
-
-    # Parse the response
-    data = response.json()
-    content = data["choices"][0]["message"]["content"]
-
-    # Perplexity returns a list of citations for a single search result
-    citations = data.get("citations", ["https://perplexity.ai"])
-
-    # Return first citation with full content, others just as references
-    results = [
-        {
-            "title": f"Perplexity Search {perplexity_search_loop_count + 1}, Source 1",
-            "url": citations[0],
-            "content": content,
-            "raw_content": content,
-        }
-    ]
-
-    # Add additional citations without duplicating content
-    for i, citation in enumerate(citations[1:], start=2):
-        results.append(
-            {
-                "title": f"Perplexity Search {perplexity_search_loop_count + 1}, Source {i}",
-                "url": citation,
-                "content": "See above for full content",
-                "raw_content": None,
-            }
-        )
-
-    return {"results": results}

modules/bar_race/router.py

@@ -1,265 +0,0 @@
-"""
-Bar Race Router
-API endpoints for bar chart race video generation.
-"""
-import logging
-import os
-import uuid
-import shutil
-import traceback
-from typing import Dict
-from fastapi import APIRouter, BackgroundTasks, HTTPException
-from fastapi.responses import FileResponse, RedirectResponse
-
-from .schemas import BarRaceRequest, JobResponse, JobStatus
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-# Job storage
-jobs: Dict[str, dict] = {}
-
-
-def update_job(
-    job_id: str,
-    status: str,
-    progress: int = 0,
-    current_step: str = None,
-    video_url: str = None,
-    error: str = None
-):
-    """Update job status"""
-    if job_id in jobs:
-        jobs[job_id].update({
-            "status": status,
-            "progress": progress,
-            "current_step": current_step,
-            "video_url": video_url,
-            "error": error
-        })
-        logger.debug(f"Job {job_id}: {status} ({progress}%) - {current_step}")
-
-
-async def generate_bar_race_video(job_id: str, request: BarRaceRequest):
-    """Background task to generate bar race video using Agentic AI Pipeline"""
-    temp_dir = f"temp/bar_race_{job_id}"
-    
-    try:
-        os.makedirs(temp_dir, exist_ok=True)
-        
-        # Get API key from environment
-        gemini_api_key = os.getenv("GEMINI_API_KEY")
-        os.environ["TAVILY_API_KEY"] = "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"
-        
-        # ============ BRAIN: Enhance Topic ============
-        update_job(job_id, "processing", 5, "Brain: Enhancing topic...")
-        
-        from .services.brain import Brain
-        brain = Brain(gemini_api_key=gemini_api_key)
-        
-        # Enhance raw topic into research-ready prompt
-        enhanced_topic = brain.enhance_topic(request.topic)
-        logger.info(f"Brain: Enhanced topic: {enhanced_topic[:100]}...")
-        
-        # ============ DEEP RESEARCHER: Tavily Search ============
-        update_job(job_id, "processing", 15, "Researcher: Searching for data...")
-        
-        try:
-            from .deep_researcher import graph
-            
-            # Run the deep research graph with ENHANCED topic
-            research_result = await graph.ainvoke(
-                {"research_topic": enhanced_topic},
-                config={"configurable": {"search_api": "tavily", "max_web_research_loops": 2}}
-            )
-            
-            research_text = research_result.get("running_summary", "")
-            
-            if not research_text:
-                raise Exception("Deep Researcher returned no data")
-            
-            logger.info(f"Researcher: Got research text ({len(research_text)} chars)")
-            
-        except Exception as e:
-            logger.error(f"Deep Researcher failed: {e}")
-            raise Exception(f"Deep Researcher failed: {e}")
-        
-        # ============ ANALYST: Extract CSV ============
-        update_job(job_id, "processing", 40, "Analyst: Extracting data...")
-        
-        from .services.analyst import Analyst
-        analyst = Analyst(gemini_api_key=gemini_api_key)
-        
-        # Extract CSV from research text
-        wide_df = analyst.extract_csv(research_text, request.topic)
-        
-        if wide_df is None or wide_df.empty:
-            raise Exception("Analyst failed to extract CSV from research")
-        
-        logger.info(f"Analyst: Extracted {len(wide_df)} rows, {len(wide_df.columns)} columns")
-        
-        # ============ ANALYST: Find & Fill Gaps ============
-        update_job(job_id, "processing", 50, "Analyst: Filling data gaps...")
-        
-        gaps = analyst.find_gaps(wide_df)
-        
-        if gaps:
-            logger.info(f"Analyst: Found {len(gaps)} gaps, filling with Brain knowledge...")
-            # Use Brain to fill gaps
-            wide_df = brain.fill_data_gaps(wide_df, gaps, enhanced_topic)
-        
-        # ============ ANALYST: Clean Data ============
-        update_job(job_id, "processing", 55, "Analyst: Cleaning data...")
-        
-        # Save raw CSV for potential Groq fixing
-        raw_csv_backup = wide_df.to_csv(index=True)  # Keep index in case it has years
-        
-        wide_df = analyst.clean_data(wide_df)
-        
-        # ============ GROQ FALLBACK: Fix Data if clean_data failed ============
-        if wide_df is None or wide_df.empty:
-            logger.warning("Analyst: Initial cleaning failed, attempting Groq fix...")
-            update_job(job_id, "processing", 58, "Analyst: Fixing data with Groq AI...")
-            
-            # Try Groq to fix the data
-            fixed_df = analyst.fix_with_groq(raw_csv_backup, enhanced_topic)
-            
-            if fixed_df is not None and not fixed_df.empty:
-                logger.info("Analyst: Groq fixed the data, re-cleaning...")
-                wide_df = analyst.clean_data(fixed_df)
-        
-        # Convert to long format for bar_chart_race
-        clean_df = analyst.convert_to_long_format(wide_df)
-        
-        if clean_df is None or clean_df.empty:
-            raise Exception("Analyst failed to produce clean data")
-        
-        # Save for debugging
-        clean_df.to_csv(os.path.join(temp_dir, "clean_data.csv"), index=False)
-        logger.info(f"Analyst: Clean data - {len(clean_df)} rows, {clean_df['name'].nunique()} entities")
-        
-        # ============ DIRECTOR ============
-        update_job(job_id, "processing", 65, "Director: Generating video...")
-        
-        from .services.director import Director
-        director = Director(temp_dir=temp_dir)
-        
-        # Create simple video metadata (replaces old 'plan')
-        video_meta = {
-            "video_meta": {"title": request.topic},
-            "value_intent": {"unit": ""},
-            "visualization": {"top_n": 10}
-        }
-        
-        video_path = director.generate_video(
-            df=clean_df,
-            plan=video_meta,
-            image_paths={},
-            duration_seconds=request.duration_seconds,
-            job_id=job_id
-        )
-        
-        if not video_path or not os.path.exists(video_path):
-            raise Exception("Director failed to generate video")
-        
-        logger.info(f"Director: Generated video at {video_path}")
-        
-        # ============ UPLOAD TO HF ============
-        update_job(job_id, "processing", 85, "Uploading to cloud storage...")
-        
-        video_url = None
-        try:
-            from modules.shared.services.hf_storage import get_hf_storage
-            hf_storage = get_hf_storage()
-            
-            if hf_storage and hf_storage.enabled:
-                # Upload video
-                from pathlib import Path
-                uploaded_url = hf_storage.upload_video(
-                    local_path=Path(video_path),
-                    video_id=job_id,
-                    folder="bar_race"
-                )
-                if uploaded_url:
-                    video_url = uploaded_url
-                    logger.info(f"Uploaded to HF: {video_url}")
-        except Exception as e:
-            logger.warning(f"HF upload failed, using local: {e}")
-        
-        # Fallback to local URL
-        if not video_url:
-            video_url = f"/api/bar-race/video/{job_id}"
-        
-        # ============ SUCCESS ============
-        update_job(job_id, "ready", 100, "Complete", video_url=video_url)
-        logger.info(f"Bar race video ready: {video_url}")
-        
-        # Cleanup temp files (only on success)
-        try:
-            if os.path.exists(temp_dir):
-                shutil.rmtree(temp_dir)
-                logger.info(f"Cleaned up temp directory: {temp_dir}")
-        except Exception as e:
-            logger.warning(f"Cleanup failed: {e}")
-        
-    except Exception as e:
-        logger.error(f"Bar race generation failed: {e}")
-        logger.error(traceback.format_exc())
-        update_job(job_id, "failed", error=str(e))
-        
-        # Keep temp files for debugging on failure
-        logger.info(f"Keeping temp directory for debugging: {temp_dir}")
-
-
-@router.post("/generate", response_model=JobResponse)
-async def generate_bar_race(request: BarRaceRequest, background_tasks: BackgroundTasks):
-    """
-    Generate a bar chart race video.
-    
-    Takes a topic and duration, returns job_id to track progress.
-    """
-    job_id = str(uuid.uuid4())[:8]
-    
-    # Initialize job
-    jobs[job_id] = {
-        "job_id": job_id,
-        "status": "queued",
-        "progress": 0,
-        "current_step": "Initializing...",
-        "video_url": None,
-        "error": None
-    }
-    
-    # Start background task
-    background_tasks.add_task(generate_bar_race_video, job_id, request)
-    
-    return JobResponse(
-        job_id=job_id,
-        status="queued",
-        message=f"Bar race generation started for topic: {request.topic}"
-    )
-
-
-@router.get("/{job_id}/status", response_model=JobStatus)
-async def get_job_status(job_id: str):
-    """Get status of a bar race generation job"""
-    if job_id not in jobs:
-        raise HTTPException(404, f"Job not found: {job_id}")
-    
-    return JobStatus(**jobs[job_id])
-
-
-@router.get("/video/{job_id}")
-async def get_video(job_id: str):
-    """Download the generated bar race video"""
-    video_path = f"videos/bar_race/bar_race_{job_id}.mp4"
-    
-    if not os.path.exists(video_path):
-        raise HTTPException(404, "Video not found")
-    
-    return FileResponse(
-        video_path,
-        media_type="video/mp4",
-        filename=f"bar_race_{job_id}.mp4"
-    )

modules/bar_race/schemas.py

@@ -1,59 +0,0 @@
-"""
-Bar Race Schemas
-Pydantic models for bar chart race video generation.
-"""
-from pydantic import BaseModel, Field
-from typing import Optional, List, Dict, Any
-from enum import Enum
-
-
-class EntityType(str, Enum):
-    """Type of entities in the bar chart"""
-    PERSON = "person"
-    COUNTRY = "country"
-    COMPANY = "company"
-    GENERAL = "general"
-
-
-class BarRaceRequest(BaseModel):
-    """Request to generate a bar chart race video"""
-    topic: str = Field(..., description="Topic/prompt for video (e.g., 'Top 10 richest cricketers')")
-    duration_seconds: int = Field(60, ge=30, le=120, description="Video duration in seconds")
-    
-    class Config:
-        json_schema_extra = {
-            "example": {
-                "topic": "Top 10 richest countries by GDP 2000-2024",
-                "duration_seconds": 60
-            }
-        }
-
-
-class BrainPlan(BaseModel):
-    """JSON plan generated by Brain (LLM)"""
-    topic: str
-    entity_type: EntityType
-    time_config: Dict[str, Any]
-    value_intent: Dict[str, Any]
-    search_strategies: List[Dict[str, Any]]
-    source_priority: List[str]
-    data_expectation: Dict[str, Any]
-    visualization: Dict[str, Any]
-    video_meta: Dict[str, Any]
-
-
-class JobResponse(BaseModel):
-    """Response when job is created"""
-    job_id: str
-    status: str
-    message: str
-
-
-class JobStatus(BaseModel):
-    """Job status response"""
-    job_id: str
-    status: str  # queued, brain, scout, surgeon, artist, director, uploading, ready, failed
-    progress: int = 0
-    current_step: Optional[str] = None
-    video_url: Optional[str] = None
-    error: Optional[str] = None

modules/bar_race/services/__init__.py

@@ -1 +0,0 @@
-# Services package

modules/bar_race/services/analyst.py

@@ -1,517 +0,0 @@
-"""
-Analyst Service - Extracts structured CSV data from research text.
-
-This service uses Gemini to parse unstructured research results into 
-clean, structured CSV data suitable for bar chart race videos.
-"""
-
-import os
-import re
-import logging
-from io import StringIO
-from typing import Optional, Dict, Any, List
-
-import pandas as pd
-
-from modules.bar_race.deep_researcher.rate_limiter import gemini_rate_limiter
-
-logger = logging.getLogger(__name__)
-
-
-class Analyst:
-    """
-    Data Analyst for Bar Race video generation.
-    
-    Responsibilities:
-    - Extract structured CSV from research text (LLM)
-    - Find gaps in data
-    - Clean and format final data
-    - Fix formatting issues using Groq fallback
-    """
-    
-    # Groq Model for data fixing (OpenAI GPT-OSS 120B via Groq)
-    GROQ_MODEL = "openai/gpt-oss-120b"
-    
-    # Universal Data Fixer System Prompt for Groq
-    DATA_FIXER_PROMPT = '''You are an expert Data Engineer specialized in fixing and formatting
-time-series data for Bar Chart Race animations.
-
-INPUT: You will receive malformed CSV data that failed initial processing.
-
-REQUIRED OUTPUT FORMAT (STRICT - ALWAYS THE SAME):
-The CSV must be in WIDE FORMAT with exactly this structure:
-- First column: "year" (integer years like 2010, 2011, 2012...)
-- Remaining columns: Entity names (countries, companies, people, etc.)
-- Each cell: Numeric value (float or integer, no symbols)
-
-EXAMPLE OUTPUT CSV:
-year,USA,China,India,Japan,Germany
-2010,14992,6087,1708,5759,3417
-2011,15543,7552,1823,6157,3757
-2012,16197,8532,1827,6203,3543
-2013,16785,9635,1857,5156,3752
-
-CRITICAL RULES:
-1. YEAR COLUMN: First column MUST be named "year" with valid years (1900-2100)
-2. ENTITY COLUMNS: Column headers = entity names (NOT numbers or years)
-3. VALUES: Pure numbers only (no commas, no symbols, no text)
-4. WIDE FORMAT: Years in rows, Entities in columns
-
-COMMON FIXES YOU MUST APPLY:
-1. If year data is in the index/row labels → Move it to first column
-2. If data is transposed (years as columns) → Transpose to correct format
-3. If year column contains large numbers (population/GDP) → Find real years elsewhere
-4. If columns are shifted → Realign correctly
-5. If values have commas or symbols → Clean to pure numbers
-
-OUTPUT FORMAT (STRICT JSON):
-{
-  "status": "ok",
-  "summary": "Fixed: [describe what was wrong and how you fixed it]",
-  "csv": "year,Entity1,Entity2,...\\n2010,100,200,...\\n2011,110,210,..."
-}
-
-If unfixable, return:
-{
-  "status": "abort",
-  "reason": "Cannot fix because: [specific reason]"
-}'''
-    
-    def __init__(self, gemini_api_key: str = None, groq_api_key: str = None):
-        self.gemini_api_key = gemini_api_key or os.getenv("GEMINI_API_KEY")
-        self.groq_api_key = groq_api_key or os.getenv("GROQ_API_KEY")
-        self.gemini_client = None
-        self.groq_client = None
-        
-        # Initialize Gemini client
-        if self.gemini_api_key:
-            try:
-                from google import genai
-                self.gemini_client = genai.Client(api_key=self.gemini_api_key)
-                logger.info("Analyst: Gemini client initialized")
-            except Exception as e:
-                logger.warning(f"Analyst: Gemini init failed: {e}")
-        
-        # Initialize Groq client (fallback for data fixing)
-        if self.groq_api_key:
-            try:
-                from groq import Groq
-                self.groq_client = Groq(api_key=self.groq_api_key)
-                logger.info("Analyst: Groq client initialized (data fixer fallback)")
-            except Exception as e:
-                logger.warning(f"Analyst: Groq init failed: {e}")
-    
-    def extract_csv(self, research_text: str, topic: str) -> Optional[pd.DataFrame]:
-        """
-        Extract structured CSV data from research text using Gemini.
-        
-        Args:
-            research_text: Raw text from Deep Researcher
-            topic: Original research topic for context
-            
-        Returns:
-            DataFrame in Wide Format (year as rows, entities as columns)
-        """
-        if not self.gemini_client:
-            logger.error("Analyst: No Gemini client available")
-            return None
-            
-        # Very explicit prompt for consistent Wide Format
-        prompt = f"""Act as a Data Extraction Expert for Bar Chart Race Animation.
-
-TOPIC: {topic}
-
-RESEARCH TEXT:
-{research_text[:8000]}
-
----
-
-## CRITICAL OUTPUT FORMAT (Wide Format CSV)
-
-The CSV MUST follow this EXACT structure:
-
-```
-year,Entity1,Entity2,Entity3,...
-2000,100,200,150,...
-2001,120,210,160,...
-2002,140,220,180,...
-```
-
-### RULES (STRICT):
-
-1. FIRST COLUMN must be named 'year' (lowercase)
-2. FIRST COLUMN contains TIME values (2000, 2001, 2002... OR Over 1, Over 2...)
-3. OTHER COLUMNS are ENTITY NAMES (USA, China, India OR Virat Kohli, Sachin...)
-4. CELLS contain NUMERIC VALUES only (no currency symbols, no commas)
-5. Each ROW = One time period
-6. Each COLUMN (after year) = One competitor/entity
-
-### EXAMPLE OUTPUT:
-
-year,United States,China,Japan,Germany
-2010,14992,6087,5700,3396
-2011,15543,7552,5893,3757
-2012,16197,8532,5954,3543
-
----
-
-OUTPUT ONLY THE CSV DATA (no markdown, no explanations, no backticks):
-"""
-        
-        try:
-            gemini_rate_limiter.acquire()  # Rate limit before API call
-            response = self.gemini_client.models.generate_content(
-                model="gemma-3-27b-it",
-                contents=prompt
-            )
-            
-            csv_content = response.text.strip()
-            
-            # Clean markdown formatting
-            if csv_content.startswith("```csv"):
-                csv_content = csv_content[6:]
-            elif csv_content.startswith("```"):
-                csv_content = csv_content[3:]
-            if csv_content.endswith("```"):
-                csv_content = csv_content[:-3]
-            csv_content = csv_content.strip()
-            
-            if not csv_content:
-                logger.warning("Analyst: Empty CSV response from Gemini")
-                return None
-            
-            # Parse CSV
-            df = pd.read_csv(StringIO(csv_content))
-            logger.info(f"Analyst: Extracted CSV with {len(df)} rows, {len(df.columns)} columns")
-            
-            # Validate and fix format if needed
-            df = self._validate_and_fix_format(df)
-            
-            return df
-            
-        except Exception as e:
-            logger.error(f"Analyst: CSV extraction failed: {e}")
-            return None
-    
-    def _validate_and_fix_format(self, df: pd.DataFrame) -> pd.DataFrame:
-        """
-        Validate CSV is in correct Wide Format and fix if needed.
-        
-        Expected Wide Format:
-        - First column: year/time (2000, 2001, 2002...)
-        - Other columns: entity names (USA, China, India...)
-        - Values: numeric
-        
-        Detects and fixes:
-        - Transposed format (entities in rows, years in columns)
-        - Wrong column order
-        """
-        if df is None or df.empty:
-            return df
-        
-        first_col = df.columns[0]
-        first_col_lower = str(first_col).lower()
-        
-        # Check if first column looks like year/time
-        is_first_col_time = False
-        
-        if first_col_lower in ['year', 'date', 'time', 'month', 'period', 'over']:
-            is_first_col_time = True
-        else:
-            # Check if values look like years (1900-2100) or sequential numbers
-            sample_values = df[first_col].dropna().head(10)
-            try:
-                numeric_values = pd.to_numeric(sample_values, errors='coerce')
-                valid_years = numeric_values.apply(lambda x: 1900 <= x <= 2100 if pd.notna(x) else False)
-                if valid_years.sum() / len(valid_years) > 0.8:
-                    is_first_col_time = True
-                    logger.info(f"Analyst: Detected first column '{first_col}' contains year values")
-            except:
-                pass
-        
-        if is_first_col_time:
-            # Format is correct (Wide Format)
-            logger.info("Analyst: Data is in correct Wide Format")
-            return df
-        
-        # Check if COLUMNS look like years (Transposed Format)
-        year_like_columns = []
-        for col in df.columns[1:]:
-            try:
-                year_val = int(col)
-                if 1900 <= year_val <= 2100:
-                    year_like_columns.append(col)
-            except:
-                pass
-        
-        if len(year_like_columns) > 5:
-            # Data is transposed! Entities in rows, Years in columns
-            logger.warning("Analyst: Detected Transposed Format, converting to Wide Format...")
-            
-            # First column contains entity names
-            df = df.rename(columns={first_col: 'entity'})
-            
-            # Melt to long format first
-            df_long = df.melt(
-                id_vars=['entity'],
-                var_name='year',
-                value_name='value'
-            )
-            
-            # Pivot to correct Wide Format
-            df_wide = df_long.pivot(index='year', columns='entity', values='value').reset_index()
-            
-            logger.info(f"Analyst: Converted from Transposed to Wide Format: {df_wide.shape}")
-            return df_wide
-        
-        # If we can't determine format, assume it's correct
-        logger.warning("Analyst: Could not determine format, assuming Wide Format")
-        return df
-    
-    def find_gaps(self, df: pd.DataFrame) -> List[Dict[str, Any]]:
-        """
-        Find missing data points in the DataFrame.
-        
-        Args:
-            df: DataFrame with potential gaps
-            
-        Returns:
-            List of gap descriptions (year, entity, missing_type)
-        """
-        gaps = []
-        
-        if df is None or df.empty:
-            return gaps
-        
-        # Assume first column is 'year'
-        year_col = df.columns[0]
-        entity_cols = df.columns[1:]
-        
-        for col in entity_cols:
-            for idx, row in df.iterrows():
-                value = row[col]
-                if pd.isna(value) or value == "":
-                    gaps.append({
-                        "year": row[year_col],
-                        "entity": col,
-                        "type": "missing_value"
-                    })
-        
-        logger.info(f"Analyst: Found {len(gaps)} data gaps")
-        return gaps
-    
-    def clean_data(self, df: pd.DataFrame) -> pd.DataFrame:
-        """
-        Final cleaning and formatting of data for video generation.
-        
-        Args:
-            df: DataFrame to clean
-            
-        Returns:
-            Cleaned DataFrame ready for Director
-        """
-        if df is None or df.empty:
-            return df
-        
-        # Log first few rows for debugging
-        logger.info(f"Analyst: Raw data before cleaning:\n{df.head(3).to_string()}")
-        
-        # Check if years are in the index instead of first column
-        # This happens when LLM outputs data with year as row index
-        first_col = df.columns[0]
-        first_col_values = df[first_col].head(3).tolist()
-        
-        # Check if first column values are too large to be years (likely population data)
-        try:
-            first_values_numeric = [float(v) for v in first_col_values if v is not None and str(v).replace('.','').isdigit()]
-            if first_values_numeric and min(first_values_numeric) > 100000:
-                # First column contains large numbers (likely population/GDP), not years
-                # Check if index contains valid years
-                index_values = df.index.tolist()[:5]
-                try:
-                    index_years = [int(float(v)) for v in index_values if str(v).replace('.','').isdigit()]
-                    if index_years and all(1900 <= y <= 2100 for y in index_years):
-                        logger.info(f"Analyst: Detected years in index ({index_years[:3]}...), fixing data structure")
-                        # Reset index to make year a column
-                        df = df.reset_index()
-                        df = df.rename(columns={'index': 'year'})
-                except:
-                    pass
-        except:
-            pass
-        
-        # Ensure year column is named correctly
-        first_col = df.columns[0]
-        if first_col.lower() != 'year':
-            df = df.rename(columns={first_col: 'year'})
-        
-        # Try to extract year from various formats
-        def extract_year(val):
-            """Extract year from various formats like '2010', 2010, '2010-01-01', etc."""
-            try:
-                # If already a number
-                if isinstance(val, (int, float)):
-                    return int(val)
-                
-                # If string, try to extract 4-digit year
-                val_str = str(val).strip()
-                
-                # Try direct conversion first
-                if val_str.isdigit() and len(val_str) == 4:
-                    return int(val_str)
-                
-                # Try to find 4-digit year pattern
-                import re
-                year_match = re.search(r'(19|20)\d{2}', val_str)
-                if year_match:
-                    return int(year_match.group())
-                
-                # Last resort: try float conversion
-                return int(float(val_str))
-            except:
-                return None
-        
-        # Apply year extraction
-        df['year'] = df['year'].apply(extract_year)
-        
-        # Log after extraction
-        logger.info(f"Analyst: Years extracted: {df['year'].tolist()[:5]}...")
-        
-        # Drop rows where year extraction failed
-        df = df.dropna(subset=['year'])
-        df['year'] = df['year'].astype(int)
-        
-        # ✅ CRITICAL: Filter out invalid years (only 1900-2100 allowed)
-        original_len = len(df)
-        df = df[(df['year'] >= 1900) & (df['year'] <= 2100)]
-        
-        if len(df) < original_len:
-            logger.warning(f"Analyst: Removed {original_len - len(df)} rows with invalid years (outside 1900-2100)")
-        
-        if df.empty:
-            logger.error("Analyst: No valid years found in data!")
-            return df
-        
-        # Convert all value columns to numeric
-        for col in df.columns[1:]:
-            df[col] = pd.to_numeric(df[col], errors='coerce')
-        
-        # Sort by year
-        df = df.sort_values('year').reset_index(drop=True)
-        
-        # Interpolate missing values
-        for col in df.columns[1:]:
-            df[col] = df[col].interpolate(method='linear')
-        
-        logger.info(f"Analyst: Cleaned data - {len(df)} rows, years {df['year'].min()}-{df['year'].max()}")
-        
-        return df
-    
-    def convert_to_long_format(self, df: pd.DataFrame) -> pd.DataFrame:
-        """
-        Convert Wide Format to Long Format for bar_chart_race.
-        
-        Wide: year, USA, China, India
-        Long: name, year, value
-        
-        Args:
-            df: Wide format DataFrame
-            
-        Returns:
-            Long format DataFrame
-        """
-        if df is None or df.empty:
-            return df
-        
-        df_long = df.melt(
-            id_vars=['year'],
-            var_name='name',
-            value_name='value'
-        )
-        
-        # Ensure correct types
-        df_long['year'] = df_long['year'].astype(int)
-        df_long['value'] = pd.to_numeric(df_long['value'], errors='coerce')
-        df_long = df_long.dropna(subset=['value'])
-        
-        logger.info(f"Analyst: Converted to long format - {len(df_long)} records")
-        
-        return df_long
-    
-    def fix_with_groq(self, raw_csv: str, topic: str) -> Optional[pd.DataFrame]:
-        """
-        Use Groq GPT-OSS 120B to fix malformed CSV data.
-        
-        This is a fallback when the initial clean_data fails due to:
-        - Year column issues
-        - Column misalignment
-        - Format confusion (wide/long)
-        
-        Args:
-            raw_csv: The raw CSV string that failed cleaning
-            topic: Topic context for better understanding
-            
-        Returns:
-            Fixed DataFrame or None if unfixable
-        """
-        if not self.groq_client:
-            logger.warning("Analyst: Groq client not available for data fixing")
-            return None
-        
-        logger.info("Analyst: Attempting to fix data with Groq...")
-        
-        try:
-            user_message = f"""Topic: {topic}
-
-The following CSV data has formatting issues. Please fix it:
-
-```csv
-{raw_csv}
-```
-
-Analyze the data structure and return a properly formatted CSV ready for bar_chart_race animation."""
-
-            completion = self.groq_client.chat.completions.create(
-                model=self.GROQ_MODEL,
-                messages=[
-                    {"role": "system", "content": self.DATA_FIXER_PROMPT},
-                    {"role": "user", "content": user_message}
-                ],
-                temperature=0.1,
-                max_tokens=4000,
-            )
-            
-            response_text = completion.choices[0].message.content.strip()
-            logger.info(f"Analyst: Groq response received ({len(response_text)} chars)")
-            
-            # Parse JSON response
-            import json
-            
-            # Try to extract JSON from response
-            json_match = re.search(r'\{[\s\S]*\}', response_text)
-            if not json_match:
-                logger.error("Analyst: Groq response is not valid JSON")
-                return None
-            
-            result = json.loads(json_match.group())
-            
-            if result.get("status") == "abort":
-                logger.warning(f"Analyst: Groq aborted - {result.get('reason', 'unknown')}")
-                return None
-            
-            if result.get("status") == "ok":
-                logger.info(f"Analyst: Groq fixed data - {result.get('summary', 'no summary')}")
-                csv_content = result.get("csv", "")
-                
-                if csv_content:
-                    # Parse the fixed CSV
-                    df = pd.read_csv(StringIO(csv_content))
-                    logger.info(f"Analyst: Groq produced {len(df)} rows, {len(df.columns)} columns")
-                    return df
-            
-            logger.warning("Analyst: Groq response did not contain valid data")
-            return None
-            
-        except Exception as e:
-            logger.error(f"Analyst: Groq fix failed - {e}")
-            return None

modules/bar_race/services/artist.py

@@ -1,301 +0,0 @@
-"""
-Artist - Image Processor
-Downloads and processes entity images for bar chart race.
-"""
-import logging
-import requests
-import os
-from PIL import Image, ImageDraw
-from typing import Dict, Any, List, Optional
-from io import BytesIO
-
-logger = logging.getLogger(__name__)
-
-
-class Artist:
-    """
-    Image Processor for Bar Race video generation.
-    
-    Responsibilities:
-    - Search and download entity images
-    - Background removal (optional, if rembg available)
-    - Face detection for person entities
-    - Circular mask application
-    """
-    
-    HEADERS = {
-        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
-    }
-    
-    # Image size for bar chart
-    IMAGE_SIZE = 80
-    
-    def __init__(self, temp_dir: str):
-        self.temp_dir = temp_dir
-        self.images_dir = os.path.join(temp_dir, "images")
-        os.makedirs(self.images_dir, exist_ok=True)
-        
-        # Check if rembg is available
-        self.rembg_available = False
-        try:
-            import rembg
-            self.rembg_available = True
-            logger.info("Artist: rembg available for background removal")
-        except ImportError:
-            logger.info("Artist: rembg not available, skipping background removal")
-    
-    def process_entities(self, entities: List[str], entity_type: str) -> Dict[str, str]:
-        """
-        Download and process images for all entities.
-        
-        Args:
-            entities: List of entity names
-            entity_type: Type of entity (person, country, company, general)
-            
-        Returns:
-            Dict mapping entity name to processed image path
-        """
-        logger.info(f"Artist: Processing images for {len(entities)} entities (type: {entity_type})")
-        
-        image_paths = {}
-        
-        for entity in entities:
-            try:
-                image_path = self._process_entity(entity, entity_type)
-                if image_path:
-                    image_paths[entity] = image_path
-                    logger.debug(f"Artist: Processed image for {entity}")
-                else:
-                    logger.warning(f"Artist: No image found for {entity}")
-            except Exception as e:
-                logger.warning(f"Artist: Failed to process {entity}: {e}")
-        
-        logger.info(f"Artist: Processed {len(image_paths)}/{len(entities)} images")
-        return image_paths
-    
-    def _process_entity(self, entity: str, entity_type: str) -> Optional[str]:
-        """Process a single entity's image"""
-        # Try to get image
-        image = self._get_image(entity, entity_type)
-        
-        if image is None:
-            return None
-        
-        # Process image
-        try:
-            # Resize to square
-            image = image.convert("RGBA")
-            image = self._resize_to_square(image)
-            
-            # Remove background if rembg available and it's a person
-            if self.rembg_available and entity_type == "person":
-                image = self._remove_background(image)
-            
-            # Apply circular mask
-            image = self._apply_circular_mask(image)
-            
-            # Save processed image
-            safe_name = "".join(c if c.isalnum() else "_" for c in entity)
-            output_path = os.path.join(self.images_dir, f"{safe_name}.png")
-            image.save(output_path, "PNG")
-            
-            return output_path
-            
-        except Exception as e:
-            logger.error(f"Artist: Error processing image for {entity}: {e}")
-            return None
-    
-    def _get_image(self, entity: str, entity_type: str) -> Optional[Image.Image]:
-        """Get image for an entity"""
-        
-        # Priority 1: Wikipedia Commons
-        image = self._search_wikipedia_commons(entity, entity_type)
-        if image:
-            return image
-        
-        # Priority 2: DuckDuckGo image search
-        image = self._search_duckduckgo(entity, entity_type)
-        if image:
-            return image
-        
-        # Priority 3: Generate placeholder
-        return self._generate_placeholder(entity)
-    
-    def _search_wikipedia_commons(self, entity: str, entity_type: str) -> Optional[Image.Image]:
-        """Search Wikipedia Commons for entity image"""
-        try:
-            # For countries, search for flag
-            if entity_type == "country":
-                search_query = f"Flag of {entity}"
-            else:
-                search_query = entity
-            
-            # Wikipedia API search
-            search_url = "https://en.wikipedia.org/w/api.php"
-            params = {
-                "action": "query",
-                "titles": search_query,
-                "prop": "pageimages",
-                "format": "json",
-                "pithumbsize": 200
-            }
-            
-            response = requests.get(search_url, params=params, headers=self.HEADERS, timeout=10)
-            if response.status_code == 200:
-                data = response.json()
-                pages = data.get("query", {}).get("pages", {})
-                
-                for page_id, page_data in pages.items():
-                    if "thumbnail" in page_data:
-                        image_url = page_data["thumbnail"]["source"]
-                        return self._download_image(image_url)
-                        
-        except Exception as e:
-            logger.debug(f"Artist: Wikipedia Commons search failed for {entity}: {e}")
-        
-        return None
-    
-    def _search_duckduckgo(self, entity: str, entity_type: str) -> Optional[Image.Image]:
-        """Search DuckDuckGo for entity image"""
-        try:
-            from ddgs import DDGS
-            
-            # Build search query
-            if entity_type == "country":
-                query = f"{entity} flag icon"
-            elif entity_type == "person":
-                query = f"{entity} portrait photo"
-            else:
-                query = f"{entity} logo"
-            
-            with DDGS() as ddgs:
-                results = list(ddgs.images(query, max_results=3))
-                
-                for result in results:
-                    image_url = result.get("image")
-                    if image_url:
-                        image = self._download_image(image_url)
-                        if image:
-                            return image
-                            
-        except ImportError:
-            logger.debug("Artist: duckduckgo-search not available")
-        except Exception as e:
-            logger.debug(f"Artist: DuckDuckGo search failed for {entity}: {e}")
-        
-        return None
-    
-    def _download_image(self, url: str) -> Optional[Image.Image]:
-        """Download image from URL"""
-        try:
-            response = requests.get(url, headers=self.HEADERS, timeout=10)
-            if response.status_code == 200:
-                return Image.open(BytesIO(response.content))
-        except Exception as e:
-            logger.debug(f"Artist: Failed to download image: {e}")
-        
-        return None
-    
-    def _resize_to_square(self, image: Image.Image) -> Image.Image:
-        """Resize image to square, center cropping if needed"""
-        width, height = image.size
-        
-        # Determine crop box for square
-        if width > height:
-            left = (width - height) // 2
-            top = 0
-            right = left + height
-            bottom = height
-        else:
-            left = 0
-            top = (height - width) // 2
-            right = width
-            bottom = top + width
-        
-        # Crop to square
-        image = image.crop((left, top, right, bottom))
-        
-        # Resize to target size
-        image = image.resize((self.IMAGE_SIZE, self.IMAGE_SIZE), Image.Resampling.LANCZOS)
-        
-        return image
-    
-    def _remove_background(self, image: Image.Image) -> Image.Image:
-        """Remove background using rembg"""
-        try:
-            import rembg
-            
-            # Convert to bytes
-            img_bytes = BytesIO()
-            image.save(img_bytes, format="PNG")
-            img_bytes.seek(0)
-            
-            # Remove background
-            output = rembg.remove(img_bytes.getvalue())
-            
-            return Image.open(BytesIO(output))
-            
-        except Exception as e:
-            logger.warning(f"Artist: Background removal failed: {e}")
-            return image
-    
-    def _apply_circular_mask(self, image: Image.Image) -> Image.Image:
-        """Apply circular mask to image"""
-        # Ensure RGBA
-        if image.mode != "RGBA":
-            image = image.convert("RGBA")
-        
-        size = image.size[0]
-        
-        # Create circular mask
-        mask = Image.new("L", (size, size), 0)
-        draw = ImageDraw.Draw(mask)
-        draw.ellipse((0, 0, size, size), fill=255)
-        
-        # Apply mask
-        output = Image.new("RGBA", (size, size), (0, 0, 0, 0))
-        output.paste(image, (0, 0), mask)
-        
-        return output
-    
-    def _generate_placeholder(self, entity: str) -> Image.Image:
-        """Generate a placeholder image with entity initial"""
-        size = self.IMAGE_SIZE
-        
-        # Create colored background
-        colors = [
-            (74, 222, 128),   # Green
-            (251, 191, 36),   # Yellow
-            (239, 68, 68),    # Red
-            (59, 130, 246),   # Blue
-            (168, 85, 247),   # Purple
-            (20, 184, 166),   # Teal
-        ]
-        
-        # Pick color based on entity name hash
-        color = colors[hash(entity) % len(colors)]
-        
-        # Create image
-        image = Image.new("RGBA", (size, size), color)
-        draw = ImageDraw.Draw(image)
-        
-        # Draw initial
-        initial = entity[0].upper() if entity else "?"
-        
-        # Use default font
-        try:
-            from PIL import ImageFont
-            font = ImageFont.truetype("arial.ttf", size // 2)
-        except:
-            font = ImageFont.load_default()
-        
-        # Center text
-        bbox = draw.textbbox((0, 0), initial, font=font)
-        text_width = bbox[2] - bbox[0]
-        text_height = bbox[3] - bbox[1]
-        x = (size - text_width) // 2
-        y = (size - text_height) // 2 - bbox[1]
-        
-        draw.text((x, y), initial, fill=(255, 255, 255), font=font)
-        
-        return image

modules/bar_race/services/brain.py

@@ -1,365 +0,0 @@
-"""
-Brain - Topic Enhancement Agent
-
-Uses Gemini to convert vague user topics into research-ready prompts
-for the Deep Researcher module.
-
-Simplified pipeline:
-User Topic → Brain.enhance_topic() → Deep Researcher → Analyst → Director
-"""
-import logging
-import os
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-# Import rate limiter (lazy import to avoid circular dependency)
-def get_rate_limiter():
-    from modules.bar_race.deep_researcher.rate_limiter import gemini_rate_limiter
-    return gemini_rate_limiter
-
-
-class Brain:
-    """
-    Topic Enhancement Agent for Bar Race video generation.
-    
-    Responsibilities:
-    - Convert vague user topics into research-ready prompts
-    - Fill data gaps using Gemini knowledge (if needed)
-    """
-    
-    GEMINI_MODEL = "gemma-3-27b-it"
-    
-    # Universal Topic Enhancer Prompt
-    TOPIC_ENHANCER_PROMPT = '''You are an intelligent AI agent named "Brain".
-
-Your task is to convert a raw, unclear, or incomplete user topic
-into a precise, research-ready prompt for a Deep Research AI agent
-(using Tavily or similar web research tools).
-
-The ultimate goal is to generate data suitable for a Bar Chart Race animation video.
-
----
-
-### USER INPUT
-- A short, vague, or poorly defined topic
-- The user may not specify time range, metrics, or competitors
-- The user may not understand data structure requirements
-
----
-
-### CORE DATA REQUIREMENTS (MANDATORY)
-
-The data MUST follow these rules:
-
-1. Time Axis (X-axis):
-   - Must represent time progression
-   - Can be: year, date, month, or sequential order (e.g., Over 1, Over 2)
-   - Must be continuous and sortable
-
-2. Categories / Competitors:
-   - Entities competing over time
-   - Examples: countries, companies, platforms, individuals, teams
-
-3. Values:
-   - Numeric values that change over time
-   - Examples: GDP, population, revenue, users, runs, points, sales
-
-4. Data Format:
-   - MUST be in WIDE FORMAT
-   - Time must be represented as rows (index)
-   - Each competitor/category must be a separate column
-   - Values must be numeric and suitable for animation
-
----
-
-### YOUR RESPONSIBILITIES
-
-1. Understand the user's intent and visualization goal
-2. Enhance the topic into a clear analytical research objective
-3. Infer missing details intelligently:
-   - Time range → assume long-term historical data
-   - Metric → use the most standard and authoritative metric
-   - Scope → assume global unless specified otherwise
-4. Ensure the research target will produce:
-   - Time-series numerical data
-   - Comparable values across competitors
-   - Data convertible into Wide Format
-
----
-
-### OUTPUT RULES (STRICT)
-
-- Output ONLY ONE enhanced research prompt
-- Write in clear, professional English
-- The prompt must be directly usable by a Deep Research AI agent
-- Do NOT include:
-  - Explanations
-  - Bullet points
-  - Multiple options
-  - CSV or table
-  - Commentary or assumptions list
-
----
-
-### EXAMPLE
-
-User Topic:
-"Cricket players performance"
-
-Enhanced Output:
-"Research year-by-year total international runs scored by the top 10 cricket players globally from 2000 to the most recent year, ensuring consistent annual time-series data suitable for wide-format bar chart race visualization."
-
----
-
-### FINAL RULE
-Your output must guarantee that the resulting dataset
-can be transformed into a Wide Format table
-with Time as rows and Competitors as columns,
-ready for Bar Chart Race animation.'''
-
-    def __init__(self, gemini_api_key: str = None):
-        self.gemini_api_key = gemini_api_key or os.getenv("GEMINI_API_KEY")
-        self.gemini_client = None
-        
-        if self.gemini_api_key:
-            try:
-                from google import genai
-                self.gemini_client = genai.Client(api_key=self.gemini_api_key)
-                logger.info("Brain: Gemini client initialized")
-            except ImportError:
-                logger.warning("google-genai package not installed")
-        else:
-            logger.warning("Brain: No Gemini API key, will use basic enhancement")
-    
-    def enhance_topic(self, raw_topic: str) -> str:
-        """
-        Convert raw user topic into research-ready prompt.
-        
-        Uses TOPIC_ENHANCER_PROMPT to transform vague topics into
-        precise, research-friendly prompts for Deep Researcher.
-        
-        Args:
-            raw_topic: User's raw topic string (may be vague/incomplete)
-            
-        Returns:
-            Enhanced research prompt ready for Deep Researcher
-        """
-        logger.info(f"Brain: Enhancing topic: {raw_topic}")
-        
-        if not self.gemini_client:
-            # Fallback: basic enhancement
-            return f"Research historical year-by-year data for {raw_topic} from 2000 to present, suitable for bar chart race visualization."
-        
-        try:
-            get_rate_limiter().acquire()  # Rate limit before API call
-            response = self.gemini_client.models.generate_content(
-                model=self.GEMINI_MODEL,
-                contents=[
-                    {"role": "user", "parts": [{"text": self.TOPIC_ENHANCER_PROMPT}]},
-                    {"role": "user", "parts": [{"text": f"User Topic:\n{raw_topic}"}]}
-                ]
-            )
-            
-            enhanced = response.text.strip()
-            
-            # Clean up any markdown formatting
-            if enhanced.startswith('"') and enhanced.endswith('"'):
-                enhanced = enhanced[1:-1]
-            
-            logger.info(f"Brain: Enhanced topic to: {enhanced[:100]}...")
-            return enhanced
-            
-        except Exception as e:
-            logger.warning(f"Brain: Topic enhancement failed: {e}")
-            return f"Research historical year-by-year data for {raw_topic} from 2000 to present, suitable for bar chart race visualization."
-
-    def fill_data_gaps(self, df, gaps: list, topic: str = ""):
-        """
-        Fill missing data points using Gemini's knowledge + Tavily fallback.
-        
-        Strategy:
-        1. First ask Gemini for all gaps (batch)
-        2. For remaining unfilled gaps, use Tavily search
-        
-        Args:
-            df: DataFrame with gaps
-            gaps: List of gap descriptions from Analyst
-            topic: The research topic for context
-            
-        Returns:
-            DataFrame with gaps filled
-        """
-        if not gaps:
-            return df
-            
-        import pandas as pd
-        import os
-        
-        filled_count = 0
-        unfilled_gaps = []
-        
-        # ============ STEP 1: Try Gemini first (batch) ============
-        if self.gemini_client:
-            try:
-                # Format gaps for Gemini
-                gap_text = "\n".join([
-                    f"- Year {g['year']}, Entity {g['entity']}"
-                    for g in gaps[:20]  # Limit to 20 gaps
-                ])
-                
-                prompt = f"""Act as a Data Expert with historical knowledge.
-
-TOPIC: {topic}
-
-MISSING DATA POINTS:
-{gap_text}
-
-For each missing data point above, provide the approximate value based on your knowledge.
-Output format (one per line): year,entity,value
-
-Rules:
-1. Use realistic values based on trends
-2. If completely unknown, write: year,entity,UNKNOWN
-3. Output ONLY the data in CSV format (no headers, no explanations)
-"""
-                
-                get_rate_limiter().acquire()  # Rate limit before API call
-                response = self.gemini_client.models.generate_content(
-                    model=self.GEMINI_MODEL,
-                    contents=prompt
-                )
-                
-                fill_data = response.text.strip()
-                
-                # Parse and apply fill values
-                for line in fill_data.split("\n"):
-                    try:
-                        parts = line.strip().split(",")
-                        if len(parts) >= 3:
-                            year = int(parts[0].strip())
-                            entity = parts[1].strip()
-                            value_str = parts[2].strip()
-                            
-                            # Check if Gemini doesn't know
-                            if value_str.upper() == "UNKNOWN" or not value_str:
-                                unfilled_gaps.append({"year": year, "entity": entity})
-                                continue
-                            
-                            value = float(value_str.replace(",", ""))
-                            
-                            # Find and fill in DataFrame
-                            if entity in df.columns:
-                                mask = df['year'] == year
-                                if mask.any():
-                                    df.loc[mask, entity] = value
-                                    filled_count += 1
-                    except:
-                        pass
-                
-                logger.info(f"Brain: Gemini filled {filled_count} gaps, {len(unfilled_gaps)} remaining")
-                
-            except Exception as e:
-                logger.warning(f"Brain: Gemini gap filling failed: {e}")
-                unfilled_gaps = gaps[:20]  # All gaps need Tavily
-        else:
-            unfilled_gaps = gaps[:20]  # No Gemini, use Tavily for all
-        
-        # ============ STEP 2: Tavily fallback for unfilled gaps ============
-        if unfilled_gaps:
-            tavily_filled = self._fill_gaps_with_tavily(df, unfilled_gaps, topic)
-            filled_count += tavily_filled
-        
-        logger.info(f"Brain: Total filled {filled_count} out of {len(gaps)} gaps")
-        return df
-    
-    def _fill_gaps_with_tavily(self, df, gaps: list, topic: str) -> int:
-        """
-        Use Tavily API to search for specific missing data points.
-        
-        Args:
-            df: DataFrame to fill
-            gaps: List of unfilled gaps
-            topic: Research topic for context
-            
-        Returns:
-            Number of gaps filled
-        """
-        import os
-        
-        tavily_api_key = os.getenv("TAVILY_API_KEY")
-        if not tavily_api_key:
-            logger.warning("Brain: No Tavily API key for gap fallback")
-            return 0
-        
-        try:
-            from tavily import TavilyClient
-            tavily = TavilyClient(api_key=tavily_api_key)
-        except ImportError:
-            logger.warning("Brain: Tavily client not available")
-            return 0
-        
-        filled_count = 0
-        
-        for gap in gaps[:5]:  # Limit to 5 Tavily searches (to save API quota)
-            try:
-                year = gap['year']
-                entity = gap['entity']
-                
-                # Specific search query for this data point
-                query = f"{topic} {entity} {year} data statistics value"
-                
-                result = tavily.search(query=query, max_results=3)
-                
-                if result and result.get('results'):
-                    # Try to extract numeric value from search results
-                    for r in result['results']:
-                        content = r.get('content', '')
-                        value = self._extract_numeric_from_text(content, entity, year)
-                        
-                        if value is not None:
-                            if entity in df.columns:
-                                mask = df['year'] == year
-                                if mask.any():
-                                    df.loc[mask, entity] = value
-                                    filled_count += 1
-                                    logger.info(f"Brain: Tavily filled {entity} {year} = {value}")
-                                    break
-                                    
-            except Exception as e:
-                logger.warning(f"Brain: Tavily search failed for {gap}: {e}")
-        
-        return filled_count
-    
-    def _extract_numeric_from_text(self, text: str, entity: str, year: int) -> float:
-        """Extract a numeric value from text that relates to entity and year."""
-        import re
-        
-        # Look for patterns like "India 2015: 2.1 trillion" or "GDP was 2100 billion"
-        patterns = [
-            rf'{year}[:\s]+[\$€]?([\d,.]+)\s*(trillion|billion|million)?',
-            rf'([\d,.]+)\s*(trillion|billion|million)?\s*(?:in|for)?\s*{year}',
-            rf'{entity}[:\s]+([\d,.]+)',
-        ]
-        
-        for pattern in patterns:
-            match = re.search(pattern, text, re.IGNORECASE)
-            if match:
-                try:
-                    value_str = match.group(1).replace(",", "")
-                    value = float(value_str)
-                    
-                    # Apply multiplier if present
-                    if match.lastindex >= 2 and match.group(2):
-                        unit = match.group(2).lower()
-                        if unit == 'trillion':
-                            value *= 1000  # Convert to billions for consistency
-                        elif unit == 'million':
-                            value /= 1000  # Convert to billions
-                    
-                    return value
-                except:
-                    pass
-        
-        return None
-

modules/bar_race/services/director.py

@@ -1,438 +0,0 @@
-"""
-Director - Video Generator
-Creates bar chart race animation and final video.
-"""
-import logging
-import pandas as pd
-import os
-from typing import Dict, Any, Optional
-import shutil
-
-logger = logging.getLogger(__name__)
-
-
-class Director:
-    """
-    Video Generator for Bar Race.
-    
-    Creates animated bar chart race video using:
-    - bar_chart_race library for animation
-    - Entity images overlay
-    - Background music
-    - 9:16 vertical format (1080x1920)
-    """
-    
-    # Video dimensions (9:16)
-    VIDEO_WIDTH = 1080
-    VIDEO_HEIGHT = 1920
-    FPS = 30
-    
-    def __init__(self, temp_dir: str, output_dir: str = "videos/bar_race"):
-        self.temp_dir = temp_dir
-        self.output_dir = output_dir
-        os.makedirs(output_dir, exist_ok=True)
-    
-    def generate_video(
-        self,
-        df: pd.DataFrame,
-        plan: Dict[str, Any],
-        image_paths: Dict[str, str],
-        duration_seconds: int = 60,
-        job_id: str = ""
-    ) -> Optional[str]:
-        """
-        Generate bar chart race video.
-        
-        Args:
-            df: Cleaned data with columns: name, year, value
-            plan: Brain's plan with video_meta
-            image_paths: Dict mapping entity name to image path
-            duration_seconds: Video duration
-            job_id: Job ID for output filename
-            
-        Returns:
-            Path to generated video, or None if failed
-        """
-        logger.info(f"Director: Starting video generation for {duration_seconds}s video")
-        
-        try:
-            # Prepare data for bar_chart_race
-            df_pivot = self._prepare_data(df)
-            
-            if df_pivot is None or df_pivot.empty:
-                logger.error("Director: Failed to prepare data")
-                return None
-            
-            # Generate animation
-            video_path = self._generate_bar_race(
-                df_pivot=df_pivot,
-                plan=plan,
-                duration_seconds=duration_seconds,
-                job_id=job_id
-            )
-            
-            if video_path and os.path.exists(video_path):
-                # Try to add background music (optional)
-                video_with_music = self._add_background_music(video_path, duration_seconds)
-                if video_with_music:
-                    return video_with_music
-            
-            return video_path
-            
-        except Exception as e:
-            logger.error(f"Director: Video generation failed: {e}")
-            import traceback
-            logger.error(traceback.format_exc())
-            return None
-    
-    def _add_background_music(self, video_path: str, duration_seconds: int) -> Optional[str]:
-        """Add background music if available in assets/music folder"""
-        music_dir = "modules/bar_race/assets/music"
-        
-        # Check if music directory exists
-        if not os.path.exists(music_dir):
-            logger.info("Director: No music folder found, skipping background music")
-            return None
-        
-        # Find music files
-        music_files = []
-        for ext in [".mp3", ".wav", ".m4a", ".ogg"]:
-            for f in os.listdir(music_dir):
-                if f.lower().endswith(ext):
-                    music_files.append(os.path.join(music_dir, f))
-        
-        if not music_files:
-            logger.info("Director: No music files found, skipping background music")
-            return None
-        
-        try:
-            from moviepy.editor import VideoFileClip, AudioFileClip
-            import random
-            
-            # Pick random music file
-            music_path = random.choice(music_files)
-            logger.info(f"Director: Adding background music: {music_path}")
-            
-            # Load video and audio
-            video = VideoFileClip(video_path)
-            audio = AudioFileClip(music_path)
-            
-            # Loop audio if shorter than video
-            if audio.duration < video.duration:
-                from moviepy.editor import concatenate_audioclips
-                loops_needed = int(video.duration / audio.duration) + 1
-                audio = concatenate_audioclips([audio] * loops_needed)
-            
-            # Trim audio to video length and lower volume
-            audio = audio.subclip(0, video.duration).volumex(0.3)
-            
-            # Add audio to video
-            video_with_audio = video.set_audio(audio)
-            
-            # Save with music
-            output_path = video_path.replace(".mp4", "_music.mp4")
-            video_with_audio.write_videofile(
-                output_path,
-                codec="libx264",
-                audio_codec="aac",
-                fps=self.FPS,
-                logger=None
-            )
-            
-            # Cleanup
-            video.close()
-            audio.close()
-            
-            # Replace original with music version
-            os.remove(video_path)
-            os.rename(output_path, video_path)
-            
-            logger.info(f"Director: Added background music to video")
-            return video_path
-            
-        except Exception as e:
-            logger.warning(f"Director: Failed to add music: {e}")
-            return None
-    
-    def _prepare_data(self, df: pd.DataFrame) -> Optional[pd.DataFrame]:
-        """Prepare data for bar_chart_race (pivoted format)"""
-        try:
-            # Pivot: rows=year, columns=entity, values=value
-            df_pivot = df.pivot(index="year", columns="name", values="value")
-            
-            # Sort by year
-            df_pivot = df_pivot.sort_index()
-            
-            # Fill NaN with 0
-            df_pivot = df_pivot.fillna(0)
-            
-            logger.info(f"Director: Prepared pivot table with shape {df_pivot.shape}")
-            return df_pivot
-            
-        except Exception as e:
-            logger.error(f"Director: Data preparation failed: {e}")
-            return None
-    
-    def _generate_bar_race(
-        self,
-        df_pivot: pd.DataFrame,
-        plan: Dict[str, Any],
-        duration_seconds: int,
-        job_id: str
-    ) -> Optional[str]:
-        """Generate bar chart race animation"""
-        
-        # Get video metadata (handle both dict and string formats)
-        video_meta = plan.get("video_meta", {})
-        if isinstance(video_meta, str):
-            title = video_meta
-        else:
-            title = video_meta.get("title", "Bar Chart Race")
-        
-        value_intent = plan.get("value_intent", {})
-        if isinstance(value_intent, str):
-            value_unit = value_intent
-        else:
-            value_unit = value_intent.get("unit", "")
-        
-        visualization = plan.get("visualization", {})
-        if isinstance(visualization, str):
-            top_n = 10
-        else:
-            top_n = visualization.get("top_n", 10)
-        
-        output_path = os.path.join(self.output_dir, f"bar_race_{job_id}.mp4")
-        
-        try:
-            import bar_chart_race as bcr
-            
-            # Calculate timing for exact user-requested duration
-            num_years = len(df_pivot)
-            
-            # Total frames = duration * FPS (e.g., 30s * 30fps = 900 frames)
-            total_frames = duration_seconds * self.FPS
-            
-            # Frames per period (year) = total_frames / num_years
-            # steps_per_period controls animation smoothness within each year
-            steps_per_period = max(10, total_frames // num_years)
-            
-            # period_length (ms) = how long each year takes on screen
-            # To get exact duration: period_length = (duration_seconds * 1000) / num_years
-            period_length = int((duration_seconds * 1000) / num_years)
-            
-            logger.info(f"Director: Duration={duration_seconds}s, Years={num_years}, "
-                       f"period_length={period_length}ms, steps_per_period={steps_per_period}")
-            
-            # Calculate figsize for 9:16 vertical format (1080x1920 at dpi=144)
-            # Resolution = figsize * dpi
-            # For 1080x1920: figsize = (1080/144, 1920/144) = (7.5, 13.33)
-            figsize_9x16 = (self.VIDEO_WIDTH / 144, self.VIDEO_HEIGHT / 144)  # (7.5, 13.33)
-            
-            logger.info(f"Director: Video resolution {self.VIDEO_WIDTH}x{self.VIDEO_HEIGHT} (9:16 YouTube Shorts)")
-            
-            # Generate bar chart race with 9:16 vertical format
-            bcr.bar_chart_race(
-                df=df_pivot,
-                filename=output_path,
-                orientation='h',  # Horizontal bars look better in vertical video
-                sort='desc',
-                n_bars=top_n,
-                fixed_order=False,
-                fixed_max=True,
-                steps_per_period=steps_per_period,
-                period_length=period_length,
-                interpolate_period=True,
-                title=title,
-                figsize=figsize_9x16,  # 9:16 vertical format
-                cmap='dark24',
-                dpi=144  # Combined with figsize gives 1080x1920
-            )
-            
-            logger.info(f"Director: Generated video at {output_path}")
-            return output_path
-            
-        except ImportError:
-            logger.warning("Director: bar_chart_race not available, using fallback")
-            return self._generate_fallback_video(df_pivot, plan, duration_seconds, job_id)
-        except Exception as e:
-            logger.error(f"Director: bar_chart_race failed: {e}")
-            return self._generate_fallback_video(df_pivot, plan, duration_seconds, job_id)
-    
-    def _generate_fallback_video(
-        self,
-        df_pivot: pd.DataFrame,
-        plan: Dict[str, Any],
-        duration_seconds: int,
-        job_id: str
-    ) -> Optional[str]:
-        """Fallback: Generate smooth bar race animation with racing positions"""
-        logger.info(f"Director: Using fallback matplotlib animation for {duration_seconds}s")
-        
-        try:
-            import matplotlib
-            matplotlib.use('Agg')
-            import matplotlib.pyplot as plt
-            from matplotlib.animation import FuncAnimation
-            import numpy as np
-            
-            video_meta = plan.get("video_meta", {})
-            if isinstance(video_meta, str):
-                title = video_meta
-            else:
-                title = video_meta.get("title", "Bar Chart Race")
-            
-            visualization = plan.get("visualization", {})
-            if isinstance(visualization, str):
-                top_n = 10
-            else:
-                top_n = visualization.get("top_n", 10)
-            
-            # 9:16 aspect ratio (portrait mode for TikTok/Reels)
-            fig, ax = plt.subplots(figsize=(5.625, 10), facecolor='#0f0f1a', dpi=144)
-            ax.set_facecolor('#0f0f1a')
-            
-            years = df_pivot.index.tolist()
-            columns = df_pivot.columns.tolist()
-            
-            # Create interpolated data for smooth animation
-            # Each year will have multiple intermediate frames
-            frames_per_year = max(20, (duration_seconds * self.FPS) // len(years))
-            total_frames = len(years) * frames_per_year
-            
-            logger.info(f"Director: {len(years)} years, {frames_per_year} frames/year, {total_frames} total frames")
-            
-            # Interpolate data between years
-            interpolated_data = []
-            for i in range(len(years) - 1):
-                year1, year2 = years[i], years[i + 1]
-                for j in range(frames_per_year):
-                    t = j / frames_per_year  # Interpolation factor 0->1
-                    # Smooth easing
-                    t = t * t * (3 - 2 * t)  # Smoothstep
-                    
-                    values = {}
-                    for col in columns:
-                        v1 = df_pivot.loc[year1, col] if not pd.isna(df_pivot.loc[year1, col]) else 0
-                        v2 = df_pivot.loc[year2, col] if not pd.isna(df_pivot.loc[year2, col]) else 0
-                        values[col] = v1 + (v2 - v1) * t
-                    
-                    interpolated_data.append({
-                        'year': year1 + (year2 - year1) * t,
-                        'values': values
-                    })
-            
-            # Add last year
-            for j in range(frames_per_year):
-                interpolated_data.append({
-                    'year': years[-1],
-                    'values': {col: df_pivot.loc[years[-1], col] for col in columns}
-                })
-            
-            total_frames = len(interpolated_data)
-            logger.info(f"Director: Created {total_frames} interpolated frames")
-            
-            # Color palette - distinct colors for each entity
-            np.random.seed(42)
-            color_map = {}
-            vibrant_colors = plt.cm.tab20.colors + plt.cm.Set3.colors
-            for i, col in enumerate(columns):
-                color_map[col] = vibrant_colors[i % len(vibrant_colors)]
-            
-            # Max value for consistent x-axis
-            max_val = df_pivot.max().max() * 1.15
-            
-            def update(frame):
-                ax.clear()
-                ax.set_facecolor('#0f0f1a')
-                
-                if frame >= len(interpolated_data):
-                    frame = len(interpolated_data) - 1
-                
-                data = interpolated_data[frame]
-                year = data['year']
-                values = data['values']
-                
-                # Sort by value (descending) and take top N
-                sorted_items = sorted(values.items(), key=lambda x: x[1] if x[1] else 0, reverse=True)[:top_n]
-                
-                # Reverse for bottom-to-top (biggest on top)
-                sorted_items = sorted_items[::-1]
-                
-                names = [item[0] for item in sorted_items]
-                vals = [item[1] if item[1] else 0 for item in sorted_items]
-                colors = [color_map[name] for name in names]
-                
-                # Draw horizontal bars with smooth animation
-                y_positions = np.arange(len(names))
-                bars = ax.barh(y_positions, vals, color=colors, height=0.75, alpha=0.9)
-                
-                # Add value labels and entity names
-                for i, (name, val) in enumerate(zip(names, vals)):
-                    # Value on bar end
-                    if val > 0:
-                        label = f'{val/1e12:.2f}T' if val >= 1e12 else f'{val/1e9:.1f}B'
-                        ax.text(val + max_val * 0.01, i, label, va='center', ha='left', 
-                               fontsize=10, color='white', fontweight='bold')
-                    
-                    # Entity name inside bar
-                    display_name = name[:15] if len(name) > 15 else name
-                    ax.text(max_val * 0.01, i, display_name, va='center', ha='left',
-                           fontsize=11, color='white', fontweight='bold')
-                
-                # Title
-                ax.set_title(title, fontsize=16, color='white', pad=20, fontweight='bold',
-                           fontfamily='sans-serif')
-                
-                # Large year display
-                ax.text(0.95, 0.12, f'{int(year)}', transform=ax.transAxes, fontsize=72,
-                       ha='right', va='top', color='white', alpha=0.7, fontweight='bold',
-                       fontfamily='sans-serif')
-                
-                # Styling
-                ax.set_yticks([])
-                ax.set_xlim(0, max_val)
-                ax.spines['top'].set_visible(False)
-                ax.spines['right'].set_visible(False)
-                ax.spines['left'].set_visible(False)
-                ax.spines['bottom'].set_color('#333')
-                ax.tick_params(colors='#666', labelsize=9)
-                
-                # X-axis formatting
-                ax.xaxis.set_major_formatter(plt.FuncFormatter(
-                    lambda x, p: f'{x/1e12:.1f}T' if x >= 1e12 else f'{x/1e9:.0f}B'
-                ))
-                
-                plt.tight_layout()
-            
-            # Create animation
-            anim = FuncAnimation(fig, update, frames=total_frames, 
-                               interval=1000/self.FPS, repeat=False)
-            
-            # Save to temp file
-            temp_path = os.path.join(self.temp_dir, f"temp_animation_{job_id}.mp4")
-            logger.info(f"Director: Saving smooth racing animation with {total_frames} frames")
-            anim.save(temp_path, writer='ffmpeg', fps=self.FPS, dpi=144,
-                     savefig_kwargs={'facecolor': '#0f0f1a'})
-            plt.close(fig)
-            
-            # Move to output
-            output_path = os.path.join(self.output_dir, f"bar_race_{job_id}.mp4")
-            shutil.move(temp_path, output_path)
-            
-            logger.info(f"Director: Generated smooth racing video at {output_path}")
-            return output_path
-            
-        except Exception as e:
-            logger.error(f"Director: Fallback video generation failed: {e}")
-            import traceback
-            logger.error(traceback.format_exc())
-            return None
-    
-    def cleanup(self):
-        """Clean up temporary files"""
-        try:
-            if os.path.exists(self.temp_dir):
-                shutil.rmtree(self.temp_dir)
-                logger.info(f"Director: Cleaned up temp directory: {self.temp_dir}")
-        except Exception as e:
-            logger.warning(f"Director: Cleanup failed: {e}")

modules/text_story/__init__.py

@@ -0,0 +1,66 @@
+"""
+ Text Story Module for NCAkit
+Generates fake iMessage-style text conversation videos.
+"""
+from fastapi import FastAPI
+import logging
+
+# Module Metadata
+MODULE_NAME = "text_story"
+MODULE_PREFIX = "/api/text-story"
+MODULE_DESCRIPTION = "Generate fake iMessage-style text story videos with TTS"
+
+logger = logging.getLogger(__name__)
+
+
+def register(app: FastAPI, config):
+    """
+    Register the text story module with FastAPI.
+    Initializes services and adds routes.
+    """
+    from .router import router
+    
+    logger.info("Registering text_story module...")
+    
+    # Validate TTS config
+    if not config.hf_tts:
+        logger.warning("HF_TTS not configured! TTS generation will fail.")
+    
+    # Create required directories
+    import os
+    os.makedirs("videos/text_story", exist_ok=True)
+    
+    # Create gameplay backgrounds folder in persistent storage
+    if os.path.exists("/data"):
+        os.makedirs("/data/gameplay_backgrounds", exist_ok=True)
+        logger.info("Created /data/gameplay_backgrounds folder for gameplay videos")
+    
+    # Check gameplay backgrounds
+    backgrounds_paths = [
+        "/data/gameplay_backgrounds",
+        "assets/gameplay_backgrounds"
+    ]
+    
+    bg_found = False
+    for path in backgrounds_paths:
+        if os.path.exists(path):
+            count = len([f for f in os.listdir(path) if f.endswith('.mp4')])
+            if count > 0:
+                logger.info(f"Found {count} gameplay backgrounds in {path}")
+                bg_found = True
+                break
+    
+    if not bg_found:
+        logger.warning("No gameplay backgrounds found! Will use solid color background.")
+        logger.info("Add .mp4 files to /data/gameplay_backgrounds for video backgrounds")
+    
+    # Register router
+    app.include_router(router)
+    
+    logger.info("text_story module registered successfully")
+
+
+# Export router for direct import
+from .router import router
+
+__all__ = ["router", "register", "MODULE_NAME", "MODULE_PREFIX", "MODULE_DESCRIPTION"]

modules/text_story/router.py

@@ -0,0 +1,344 @@
+"""
+Text Story Router - FastAPI endpoints for fake iMessage chat video generation.
+"""
+
+import os
+import uuid
+import logging
+import asyncio
+from typing import Dict, Any
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from fastapi.responses import FileResponse
+
+from .schemas import TextStoryRequest, TextStoryResponse, TextStoryStatus
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/text-story", tags=["Text Story"])
+
+# Job storage (in-memory for now)
+jobs: Dict[str, Dict[str, Any]] = {}
+
+
+def update_job(job_id: str, status: str, progress: int, step: str = None, 
+               video_url: str = None, error: str = None):
+    """Update job status."""
+    if job_id in jobs:
+        jobs[job_id].update({
+            "status": status,
+            "progress": progress,
+            "current_step": step,
+            "video_url": video_url,
+            "error": error
+        })
+
+
+async def generate_text_story_video(job_id: str, request: TextStoryRequest):
+    """
+    Main video generation pipeline.
+    
+    Pipeline:
+    1. Setup temp directory
+    2. Generate TTS for each message
+    3. Create chat UI frames
+    4. Load gameplay background
+    5. Compose final video
+    """
+    try:
+        import tempfile
+        import shutil
+        
+        temp_dir = tempfile.mkdtemp(prefix="text_story_")
+        logger.info(f"TextStory: Starting job {job_id}")
+        
+        # ============ STEP 1: TTS Generation ============
+        update_job(job_id, "processing", 10, "Generating voices...")
+        
+        from .services.tts_handler import TTSHandler
+        tts = TTSHandler()
+        
+        audio_files = []
+        for i, msg in enumerate(request.messages):
+            voice = request.voice_a if msg.sender == "A" else request.voice_b
+            audio_path = os.path.join(temp_dir, f"msg_{i:03d}.wav")
+            
+            duration = await tts.generate_tts(msg.text, voice, audio_path)
+            audio_files.append({
+                "path": audio_path,
+                "duration": duration,
+                "sender": msg.sender,
+                "text": msg.text
+            })
+            
+            progress = 10 + int((i + 1) / len(request.messages) * 30)
+            update_job(job_id, "processing", progress, f"Voice {i+1}/{len(request.messages)}")
+        
+        # ============ STEP 2: Create Chat Frames ============
+        update_job(job_id, "processing", 45, "Rendering chat UI...")
+        
+        from .services.renderer import ChatRenderer
+        renderer = ChatRenderer(
+            person_a_name=request.person_a_name,
+            person_b_name=request.person_b_name,
+            person_b_avatar=request.person_b_avatar
+        )
+        
+        # ============ STEP 3: Load Background ============
+        update_job(job_id, "processing", 55, "Loading background...")
+        
+        from .services.background import BackgroundHandler
+        bg_handler = BackgroundHandler()
+        
+        # ============ STEP 4: Compose Video ============
+        update_job(job_id, "processing", 65, "Composing video...")
+        
+        from .services.video_composer import VideoComposer
+        composer = VideoComposer(
+            renderer=renderer,
+            bg_handler=bg_handler,
+            tts_handler=tts
+        )
+        
+        output_path = await composer.compose(
+            messages=audio_files,
+            ending_text=request.ending_text,
+            output_dir=temp_dir
+        )
+        
+        # ============ STEP 5: Save Final Video ============
+        update_job(job_id, "processing", 90, "Saving video...")
+        
+        # Create output directory
+        videos_dir = os.path.join("videos", "text_story")
+        os.makedirs(videos_dir, exist_ok=True)
+        
+        final_path = os.path.join(videos_dir, f"text_story_{job_id}.mp4")
+        shutil.copy2(output_path, final_path)
+        
+        # Also save to persistent storage if available
+        persistent_dir = "/data/videos/text_story"
+        if os.path.exists("/data"):
+            os.makedirs(persistent_dir, exist_ok=True)
+            shutil.copy2(output_path, os.path.join(persistent_dir, f"text_story_{job_id}.mp4"))
+        
+        # Cleanup temp
+        shutil.rmtree(temp_dir, ignore_errors=True)
+        
+        video_url = f"/api/text-story/{job_id}/video"
+        update_job(job_id, "ready", 100, "Complete!", video_url=video_url)
+        logger.info(f"TextStory: Job {job_id} completed successfully")
+        
+    except Exception as e:
+        logger.error(f"TextStory: Job {job_id} failed - {e}")
+        update_job(job_id, "failed", 0, error=str(e))
+        
+        # Cleanup on failure
+        if 'temp_dir' in locals():
+            shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+@router.post("/generate", response_model=TextStoryResponse)
+async def generate_text_story(
+    request: TextStoryRequest,
+    background_tasks: BackgroundTasks
+):
+    """
+    Start text story video generation.
+    
+    Returns job_id for status polling.
+    """
+    job_id = uuid.uuid4().hex[:12]
+    
+    # Initialize job
+    jobs[job_id] = {
+        "status": "processing",
+        "progress": 0,
+        "current_step": "Starting...",
+        "video_url": None,
+        "error": None,
+        "request": request.model_dump()
+    }
+    
+    # Start background generation
+    background_tasks.add_task(generate_text_story_video, job_id, request)
+    
+    logger.info(f"TextStory: Started job {job_id} with {len(request.messages)} messages")
+    
+    return TextStoryResponse(
+        job_id=job_id,
+        status="processing",
+        message=f"Started generating text story with {len(request.messages)} messages"
+    )
+
+
+@router.get("/{job_id}/status", response_model=TextStoryStatus)
+async def get_text_story_status(job_id: str):
+    """Get status of a text story generation job."""
+    if job_id not in jobs:
+        raise HTTPException(status_code=404, detail="Job not found")
+    
+    job = jobs[job_id]
+    return TextStoryStatus(
+        job_id=job_id,
+        status=job["status"],
+        progress=job["progress"],
+        current_step=job.get("current_step"),
+        video_url=job.get("video_url"),
+        error=job.get("error")
+    )
+
+
+@router.get("/{job_id}/video")
+async def download_text_story_video(job_id: str):
+    """Download the generated text story video."""
+    if job_id not in jobs:
+        raise HTTPException(status_code=404, detail="Job not found")
+    
+    job = jobs[job_id]
+    if job["status"] != "ready":
+        raise HTTPException(status_code=400, detail="Video not ready yet")
+    
+    # Check persistent storage first
+    persistent_path = f"/data/videos/text_story/text_story_{job_id}.mp4"
+    local_path = f"videos/text_story/text_story_{job_id}.mp4"
+    
+    if os.path.exists(persistent_path):
+        video_path = persistent_path
+    elif os.path.exists(local_path):
+        video_path = local_path
+    else:
+        raise HTTPException(status_code=404, detail="Video file not found")
+    
+    return FileResponse(
+        video_path,
+        media_type="video/mp4",
+        filename=f"text_story_{job_id}.mp4"
+    )
+
+
+# ============================================
+# AI CONVERSATION GENERATION
+# ============================================
+
+from pydantic import BaseModel
+from typing import List, Optional
+
+class AiGenerateRequest(BaseModel):
+    """Request for AI-generated conversation."""
+    prompt: str
+    person_a_name: str = "You"
+    person_b_name: str = "My Ex"
+    message_count: int = 7
+    tone: str = "emotional"
+
+
+class AiGenerateResponse(BaseModel):
+    """Response with generated messages."""
+    messages: List[dict]
+    ending_text: Optional[str] = None
+
+
+@router.post("/ai-generate", response_model=AiGenerateResponse)
+async def ai_generate_conversation(request: AiGenerateRequest):
+    """
+    Generate a fake conversation using Groq AI (openai/gpt-oss-120b).
+    
+    Returns a list of messages for the text story.
+    """
+    import aiohttp
+    import json
+    
+    groq_api_key = os.getenv("GROQ_API_KEY", "")
+    if not groq_api_key:
+        raise HTTPException(status_code=500, detail="GROQ_API_KEY not configured")
+    
+    # Tone descriptions
+    tone_prompts = {
+        "emotional": "Make it emotional and dramatic with deep feelings.",
+        "funny": "Make it funny and comedic with witty responses.",
+        "shocking": "Include a shocking plot twist at the end.",
+        "romantic": "Make it romantic with heartfelt messages.",
+        "angry": "Make it an angry argument with heated exchanges."
+    }
+    
+    tone_instruction = tone_prompts.get(request.tone, tone_prompts["emotional"])
+    
+    system_prompt = f"""You are a viral content script writer. Generate a fake text message conversation.
+
+RULES:
+1. Create exactly {request.message_count} messages
+2. Alternate between Person A ({request.person_a_name}) and Person B ({request.person_b_name})
+3. {tone_instruction}
+4. Make it engaging and viral-worthy
+5. Keep messages short (1-3 sentences each)
+6. End with impact (twist or emotional ending)
+
+OUTPUT FORMAT (strict JSON):
+{{
+    "messages": [
+        {{"sender": "B", "text": "message from {request.person_b_name}"}},
+        {{"sender": "A", "text": "message from {request.person_a_name}"}},
+        ...
+    ],
+    "ending_text": "Optional ending text like 'To be continued...'"
+}}
+
+Only output valid JSON, nothing else."""
+
+    user_prompt = f"Create a conversation about: {request.prompt}"
+    
+    try:
+        async with aiohttp.ClientSession() as session:
+            payload = {
+                "model": "meta-llama/llama-4-scout-17b-16e-instruct",
+                "messages": [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt}
+                ],
+                "temperature": 0.8,
+                "max_tokens": 2000
+            }
+            
+            headers = {
+                "Authorization": f"Bearer {groq_api_key}",
+                "Content-Type": "application/json"
+            }
+            
+            async with session.post(
+                "https://api.groq.com/openai/v1/chat/completions",
+                json=payload,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=30)
+            ) as response:
+                if response.status != 200:
+                    error_text = await response.text()
+                    logger.error(f"Groq API error: {error_text}")
+                    raise HTTPException(status_code=500, detail=f"Groq API error: {response.status}")
+                
+                data = await response.json()
+                content = data["choices"][0]["message"]["content"]
+                
+                # Parse JSON response
+                try:
+                    # Clean up content (remove markdown code blocks if present)
+                    content = content.strip()
+                    if content.startswith("```"):
+                        content = content.split("```")[1]
+                        if content.startswith("json"):
+                            content = content[4:]
+                    content = content.strip()
+                    
+                    result = json.loads(content)
+                    
+                    return AiGenerateResponse(
+                        messages=result.get("messages", []),
+                        ending_text=result.get("ending_text")
+                    )
+                except json.JSONDecodeError as e:
+                    logger.error(f"Failed to parse AI response: {content}")
+                    raise HTTPException(status_code=500, detail="AI returned invalid JSON")
+                    
+    except aiohttp.ClientError as e:
+        logger.error(f"Groq API request failed: {e}")
+        raise HTTPException(status_code=500, detail=f"AI request failed: {str(e)}")
+

modules/text_story/schemas.py

@@ -0,0 +1,69 @@
+"""
+Pydantic schemas for Text Story module.
+Defines input/output models for the API.
+"""
+
+from pydantic import BaseModel, Field
+from typing import List, Optional, Literal
+
+
+class Message(BaseModel):
+    """Single chat message."""
+    sender: Literal["A", "B"] = Field(
+        description="A = User (right, blue bubble), B = Other person (left, gray bubble)"
+    )
+    text: str = Field(
+        description="Message text content",
+        min_length=1,
+        max_length=500
+    )
+
+
+class TextStoryRequest(BaseModel):
+    """Request to generate a text story video."""
+    person_a_name: str = Field(
+        default="You",
+        description="Name for Person A (user, right side)"
+    )
+    person_b_name: str = Field(
+        default="Unknown",
+        description="Name for Person B (other, left side)"
+    )
+    person_b_avatar: Optional[str] = Field(
+        default=None,
+        description="Avatar letter or emoji for Person B header (e.g., 'M' or '😊')"
+    )
+    messages: List[Message] = Field(
+        description="List of chat messages in order",
+        min_length=2,
+        max_length=50
+    )
+    ending_text: Optional[str] = Field(
+        default=None,
+        description="Emotional ending text (e.g., 'To be continued...')"
+    )
+    voice_a: str = Field(
+        default="af_heart",
+        description="Kokoro TTS voice for Person A"
+    )
+    voice_b: str = Field(
+        default="am_fenrir",
+        description="Kokoro TTS voice for Person B"
+    )
+
+
+class TextStoryResponse(BaseModel):
+    """Response after starting video generation."""
+    job_id: str
+    status: str = "processing"
+    message: str = "Text story generation started"
+
+
+class TextStoryStatus(BaseModel):
+    """Status of a text story generation job."""
+    job_id: str
+    status: Literal["processing", "ready", "failed"]
+    progress: int = Field(default=0, ge=0, le=100)
+    current_step: Optional[str] = None
+    video_url: Optional[str] = None
+    error: Optional[str] = None

modules/text_story/services/__init__.py

@@ -0,0 +1 @@
+# Services init

modules/text_story/services/background.py

@@ -0,0 +1,231 @@
+"""
+Background Handler for Text Story module.
+Handles gameplay video loading from HuggingFace Dataset storage.
+"""
+
+import os
+import random
+import logging
+from moviepy.editor import VideoFileClip, vfx
+from typing import Optional, List
+from huggingface_hub import hf_hub_download, list_repo_files
+
+logger = logging.getLogger(__name__)
+
+# Folder name in HF Dataset for gameplay backgrounds
+HF_BACKGROUNDS_FOLDER = "gameplay_backgrounds"
+
+# Local cache path
+LOCAL_CACHE_DIR = "cache/gameplay_backgrounds"
+
+
+class BackgroundHandler:
+    """
+    Handles gameplay background video processing.
+    Downloads from HuggingFace Dataset (HF_REPO env variable).
+    
+    Features:
+    - Download videos from HF Dataset
+    - Random video selection
+    - Audio removal
+    - Slow motion (0.7x)
+    - Dark overlay
+    - Seamless looping
+    """
+    
+    def __init__(self):
+        # Get repo from environment variable (e.g., robiul487/NCAkit)
+        self.repo_id = os.getenv("HF_REPO", "")
+        self.folder = HF_BACKGROUNDS_FOLDER
+        self.cache_dir = LOCAL_CACHE_DIR
+        
+        if not self.repo_id:
+            logger.warning("BackgroundHandler: HF_REPO not set! Using solid background.")
+            self.available_videos = []
+            return
+        
+        # Ensure cache directory exists
+        os.makedirs(self.cache_dir, exist_ok=True)
+        
+        # Get list of available videos
+        self.available_videos = self._list_available_videos()
+        
+        if self.available_videos:
+            logger.info(f"BackgroundHandler: Found {len(self.available_videos)} videos in {self.repo_id}/{self.folder}")
+        else:
+            logger.warning(f"BackgroundHandler: No videos found in {self.repo_id}/{self.folder}")
+    
+    def _list_available_videos(self) -> List[str]:
+        """List available video files in HF Dataset folder."""
+        if not self.repo_id:
+            return []
+        
+        try:
+            all_files = list_repo_files(
+                repo_id=self.repo_id,
+                repo_type="dataset"
+            )
+            
+            # Filter for videos in gameplay_backgrounds folder
+            videos = [
+                f for f in all_files 
+                if f.startswith(f"{self.folder}/") 
+                and f.lower().endswith(('.mp4', '.mov', '.avi', '.webm'))
+            ]
+            
+            return videos
+            
+        except Exception as e:
+            logger.error(f"BackgroundHandler: Failed to list files - {e}")
+            return []
+    
+    def _download_video(self, filename: str) -> Optional[str]:
+        """Download a video from HF Dataset to local cache."""
+        try:
+            # Check if already cached
+            local_name = os.path.basename(filename)
+            cached_path = os.path.join(self.cache_dir, local_name)
+            
+            if os.path.exists(cached_path):
+                logger.info(f"BackgroundHandler: Using cached {local_name}")
+                return cached_path
+            
+            # Download from HF
+            logger.info(f"BackgroundHandler: Downloading {filename}...")
+            
+            downloaded_path = hf_hub_download(
+                repo_id=self.repo_id,
+                filename=filename,
+                repo_type="dataset",
+                local_dir=self.cache_dir,
+                local_dir_use_symlinks=False
+            )
+            
+            logger.info(f"BackgroundHandler: Downloaded to {downloaded_path}")
+            return downloaded_path
+            
+        except Exception as e:
+            logger.error(f"BackgroundHandler: Download failed - {e}")
+            return None
+    
+    def get_random_video(self) -> Optional[str]:
+        """Get random video from HF Dataset and download it."""
+        if not self.available_videos:
+            # Retry listing
+            self.available_videos = self._list_available_videos()
+        
+        if not self.available_videos:
+            logger.warning("BackgroundHandler: No videos available")
+            return None
+        
+        selected = random.choice(self.available_videos)
+        logger.info(f"BackgroundHandler: Selected {selected}")
+        
+        return self._download_video(selected)
+    
+    def load_and_process(self, 
+                         target_duration: float,
+                         video_path: str = None) -> Optional[VideoFileClip]:
+        """
+        Load and process a background video.
+        
+        Args:
+            target_duration: Required duration in seconds
+            video_path: Optional specific video path (or random if None)
+            
+        Returns:
+            Processed VideoFileClip or None
+        """
+        # Get video path
+        if video_path is None:
+            video_path = self.get_random_video()
+        
+        if not video_path or not os.path.exists(video_path):
+            logger.warning("BackgroundHandler: No video available, creating solid background")
+            return self._create_solid_background(target_duration)
+        
+        try:
+            # Load video WITHOUT audio
+            clip = VideoFileClip(video_path).without_audio()
+            logger.info(f"BackgroundHandler: Loaded {video_path}, duration: {clip.duration:.1f}s")
+            
+            # Apply slow motion (0.7x speed)
+            clip = clip.fx(vfx.speedx, 0.7)
+            
+            # Loop if needed to match target duration
+            clip = self._loop_to_duration(clip, target_duration)
+            
+            # Apply visual effects
+            clip = self._apply_visual_effects(clip)
+            
+            return clip
+            
+        except Exception as e:
+            logger.error(f"BackgroundHandler: Failed to process video - {e}")
+            return self._create_solid_background(target_duration)
+    
+    def _loop_to_duration(self, clip: VideoFileClip, target_duration: float) -> VideoFileClip:
+        """Loop video to match target duration."""
+        if clip.duration >= target_duration:
+            return clip.subclip(0, target_duration)
+        
+        loops_needed = int(target_duration / clip.duration) + 1
+        looped = clip.loop(n=loops_needed)
+        return looped.subclip(0, target_duration)
+    
+    def _apply_visual_effects(self, clip: VideoFileClip) -> VideoFileClip:
+        """
+        Apply resize, crop (if needed), dark overlay, and saturation reduction.
+        
+        - 9:16 videos: just resize (no crop needed)
+        - 16:9 videos: center crop to 9:16
+        """
+        target_w, target_h = 1080, 1920
+        target_ratio = target_w / target_h  # 0.5625 (9:16)
+        
+        # Calculate source aspect ratio
+        clip_ratio = clip.w / clip.h
+        
+        # Check if already 9:16 (or close to it)
+        # 9:16 ratio is ~0.5625, allow some tolerance
+        is_vertical = clip_ratio < 0.7  # Less than ~11:16 is considered vertical
+        
+        if is_vertical:
+            # Already vertical (9:16)
+            if clip.w == target_w and clip.h == target_h:
+                # Perfect match, no resize needed
+                logger.info(f"BackgroundHandler: Video is already {target_w}x{target_h}, no resize")
+            else:
+                # Resize to target resolution
+                logger.info(f"BackgroundHandler: Video is vertical ({clip.w}x{clip.h}), resizing to {target_w}x{target_h}")
+                clip = clip.resize(newsize=(target_w, target_h))
+        else:
+            # Horizontal (16:9), need to crop
+            logger.info(f"BackgroundHandler: Video is horizontal ({clip.w}x{clip.h}), center cropping to 9:16")
+            
+            # Scale to match height, then center crop width
+            new_h = target_h
+            new_w = int(clip_ratio * new_h)
+            clip = clip.resize(height=new_h)
+            
+            # Center crop
+            x_center = new_w // 2
+            clip = clip.crop(x_center=x_center, width=target_w, height=target_h)
+        
+        # Dark overlay (reduce brightness by 40%)
+        clip = clip.fx(vfx.colorx, 0.6)
+        
+        # Saturation reduction
+        clip = clip.fx(vfx.lum_contrast, lum=-10, contrast=-0.1)
+        
+        return clip
+    
+    def _create_solid_background(self, duration: float) -> VideoFileClip:
+        """Create solid dark background as fallback."""
+        from moviepy.editor import ColorClip
+        
+        return ColorClip(
+            size=(1080, 1920),
+            color=(15, 15, 25),
+            duration=duration
+        )

modules/text_story/services/renderer.py

@@ -0,0 +1,295 @@
+"""
+Chat UI Renderer for Text Story module.
+Creates iMessage-style chat bubbles and UI.
+"""
+
+import os
+import logging
+from PIL import Image, ImageDraw, ImageFont
+from typing import List, Tuple, Optional
+
+logger = logging.getLogger(__name__)
+
+# Canvas dimensions (9:16 vertical)
+CANVAS_WIDTH = 1080
+CANVAS_HEIGHT = 1920
+
+# Colors (iMessage style)
+COLORS = {
+    "header_bg": (28, 28, 30),       # #1C1C1E - Dark header
+    "bubble_user": (0, 122, 255),    # #007AFF - Blue (Person A/right)
+    "bubble_other": (58, 58, 60),    # #3A3A3C - Gray (Person B/left)
+    "text_white": (255, 255, 255),   # White text
+    "text_gray": (142, 142, 147),    # #8E8E93 - Secondary text
+}
+
+# UI Measurements
+UI = {
+    "header_height": 100,
+    "margin_side": 30,
+    "bubble_max_width_ratio": 0.75,  # 75% of screen
+    "bubble_padding_h": 16,
+    "bubble_padding_v": 12,
+    "bubble_radius": 20,
+    "bubble_gap": 10,
+    "font_size": 34,
+    "header_font_size": 22,
+    "avatar_size": 50,
+    "max_visible_messages": 7,
+}
+
+
+class ChatRenderer:
+    """
+    Renders iMessage-style chat UI frames.
+    Handles dynamic box sizing and message bubbles.
+    """
+    
+    def __init__(self, 
+                 person_a_name: str = "You",
+                 person_b_name: str = "Unknown",
+                 person_b_avatar: str = None):
+        self.person_a_name = person_a_name
+        self.person_b_name = person_b_name
+        self.person_b_avatar = person_b_avatar or person_b_name[0].upper()
+        
+        # Load fonts
+        self.font = self._load_font(UI["font_size"])
+        self.font_small = self._load_font(UI["header_font_size"])
+        self.font_avatar = self._load_font(28)
+        
+        # Track visible messages for scroll behavior
+        self.visible_messages: List[dict] = []
+    
+    def _load_font(self, size: int) -> ImageFont.FreeTypeFont:
+        """Load font with fallback."""
+        font_paths = [
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+            "C:/Windows/Fonts/arial.ttf",
+            "/System/Library/Fonts/SFNS.ttf",
+        ]
+        
+        for path in font_paths:
+            if os.path.exists(path):
+                try:
+                    return ImageFont.truetype(path, size)
+                except:
+                    continue
+        
+        # Fallback to default
+        return ImageFont.load_default()
+    
+    def _wrap_text(self, text: str, max_width: int) -> List[str]:
+        """Wrap text to fit within max width."""
+        words = text.split()
+        lines = []
+        current_line = []
+        
+        for word in words:
+            test_line = " ".join(current_line + [word])
+            bbox = self.font.getbbox(test_line)
+            width = bbox[2] - bbox[0]
+            
+            if width <= max_width:
+                current_line.append(word)
+            else:
+                if current_line:
+                    lines.append(" ".join(current_line))
+                current_line = [word]
+        
+        if current_line:
+            lines.append(" ".join(current_line))
+        
+        return lines if lines else [text]
+    
+    def _calculate_bubble_size(self, text: str) -> Tuple[int, int, List[str]]:
+        """Calculate bubble size based on text."""
+        max_text_width = int(CANVAS_WIDTH * UI["bubble_max_width_ratio"]) - UI["bubble_padding_h"] * 2
+        lines = self._wrap_text(text, max_text_width)
+        
+        # Calculate text dimensions
+        line_height = self.font.getbbox("Ay")[3] + 4
+        text_height = line_height * len(lines)
+        
+        max_line_width = 0
+        for line in lines:
+            bbox = self.font.getbbox(line)
+            max_line_width = max(max_line_width, bbox[2] - bbox[0])
+        
+        # Add padding
+        bubble_width = max_line_width + UI["bubble_padding_h"] * 2
+        bubble_height = text_height + UI["bubble_padding_v"] * 2
+        
+        return bubble_width, bubble_height, lines
+    
+    def _draw_header(self, draw: ImageDraw.Draw, img: Image.Image):
+        """Draw iMessage-style header."""
+        # Header background
+        draw.rectangle(
+            [0, 0, CANVAS_WIDTH, UI["header_height"]],
+            fill=COLORS["header_bg"]
+        )
+        
+        # Avatar circle
+        avatar_x = CANVAS_WIDTH // 2
+        avatar_y = 35
+        avatar_r = UI["avatar_size"] // 2
+        
+        draw.ellipse(
+            [avatar_x - avatar_r, avatar_y - avatar_r,
+             avatar_x + avatar_r, avatar_y + avatar_r],
+            fill=(100, 100, 105)  # Gray circle
+        )
+        
+        # Avatar letter
+        bbox = self.font_avatar.getbbox(self.person_b_avatar)
+        text_w = bbox[2] - bbox[0]
+        text_h = bbox[3] - bbox[1]
+        draw.text(
+            (avatar_x - text_w // 2, avatar_y - text_h // 2 - 2),
+            self.person_b_avatar,
+            fill=COLORS["text_white"],
+            font=self.font_avatar
+        )
+        
+        # Name below avatar
+        name_bbox = self.font_small.getbbox(self.person_b_name)
+        name_w = name_bbox[2] - name_bbox[0]
+        draw.text(
+            (avatar_x - name_w // 2, avatar_y + avatar_r + 8),
+            self.person_b_name,
+            fill=COLORS["text_white"],
+            font=self.font_small
+        )
+        
+        # Left chevron (back button)
+        draw.text((20, 30), "‹", fill=(0, 122, 255), font=self.font)
+        
+        # Right video icon
+        draw.text((CANVAS_WIDTH - 50, 30), "📹", fill=(0, 122, 255), font=self.font_small)
+    
+    def _draw_bubble(self, draw: ImageDraw.Draw, 
+                     x: int, y: int, 
+                     width: int, height: int,
+                     lines: List[str],
+                     is_user: bool) -> int:
+        """
+        Draw a chat bubble.
+        
+        Returns:
+            Bottom Y position of bubble
+        """
+        # Bubble color
+        color = COLORS["bubble_user"] if is_user else COLORS["bubble_other"]
+        
+        # Draw rounded rectangle
+        radius = UI["bubble_radius"]
+        draw.rounded_rectangle(
+            [x, y, x + width, y + height],
+            radius=radius,
+            fill=color
+        )
+        
+        # Draw text
+        text_x = x + UI["bubble_padding_h"]
+        text_y = y + UI["bubble_padding_v"]
+        line_height = self.font.getbbox("Ay")[3] + 4
+        
+        for line in lines:
+            draw.text((text_x, text_y), line, fill=COLORS["text_white"], font=self.font)
+            text_y += line_height
+        
+        return y + height
+    
+    def render_frame(self, messages: List[dict], show_typing: bool = False) -> Image.Image:
+        """
+        Render a single frame with current messages.
+        
+        Args:
+            messages: List of {"sender": "A"/"B", "text": "..."} dicts
+            show_typing: Whether to show typing indicator
+            
+        Returns:
+            PIL Image of the frame
+        """
+        # Create transparent image (gameplay will be behind)
+        img = Image.new("RGBA", (CANVAS_WIDTH, CANVAS_HEIGHT), (0, 0, 0, 0))
+        draw = ImageDraw.Draw(img)
+        
+        # Calculate total height needed for messages
+        message_heights = []
+        for msg in messages:
+            _, height, _ = self._calculate_bubble_size(msg["text"])
+            message_heights.append(height + UI["bubble_gap"])
+        
+        total_msg_height = sum(message_heights)
+        
+        # Calculate UI box height (dynamic)
+        ui_height = UI["header_height"] + total_msg_height + 20  # 20px bottom padding
+        
+        # Draw semi-transparent black background for chat area
+        draw.rectangle(
+            [0, 0, CANVAS_WIDTH, ui_height],
+            fill=(0, 0, 0, 220)  # Semi-transparent black
+        )
+        
+        # Draw header
+        self._draw_header(draw, img)
+        
+        # Draw messages
+        current_y = UI["header_height"] + 15
+        
+        # Only show last N messages if too many
+        visible_messages = messages[-UI["max_visible_messages"]:]
+        
+        for msg in visible_messages:
+            width, height, lines = self._calculate_bubble_size(msg["text"])
+            
+            # Position: A (user) = right, B (other) = left
+            if msg["sender"] == "A":
+                x = CANVAS_WIDTH - UI["margin_side"] - width
+            else:
+                x = UI["margin_side"]
+            
+            current_y = self._draw_bubble(draw, x, current_y, width, height, lines, msg["sender"] == "A")
+            current_y += UI["bubble_gap"]
+        
+        # Draw typing indicator if needed
+        if show_typing:
+            typing_y = current_y + 5
+            self._draw_typing_indicator(draw, typing_y)
+        
+        return img
+    
+    def _draw_typing_indicator(self, draw: ImageDraw.Draw, y: int):
+        """Draw typing indicator (●●●)."""
+        x = UI["margin_side"]
+        
+        # Background bubble
+        bubble_width = 70
+        bubble_height = 40
+        draw.rounded_rectangle(
+            [x, y, x + bubble_width, y + bubble_height],
+            radius=15,
+            fill=COLORS["bubble_other"]
+        )
+        
+        # Three dots
+        dot_y = y + bubble_height // 2
+        for i, dx in enumerate([20, 35, 50]):
+            draw.ellipse(
+                [x + dx - 4, dot_y - 4, x + dx + 4, dot_y + 4],
+                fill=COLORS["text_gray"]
+            )
+    
+    def get_ui_height(self, messages: List[dict]) -> int:
+        """Calculate the height of the chat UI for given messages."""
+        message_heights = []
+        visible_messages = messages[-UI["max_visible_messages"]:]
+        
+        for msg in visible_messages:
+            _, height, _ = self._calculate_bubble_size(msg["text"])
+            message_heights.append(height + UI["bubble_gap"])
+        
+        return UI["header_height"] + sum(message_heights) + 20

modules/text_story/services/tts_handler.py

@@ -0,0 +1,134 @@
+"""
+TTS Handler for Text Story module.
+Handles voice generation and audio processing.
+"""
+
+import os
+import logging
+import aiohttp
+from pydub import AudioSegment
+
+logger = logging.getLogger(__name__)
+
+
+class TTSHandler:
+    """
+    Handles Text-to-Speech generation using Kokoro TTS.
+    Also handles silence trimming and duration detection.
+    """
+    
+    def __init__(self):
+        self.tts_url = os.getenv("HF_TTS", "")
+        if not self.tts_url:
+            logger.warning("TTSHandler: HF_TTS not configured, TTS will fail")
+    
+    async def generate_tts(self, text: str, voice: str, output_path: str) -> float:
+        """
+        Generate TTS audio for text.
+        
+        Args:
+            text: Text to speak
+            voice: Kokoro voice ID (e.g., 'af_heart', 'am_fenrir')
+            output_path: Path to save WAV file
+            
+        Returns:
+            Duration in seconds
+        """
+        if not self.tts_url:
+            raise ValueError("HF_TTS environment variable not set")
+        
+        try:
+            async with aiohttp.ClientSession() as session:
+                payload = {
+                    "text": text,
+                    "voice": voice
+                }
+                
+                async with session.post(
+                    f"{self.tts_url}/tts",
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=60)
+                ) as response:
+                    if response.status != 200:
+                        error_text = await response.text()
+                        raise Exception(f"TTS failed: {error_text}")
+                    
+                    audio_data = await response.read()
+                    
+                    # Save raw audio
+                    temp_path = output_path + ".temp.wav"
+                    with open(temp_path, "wb") as f:
+                        f.write(audio_data)
+                    
+                    # Trim silence and get duration
+                    duration = self.trim_silence(temp_path, output_path)
+                    
+                    # Cleanup temp
+                    if os.path.exists(temp_path):
+                        os.remove(temp_path)
+                    
+                    logger.info(f"TTS: Generated {len(text)} chars, {duration:.2f}s")
+                    return duration
+                    
+        except Exception as e:
+            logger.error(f"TTS generation failed: {e}")
+            raise
+    
+    def trim_silence(self, input_path: str, output_path: str, 
+                     silence_thresh: int = -40, min_silence_len: int = 100) -> float:
+        """
+        Trim leading and trailing silence from audio.
+        
+        Args:
+            input_path: Input audio file
+            output_path: Output audio file
+            silence_thresh: Silence threshold in dB
+            min_silence_len: Minimum silence length in ms
+            
+        Returns:
+            Duration of trimmed audio in seconds
+        """
+        try:
+            audio = AudioSegment.from_file(input_path)
+            
+            # Detect non-silent parts
+            from pydub.silence import detect_nonsilent
+            
+            nonsilent_ranges = detect_nonsilent(
+                audio, 
+                min_silence_len=min_silence_len,
+                silence_thresh=silence_thresh
+            )
+            
+            if nonsilent_ranges:
+                # Get start and end of non-silent audio
+                start_ms = max(0, nonsilent_ranges[0][0] - 50)  # Add 50ms padding
+                end_ms = min(len(audio), nonsilent_ranges[-1][1] + 100)  # Add 100ms padding
+                
+                trimmed = audio[start_ms:end_ms]
+            else:
+                # No speech detected, use original
+                trimmed = audio
+            
+            # Export trimmed audio
+            trimmed.export(output_path, format="wav")
+            
+            duration = len(trimmed) / 1000.0  # Convert ms to seconds
+            return duration
+            
+        except Exception as e:
+            logger.error(f"Silence trim failed: {e}")
+            # Fallback: just copy the file
+            import shutil
+            shutil.copy2(input_path, output_path)
+            audio = AudioSegment.from_file(output_path)
+            return len(audio) / 1000.0
+    
+    def get_duration(self, audio_path: str) -> float:
+        """Get duration of audio file in seconds."""
+        try:
+            audio = AudioSegment.from_file(audio_path)
+            return len(audio) / 1000.0
+        except Exception as e:
+            logger.error(f"Failed to get audio duration: {e}")
+            return 2.0  # Default fallback

modules/text_story/services/video_composer.py

@@ -0,0 +1,236 @@
+"""
+Video Composer for Text Story module.
+Assembles final video with realistic timing and effects.
+"""
+
+import os
+import logging
+from typing import List, Dict, Optional
+from moviepy.editor import (
+    VideoFileClip, ImageClip, AudioFileClip, 
+    CompositeVideoClip, concatenate_videoclips,
+    ColorClip, TextClip
+)
+from moviepy.video.fx.all import fadein, fadeout
+import numpy as np
+from PIL import Image
+
+from .renderer import ChatRenderer, CANVAS_WIDTH, CANVAS_HEIGHT
+from .background import BackgroundHandler
+from .tts_handler import TTSHandler
+
+logger = logging.getLogger(__name__)
+
+# Timing configurations (realistic chat behavior)
+TIMING = {
+    "typing_base": 0.5,          # Base typing indicator duration
+    "typing_per_char": 0.008,    # Additional time per character
+    "typing_max": 1.2,           # Max typing duration
+    "human_pause_min": 0.3,      # Minimum pause before message
+    "human_pause_max": 0.8,      # Maximum pause
+    "voice_delay": 0.15,         # Gap between text appear and voice
+    "micro_silence": 0.3,        # Silence between messages
+    "last_msg_pause": 1.5,       # Pause after last message
+    "ending_duration": 3.0,      # Ending text duration
+    "ending_fade": 0.5,          # Ending fade in/out
+}
+
+
+class VideoComposer:
+    """
+    Composes the final text story video.
+    
+    Pipeline:
+    1. Load gameplay background
+    2. For each message:
+       - Show typing indicator
+       - Pop in message bubble
+       - Play TTS audio
+       - Add micro silence
+    3. Add ending text
+    4. Export final video
+    """
+    
+    def __init__(self, 
+                 renderer: ChatRenderer,
+                 bg_handler: BackgroundHandler,
+                 tts_handler: TTSHandler):
+        self.renderer = renderer
+        self.bg_handler = bg_handler
+        self.tts_handler = tts_handler
+    
+    def _calculate_typing_duration(self, text: str) -> float:
+        """Calculate typing indicator duration based on message length."""
+        duration = TIMING["typing_base"] + len(text) * TIMING["typing_per_char"]
+        return min(duration, TIMING["typing_max"])
+    
+    def _calculate_human_pause(self, msg_index: int, total: int) -> float:
+        """Calculate human-like pause before message."""
+        # First message: shorter pause
+        if msg_index == 0:
+            return TIMING["human_pause_min"]
+        
+        # Vary pause based on position
+        import random
+        return random.uniform(TIMING["human_pause_min"], TIMING["human_pause_max"])
+    
+    def _pil_to_moviepy(self, pil_image: Image.Image, duration: float) -> ImageClip:
+        """Convert PIL Image to MoviePy ImageClip."""
+        # Convert to numpy array
+        np_array = np.array(pil_image)
+        
+        # Create ImageClip
+        clip = ImageClip(np_array, duration=duration)
+        
+        return clip
+    
+    async def compose(self, 
+                      messages: List[Dict],
+                      ending_text: Optional[str],
+                      output_dir: str) -> str:
+        """
+        Compose the full text story video.
+        
+        Args:
+            messages: List of {path, duration, sender, text} dicts
+            ending_text: Optional ending text
+            output_dir: Directory for output files
+            
+        Returns:
+            Path to final video file
+        """
+        logger.info(f"VideoComposer: Starting composition with {len(messages)} messages")
+        
+        # Calculate total duration
+        total_duration = 0
+        for i, msg in enumerate(messages):
+            total_duration += self._calculate_typing_duration(msg["text"])
+            total_duration += TIMING["voice_delay"]
+            total_duration += msg["duration"]
+            total_duration += TIMING["micro_silence"]
+        
+        total_duration += TIMING["last_msg_pause"]
+        
+        if ending_text:
+            total_duration += TIMING["ending_duration"]
+        
+        logger.info(f"VideoComposer: Total duration: {total_duration:.1f}s")
+        
+        # Load background
+        background = self.bg_handler.load_and_process(total_duration)
+        
+        # Create message sequence
+        clips = []
+        current_time = 0
+        displayed_messages = []
+        
+        for i, msg in enumerate(messages):
+            msg_dict = {"sender": msg["sender"], "text": msg["text"]}
+            
+            # 1. Typing indicator phase
+            typing_duration = self._calculate_typing_duration(msg["text"])
+            typing_frame = self.renderer.render_frame(displayed_messages, show_typing=True)
+            typing_clip = self._pil_to_moviepy(typing_frame, typing_duration)
+            typing_clip = typing_clip.set_start(current_time)
+            clips.append(typing_clip)
+            current_time += typing_duration
+            
+            # 2. Add message (with voice delay)
+            displayed_messages.append(msg_dict)
+            
+            # Message appears (voice delay gap)
+            msg_frame = self.renderer.render_frame(displayed_messages)
+            voice_delay_clip = self._pil_to_moviepy(msg_frame, TIMING["voice_delay"])
+            voice_delay_clip = voice_delay_clip.set_start(current_time)
+            clips.append(voice_delay_clip)
+            current_time += TIMING["voice_delay"]
+            
+            # 3. Message with audio
+            msg_clip = self._pil_to_moviepy(msg_frame, msg["duration"])
+            msg_clip = msg_clip.set_start(current_time)
+            
+            # Add audio
+            audio = AudioFileClip(msg["path"])
+            msg_clip = msg_clip.set_audio(audio.set_start(0))
+            clips.append(msg_clip)
+            current_time += msg["duration"]
+            
+            # 4. Micro silence
+            silence_clip = self._pil_to_moviepy(msg_frame, TIMING["micro_silence"])
+            silence_clip = silence_clip.set_start(current_time)
+            clips.append(silence_clip)
+            current_time += TIMING["micro_silence"]
+            
+            logger.info(f"VideoComposer: Message {i+1}/{len(messages)} at {current_time:.1f}s")
+        
+        # Last message pause
+        final_frame = self.renderer.render_frame(displayed_messages)
+        pause_clip = self._pil_to_moviepy(final_frame, TIMING["last_msg_pause"])
+        pause_clip = pause_clip.set_start(current_time)
+        clips.append(pause_clip)
+        current_time += TIMING["last_msg_pause"]
+        
+        # Ending text
+        if ending_text:
+            ending_clip = self._create_ending_clip(ending_text, displayed_messages)
+            ending_clip = ending_clip.set_start(current_time)
+            clips.append(ending_clip)
+        
+        # Composite all clips over background
+        final = CompositeVideoClip([background] + clips, size=(CANVAS_WIDTH, CANVAS_HEIGHT))
+        final = final.set_duration(total_duration)
+        
+        # Export
+        output_path = os.path.join(output_dir, "text_story_output.mp4")
+        
+        final.write_videofile(
+            output_path,
+            fps=30,
+            codec="libx264",
+            audio_codec="aac",
+            preset="medium",
+            threads=4,
+            logger=None  # Suppress MoviePy logs
+        )
+        
+        # Cleanup
+        final.close()
+        background.close()
+        for clip in clips:
+            clip.close()
+        
+        logger.info(f"VideoComposer: Saved to {output_path}")
+        return output_path
+    
+    def _create_ending_clip(self, text: str, messages: List[dict]) -> ImageClip:
+        """Create ending text overlay."""
+        # Render current state
+        frame = self.renderer.render_frame(messages)
+        
+        # Add ending text overlay
+        from PIL import ImageDraw, ImageFont
+        draw = ImageDraw.Draw(frame)
+        
+        # Load font
+        try:
+            font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 48)
+        except:
+            font = ImageFont.load_default()
+        
+        # Calculate text position (center bottom area)
+        bbox = font.getbbox(text)
+        text_w = bbox[2] - bbox[0]
+        text_h = bbox[3] - bbox[1]
+        
+        x = (CANVAS_WIDTH - text_w) // 2
+        y = CANVAS_HEIGHT - 300
+        
+        # Draw text with shadow
+        draw.text((x + 2, y + 2), text, fill=(0, 0, 0, 200), font=font)
+        draw.text((x, y), text, fill=(255, 255, 255, 255), font=font)
+        
+        # Convert to clip with fade
+        clip = self._pil_to_moviepy(frame, TIMING["ending_duration"])
+        clip = clip.fx(fadein, TIMING["ending_fade"])
+        
+        return clip

requirements.txt

@@ -29,15 +29,3 @@ imageio-ffmpeg>=0.4.9
 # Trends Analysis
 pytrends
 pandas
-
-# Bar Race Module
-bar_chart_race
-ddgs
-tavily-python
-
-# Deep Researcher (LangGraph)
-langchain-core
-langchain-google-genai>=2.0.0,<2.1.0
-langgraph
-markdownify
-duckduckgo-search

static/index.html

@@ -279,8 +279,8 @@
             <button class="tab-btn" data-tab="quiz">
                 🎯 Quiz Reel
             </button>
-            <button class="tab-btn" data-tab="barrace">
-                📊 Bar Race
+            <button class="tab-btn" data-tab="textstory">
+                📱 Text Story
             </button>
         </div>
 
@@ -646,38 +646,141 @@
         </div>
     </div>
 
-    <!-- Bar Race Tab -->
-    <div id="barrace-tab" class="tab-content">
+    <!-- Text Story Tab -->
+    <div id="textstory-tab" class="tab-content">
         <div class="card">
-            <h2>📊 Bar Chart Race Generator</h2>
+            <h2>📱 Fake Text Story Generator</h2>
             <p style="color: var(--text-secondary); margin-bottom: 1.5rem;">
-                Create animated bar chart race videos showing data over time
+                Create viral iMessage-style fake conversation videos with AI voice
             </p>
 
-            <form id="barRaceForm">
+            <!-- Mode Toggle -->
+            <div class="form-group" style="margin-bottom: 1.5rem;">
+                <label>Mode</label>
+                <div style="display: flex; gap: 1rem;">
+                    <label style="display: flex; align-items: center; gap: 0.5rem; cursor: pointer;">
+                        <input type="radio" name="tsMode" value="manual" checked onchange="toggleTsMode()">
+                        ✍️ Manual
+                    </label>
+                    <label style="display: flex; align-items: center; gap: 0.5rem; cursor: pointer;">
+                        <input type="radio" name="tsMode" value="ai" onchange="toggleTsMode()">
+                        🤖 AI Generate
+                    </label>
+                </div>
+            </div>
+
+            <form id="textStoryForm">
+                <!-- AI Mode Section (Hidden by default) -->
+                <div id="tsAiSection" style="display: none;">
+                    <div class="form-group"
+                        style="background: linear-gradient(135deg, rgba(99,102,241,0.1), rgba(168,85,247,0.1)); padding: 1.5rem; border-radius: 12px; margin-bottom: 1rem;">
+                        <label>🤖 AI Prompt - Describe the conversation</label>
+                        <textarea id="tsAiPrompt" rows="3"
+                            placeholder="e.g., A breakup conversation where the ex wants to get back together but gets rejected. Emotional and dramatic. End with a plot twist."></textarea>
+                        <small style="color: var(--text-secondary); display: block; margin-top: 0.5rem;">
+                            AI will generate a realistic conversation based on your prompt
+                        </small>
+                    </div>
+
+                    <div class="form-row">
+                        <div class="form-group">
+                            <label>Number of Messages</label>
+                            <select id="tsAiMsgCount">
+                                <option value="5">5 messages</option>
+                                <option value="7" selected>7 messages</option>
+                                <option value="10">10 messages</option>
+                                <option value="15">15 messages</option>
+                            </select>
+                        </div>
+                        <div class="form-group">
+                            <label>Conversation Tone</label>
+                            <select id="tsAiTone">
+                                <option value="emotional">Emotional / Dramatic</option>
+                                <option value="funny">Funny / Comedy</option>
+                                <option value="shocking">Shocking / Twist</option>
+                                <option value="romantic">Romantic</option>
+                                <option value="angry">Angry / Fight</option>
+                            </select>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Common Fields -->
+                <div class="form-row">
+                    <div class="form-group">
+                        <label>Person A Name (You - Right/Blue)</label>
+                        <input type="text" id="tsPersonA" value="You" placeholder="Your name">
+                    </div>
+                    <div class="form-group">
+                        <label>Person B Name (Other - Left/Gray)</label>
+                        <input type="text" id="tsPersonB" value="My Ex" placeholder="Other person name">
+                    </div>
+                </div>
+
                 <div class="form-group">
-                    <label>Topic / Prompt *</label>
-                    <input type="text" id="barRaceTopic" placeholder="e.g., Top 10 richest countries by GDP 2000-2024"
-                        required>
-                    <small style="color: var(--text-secondary); display: block; margin-top: 0.5rem;">
-                        Enter any topic - the AI will find data and create the video
-                    </small>
+                    <label>Person B Avatar (1 letter or emoji)</label>
+                    <input type="text" id="tsAvatar" maxlength="2" placeholder="M" style="width: 80px;">
+                </div>
+
+                <!-- Manual Mode Section -->
+                <div id="tsManualSection">
+                    <div id="tsMessagesContainer">
+                        <div class="ts-message-item"
+                            style="background: var(--bg-secondary); padding: 1rem; border-radius: 8px; margin-bottom: 0.5rem;">
+                            <div class="form-row" style="align-items: flex-end;">
+                                <div class="form-group" style="flex: 0 0 100px;">
+                                    <label>Sender</label>
+                                    <select class="ts-sender">
+                                        <option value="B">B (Other)</option>
+                                        <option value="A">A (You)</option>
+                                    </select>
+                                </div>
+                                <div class="form-group" style="flex: 1;">
+                                    <label>Message</label>
+                                    <input type="text" class="ts-text" placeholder="Type message...">
+                                </div>
+                                <button type="button" class="btn btn-secondary ts-remove"
+                                    style="height: 42px;">✕</button>
+                            </div>
+                        </div>
+                    </div>
+
+                    <button type="button" id="tsAddMessage" class="btn btn-secondary"
+                        style="width: 100%; margin-bottom: 1rem;">
+                        ➕ Add Message
+                    </button>
                 </div>
 
                 <div class="form-group">
-                    <label>Duration</label>
-                    <select id="barRaceDuration">
-                        <option value="30">30 seconds</option>
-                        <option value="60" selected>60 seconds</option>
-                        <option value="90">90 seconds</option>
-                        <option value="120">120 seconds</option>
-                    </select>
+                    <label>Ending Text (Optional)</label>
+                    <input type="text" id="tsEnding" placeholder="e.g., To be continued...">
+                </div>
+
+                <div class="form-row">
+                    <div class="form-group">
+                        <label>Voice A (You)</label>
+                        <select id="tsVoiceA">
+                            <option value="af_heart">Female - Heart</option>
+                            <option value="af_bella">Female - Bella</option>
+                            <option value="am_fenrir">Male - Fenrir</option>
+                            <option value="am_michael">Male - Michael</option>
+                        </select>
+                    </div>
+                    <div class="form-group">
+                        <label>Voice B (Other)</label>
+                        <select id="tsVoiceB">
+                            <option value="am_fenrir">Male - Fenrir</option>
+                            <option value="am_michael">Male - Michael</option>
+                            <option value="af_heart">Female - Heart</option>
+                            <option value="af_bella">Female - Bella</option>
+                        </select>
+                    </div>
                 </div>
 
-                <button type="submit" class="btn btn-primary" style="width: 100%;">📊 Generate Bar Race Video</button>
+                <button type="submit" class="btn btn-primary" style="width: 100%;">📱 Generate Text Story Video</button>
             </form>
 
-            <div id="barRaceStatus" class="status hidden"></div>
+            <div id="textStoryStatus" class="status hidden"></div>
         </div>
     </div>
 
@@ -1205,59 +1308,172 @@
             }
         }, 100);  // End of setTimeout
 
-        // Bar Race Form
-        document.getElementById('barRaceForm').addEventListener('submit', async (e) => {
+        // ==========================================
+        // TEXT STORY MODULE
+        // ==========================================
+
+        // Add message row
+        document.getElementById('tsAddMessage').addEventListener('click', () => {
+            const container = document.getElementById('tsMessagesContainer');
+            const count = container.querySelectorAll('.ts-message-item').length + 1;
+            const html = `
+                <div class="ts-message-item" style="background: var(--bg-secondary); padding: 1rem; border-radius: 8px; margin-bottom: 0.5rem;">
+                    <div class="form-row" style="align-items: flex-end;">
+                        <div class="form-group" style="flex: 0 0 100px;">
+                            <label>Sender</label>
+                            <select class="ts-sender">
+                                <option value="B">B (Other)</option>
+                                <option value="A">A (You)</option>
+                            </select>
+                        </div>
+                        <div class="form-group" style="flex: 1;">
+                            <label>Message ${count}</label>
+                            <input type="text" class="ts-text" placeholder="Type message..." required>
+                        </div>
+                        <button type="button" class="btn btn-secondary ts-remove" style="height: 42px;">✕</button>
+                    </div>
+                </div>
+            `;
+            container.insertAdjacentHTML('beforeend', html);
+        });
+
+        // Remove message row
+        document.getElementById('tsMessagesContainer').addEventListener('click', (e) => {
+            if (e.target.classList.contains('ts-remove')) {
+                const items = document.querySelectorAll('.ts-message-item');
+                if (items.length > 1) {
+                    e.target.closest('.ts-message-item').remove();
+                }
+            }
+        });
+
+        // Toggle Manual/AI mode
+        function toggleTsMode() {
+            const mode = document.querySelector('input[name="tsMode"]:checked').value;
+            document.getElementById('tsAiSection').style.display = mode === 'ai' ? 'block' : 'none';
+            document.getElementById('tsManualSection').style.display = mode === 'manual' ? 'block' : 'none';
+        }
+
+        // Form submit
+        document.getElementById('textStoryForm').addEventListener('submit', async (e) => {
             e.preventDefault();
-            const status = document.getElementById('barRaceStatus');
+            const status = document.getElementById('textStoryStatus');
             status.className = 'status processing';
-            status.innerHTML = '⏳ Starting bar race generation...';
+            status.classList.remove('hidden');
 
-            const topic = document.getElementById('barRaceTopic').value;
-            const duration = parseInt(document.getElementById('barRaceDuration').value);
+            const mode = document.querySelector('input[name="tsMode"]:checked').value;
+            let messages = [];
+
+            if (mode === 'ai') {
+                // AI Mode - Generate conversation first
+                const prompt = document.getElementById('tsAiPrompt').value.trim();
+                if (!prompt) {
+                    status.className = 'status error';
+                    status.innerHTML = '❌ Please enter a prompt for AI!';
+                    return;
+                }
+
+                status.innerHTML = '🤖 AI generating conversation...';
+
+                try {
+                    const aiRes = await fetch('/api/text-story/ai-generate', {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            prompt: prompt,
+                            person_a_name: document.getElementById('tsPersonA').value || 'You',
+                            person_b_name: document.getElementById('tsPersonB').value || 'My Ex',
+                            message_count: parseInt(document.getElementById('tsAiMsgCount').value),
+                            tone: document.getElementById('tsAiTone').value
+                        })
+                    });
+                    const aiData = await aiRes.json();
+
+                    if (aiData.messages) {
+                        messages = aiData.messages;
+                        status.innerHTML = `🤖 Generated ${messages.length} messages. Now creating video...`;
+                    } else {
+                        status.className = 'status error';
+                        status.innerHTML = '❌ AI failed: ' + (aiData.detail || 'Unknown error');
+                        return;
+                    }
+                } catch (err) {
+                    status.className = 'status error';
+                    status.innerHTML = '❌ AI Error: ' + err.message;
+                    return;
+                }
+            } else {
+                // Manual Mode - Collect messages from form
+                const messageItems = document.querySelectorAll('.ts-message-item');
+                messageItems.forEach(item => {
+                    const sender = item.querySelector('.ts-sender').value;
+                    const text = item.querySelector('.ts-text').value.trim();
+                    if (text) {
+                        messages.push({ sender, text });
+                    }
+                });
+
+                if (messages.length < 2) {
+                    status.className = 'status error';
+                    status.innerHTML = '❌ Need at least 2 messages!';
+                    return;
+                }
+            }
+
+            status.innerHTML = '⏳ Starting video generation...';
+
+            const data = {
+                person_a_name: document.getElementById('tsPersonA').value || 'You',
+                person_b_name: document.getElementById('tsPersonB').value || 'My Ex',
+                person_b_avatar: document.getElementById('tsAvatar').value || null,
+                messages: messages,
+                ending_text: document.getElementById('tsEnding').value || null,
+                voice_a: document.getElementById('tsVoiceA').value,
+                voice_b: document.getElementById('tsVoiceB').value
+            };
 
             try {
-                const response = await fetch('/api/bar-race/generate', {
+                const res = await fetch('/api/text-story/generate', {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({
-                        topic: topic,
-                        duration_seconds: duration
-                    })
+                    body: JSON.stringify(data)
                 });
+                const result = await res.json();
 
-                const data = await response.json();
-                if (!response.ok) throw new Error(data.detail || 'Failed to start');
-
-                status.innerHTML = `⏳ Job started: ${data.job_id}. Analyzing topic...`;
-                pollBarRaceStatus(data.job_id);
-
+                if (result.job_id) {
+                    status.innerHTML = `⏳ Job started: ${result.job_id}`;
+                    pollTextStoryStatus(result.job_id);
+                } else {
+                    status.className = 'status error';
+                    status.innerHTML = `❌ Error: ${result.detail || 'Failed to start'}`;
+                }
             } catch (err) {
                 status.className = 'status error';
-                status.innerHTML = '❌ ' + err.message;
+                status.innerHTML = '❌ Error: ' + err.message;
             }
         });
 
-        async function pollBarRaceStatus(jobId) {
-            const status = document.getElementById('barRaceStatus');
+        // Poll status
+        async function pollTextStoryStatus(jobId) {
+            const status = document.getElementById('textStoryStatus');
             const poll = async () => {
                 try {
-                    const res = await fetch(`/api/bar-race/${jobId}/status`);
+                    const res = await fetch(`/api/text-story/${jobId}/status`);
                     const data = await res.json();
 
                     if (data.status === 'ready') {
                         status.className = 'status success';
-                        status.innerHTML = `✅ Video ready! <a href="${data.video_url}" target="_blank" style="color:#4ade80;">Download Video</a>`;
+                        status.innerHTML = `✅ Video ready! <a href="${data.video_url}" target="_blank" class="btn btn-primary" style="margin-left: 1rem;">📥 Download</a>`;
                     } else if (data.status === 'failed') {
                         status.className = 'status error';
                         status.innerHTML = '❌ Failed: ' + (data.error || 'Unknown error');
                     } else {
-                        const step = data.current_step || data.status;
+                        const step = data.current_step || 'Processing';
                         status.innerHTML = `⏳ ${step} (${data.progress}%)`;
                         setTimeout(poll, 2000);
                     }
                 } catch (err) {
-                    status.className = 'status error';
-                    status.innerHTML = '❌ Status check failed: ' + err.message;
+                    setTimeout(poll, 3000);
                 }
             };
             poll();