Add initial implementation of Excel Analyst Agent with Gradio interface

- Created .gitignore to exclude unnecessary files and directories.
- Implemented main application logic in app.py for processing Excel and CSV files.
- Added requirements.txt for necessary dependencies.
- Developed multi-agent system in app_agents for data analysis using OpenAI Agents SDK.
- Included tools for executing Python code and web searching.
- Established logging and error handling throughout the application.
- Provided user interface for file upload and query input with results display.

.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

app.py

@@ -0,0 +1,281 @@
+"""
+Excel Analyst Agent - Gradio Application
+Main entry point for the web interface
+"""
+
+import os
+import logging
+import base64
+from io import BytesIO
+from typing import Optional, Tuple, List
+import gradio as gr
+import pandas as pd
+from PIL import Image
+from dotenv import load_dotenv
+from app_agents.master_agent import MasterAgent
+
+# Load environment variables
+load_dotenv()
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Get OpenAI API key
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+if not OPENAI_API_KEY:
+    logger.warning("OPENAI_API_KEY not found in environment variables")
+
+
+def process_analysis(
+    file: Optional[gr.File],
+    query: str,
+    api_key: Optional[str] = None
+) -> Tuple[str, Optional[pd.DataFrame], Optional[List[Image.Image]]]:
+    """
+    Process the user's file and query
+    
+    Args:
+        file: Uploaded file object
+        query: User's natural language query
+        api_key: Optional API key override
+        
+    Returns:
+        Tuple of (output_text, dataframe, images)
+    """
+    try:
+        # Validate inputs
+        if not file:
+            return "❌ Please upload an Excel (.xlsx) or CSV (.csv) file.", None, None
+        
+        if not query or query.strip() == "":
+            return "❌ Please enter a query describing what you want to analyze.", None, None
+        
+        # Get API key
+        used_api_key = api_key if api_key else OPENAI_API_KEY
+        # Log presence (masked) of API key from UI/env for diagnostics
+        if api_key:
+            masked = f"{api_key[:4]}...{api_key[-4:]}" if len(api_key) >= 8 else "***"
+            logger.info(f"API key provided via UI: True (masked: {masked})")
+        else:
+            logger.info(f"API key provided via UI: False")
+            if OPENAI_API_KEY:
+                masked_env = f"{OPENAI_API_KEY[:4]}...{OPENAI_API_KEY[-4:]}" if len(OPENAI_API_KEY) >= 8 else "***"
+                logger.info(f"Using OPENAI_API_KEY from env: True (masked: {masked_env})")
+            else:
+                logger.info("Using OPENAI_API_KEY from env: False")
+        if not used_api_key:
+            return "❌ Please provide an OpenAI API key either in the interface or as an environment variable (OPENAI_API_KEY).", None, None
+        
+        # Get file path
+        file_path = file.name
+        logger.info(f"Processing file: {file_path}")
+        logger.info(f"User query: {query}")
+        
+        # Validate file extension
+        if not (file_path.endswith('.xlsx') or file_path.endswith('.csv')):
+            return "❌ Please upload a valid Excel (.xlsx) or CSV (.csv) file.", None, None
+        
+        # Initialize the master agent
+        logger.info("Initializing Master Agent...")
+        agent = MasterAgent(api_key=used_api_key, model="gpt-4o-mini")
+        
+        # Analyze the file
+        logger.info("Starting analysis...")
+        result = agent.analyze(user_query=query, file_path=file_path)
+        
+        if not result['success']:
+            error_msg = result.get('error', 'Unknown error occurred')
+            return f"❌ Analysis failed:\n\n{error_msg}", None, None
+        
+        # Format output
+        output_parts = ["✅ **Analysis Complete**\n"]
+        
+        # Add text output
+        if result['output']:
+            output_parts.append("### Results:\n")
+            output_parts.append(result['output'])
+            output_parts.append("\n")
+        
+        # Add code if available
+        if result['code']:
+            output_parts.append("\n### Generated Code:\n")
+            output_parts.append("```python\n")
+            output_parts.append(result['code'])
+            output_parts.append("\n```\n")
+        
+        output_text = "\n".join(output_parts)
+        
+        # Prepare dataframe
+        df_output = None
+        if result['dataframe']:
+            try:
+                df_output = pd.DataFrame(result['dataframe'])
+                logger.info(f"Dataframe prepared: {len(df_output)} rows")
+            except Exception as e:
+                logger.error(f"Error preparing dataframe: {e}")
+                output_text += f"\n\n⚠️ Note: Could not display dataframe - {str(e)}"
+        
+        # Prepare images
+        images_output = None
+        if result['images']:
+            try:
+                images_output = []
+                for img_base64 in result['images']:
+                    img_data = base64.b64decode(img_base64)
+                    img = Image.open(BytesIO(img_data))
+                    images_output.append(img)
+                logger.info(f"Prepared {len(images_output)} images")
+            except Exception as e:
+                logger.error(f"Error preparing images: {e}")
+                output_text += f"\n\n⚠️ Note: Could not display images - {str(e)}"
+        
+        return output_text, df_output, images_output
+        
+    except Exception as e:
+        error_msg = f"Unexpected error: {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return f"❌ {error_msg}", None, None
+
+
+def create_interface() -> gr.Blocks:
+    """
+    Create the Gradio interface
+    
+    Returns:
+        Gradio Blocks interface
+    """
+    with gr.Blocks(
+        title="Excel Analyst Agent",
+        theme=gr.themes.Soft()
+    ) as interface:
+        
+        gr.Markdown(
+            """
+            # 📊 Excel Analyst Agent
+            
+            **Intelligent data analysis powered by AI**
+            
+            Upload your Excel or CSV file and describe what you want to analyze in plain English.
+            The agent will generate and execute Python code to fulfill your request.
+            
+            ### Features:
+            - 📈 Data analysis and statistics
+            - 📊 Automatic visualizations
+            - 🔍 Natural language queries
+            - 🤖 Powered by OpenAI GPT-4o-mini
+            
+            ### Example queries:
+            - *"Show me the average sales per region and create a bar chart"*
+            - *"Find the top 10 customers by revenue"*
+            - *"Calculate monthly trends and visualize them"*
+            - *"Identify outliers in the price column"*
+            """
+        )
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("### 📁 Input")
+                
+                file_input = gr.File(
+                    label="Upload Excel or CSV file",
+                    file_types=[".xlsx", ".csv"],
+                    type="filepath"
+                )
+                
+                query_input = gr.Textbox(
+                    label="What would you like to analyze?",
+                    placeholder="E.g., Show me the average sales per region and create a bar chart",
+                    lines=3
+                )
+                
+                api_key_input = gr.Textbox(
+                    label="OpenAI API Key (optional if set in environment)",
+                    placeholder="sk-...",
+                    type="password"
+                )
+                
+                with gr.Row():
+                    submit_btn = gr.Button("🚀 Analyze", variant="primary", size="lg")
+                    clear_btn = gr.ClearButton(
+                        components=[file_input, query_input, api_key_input],
+                        value="🔄 Clear"
+                    )
+            
+            with gr.Column(scale=2):
+                gr.Markdown("### 📊 Results")
+                
+                output_text = gr.Markdown(
+                    label="Analysis Output",
+                    value="Results will appear here..."
+                )
+                
+                output_dataframe = gr.Dataframe(
+                    label="Data Preview",
+                    interactive=False,
+                    wrap=True
+                )
+                
+                output_images = gr.Gallery(
+                    label="Visualizations",
+                    columns=2,
+                    height="auto"
+                )
+        
+        gr.Markdown(
+            """
+            ---
+            ### 💡 Tips:
+            - Be specific in your queries for better results
+            - The agent can create multiple visualizations in one request
+            - If something doesn't work, try rephrasing your query
+            - All processing is done securely in a sandboxed environment
+            
+            ### 🔒 Privacy:
+            - Your files are processed temporarily and not stored
+            - Code execution is sandboxed without internet access
+            - Only you and OpenAI's API see your data
+            """
+        )
+        
+        # Connect the submit button
+        submit_btn.click(
+            fn=process_analysis,
+            inputs=[file_input, query_input, api_key_input],
+            outputs=[output_text, output_dataframe, output_images]
+        )
+        
+        # Also allow Enter key to submit
+        query_input.submit(
+            fn=process_analysis,
+            inputs=[file_input, query_input, api_key_input],
+            outputs=[output_text, output_dataframe, output_images]
+        )
+    
+    return interface
+
+
+def main():
+    """
+    Main entry point
+    """
+    logger.info("Starting Excel Analyst Agent application...")
+    
+    # Create and launch the interface
+    interface = create_interface()
+    
+    interface.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )
+
+
+if __name__ == "__main__":
+    main()
+
+

app_agents/__init__.py

@@ -0,0 +1,8 @@
+"""
+Excel Analyst Agents (renamed package)
+Multi-agent system for Excel data analysis using OpenAI Agents SDK
+"""
+
+__version__ = "1.1.0"
+
+

app_agents/excel_agent.py

@@ -0,0 +1,113 @@
+"""
+Excel Analysis Agent - MCP client using Agents SDK
+"""
+
+import logging
+
+from agents import Agent
+from agents.mcp import MCPServerStdio, create_static_tool_filter
+from agents.model_settings import ModelSettings
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+EXCEL_ANALYSIS_INSTRUCTIONS = """You are an expert Excel Data Analyst Agent specialized in analyzing and visualizing data from Excel and CSV files.
+
+IMPORTANT: You MUST use the MCP tool execute_python_code(code, file_path) to run Python code. Do NOT just explain the code — EXECUTE it via the tool.
+
+Your capabilities:
+1. Read and analyze Excel (.xlsx) and CSV files using pandas
+2. Perform data manipulation, aggregation, and statistical analysis
+3. Create visualizations using matplotlib and seaborn
+4. Generate clear, actionable insights from data
+5. Write clean, efficient Python code
+
+Available Actions:
+- execute_python_code(code, file_path): Execute Python for data analysis. The file path is provided in user messages.
+
+Guidelines:
+- YOU MUST CALL execute_python_code — never just describe code
+- Always read the file first using: pd.read_excel(file_path) or pd.read_csv(file_path)
+- Store the main dataframe in a variable named 'df' (or 'result')
+- CRITICAL: Always use print() to display results and data to the user
+- For dataframes: use print(df.head(10)) or print(df)
+- For statistics: use print(df.describe()) or print(<metric>)
+- Create clear, well-labeled visualizations; do not call plt.show() (figures are captured automatically)
+
+IMPORTANT OUTPUT FORMATTING:
+After calling execute_python_code, the tool returns a result with structure: {'success': bool, 'output': str, 'error': str, 'dataframe': list, 'images': list}
+- Your final response MUST be the complete JSON object returned by the execute_python_code tool
+- Return it exactly as received, including all fields: 'success', 'output', 'error', 'dataframe', and 'images'
+- This allows the orchestrator to properly extract dataframe and images from your response
+
+
+Code Examples:
+
+Example 1: Show first N rows
+```python
+import pandas as pd
+
+df = pd.read_excel(file_path)
+print("First 10 rows:")
+print(df.head(10))
+```
+
+Example 2: Calculate statistics (average of a column)
+```python
+import pandas as pd
+
+df = pd.read_excel(file_path)
+average_sales = df['Sales'].mean()
+print(f"Average Sales: {average_sales:.2f}")
+
+avg_by_category = df.groupby('Category')['Sales'].mean()
+print("\nAverage Sales by Category:")
+print(avg_by_category)
+```
+
+Example 3: Create a visualization
+```python
+import pandas as pd
+import matplotlib.pyplot as plt
+
+df = pd.read_excel(file_path)
+country_counts = df['Country'].value_counts()
+plt.figure(figsize=(10, 8))
+plt.pie(country_counts, labels=country_counts.index, autopct='%1.1f%%', startangle=90)
+plt.title('Distribution by Country')
+plt.axis('equal')
+# Do not call plt.show()
+```
+
+Example 4: Calculate median of a column
+```python
+import pandas as pd
+
+df = pd.read_excel(file_path)
+median_price = df['Sale Price'].median()
+print(f"Median Sale Price: {median_price:.2f}")
+```
+"""
+
+
+def create_excel_agent(mcp_server: MCPServerStdio, model: str = "gpt-4o-mini") -> Agent:
+    """
+    Create an Agent SDK for Excel analysis
+    
+    Args:
+        mcp_server: MCP server already configured with execute_python_code tool filter
+        model: OpenAI model to use
+    
+    Returns:
+        Agent configured for Excel analysis
+    """
+    return Agent(
+        name="ExcelAnalysisAgent",
+        instructions=EXCEL_ANALYSIS_INSTRUCTIONS,
+        mcp_servers=[mcp_server],
+        model=model,
+    )
+
+

app_agents/master_agent.py

@@ -0,0 +1,179 @@
+"""
+Master Agent - coordinates ExcelAnalysisAgent and WebSearchAgent as tools
+"""
+
+import logging
+import os
+import asyncio
+import json
+from typing import Dict, Any, Optional
+
+from agents import Agent, Runner
+from agents.mcp import MCPServerStdio, create_static_tool_filter
+
+from .excel_agent import create_excel_agent
+from .web_agent import create_web_search_agent
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+MASTER_AGENT_PROMPT = """
+You are the orchestrator of a multi-agent system. Your task is to take the user's query and the file path and pass it to the appropriate agent tool.
+
+Available agent tools:
+- excel_analysis_agent: Executes Python code for data analysis and visualization using pandas and matplotlib. 
+  When calling this tool, you MUST pass the complete user query and the file path so it can execute the correct analysis.
+- web_search_agent: Searches the web for documentation, examples, and solutions.
+
+Your strategy:
+1. First, try to use the excel_analysis_agent to directly answer the user's query using the file path.
+   IMPORTANT: When calling excel_analysis_agent, include the FULL user query in your message to the tool.
+2. If the analysis fails or needs additional context, use the web_search_agent to find relevant information.
+3. Use the web search results to guide a retry with the excel_analysis_agent.
+
+Always provide clear, actionable results to the user.
+"""
+
+
+class MasterAgent:
+    """
+    Master agent that coordinates ExcelAnalysisAgent and WebSearchAgent as tools.
+    """
+
+    def __init__(self, api_key: str, model: str = "gpt-4o-mini"):
+        if api_key:
+            os.environ["OPENAI_API_KEY"] = api_key
+        self.model = model
+
+    def analyze(self, user_query: str, file_path: str) -> Dict[str, Any]:
+        """
+        Coordinate the two agents to get the best possible result
+        """
+        async def _arun():
+            # Create MCP servers
+            python_server = MCPServerStdio(
+                name="excel-tools-python",
+                params={"command": "python", "args": ["-m", "app_agents.mcp_server"]},
+                cache_tools_list=True,
+                use_structured_content=True,
+                tool_filter=create_static_tool_filter(allowed_tool_names=["execute_python_code"]),
+            )
+            
+            web_server = MCPServerStdio(
+                name="excel-tools-web",
+                params={"command": "python", "args": ["-m", "app_agents.mcp_server"]},
+                cache_tools_list=True,
+                tool_filter=create_static_tool_filter(allowed_tool_names=["search_web"]),
+            )
+            
+            # Connect servers
+            await python_server.connect()
+            await web_server.connect()
+            
+            try:
+                # Create specialized agents using functions from their respective modules
+                excel_agent = create_excel_agent(mcp_server=python_server, model=self.model)
+                web_agent = create_web_search_agent(mcp_server=web_server, model=self.model)
+                
+                # Create orchestrator agent with other agents as tools
+                orchestrator = Agent(
+                    name="MasterAgent",
+                    model=self.model,
+                    instructions=MASTER_AGENT_PROMPT,
+                    tools=[
+                        excel_agent.as_tool(
+                            tool_name="excel_analysis_agent",
+                            tool_description="Execute Python code to analyze Excel/CSV files and create visualizations. The agent receives the user query and file path and must execute the exact analysis requested."
+                        ),
+                        web_agent.as_tool(
+                            tool_name="web_search_agent",
+                            tool_description="Search the web for up-to-date information, documentation, and code examples"
+                        ),
+                    ],
+                )
+                
+                # Prepare user message with file path
+                user_msg = (
+                    f"User query: {user_query}\n"
+                    f"File path: {file_path}\n\n"
+                    f"Call the excel_analysis_agent tool with this exact message:\n"
+                    f"'Analyze this request: {user_query}\\n\\nThe file is located at: {file_path}\\n\\n"
+                    f"Write Python code and call execute_python_code with that code and the same file_path.'\n\n"
+                    f"Make sure to pass the complete user query to the excel_analysis_agent so it can perform the correct analysis."
+                )
+                
+                # Run orchestrator
+                result = await Runner.run(orchestrator, user_msg, max_turns=20)
+                
+                return result
+            finally:
+                # Clean up servers
+                for server in [python_server, web_server]:
+                    close_fn = getattr(server, "close", None) or getattr(server, "aclose", None)
+                    if close_fn:
+                        res = close_fn()
+                        if hasattr(res, "__await__"):
+                            await res
+
+        try:
+            loop = asyncio.new_event_loop()
+            try:
+                asyncio.set_event_loop(loop)
+                result = loop.run_until_complete(_arun())
+            finally:
+                loop.close()
+                asyncio.set_event_loop(None)
+
+            raw_output = result.final_output or ""
+            
+            # Extract dataframe and images from tool output
+            extracted_df = None
+            extracted_images = []
+            final_text = raw_output
+            
+            # Extract from result.new_items - Item 1 (ToolCallOutputItem) contains the JSON
+            for item in result.new_items:
+                if hasattr(item, 'output') and isinstance(item.output, str):
+                    # Extract JSON from markdown code blocks if present
+                    json_str = item.output
+                    if "```json" in item.output:
+                        parts = item.output.split("```json")
+                        if len(parts) > 1:
+                            json_str = parts[1].split("```")[0].strip()
+                    
+                    try:
+                        tool_result = json.loads(json_str)
+                        if isinstance(tool_result, dict) and "success" in tool_result:
+                            # Extract dataframe and images from tool result
+                            if isinstance(tool_result.get("dataframe"), list) and tool_result.get("dataframe"):
+                                extracted_df = tool_result.get("dataframe")
+                            if isinstance(tool_result.get("images"), list) and tool_result.get("images"):
+                                extracted_images = tool_result.get("images")
+                            break  # Found the JSON, no need to continue
+                    except (json.JSONDecodeError, ValueError):
+                        continue
+
+            return {
+                'success': True,
+                'output': final_text,
+                'dataframe': extracted_df,
+                'images': extracted_images,
+                'code': None,
+                'error': None
+            }
+
+        except Exception as e:
+            err = f"MasterAgent error: {e}"
+            logger.error(err)
+            return {
+                "success": False,
+                "output": None,
+                "dataframe": None,
+                "images": [],
+                "code": None,
+                "error": err,
+            }
+
+

app_agents/mcp_server.py

@@ -0,0 +1,43 @@
+"""
+MCP stdio server exposing execute_python_code and search_web tools (FastMCP)
+"""
+
+from fastmcp import FastMCP
+
+
+mcp = FastMCP("excel-tools")
+
+# Lazy singletons to avoid heavy imports at startup
+_python_tool = None
+_web_tool = None
+
+
+@mcp.tool
+def execute_python_code(code: str, file_path: str) -> str:
+    """Execute Python code and return results as JSON string to avoid MCP serialization issues"""
+    import json
+    global _python_tool
+    if _python_tool is None:
+        from app_agents.tools.python_tool import PythonSandboxTool
+        _python_tool = PythonSandboxTool(timeout=30)
+    result = _python_tool.execute(code=code, file_path=file_path)
+    return json.dumps(result, ensure_ascii=False)
+
+
+@mcp.tool
+def search_web(query: str) -> str:
+    global _web_tool
+    if _web_tool is None:
+        from app_agents.tools.web_search_tool import WebSearchTool
+        _web_tool = WebSearchTool(max_results=5)
+    res = _web_tool.search(query)
+    if res.get("success"):
+        return _web_tool.format_results(res["results"])
+    return f"Search failed: {res.get('error', 'Unknown error')}"
+
+
+if __name__ == "__main__":
+    # stdio is the default; we specify it explicitly for clarity
+    mcp.run(transport="stdio")
+
+

app_agents/tools/__init__.py

@@ -0,0 +1,11 @@
+"""
+Tools package for Excel Analyst Agent
+Contains Python sandbox and web search tools
+"""
+
+from .python_tool import PythonSandboxTool
+from .web_search_tool import WebSearchTool
+
+__all__ = ["PythonSandboxTool", "WebSearchTool"]
+
+

app_agents/tools/python_tool.py

@@ -0,0 +1,418 @@
+"""
+Python Sandbox Tool for safe code execution
+Uses standard exec() with AST validation and namespace control
+"""
+
+import io
+import sys
+import base64
+import logging
+import ast
+from typing import Dict, Any, Optional, Set
+from contextlib import redirect_stdout, redirect_stderr
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
+import pandas as pd
+import numpy as np
+import matplotlib
+matplotlib.use('Agg')  # Non-interactive backend
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class TimeoutException(Exception):
+    """Exception raised when code execution times out"""
+    pass
+
+
+class CodeValidator(ast.NodeVisitor):
+    """
+    AST validator to block dangerous operations
+    """
+    
+    # Dangerous functions/modules to block
+    BLOCKED_NAMES: Set[str] = {
+        'eval', 'exec', 'compile',
+        'open', 'file', 'input', 'raw_input',
+        'execfile', 'reload', 'breakpoint',
+        'exit', 'quit', 'help',
+    }
+    
+    # Dangerous modules to block
+    BLOCKED_MODULES: Set[str] = {
+        'os', 'sys', 'subprocess', 'socket', 'urllib',
+        'requests', 'http', 'ftplib', 'telnetlib',
+        'pickle', 'shelve', 'marshal', 'importlib',
+    }
+    
+    def __init__(self):
+        self.errors = []
+    
+    def visit_Import(self, node):
+        """Check import statements"""
+        for alias in node.names:
+            module_name = alias.name.split('.')[0]
+            if module_name in self.BLOCKED_MODULES:
+                self.errors.append(f"Import of '{alias.name}' is not allowed")
+        self.generic_visit(node)
+    
+    def visit_ImportFrom(self, node):
+        """Check from-import statements"""
+        if node.module:
+            module_name = node.module.split('.')[0]
+            if module_name in self.BLOCKED_MODULES:
+                self.errors.append(f"Import from '{node.module}' is not allowed")
+        self.generic_visit(node)
+    
+    def visit_Name(self, node):
+        """Check for blocked names"""
+        if node.id in self.BLOCKED_NAMES:
+            self.errors.append(f"Use of '{node.id}' is not allowed")
+        self.generic_visit(node)
+    
+    def visit_Attribute(self, node):
+        """Check for dangerous attribute access"""
+        # Block access to __builtins__, __globals__, etc.
+        if isinstance(node.attr, str) and node.attr.startswith('__') and node.attr.endswith('__'):
+            if node.attr not in {'__init__', '__str__', '__repr__'}:
+                self.errors.append(f"Access to '{node.attr}' is not allowed")
+        self.generic_visit(node)
+
+
+class PythonSandboxTool:
+    """
+    Safe Python code execution sandbox with restricted access
+    """
+    
+    def __init__(self, timeout: int = 30):
+        """
+        Initialize the sandbox tool
+        
+        Args:
+            timeout: Maximum execution time in seconds (default: 30)
+        """
+        self.timeout = timeout
+        self.allowed_modules = {
+            'pd': pd,
+            'pandas': pd,
+            'np': np,
+            'numpy': np,
+            'plt': plt,
+            'matplotlib': matplotlib,
+            'sns': sns,
+            'seaborn': sns,
+        }
+    
+    def _safe_import(self, name, globals=None, locals=None, fromlist=(), level=0):
+        """
+        Custom import function that uses pre-loaded modules
+        
+        Args:
+            name: Module name to import
+            globals: Global namespace (ignored)
+            locals: Local namespace (ignored)
+            fromlist: Names to import from module
+            level: Relative import level
+            
+        Returns:
+            Pre-loaded module object if allowed
+            
+        Raises:
+            ImportError: If module is not allowed
+        """
+        # Map import names to allowed modules
+        allowed = {
+            'pandas': pd,
+            'numpy': np,
+            'matplotlib': matplotlib,
+            'seaborn': sns,
+        }
+        
+        # Return pre-loaded module if allowed
+        if name in allowed:
+            return allowed[name]
+        
+        # Handle matplotlib sub-modules (e.g., matplotlib.pyplot)
+        if name.startswith('matplotlib.'):
+            # Return the base matplotlib module
+            # Python will then access the sub-module as an attribute
+            return matplotlib
+        
+        # Check if it's a blocked module
+        if name.split('.')[0] in CodeValidator.BLOCKED_MODULES:
+            raise ImportError(f"Import of '{name}' is not allowed for security reasons")
+        
+        # For any other module not specifically allowed, raise error
+        raise ImportError(f"Cannot import '{name}'. Only pandas, numpy, matplotlib, and seaborn are allowed.")
+    
+    def _create_safe_globals(self, file_path: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Create a safe globals dictionary with whitelisted modules
+        
+        Args:
+            file_path: Path to the uploaded Excel/CSV file
+            
+        Returns:
+            Dictionary of safe globals
+        """
+        # Create a limited builtins dictionary
+        safe_builtins = {
+            'print': print,
+            'len': len,
+            'range': range,
+            'enumerate': enumerate,
+            'zip': zip,
+            'map': map,
+            'filter': filter,
+            'sum': sum,
+            'min': min,
+            'max': max,
+            'abs': abs,
+            'round': round,
+            'sorted': sorted,
+            'list': list,
+            'dict': dict,
+            'set': set,
+            'tuple': tuple,
+            'str': str,
+            'int': int,
+            'float': float,
+            'bool': bool,
+            'isinstance': isinstance,
+            'type': type,
+            'hasattr': hasattr,
+            'getattr': getattr,
+            'setattr': setattr,
+            'True': True,
+            'False': False,
+            'None': None,
+            '__import__': self._safe_import,  # Enable safe imports
+            # Exception types (necessary for try/except blocks)
+            'Exception': Exception,
+            'ValueError': ValueError,
+            'TypeError': TypeError,
+            'KeyError': KeyError,
+            'IndexError': IndexError,
+            'AttributeError': AttributeError,
+            'RuntimeError': RuntimeError,
+            'ImportError': ImportError,
+            'ZeroDivisionError': ZeroDivisionError,
+            # Additional useful builtins
+            'locals': locals,
+            'globals': lambda: safe_builtins,  # Return safe version
+            'dir': dir,
+            'any': any,
+            'all': all,
+        }
+        
+        safe_dict = {
+            '__builtins__': safe_builtins,
+            '__name__': 'sandbox',
+        }
+        
+        # Add allowed modules (also available directly without import)
+        safe_dict.update(self.allowed_modules)
+        
+        # Add file path if provided
+        if file_path:
+            safe_dict['file_path'] = file_path
+            
+        return safe_dict
+    
+    def _execute_code(self, byte_code, safe_dict, stdout_capture, stderr_capture) -> None:
+        """
+        Helper method to execute code (can be run in a separate thread)
+        
+        Args:
+            byte_code: Compiled code object
+            safe_dict: Safe globals dictionary
+            stdout_capture: StringIO for capturing stdout
+            stderr_capture: StringIO for capturing stderr
+        """
+        with redirect_stdout(stdout_capture), redirect_stderr(stderr_capture):
+            exec(byte_code, safe_dict)
+    
+    def execute(self, code: str, file_path: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Execute Python code in a restricted environment
+        
+        Args:
+            code: Python code to execute
+            file_path: Path to the uploaded Excel/CSV file
+            
+        Returns:
+            Dictionary containing:
+                - success: bool
+                - output: str (stdout)
+                - error: str (if any)
+                - dataframe: dict (if df variable exists)
+                - images: list of base64 encoded images
+        """
+        result = {
+            'success': False,
+            'output': '',
+            'error': '',
+            'dataframe': None,
+            'images': []
+        }
+        
+        try:
+            # Validate code using AST
+            try:
+                tree = ast.parse(code, filename='<user_code>', mode='exec')
+            except SyntaxError as e:
+                result['error'] = f"Syntax error: {str(e)}"
+                logger.error(f"Syntax error: {str(e)}")
+                return result
+            
+            # Check for dangerous operations
+            validator = CodeValidator()
+            validator.visit(tree)
+            
+            if validator.errors:
+                result['error'] = f"Security validation failed:\n" + "\n".join(validator.errors)
+                logger.error(f"Validation errors: {validator.errors}")
+                return result
+            
+            # Configure pandas display to avoid truncated columns/rows in printed output
+            try:
+                pd.set_option('display.max_columns', None)
+                pd.set_option('display.width', 2000)
+                pd.set_option('display.max_colwidth', None)
+                pd.set_option('display.expand_frame_repr', False)
+            except Exception:
+                pass
+
+            # Compile the validated code
+            byte_code = compile(tree, filename='<user_code>', mode='exec')
+            
+            # Create safe execution environment
+            safe_dict = self._create_safe_globals(file_path)
+            
+            # Capture stdout and stderr
+            stdout_capture = io.StringIO()
+            stderr_capture = io.StringIO()
+            
+            # Execute with timeout using ThreadPoolExecutor
+            try:
+                with ThreadPoolExecutor(max_workers=1) as executor:
+                    future = executor.submit(
+                        self._execute_code,
+                        byte_code,
+                        safe_dict,
+                        stdout_capture,
+                        stderr_capture
+                    )
+                    # Wait for completion with timeout
+                    future.result(timeout=self.timeout)
+                
+                # Get stdout
+                result['output'] = stdout_capture.getvalue()
+                
+                # Check for dataframe in the namespace
+                if 'df' in safe_dict and isinstance(safe_dict['df'], pd.DataFrame):
+                    # Convert dataframe to dict and make it JSON-safe
+                    records = safe_dict['df'].head(5).to_dict('records')
+                    result['dataframe'] = self._make_json_safe_records(records)
+                elif 'result' in safe_dict and isinstance(safe_dict['result'], pd.DataFrame):
+                    records = safe_dict['result'].head(5).to_dict('records')
+                    result['dataframe'] = self._make_json_safe_records(records)
+                
+                # Capture matplotlib figures
+                figures = [plt.figure(i) for i in plt.get_fignums()]
+                for fig in figures:
+                    buf = io.BytesIO()
+                    fig.savefig(buf, format='png', bbox_inches='tight', dpi=100)
+                    buf.seek(0)
+                    img_base64 = base64.b64encode(buf.read()).decode('utf-8')
+                    result['images'].append(img_base64)
+                    buf.close()
+                
+                # Close all figures to free memory
+                plt.close('all')
+                
+                result['success'] = True
+                logger.info("Code executed successfully")
+                
+            except FuturesTimeoutError:
+                result['error'] = f"Execution timeout: Code took longer than {self.timeout} seconds"
+                logger.error(f"Timeout: Code execution exceeded {self.timeout} seconds")
+            except Exception as e:
+                result['error'] = f"Runtime error: {str(e)}"
+                logger.error(f"Runtime error: {str(e)}")
+                
+                # Include stderr if available
+                stderr_output = stderr_capture.getvalue()
+                if stderr_output:
+                    result['error'] += f"\n{stderr_output}"
+        
+        except Exception as e:
+            result['error'] = f"Sandbox error: {str(e)}"
+            logger.error(f"Sandbox error: {str(e)}")
+
+        logger.info(f"Result: {result}")
+        
+        return result
+
+    def _make_json_safe_records(self, records):
+        """
+        Convert a list of dict records into JSON-serializable values:
+        - pandas.Timestamp -> ISO string
+        - numpy types -> native Python
+        - NaN -> None
+        """
+        import math
+        from datetime import datetime
+
+        def to_safe(value):
+            if isinstance(value, pd.Timestamp):
+                return value.isoformat()
+            if isinstance(value, datetime):
+                return value.isoformat()
+            if isinstance(value, np.generic):
+                # numpy scalar -> native python
+                py = value.item()
+                if isinstance(py, float) and (math.isnan(py) or py == float('inf') or py == float('-inf')):
+                    return None
+                return py
+            if isinstance(value, float):
+                if math.isnan(value) or value == float('inf') or value == float('-inf'):
+                    return None
+                return value
+            return value
+
+        safe_records = []
+        for rec in records or []:
+            safe_rec = {k: to_safe(v) for k, v in rec.items()}
+            safe_records.append(safe_rec)
+        return safe_records
+    
+    def get_tool_definition(self) -> Dict[str, Any]:
+        """
+        Get the tool definition for OpenAI function calling
+        
+        Returns:
+            Tool definition dictionary
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": "execute_python_code",
+                "description": "Execute Python code to analyze Excel/CSV data. Use pandas (pd), numpy (np), matplotlib (plt), and seaborn (sns). The uploaded file path is available as 'file_path' variable. Store results in 'df' or 'result' variable to return dataframes.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "code": {
+                            "type": "string",
+                            "description": "Python code to execute. Must use pandas to read the file (e.g., pd.read_excel(file_path) or pd.read_csv(file_path)). Store final dataframe in 'df' or 'result' variable."
+                        }
+                    },
+                    "required": ["code"]
+                }
+            }
+        }
+
+
+

app_agents/tools/web_search_tool.py

@@ -0,0 +1,123 @@
+"""
+Web Search Tool using DuckDuckGo
+Provides web search capability for finding documentation and examples
+"""
+
+import logging
+from typing import Dict, Any, List
+from ddgs import DDGS
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class WebSearchTool:
+    """
+    Web search tool using DuckDuckGo API
+    """
+    
+    def __init__(self, max_results: int = 5):
+        """
+        Initialize the web search tool
+        
+        Args:
+            max_results: Maximum number of search results to return (default: 5)
+        """
+        self.max_results = max_results
+    
+    def search(self, query: str) -> Dict[str, Any]:
+        """
+        Search the web using DuckDuckGo
+        
+        Args:
+            query: Search query string
+            
+        Returns:
+            Dictionary containing:
+                - success: bool
+                - results: list of search results
+                - error: str (if any)
+        """
+        result = {
+            'success': False,
+            'results': [],
+            'error': ''
+        }
+        
+        try:
+            logger.info(f"Searching for: {query}")
+            
+            with DDGS() as ddgs:
+                search_results = list(ddgs.text(
+                    query,
+                    max_results=self.max_results
+                ))
+            
+            # Format results
+            formatted_results = []
+            for idx, res in enumerate(search_results, 1):
+                formatted_results.append({
+                    'position': idx,
+                    'title': res.get('title', ''),
+                    'snippet': res.get('body', ''),
+                    'url': res.get('href', '')
+                })
+            
+            result['results'] = formatted_results
+            result['success'] = True
+            logger.info(f"Found {len(formatted_results)} results")
+            
+        except Exception as e:
+            result['error'] = f"Search error: {str(e)}"
+            logger.error(f"Search error: {str(e)}")
+        
+        return result
+    
+    def format_results(self, search_results: List[Dict[str, Any]]) -> str:
+        """
+        Format search results into a readable string
+        
+        Args:
+            search_results: List of search result dictionaries
+            
+        Returns:
+            Formatted string of search results
+        """
+        if not search_results:
+            return "No results found."
+        
+        formatted = "Search Results:\n\n"
+        for res in search_results:
+            formatted += f"{res['position']}. {res['title']}\n"
+            formatted += f"   {res['snippet']}\n"
+            formatted += f"   URL: {res['url']}\n\n"
+        
+        return formatted
+    
+    def get_tool_definition(self) -> Dict[str, Any]:
+        """
+        Get the tool definition for OpenAI function calling
+        
+        Returns:
+            Tool definition dictionary
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": "search_web",
+                "description": "Search the web using DuckDuckGo to find Python/pandas documentation, code examples, or solutions to data analysis problems. Use this when you need help with specific pandas operations, matplotlib visualizations, or data manipulation techniques.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query. Be specific and include relevant keywords like 'pandas', 'python', 'matplotlib', etc."
+                        }
+                    },
+                    "required": ["query"]
+                }
+            }
+        }
+
+
+

app_agents/web_agent.py

@@ -0,0 +1,58 @@
+"""
+WebSearch Agent - MCP client using Agents SDK
+"""
+
+import logging
+
+from agents import Agent
+from agents.mcp import MCPServerStdio, create_static_tool_filter
+from agents.model_settings import ModelSettings
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# System prompt for the WebSearchAgent
+WEB_SEARCH_INSTRUCTIONS = """You are a research assistant specialized in Python, pandas, matplotlib, and data analysis.
+
+Your role is to search the web for:
+- Documentation and API references
+- Solutions to Python/pandas errors
+- Code examples and best practices
+- Matplotlib/seaborn visualization techniques
+
+Use the MCP tool `search_web(query)` to find relevant information.
+
+Guidelines:
+- Provide concise, actionable summaries
+- Include concrete code snippets when available
+- Focus on authoritative sources (official docs, Stack Overflow, etc.)
+- Return your findings in a clear, structured format
+- The code you provide should be formatted as 
+```python 
+YOUR CODE HERE
+```
+"""
+
+
+def create_web_search_agent(mcp_server: MCPServerStdio, model: str = "gpt-4o-mini") -> Agent:
+    """
+    Create an Agent SDK for web search
+    
+    Args:
+        mcp_server: MCP server already configured with search_web tool filter
+        model: OpenAI model to use
+    
+    Returns:
+        Agent configured for web search
+    """
+    return Agent(
+        name="WebSearchAgent",
+        instructions=WEB_SEARCH_INSTRUCTIONS,
+        mcp_servers=[mcp_server],
+        model=model,
+        model_settings=ModelSettings(tool_choice="required"),
+    )
+
+

requirements.txt

@@ -0,0 +1,11 @@
+gradio
+openai>=1.12.0
+pandas>=2.0.0
+numpy>=1.24.0
+openpyxl>=3.1.0
+matplotlib>=3.7.0
+seaborn>=0.12.0
+ddgs
+python-dotenv>=1.0.0
+openai-agents
+fastmcp