first commit

.cursor/rules/cmw-platform-agent.mdc

@@ -0,0 +1,16 @@
+---
+alwaysApply: true
+---
+
+- Be super smart, create super lean and dry code.
+- Use abstractions.
+- Group and isolate code based on its function in different files to avoid clutter.
+- Do not duplicate code, encapsulate any reused code in methods/functions.
+- Never break existing code.
+- Do not delete logging, but update it.
+- Do not delete comments, rather update them.
+- Produce flawless code.
+- Reanalyze your changes twice for any issues you might have introduced.
+- Place imports always on top.
+- Use environment variables for secrets.
+- Ensure testability and extensibility.

.env.example

@@ -0,0 +1,7 @@
+HF_TOKEN=XXX
+HUGGINGFACE_API_KEY=XXX
+SUPABASE_URL=XXX
+SUPABASE_KEY=XXX
+GEMINI_KEY=XXX
+GROQ_API_KEY=XXX
+TAVILY_API_KEY=XXX

.gitattributes

@@ -0,0 +1,40 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.csv filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.xlsx filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+.env
+venv/
+__pycache__/
+!logs/*.log

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "terminal.integrated.defaultProfile.windows": "Ubuntu"
+}

README.md

@@ -0,0 +1,387 @@
+---
+emoji: 🕵🏻‍♂️
+colorFrom: indigo
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.35.0
+app_file: app.py
+pinned: false
+hf_oauth: true
+hf_oauth_expiration_minutes: 480
+---
+
+# CMW Platform Agent
+
+---
+
+**Authors:** Arte(r)m Sedov & Marat Mutalimov
+
+**Github:** <https://github.com/arterm-sedov/>
+
+**This repo:** <https://github.com/arterm-sedov/cmw-platform-agent>
+
+## 🚀 The CMW Platform Agent
+
+Behold the CMW Platform Agent — a robust and extensible system designed for real-world reliability and performance.
+
+## 🕵🏻‍♂️ What is this project?
+
+This is an **experimental multi-LLM agent** that demonstrates AI agent and CMW Platform iteration:
+
+- **Input**: The user asks the CMW Platform Agent to create entities in the CMW Platform instance.
+- **Task**: The agent agent has a set of tools to translate natural language user requests into the CMW Platform API calls.
+
+## 🎯 Project Goals
+
+To create an agent that will allow batch entity creation within the CMW Platform.
+
+## ❓ Why This Project?
+
+This experimental system is based on current AI agent technology and demonstrates:
+
+- **Advanced Tool Usage**: Seamless integration of 20+ specialized tools including AI-powered tools and third-party AI engines
+- **Multi-Provider Resilience**: Automatic testing and switching between different LLM providers
+- **Comprehensive Tracing**: Complete visibility into the agent's decision-making process
+- **Structured Initialization Summary:** After startup, a clear table shows which models/providers are available, with/without
+tools, and any errors—so you always know your agent's capabilities.
+
+## 📊 What You'll Find Here
+
+- **Documentation**: Detailed technical specifications and usage guides
+
+## 🏗️ Technical Architecture
+
+### LLM Configuration
+
+The agent uses a sophisticated multi-LLM approach with the following providers in sequence:
+
+1. **OpenRouter** (Primary)
+   - Models: `deepseek/deepseek-chat-v3-0324:free`, `mistralai/mistral-small-3.2-24b-instruct:free`, `openrouter/cypher-alpha:free`
+   - Token Limits: 100K-1M tokens
+   - Tool Support: ✅ Full tool-calling capabilities
+
+2. **Google Gemini** (Fallback)
+   - Model: `gemini-2.5-pro`
+   - Token Limit: 2M tokens (virtually unlimited)
+   - Tool Support: ✅ Full tool-calling capabilities
+
+3. **Groq** (Second Fallback)
+   - Model: `qwen-qwq-32b`
+   - Token Limit: 3K tokens
+   - Tool Support: ✅ Full tool-calling capabilities
+
+4. **HuggingFace** (Final Fallback)
+   - Models: `Qwen/Qwen2.5-Coder-32B-Instruct`, `microsoft/DialoGPT-medium`, `gpt2`
+   - Token Limits: 1K tokens
+   - Tool Support: ❌ No tool-calling (text-only responses)
+
+### Tool Suite
+
+The agent includes 20+ specialized tools:
+
+- **Attribute creation**: creates an attribute in a specified template.
+
+### Performance Expectations
+
+- **Success Rate**: 50-65% entities created
+- **Response Time**: 30-100 seconds per question (depending on complexity and LLM)
+- **Tool Usage**: 2-8 tool calls per request on average
+- **Fallback Rate**: 20-40% of questions require human clarification
+
+## Dataset Structure
+
+The output trace facilitates:
+
+- **Debugging**: Complete visibility into execution flow
+- **Performance Analysis**: Detailed timing and token usage metrics
+- **Error Analysis**: Comprehensive error information with context
+- **Tool Usage Analysis**: Complete tool execution history
+- **LLM Comparison**: Detailed comparison of different LLM behaviors
+- **Cost Optimization**: Token usage analysis for cost management
+
+Each request trace is uploaded to a HuggingFace dataset.
+
+The dataset contains comprehensive execution traces with the following structure:
+
+### Root Level Fields
+
+```python
+{
+    "question": str,                    # Original question text
+    "file_name": str,                   # Name of attached file (if any)
+    "file_size": int,                   # Length of base64 file data (if any)
+    "start_time": str,                  # ISO format timestamp when processing started
+    "end_time": str,                    # ISO format timestamp when processing ended
+    "total_execution_time": float,      # Total execution time in seconds
+    "tokens_total": int,                # Total tokens used across all LLM calls
+    "debug_output": str,                # Comprehensive debug output as text
+}
+```
+
+### LLM Traces
+
+```python
+"llm_traces": {
+    "llm_type": [                      # e.g., "openrouter", "gemini", "groq", "huggingface"
+        {
+            "call_id": str,             # e.g., "openrouter_call_1"
+            "llm_name": str,            # e.g., "deepseek-chat-v3-0324" or "Google Gemini"
+            "timestamp": str,           # ISO format timestamp
+            
+            # === LLM CALL INPUT ===
+            "input": {
+                "messages": List,       # Input messages (trimmed for base64)
+                "use_tools": bool,      # Whether tools were used
+                "llm_type": str         # LLM type
+            },
+            
+            # === LLM CALL OUTPUT ===
+            "output": {
+                "content": str,         # Response content
+                "tool_calls": List,     # Tool calls from response
+                "response_metadata": dict,  # Response metadata
+                "raw_response": dict    # Full response object (trimmed for base64)
+            },
+            
+            # === TOOL EXECUTIONS ===
+            "tool_executions": [
+                {
+                    "tool_name": str,      # Name of the tool
+                    "args": dict,          # Tool arguments (trimmed for base64)
+                    "result": str,         # Tool result (trimmed for base64)
+                    "execution_time": float, # Time taken for tool execution
+                    "timestamp": str,      # ISO format timestamp
+                    "logs": List           # Optional: logs during tool execution
+                }
+            ],
+            
+            # === TOOL LOOP DATA ===
+            "tool_loop_data": [
+                {
+                    "step": int,           # Current step number
+                    "tool_calls_detected": int,  # Number of tool calls detected
+                    "consecutive_no_progress": int,  # Steps without progress
+                    "timestamp": str,      # ISO format timestamp
+                    "logs": List           # Optional: logs during this step
+                }
+            ],
+            
+            # === EXECUTION METRICS ===
+            "execution_time": float,       # Time taken for this LLM call
+            "total_tokens": int,           # Estimated token count (fallback)
+            
+            # === TOKEN USAGE TRACKING ===
+            "token_usage": {               # Detailed token usage data
+                "prompt_tokens": int,      # Total prompt tokens across all calls
+                "completion_tokens": int,  # Total completion tokens across all calls
+                "total_tokens": int,       # Total tokens across all calls
+                "call_count": int,         # Number of calls made
+                "calls": [                 # Individual call details
+                    {
+                        "call_id": str,   # Unique call identifier
+                        "timestamp": str,  # ISO format timestamp
+                        "prompt_tokens": int,     # This call's prompt tokens
+                        "completion_tokens": int, # This call's completion tokens
+                        "total_tokens": int,      # This call's total tokens
+                        "finish_reason": str,     # How the call finished (optional)
+                        "system_fingerprint": str, # System fingerprint (optional)
+                        "input_token_details": dict,  # Detailed input breakdown (optional)
+                        "output_token_details": dict  # Detailed output breakdown (optional)
+                    }
+                ]
+            },
+            
+            # === ERROR INFORMATION ===
+            "error": {                     # Only present if error occurred
+                "type": str,              # Exception type name
+                "message": str,           # Error message
+                "timestamp": str          # ISO format timestamp
+            },
+            
+            # === LLM-SPECIFIC LOGS ===
+            "logs": List,                 # Logs specific to this LLM call
+            
+            # === FINAL ANSWER ENFORCEMENT ===
+            "final_answer_enforcement": [  # Optional: logs from _force_final_answer for this LLM call
+                {
+                    "timestamp": str,     # ISO format timestamp
+                    "message": str,       # Log message
+                    "function": str       # Function that generated the log (always "_force_final_answer")
+                }
+            ]
+        }
+    ]
+}
+```
+
+### Per-LLM Stdout Capture
+
+```python
+"per_llm_stdout": [
+    {
+        "llm_type": str,            # LLM type
+        "llm_name": str,            # LLM name (model ID or provider name)
+        "call_id": str,             # Call ID
+        "timestamp": str,           # ISO format timestamp
+        "stdout": str               # Captured stdout content
+    }
+]
+```
+
+### Question-Level Logs
+
+```python
+"logs": [
+    {
+        "timestamp": str,           # ISO format timestamp
+        "message": str,             # Log message
+        "function": str             # Function that generated the log
+    }
+]
+```
+
+### Final Results
+
+```python
+"final_result": {
+    "submitted_answer": str,        # Final answer (consistent with code)
+    "similarity_score": float,      # Similarity score (0.0-1.0)
+    "llm_used": str,               # LLM that provided the answer
+    "reference": str,               # Reference answer used
+    "question": str,                # Original question
+    "file_name": str,               # File name (if any)
+    "error": str                    # Error message (if any)
+}
+```
+
+## Key Features
+
+### Intelligent Fallback System
+
+The agent automatically tries multiple LLM providers in sequence:
+
+- **OpenRouter** (Primary): Fast, reliable, good tool support, has tight daily limits on free tiers
+- **Google Gemini** (Fallback): High token limits, excellent reasoning
+- **Groq** (Second Fallback): Fast inference, good for simple tasks, has tight token limits per request
+- **HuggingFace** (Final Fallback): Local models, no API costs, does not support tools typically
+
+### Advanced Tool Management
+
+- **Automatic Tool Selection**: LLM chooses appropriate tools based on question
+- **Tool Deduplication**: Prevents duplicate tool calls using vector similarity
+- **Usage Limits**: Prevents excessive tool usage (e.g., max 3 web searches per question)
+- **Error Handling**: Graceful degradation when tools fail
+
+### Sophisticated implementations
+
+- **Recursive Truncation**: Separate methods for base64 and max-length truncation
+- **Recursive JSON Serialization**: Ensures the complex objects ar passable as HuggingFace JSON dataset
+- **Decorator-Based Print Capture**: Captures all print statements into trace data
+- **Multilevel Contextual Logging**: Logs tied to specific execution contexts
+- **Per-LLM Stdout Traces**: Stdout captured separately for each LLM attempt in a human-readable form
+- **Consistent LLM Schema**: Data structures for consistent model identification, configuring and calling
+- **Complete Trace Model**: Hierarchical structure with comprehensive coverage
+- **Structured dataset uploads** to HuggingFace datasets
+- **Schema validation** against `dataset_config.json`
+- **Three data splits**: `init` (initialization), `runs` (legacy aggregated results), and `runs_new` (granular per-question results)
+- **Robust error handling** with fallback mechanisms
+
+### Comprehensive Tracing
+
+Every question generates a complete execution trace including:
+
+- **LLM Interactions**: All input/output for each LLM attempt
+- **Tool Executions**: Detailed logs of every tool call
+- **Performance Metrics**: Token usage, execution times, success rates
+- **Error Information**: Complete error context and fallback decisions
+- **Stdout Capture**: All debug output from each LLM attempt
+
+### Rate Limiting & Reliability
+
+- **Smart Rate Limiting**: Different intervals for different providers
+- **Token Management**: Automatic truncation and summarization
+- **Error Recovery**: Automatic retry with different LLMs
+- **Graceful Degradation**: Continues processing even if some components fail
+
+## Usage
+
+### Live Demo
+
+Visit the Gradio interface to test the agent interactively:
+
+<https://localhost/cmw-platform-agent>
+
+### Programmatic Usage
+
+```python
+from agent import GaiaAgent
+
+# Initialize the agent
+agent = GaiaAgent()
+
+# Process a question
+result = agent("What is the capital of France?")
+
+# Access the results
+print(f"Answer: {result['submitted_answer']}")
+print(f"Similarity: {result['similarity_score']}")
+print(f"LLM Used: {result['llm_used']}")
+```
+
+### Dataset Access
+
+```python
+from datasets import load_dataset
+
+# Load the dataset
+dataset = load_dataset("arterm-sedov/agent-course-final-assignment")
+
+# Access initialization data
+init_data = dataset["init"]["train"]
+
+# Access evaluation results
+runs_data = dataset["runs_new"]["train"]
+```
+
+## File Structure
+
+The main agent runtime files are:
+
+```
+gaia-agent/
+├── agent.py              # Main agent implementation
+├── app.py                # Gradio web interface
+├── tools.py              # Tool definitions and implementations
+├── utils.py              # Core upload functions with validation
+├── system_prompt.json    # System prompt configuration
+└── logs/               # Execution logs and results
+```
+
+There are other files in the root directory, but they are not used at the runtime, rather for setting up the Supabase vector store.
+
+## Performance Statistics
+
+The agent has been evaluated on complex benchmark questions with the following results:
+
+- **Overall Success Rate**: 50-65%, up to 80% with all four LLMs available
+- **Tool Usage**: Average 2-8 tools per question
+- **LLM Fallback Rate**: 20-40% of questions require multiple LLMs
+- **Response Time**: 30-120 seconds per question
+- **Token Usage**: 1K-100K tokens per question (depending on complexity)
+
+## Contributing
+
+This is an experimental research project. Contributions are welcome in the form of:
+
+- **Bug Reports**: Issues with the agent's reasoning or tool usage
+- **Feature Requests**: New tools or capabilities
+- **Performance Improvements**: Optimizations for speed or accuracy
+- **Documentation**: Improvements to this README or code comments
+
+## License
+
+This project is part of the Hugging Face Agents Course final assignment. See the course materials for licensing information.
+
+---
+
+**Built with ❤️ by Arte(r)m Sedov using Cursor IDE**

SETUP_INSTRUCTIONS.md

@@ -0,0 +1,222 @@
+# arterm-sedov Setup Instructions
+
+## Overview
+
+Welcome to the arterm-sedov CMW Platform Agent project! This guide ensures a smooth setup for both Windows and Linux/macOS, leveraging robust multi-LLM orchestration, model-level tool support, and transparent initialization diagnostics.
+
+## Prerequisites
+
+- **Python 3.8 or higher**
+- **Git** (for cloning)
+- **Internet connection**
+
+## Quick Start
+
+### Option 1: Automated Setup (Recommended)
+
+```bash
+# Clone the repository (if not already done)
+git clone <repository-url>
+cd arterm-sedov
+
+# Run the automated setup script
+python setup_venv.py
+```
+
+This script will:
+- Detect your platform and Python version
+- Create a virtual environment
+- Use the correct requirements file for your OS
+- Install all dependencies in order
+- Verify installation and print next steps
+- Print a summary of LLM/model initialization and tool support
+
+### Option 2: Manual Setup
+
+#### Step 1: Create Virtual Environment
+
+**Windows:**
+```cmd
+python -m venv venv
+venv\Scripts\activate
+```
+
+**Linux/macOS:**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+#### Step 2: Install Dependencies
+
+**For Windows:**
+```bash
+python -m pip install --upgrade pip
+pip install wheel setuptools
+pip install -r requirements.win.txt
+```
+
+**For Linux/macOS:**
+```bash
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+## Requirements Files
+
+- `requirements.txt`: For Linux/macOS/Hugging Face Spaces
+- `requirements.win.txt`: For Windows (handles platform quirks)
+
+The setup script auto-selects the right file for you.
+
+## Environment Variables Setup
+
+Create a `.env` file in the project root:
+
+```env
+# Required for Google Gemini integration
+GEMINI_KEY=your_gemini_api_key_here
+# Required for Supabase vector store
+SUPABASE_URL=your_supabase_url_here
+SUPABASE_KEY=your_supabase_key_here
+# Optional: For HuggingFace, OpenRouter, Groq
+HUGGINGFACEHUB_API_TOKEN=your_hf_token
+OPENROUTER_API_KEY=your_openrouter_key
+GROQ_API_KEY=your_groq_key
+```
+
+### Getting API Keys
+
+- **Google Gemini:** [Google AI Studio](https://makersuite.google.com/app/apikey)
+- **Supabase:** [supabase.com](https://supabase.com) > Settings > API
+- **HuggingFace:** [HuggingFace Tokens](https://huggingface.co/settings/tokens)
+
+## Vector Store Setup
+
+```bash
+python setup_vector_store.py
+```
+This loads reference Q&A into Supabase for similarity search.
+
+## Running the Agent
+
+```bash
+python app.py
+```
+This launches the Gradio web interface for interactive testing and evaluation.
+
+## LLM Initialization & Tool Support
+
+- On startup, each LLM/model is tested for plain and tool-calling support.
+- **Google Gemini** is always bound with tools if enabled, even if the tool test returns empty (tool-calling works in practice; a warning is logged for transparency).
+- **OpenRouter, Groq, and HuggingFace** are supported with model-level tool-calling detection and fallback.
+- After initialization, a summary table is printed showing provider, model, plain/tools status, and any errors—so you always know what's available.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Wrong requirements file used:**
+   - The setup script auto-detects your platform. To force a file:
+     ```bash
+     pip install -r requirements.win.txt  # Windows
+     pip install -r requirements.txt      # Linux/macOS
+     ```
+2. **Virtual environment creation fails:**
+   - Remove and recreate:
+     ```bash
+     rm -rf venv  # Linux/macOS
+     rmdir /s /q venv  # Windows
+     python setup_venv.py
+     ```
+3. **Permission errors:**
+   - Use `--user` flag:
+     ```bash
+     pip install --user -r requirements.txt
+     ```
+4. **Import errors after install:**
+   - Reinstall dependencies:
+     ```bash
+     pip install --force-reinstall -r requirements.txt
+     ```
+5. **API key issues:**
+   - Check your `.env` file for correct format and valid keys.
+
+### Platform-Specific Issues
+
+**Windows:**
+- PowerShell execution policy: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
+- Visual Studio Build Tools may be required for TensorFlow. Or use conda:
+  ```cmd
+  conda install pandas numpy
+  pip install -r requirements.win.txt
+  ```
+
+**Linux/macOS:**
+- Install system packages if needed:
+  ```bash
+  sudo apt-get install python3-dev build-essential  # Ubuntu/Debian
+  xcode-select --install  # macOS
+  ```
+
+## Verification
+
+After setup, verify everything works:
+
+```python
+import numpy as np
+import pandas as pd
+import langchain
+import supabase
+import gradio
+print("✅ All core packages imported successfully!")
+print(f"Pandas version: {pd.__version__}")
+```
+
+## Project Structure
+
+```
+arterm-sedov/
+├── agent.py              # Main agent implementation
+├── app.py                # Gradio web interface
+├── tools.py              # Tool functions for the agent
+├── setup_venv.py         # Cross-platform setup script
+├── setup_vector_store.py # Vector store initialization
+├── requirements.txt      # Dependencies (Linux/macOS/HF Space)
+├── requirements.win.txt  # Dependencies (Windows)
+├── system_prompt.txt     # Agent system prompt
+├── metadata.jsonl        # Reference Q&A data
+├── supabase_docs.csv     # Vector store backup
+└── .env                  # Environment variables (create this)
+```
+
+## Advanced Configuration
+
+### Custom Model Providers
+
+The agent supports multiple LLM providers with robust fallback and model-level tool support:
+- **Google Gemini**: Always bound with tools if enabled (tool-calling works even if test is empty)
+- **Groq, OpenRouter, HuggingFace**: Model-level tool-calling detection and fallback
+
+### Vector Store Configuration
+- **Table:** `agent_course_reference`
+- **Embedding Model:** `sentence-transformers/all-mpnet-base-v2`
+- **Similarity Search:** Cosine similarity
+
+### Tool Configuration
+- Math, web, file, image, chess, code, and more—modular and extensible
+
+## Support
+
+- See the summary table after startup for LLM/model/tool status
+- Review error logs for diagnostics
+- For advanced help, see the troubleshooting section above
+
+## Next Steps
+
+1. **Test the agent** with sample questions
+2. **Run the evaluation** for performance metrics
+3. **Submit to CMW Platform Agent benchmark** for scoring
+4. **Customize the agent** for your needs
+
+The agent is now ready for the CMW Platform benchmark—battle-tested, transparent, and extensible. 🚀

app.py

@@ -0,0 +1,735 @@
+import os
+import gradio as gr
+import requests
+import inspect
+import pandas as pd
+import random
+import datetime
+import subprocess
+import json
+import re
+import base64
+from typing import Any
+from agent import GaiaAgent
+from utils import TRACES_DIR, upload_run_data, ensure_valid_answer
+
+# (Keep Constants as is)
+# --- Constants ---
+DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+
+# --- Main Agent Definition ---
+# Instantiate the agent once (choose provider as needed)
+AGENT_PROVIDER = os.environ.get("AGENT_PROVIDER", "google")
+try:
+    agent = GaiaAgent(provider=AGENT_PROVIDER)
+except Exception as e:
+    agent = None
+    print(f"Error initializing GaiaAgent: {e}")
+
+
+
+# Helper to save DataFrame as CSV and upload via API
+def save_df_to_csv(df, path):
+    try:
+        # Convert DataFrame to CSV string
+        csv_content = df.to_csv(index=False, encoding="utf-8")
+        
+        # Upload via API
+        success = save_and_commit_file(
+            file_path=path,
+            content=csv_content,
+            commit_message=f"Add results CSV {path}"
+        )
+        if success:
+            print(f"✅ Results CSV uploaded successfully: {path}")
+        else:
+            print(f"⚠️ Results CSV upload failed, saved locally only: {path}")
+            # Fallback to local save
+            df.to_csv(path, index=False, encoding="utf-8")
+    except Exception as e:
+        print(f"⚠️ Results CSV upload error: {e}, saving locally only")
+        # Fallback to local save
+        df.to_csv(path, index=False, encoding="utf-8")
+    
+    return path
+
+# --- Provide init log for download on app load ---
+def get_init_log():
+    init_log_path = getattr(agent, "init_log_path", None)
+    if init_log_path and os.path.exists(init_log_path):
+        return init_log_path
+    return None
+
+def generate_run_id(timestamp: str, idx: int) -> str:
+    """Generate a unique run ID for a question."""
+    return f"{timestamp}_q{idx+1:02d}"
+
+def upload_questions_with_results(results_log: list, timestamp: str, username: str, total_score: str, success_type: str = "final"):
+    """
+    Upload all questions with their results to the runs_new dataset.
+    
+    Args:
+        results_log: List of question results
+        timestamp: Timestamp for run IDs
+        username: Username for the run
+        total_score: Final score from evaluator
+        success_type: Type of upload ("final evaluated results" or "unevaluated results")
+    """
+    successful_uploads = 0
+    for idx, result in enumerate(results_log):
+        try:
+            run_id = generate_run_id(timestamp, idx)
+            
+            # Get LLM stats JSON for this run
+            llm_stats_json = agent._get_llm_stats_json()
+            
+            # Create updated run data for this question
+            run_data = create_run_data_for_runs_new(
+                run_id,
+                idx,
+                len(results_log),
+                result,
+                llm_stats_json,
+                username,
+                total_score
+            )
+            
+            success = upload_run_data(run_data, split="runs_new")
+            if success:
+                print(f"✅ Uploaded question {idx+1} with {success_type}. Run ID: {run_id}")
+                successful_uploads += 1
+            else:
+                print(f"⚠️ Failed to upload question {idx+1} with {success_type}")
+                
+        except Exception as e:
+            print(f"⚠️ Failed to upload question {idx+1}. Error: {e}")
+    
+    return successful_uploads
+
+def create_run_data_for_runs_new(
+    run_id: str,
+    idx: int,
+    total_questions: int,
+    result: dict,
+    llm_stats_json: dict,
+    username: str = "N/A",
+    total_score: str = "N/A"
+) -> dict:
+    """
+    Create run data for the runs_new split.
+    
+    Args:
+        run_id: Unique identifier for the run
+        idx: Index of the question in the batch (0-based)
+        total_questions: Total number of questions in the batch
+        result: Individual result dictionary
+        llm_stats_json: LLM statistics JSON
+        username: Username of the person running the agent
+        total_score: Overall score for the complete evaluation run
+        
+    Returns:
+        dict: Run data for upload to runs_new split
+    """
+    # Extract trace data from result
+    trace = result.get("trace", {})
+    
+    # Extract final_result from trace
+    final_result = trace.get("final_result", {})
+    
+    file_name = trace.get("file_name", "")
+    
+    question = trace.get("question", "")
+    
+    return {
+        "run_id": run_id,
+        "questions_count": f"{idx+1}/{total_questions}",
+        "input_data": json.dumps([{
+            "task_id": result.get("task_id", f"task_{idx+1:03d}"),
+            "question": question or "N/A",
+            "file_name": file_name or "N/A"
+        }]),
+        "reference_answer": final_result.get("reference", "N/A"),
+        "final_answer": final_result.get("submitted_answer", "N/A"),
+        "reference_similarity": float(final_result.get("similarity_score", 0.0)),
+        "question": question or "N/A",
+        "file_name": file_name or "N/A",
+        "file_size": trace.get("file_size", 0),
+        "llm_used": final_result.get("llm_used", "N/A"),  # LLM used
+        "llm_stats_json": json.dumps(llm_stats_json),  # LLM statistics JSON
+        "total_score": total_score or "N/A",  # Overall score for the complete evaluation run
+        "start_time": trace.get("start_time") or "N/A",  # Start time with fallback
+        "end_time": trace.get("end_time") or "N/A",  # End time with fallback
+        "total_execution_time": float(trace.get("total_execution_time", 0.0)),  # Total execution time with fallback, ensure float
+        "tokens_total": int(trace.get("tokens_total", 0)),  # Tokens total with fallback, ensure int
+        "llm_traces_json": json.dumps(trace.get("llm_traces", {})),
+        "logs_json": json.dumps(trace.get("logs", [])),
+        "per_llm_stdout_json": json.dumps(trace.get("per_llm_stdout", [])),
+        "full_debug": trace.get("debug_output", "N/A"),
+        "error": final_result.get("error", "N/A"),  # Error information
+        "username": username.strip() if username else "N/A"
+    }
+
+def run_and_submit_all(profile: gr.OAuthProfile | None):
+    """
+    Fetches all questions, runs the GaiaAgent on them, submits all answers,
+    and displays the results.
+    """
+    space_id = os.getenv("SPACE_ID")
+    if profile:
+        username = f"{profile.username}"
+        print(f"User logged in: {username}")
+    else:
+        print("User not logged in.")
+        return "Please Login to Hugging Face with the button.", None
+
+    api_url = DEFAULT_API_URL
+    questions_url = f"{api_url}/questions"
+    submit_url = f"{api_url}/submit"
+
+    # 1. Instantiate Agent (already done globally)
+    if agent is None:
+        return "Error initializing agent. Check logs for details.", None
+    agent_code = f"https://huggingface.co/spaces/{username}/agent-course-final-assignment/tree/main"
+    print(agent_code)
+
+    # 2. Fetch Questions
+    print(f"Fetching questions from: {questions_url}")
+    try:
+        response = requests.get(questions_url, timeout=15)
+        response.raise_for_status()
+        questions_data = response.json()
+        if not questions_data:
+            print("Fetched questions list is empty.")
+            return "Fetched questions list is empty or invalid format.", None
+        print(f"Fetched {len(questions_data)} questions.")
+    except requests.exceptions.RequestException as e:
+        print(f"Error fetching questions: {e}")
+        return f"Error fetching questions: {e}", None
+    except requests.exceptions.JSONDecodeError as e:
+        print(f"Error decoding JSON response from questions endpoint: {e}")
+        print(f"Response text: {response.text[:500]}")
+        return f"Error decoding server response for questions: {e}", None
+    except Exception as e:
+        print(f"An unexpected error occurred fetching questions: {e}")
+        return f"An unexpected error occurred fetching questions: {e}", None
+
+    # 3. Run the Agent
+    results_log = []
+    results_log_df = []
+    answers_payload = []
+    print(f"Running GaiaAgent on {len(questions_data)} questions...")
+    # Select all questions randomly
+    questions_data = random.sample(questions_data, len(questions_data))
+    # DEBUG: Select one random task instead of all
+    # questions_data = random.sample(questions_data, 1)
+    #questions_data = [questions_data[0]]
+    
+    for item in questions_data:
+        task_id = item.get("task_id")
+        question_text = item.get("question")
+        file_name = item.get("file_name", "")  # Extract file_name from question data
+        
+        if not task_id or question_text is None:
+            print(f"Skipping item with missing task_id or question: {item}")
+            continue
+        
+        # Download file if one is referenced
+        file_data = None
+        if file_name and file_name.strip():
+            try:
+                print(f"\U0001F4C1 Downloading file: {file_name} for task {task_id}")
+                file_url = f"{api_url}/files/{task_id}"
+                file_response = requests.get(file_url, timeout=30)
+                file_response.raise_for_status()
+                
+                # Convert file to base64
+                file_data = base64.b64encode(file_response.content).decode('utf-8')
+                print(f"✅ Downloaded and encoded file: {file_name} ({len(file_data)} chars)")
+            except Exception as e:
+                print(f"⚠️ Failed to download file {file_name} for task {task_id}: {e}")
+                file_data = None
+        
+        try:
+            # Pass both question text and file data to agent
+            if file_data:
+                # Create enhanced question with file context
+                enhanced_question = f"{question_text}\n\n[File attached: {file_name} - base64 encoded data available]"
+                agent_result = agent(enhanced_question, file_data=file_data, file_name=file_name)
+            else:
+                agent_result = agent(question_text)
+            
+            # Extract answer and additional info from agent result
+            # Extract data from the trace structure
+            trace = agent_result  # The entire trace is now the result
+            final_result = trace.get("final_result", {})
+            submitted_answer = final_result.get("submitted_answer", "N/A")
+            
+            # Use helper function to ensure valid answer
+            submitted_answer = ensure_valid_answer(submitted_answer)
+            
+            reference_similarity = final_result.get("similarity_score", 0.0)
+            llm_used = final_result.get("llm_used", "unknown")
+            reference_answer = final_result.get("reference", "N/A")
+            question_text = trace.get("question", "")
+            file_name = trace.get("file_name", "")
+        
+            
+            answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
+            results_log.append({
+                "task_id": task_id, 
+                "trace": trace,
+                "full_debug": ""
+            })
+            # Shorter results for dataframe for gradio table 
+            results_log_df.append({
+                "task_id": task_id, 
+                "question": question_text, 
+                "file_name": file_name, 
+                "submitted_answer": submitted_answer,
+                "reference_answer": reference_answer,
+                "reference_similarity": reference_similarity,
+                "llm_used": llm_used
+            })
+        except Exception as e:
+            print(f"Error running agent on task {task_id}: {e}")
+            results_log.append({
+                "task_id": task_id, 
+                "question": question_text, 
+                "file_name": file_name, 
+                "submitted_answer": f"AGENT ERROR: {e}",
+                "reference_answer": reference_answer,
+                "reference_similarity": 0.0,
+                "llm_used": "none",
+                "trace": trace, 
+                "full_debug": "",
+                "error": str(e)
+            })
+            results_log_df.append({
+                "task_id": task_id, 
+                "question": question_text, 
+                "file_name": file_name, 
+                "submitted_answer": f"AGENT ERROR: {e}",
+                "reference_answer": "N/A",
+                "reference_similarity": 0.0,
+                "llm_used": "none"
+            })
+
+    # --- Convert results to dataframe ---
+    results_df = pd.DataFrame(results_log_df)
+    
+    if not answers_payload:
+        print("Agent did not produce any answers to submit.")
+        return "Agent did not produce any answers to submit.", results_df
+
+
+    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    
+    # Note: Questions will be uploaded after evaluator response with final scores
+    print(f"📊 Prepared {len(results_log)} questions for evaluation")
+
+    # 4. Prepare Submission
+    submission_data = {"username": username.strip(), "agent_code": agent_code, "answers": answers_payload}
+    status_update = f"Agent finished. Submitting {len(answers_payload)} answers for user '{username}'..."
+    print(status_update)
+
+    # 5. Submit
+    total_score = "N/A (not evaluated)"
+    print(f"Submitting {len(answers_payload)} answers to: {submit_url}")
+    try:
+        response = requests.post(submit_url, json=submission_data, timeout=60)
+        response.raise_for_status()
+        result_data = response.json()
+        status_message = (
+            f"Submission Successful!\n"
+            f"User: {result_data.get('username')}\n"
+            f"Overall Score: {result_data.get('score', 'N/A')}% "
+            f"({result_data.get('correct_count', '?')}/{result_data.get('total_attempted', '?')} correct)\n"
+            f"Message: {result_data.get('message', 'No message received.')}"
+        )
+        print(status_message)
+        print("Submission successful.")
+        # Extract just the score percentage from the result data
+        total_score = f"{result_data.get('score', 'N/A')}% ({result_data.get('correct_count', '?')}/{result_data.get('total_attempted', '?')} correct)"
+            
+    except Exception as e:
+        status_message = f"Submission Failed: {e}"
+        print(status_message)
+        # Set error score result
+        total_score = "N/A (Submission Failed)"
+        
+        print(f"⚠️ Submission failed: {e}")
+            
+    # Upload questions once after submission attempt (success or failure)
+    try:
+        if len(results_log) > 0:
+            print(f"✅ Uploading all questions with results: {timestamp}")
+            successful_uploads = upload_questions_with_results(results_log, timestamp, username, total_score, "final")
+            
+            # Log complete evaluation run status
+            if successful_uploads == len(results_log):
+                print(f"✅ All evaluation runs uploaded with results: {timestamp}")
+            else:
+                print(f"⚠️ Failed to upload some evaluation runs: {successful_uploads}/{len(results_log)} questions uploaded")
+    except Exception as e:
+        print(f"⚠️ Upload failed: {e}")
+        
+    return status_message, results_df
+
+def get_dataset_stats_html():
+    """
+    Get dataset statistics and return as HTML.
+    """
+    try:
+        from datasets import load_dataset
+        
+        # Load each config separately
+        configs = ['init', 'runs_new']
+        stats_html = "<div style='margin: 20px 0; padding: 15px; background: #f5f5f5; border-radius: 8px;'>"
+        stats_html += "<h3>📊 Dataset Statistics</h3>"
+        
+        for config_name in configs:
+            try:
+                # Load specific config
+                config_data = load_dataset("arterm-sedov/agent-course-final-assignment", config_name)
+                
+                stats_html += f"<div style='margin: 15px 0; padding: 10px; background: #e9ecef; border-radius: 5px;'>"
+                stats_html += f"<h4>🔧 Config: {config_name.upper()}</h4>"
+                
+                # Get statistics for each split in this config
+                for split_name in config_data.keys():
+                    split_data = config_data[split_name]
+                    stats_html += f"<div style='margin: 8px 0;'>"
+                    stats_html += f"<strong>{split_name.upper()} Split:</strong> {len(split_data)} records"
+                    stats_html += "</div>"
+                
+                # Add latest run info for runs_new config
+                if config_name == "runs_new" and "default" in config_data:
+                    runs_new_data = config_data["default"]
+                    if len(runs_new_data) > 0:
+                        latest_run = runs_new_data[-1]
+                        stats_html += f"<div style='margin: 10px 0; padding: 8px; background: #d4edda; border-radius: 3px;'>"
+                        stats_html += f"<strong>Latest Run:</strong> {latest_run.get('run_id', 'N/A')}"
+                        stats_html += f"<br><strong>Total Score:</strong> {latest_run.get('total_score', 'N/A')}"
+                        stats_html += f"<br><strong>Username:</strong> {latest_run.get('username', 'N/A')}"
+                        stats_html += "</div>"
+                
+                stats_html += "</div>"
+                
+            except Exception as config_error:
+                stats_html += f"<div style='margin: 15px 0; padding: 10px; background: #f8d7da; border-radius: 5px;'>"
+                stats_html += f"<h4>❌ Config: {config_name.upper()}</h4>"
+                stats_html += f"<div style='margin: 8px 0; color: #721c24;'>Error loading config: {config_error}</div>"
+                stats_html += "</div>"
+        
+        stats_html += "</div>"
+        return stats_html
+        
+    except Exception as e:
+        return f"<div style='margin: 20px 0; padding: 15px; background: #fff3cd; border: 1px solid #ffeaa7; border-radius: 8px;'>⚠️ Could not load dataset statistics: {e}</div>"
+
+def get_logs_html():
+    logs_dir = "logs"
+    rows = []
+    files = []
+    
+    # Get space ID for repository links
+    space_id = os.getenv("SPACE_ID", "arterm-sedov/agent-course-final-assignment")
+    repo_base_url = f"https://huggingface.co/spaces/{space_id}/resolve/main"
+    
+    if os.path.exists(logs_dir):
+        for fname in os.listdir(logs_dir):
+            fpath = os.path.join(logs_dir, fname)
+            if os.path.isfile(fpath):
+                timestamp, dt = extract_timestamp_from_filename(fname)
+                if not dt:
+                    # Fallback to modification time for files without timestamp in filename
+                    dt = datetime.datetime.fromtimestamp(os.path.getmtime(fpath))
+                    timestamp = dt.strftime('%Y-%m-%d %H:%M:%S (mtime)')
+                files.append((fname, timestamp, dt, fpath))
+        # Sort all files by datetime descending (newest first)
+        files.sort(key=lambda x: x[2], reverse=True)
+        for fname, timestamp, dt, fpath in files:
+            # Create repository download link
+            repo_download_url = f"{repo_base_url}/logs/{fname}?download=true"
+            download_link = f'<a href="{repo_download_url}" target="_blank" rel="noopener noreferrer">Download from Repo</a>'
+            date_str = dt.strftime('%Y-%m-%d %H:%M:%S')
+            rows.append(f"<tr><td>{fname}</td><td>{date_str}</td><td>{download_link}</td></tr>")
+    
+    table_html = (
+        "<table border='1' style='width:100%;border-collapse:collapse;'>"
+        "<thead><tr><th>File Name</th><th>Date/Time</th><th>Download</th></tr></thead>"
+        "<tbody>" + "".join(rows) + "</tbody></table>"
+    )
+    return table_html
+
+def extract_timestamp_from_filename(filename):
+    """
+    Extract timestamp from filename using comprehensive regex patterns for all log formats in @/logs.
+    Returns (timestamp_str, datetime_obj) or (None, None) if no timestamp found.
+    """
+    import re
+    
+    # Handle multiple extensions by removing all extensions
+    name = filename
+    while '.' in name:
+        name = os.path.splitext(name)[0]
+    
+    # 1. 14-digit datetime: YYYYMMDDHHMMSS (must be exact 14 digits)
+    m = re.match(r'^(\d{14})$', name)
+    if m:
+        timestamp_str = m.group(1)
+        try:
+            dt = datetime.datetime.strptime(timestamp_str, "%Y%m%d%H%M%S")
+            return timestamp_str, dt
+        except ValueError:
+            pass
+    
+    # 2. Leaderboard format: 2025-07-02 090007
+    m = re.search(r'(\d{4})-(\d{2})-(\d{2})[ _]+(\d{2})(\d{2})(\d{2})', name)
+    if m:
+        y, mo, d, h, mi, s = m.groups()
+        try:
+            dt = datetime.datetime.strptime(f"{y}{mo}{d}{h}{mi}{s}", "%Y%m%d%H%M%S")
+            return f"{y}-{mo}-{d} {h}:{mi}:{s}", dt
+        except ValueError:
+            pass
+    
+    # 3. LOG prefix with 12-digit timestamp: LOG202506281412
+    m = re.match(r'^LOG(\d{12})$', name)
+    if m:
+        timestamp_str = m.group(1)
+        try:
+            dt = datetime.datetime.strptime(timestamp_str, "%Y%m%d%H%M%S")
+            return f"LOG{timestamp_str}", dt
+        except ValueError:
+            pass
+    
+    # 4. LOG prefix with 8-digit date and optional suffix: LOG20250628_2, LOG20250629_1
+    m = re.match(r'^LOG(\d{8})(?:_(\d+))?$', name)
+    if m:
+        date_str, suffix = m.groups()
+        try:
+            dt = datetime.datetime.strptime(date_str, "%Y%m%d")
+            timestamp_str = f"LOG{date_str}"
+            if suffix:
+                timestamp_str += f"_{suffix}"
+            return timestamp_str, dt
+        except ValueError:
+            pass
+    
+    # 5. INIT prefix with date and time: INIT_20250704_000343
+    m = re.match(r'^INIT_(\d{8})_(\d{6})$', name)
+    if m:
+        date_str, time_str = m.groups()
+        try:
+            dt = datetime.datetime.strptime(f"{date_str}{time_str}", "%Y%m%d%H%M%S")
+            return f"INIT_{date_str}_{time_str}", dt
+        except ValueError:
+            pass
+    
+    # 6. Date with underscore and time: 20250702_202757, 20250703_135654
+    m = re.match(r'^(\d{8})_(\d{6})$', name)
+    if m:
+        date_str, time_str = m.groups()
+        try:
+            dt = datetime.datetime.strptime(f"{date_str}{time_str}", "%Y%m%d%H%M%S")
+            return f"{date_str}_{time_str}", dt
+        except ValueError:
+            pass
+    
+    # 7. Date only (8 digits): 20250628
+    m = re.match(r'^(\d{8})$', name)
+    if m:
+        date_str = m.group(1)
+        try:
+            dt = datetime.datetime.strptime(date_str, "%Y%m%d")
+            return date_str, dt
+        except ValueError:
+            pass
+    
+    # 8. Files with no timestamp pattern (like "Score 60.log")
+    # These will return None and fall back to modification time
+    
+    return None, None
+
+def save_results_log(results_log: list) -> str:
+    """
+    Save the complete results log to a file and upload via API.
+    
+    Args:
+        results_log (list): List of dictionaries containing task results
+        
+    Returns:
+        str: Path to the saved log file, or None if failed
+    """
+    try:
+        # Create traces directory if it doesn't exist
+        os.makedirs(TRACES_DIR, exist_ok=True)
+        
+        # Generate timestamp
+        timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        # Prepare log content
+        log_content = json.dumps(results_log, indent=2, ensure_ascii=False)
+        log_path = f"{TRACES_DIR}/{timestamp}_llm_trace.log"
+        
+        return log_path
+        
+    except Exception as e:
+        print(f"⚠️ Failed to save results log: {e}")
+        return None
+
+
+
+# --- Build Gradio Interface using Blocks ---
+with gr.Blocks() as demo:
+    gr.Markdown("# CMW Platform Agent Evaluation Runner by Arte(r)m Sedov")
+    
+
+    with gr.Tabs():
+        with gr.TabItem("Readme"):
+            gr.Markdown("""
+            ## 🕵🏻‍♂️ CMW Platform Agent - Experimental Project
+
+            **Welcome to my graduation project for the HuggingFace Agents Course!**
+            
+            ### 🚀 **What is this project**:
+            
+            - **Input**: HuggingFace supplies a set of curated CMW Platform Agent questions
+            - **Challenge**: Create an agent that gets a score of at least 30% on the CMW Platform Agent questions
+            - **Solution**: The agent tries to get the right answers: it cycles through several LLMs and tools to get the best answer
+            - **Results**: The agent can get up to 80% score depending on the available LLMs. Typically it gets 50-65% score (because I often run out of LLM providers inference limits on the free tiers)
+            
+            **Dataset Results**: [View live results](https://huggingface.co/datasets/arterm-sedov/agent-course-final-assignment/viewer/runs_new)
+            
+            **For more project details**, see the [README.md](https://huggingface.co/spaces/arterm-sedov/agent-course-final-assignment/blob/main/README.md)
+            
+            This is an experimental multi-LLM agent system that demonstrates advanced AI agent capabilities. I created this project to explore and showcase:
+
+            ### 🎯 **Project Goals**
+            
+            - **Multi-LLM Orchestration**: Dynamically switches between Google Gemini, Groq, OpenRouter, and HuggingFace models
+            - **Comprehensive Tool Suite**: Math, code execution, web search, file analysis, chess, and more
+            - **Robust Fallback System**: Automatic model switching when one fails
+            - **Complete Transparency**: Full trace logging of reasoning and tool usage
+            - **Real-world Reliability**: Battle-tested for the CMW Platform benchmark
+
+            ### 🔬 **Why This Project?**
+            
+            This project represents what I learned at HuggingFace Agents Course, eg. to build sophisticated AI agents. The experimental nature comes from:
+
+            - **Multi-Provider Testing**: Exploring different LLM providers and their capabilities, all providers are free of charge and thus may fail
+            - **Tool Integration**: Creating a modular system where tools can chain together
+            - **Performance Optimization**: Balancing speed, accuracy, logging verbosity and cost across multiple models
+            - **Transparency**: Making AI reasoning visible and debuggable
+
+            ### 📊 **What You'll Find Here**
+            
+            - **Live Evaluation**: Test the agent against CMW Platform questions. See the **Evaluation** tab. 
+                - When starting, the agent talks to LLMs and initializes them and outputs some interesting debugging logs. Select **Logs** at the top to vew the init log.
+                - NOTE: LLM availability is subject to my inference limits with each provider
+            - **Dataset Tracking**: All runs are uploaded to the HuggingFace dataset for analysis. See the the **Dataset** tab
+            - **Performance Metrics**: Detailed timing, token usage, and success rates. See the the **Dataset** tab
+            - **Complete Traces**: See exactly how the agent thinks and uses tools. See the **Log files** tab
+
+            This course project is a demonstration of what's possible when you combine multiple AI models with intelligent tool orchestration.
+            """)
+        
+        with gr.TabItem("Evaluation"):
+            gr.Markdown(
+            """
+        
+            **Instructions:**
+            
+            **If you want to test the agent**
+            
+            1. Click **Run Evaluation & Submit All Answers** to fetch questions, run your agent, submit answers, and see the score.
+            2. Once you clicked **Run Evaluation & Submit All Answers**, it can take quite some time (this is the time for the agent to go through all the questions). This space provides a basic setup and is sub-optimal.
+            3. Select **Logs** at the top of the screen and watch the action unfold in real time while the agent cycles through the questions and LLMs.
+            4. While the agent runs, from the **Log files** download some sample agent traces.
+            5. When the run completes, the agent should upload all the results to the **Dataset** tab.
+            
+            **If you want to copy the agent**
+            
+            1. Clone this space, then modify the code to define your agent's logic, the tools, the necessary packages, etc...
+            2. Complete the HuggingFace Agents Course: <https://huggingface.co/learn/agents-course/en/unit0/introduction>.
+            2. Log in to your HuggingFace account using the button below. This uses your HF username for submission.
+            3. Click **Run Evaluation & Submit All Answers** to fetch questions, run your agent, submit answers, and see the score.
+            
+            """
+            )
+            gr.LoginButton()
+            run_button = gr.Button("Run Evaluation & Submit All Answers")
+            status_output = gr.Textbox(label="Run Status / Submission Result", lines=5, interactive=False)
+            results_table = gr.DataFrame(label="Questions and Agent Answers", wrap=True)
+            # Note: get_init_log() returns a value but demo.load() doesn't expect outputs
+            # This is just for initialization, so we ignore the return value
+            demo.load(
+                fn=lambda: None,  # Use a no-op function instead
+                inputs=[]
+            )
+            run_button.click(
+                fn=run_and_submit_all,
+                outputs=[status_output, results_table]
+            )
+        with gr.TabItem("Results dataset"):
+            
+            gr.Markdown(
+                """
+                ## Live Dataset viewer
+                
+                View the latest evaluation runs uploaded to the HuggingFace dataset.
+                
+                **Dataset URL:** [arterm-sedov/agent-course-final-assignment](https://huggingface.co/datasets/arterm-sedov/agent-course-final-assignment)
+                
+                **Runs dataset:** [View and query latest runs in Data Studio with SQL](https://huggingface.co/datasets/arterm-sedov/agent-course-final-assignment/viewer/runs_new)
+                
+                > **Note:** The dataset viewer may show schema conflicts between different splits (init, runs, runs_new). This is expected as each split has different schemas. The `runs_new` split contains the latest granular evaluation data.
+                """
+            )
+            
+            # Embed the dataset viewer
+            vew_params = "?sort[column]=start_time&sort[direction]=desc"
+            dataset_viewer_html = f"""
+            <div style="width: 100%; height: 600px; border: 1px solid #ccc; border-radius: 8px; overflow: hidden;">
+                <iframe
+                  src="https://huggingface.co/datasets/arterm-sedov/agent-course-final-assignment/embed/viewer/runs_new/train{vew_params}"
+                  frameborder="0"
+                  width="100%"
+                  height="560px"
+                ></iframe>
+            </div>
+            """
+            gr.HTML(dataset_viewer_html)
+            dataset_stats_output = gr.HTML(get_dataset_stats_html())
+            refresh_stats_btn = gr.Button("🔄 Refresh Dataset Statistics")
+            refresh_stats_btn.click(fn=get_dataset_stats_html, outputs=dataset_stats_output)
+        with gr.TabItem("Log files"):
+            gr.Markdown("## Log files download links")
+            gr.Markdown("The `YYYMMDD_hhmmss_llm_trace.log` files contain complete traces of LLM initialization and calling.")
+            gr.Markdown("The `20250706_141040_score.results..csv` files contain submission and HuggingFace evaluation results.")
+            gr.HTML(get_logs_html())
+
+if __name__ == "__main__":
+    print("\n" + "-"*30 + " App Starting " + "-"*30)
+    space_host_startup = os.getenv("SPACE_HOST")
+    space_id_startup = os.getenv("SPACE_ID")
+
+    if space_host_startup:
+        print(f"✅ SPACE_HOST found: {space_host_startup}")
+        print(f"   Runtime URL should be: https://{space_host_startup}.hf.space")
+    else:
+        print("ℹ️  SPACE_HOST environment variable not found (running locally?).")
+
+    if space_id_startup:
+        print(f"✅ SPACE_ID found: {space_id_startup}")
+        print(f"   Repo URL: https://huggingface.co/spaces/{space_id_startup}")
+        print(f"   Repo Tree URL: https://huggingface.co/spaces/{space_id_startup}/tree/main")
+    else:
+        print("ℹ️  SPACE_ID environment variable not found (running locally?). Repo URL cannot be determined.")
+
+    print("-"*(60 + len(" App Starting ")) + "\n")
+
+    print("Launching Gradio Interface for CMW Platform Agent Evaluation...")
+    
+    demo.launch(debug=True, share=False)

packages.txt

@@ -0,0 +1 @@
+tesseract-ocr 

requirements.txt

@@ -0,0 +1,43 @@
+# Core dependencies for Hugging Face Space and Linux deployment
+gradio
+requests
+#langchain
+langchain-community
+langchain-openai
+langchain-core
+langchain-google-genai
+langchain-huggingface
+langchain-groq
+langchain-tavily
+langchain-chroma
+langgraph
+huggingface_hub
+supabase
+arxiv
+pymupdf
+wikipedia
+pgvector
+python-dotenv
+pytesseract
+matplotlib
+pandas
+numpy
+pillow
+jupyter
+openpyxl
+beautifulsoup4
+lxml
+sentence-transformers
+google-genai
+litellm
+scipy
+scikit-learn
+sympy
+networkx
+nltk
+opencv-python
+python-chess
+tiktoken
+exa-py
+openai
+chess

setup_venv.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""
+Cross-platform virtual environment setup and dependency installation for arterm-sedov.
+Supports both Windows and Linux/macOS environments.
+
+This script:
+1. Creates a virtual environment
+2. Installs dependencies using platform-specific requirements files
+3. Handles platform-specific issues automatically
+4. Provides comprehensive error handling and user feedback
+
+Usage:
+    python setup_venv.py [--skip-venv] [--skip-deps] [--verbose]
+"""
+
+import os
+import sys
+import subprocess
+import platform
+import shutil
+from pathlib import Path
+import argparse
+
+def print_status(message, status="INFO"):
+    """Print a formatted status message."""
+    colors = {
+        "INFO": "\033[94m",    # Blue
+        "SUCCESS": "\033[92m", # Green
+        "WARNING": "\033[93m", # Yellow
+        "ERROR": "\033[91m",   # Red
+        "RESET": "\033[0m"     # Reset
+    }
+    
+    if platform.system() == "Windows" and not os.environ.get("TERM"):
+        # Windows without color support
+        print(f"[{status}] {message}")
+    else:
+        # Unix-like systems or Windows with color support
+        color = colors.get(status, colors["INFO"])
+        reset = colors["RESET"]
+        print(f"{color}[{status}]{reset} {message}")
+
+def run_command(command, check=True, capture_output=True, shell=False):
+    """
+    Run a command and return the result.
+    
+    Args:
+        command: Command to run (list or string)
+        check: Whether to raise exception on non-zero exit code
+        capture_output: Whether to capture stdout/stderr
+        shell: Whether to run in shell mode
+    
+    Returns:
+        subprocess.CompletedProcess object
+    """
+    try:
+        if isinstance(command, str) and not shell:
+            command = command.split()
+        
+        result = subprocess.run(
+            command,
+            check=check,
+            capture_output=capture_output,
+            shell=shell,
+            text=True
+        )
+        return result
+    except subprocess.CalledProcessError as e:
+        print_status(f"Command failed: {' '.join(command) if isinstance(command, list) else command}", "ERROR")
+        print_status(f"Exit code: {e.returncode}", "ERROR")
+        if e.stdout:
+            print(f"STDOUT: {e.stdout}")
+        if e.stderr:
+            print(f"STDERR: {e.stderr}")
+        raise
+
+def get_python_command():
+    """Get the appropriate python command for the current platform."""
+    if platform.system() == "Windows":
+        return "python"
+    else:
+        return "python3"
+
+def check_python_version():
+    """Check if Python version is compatible (3.8+)."""
+    version = sys.version_info
+    if version.major < 3 or (version.major == 3 and version.minor < 8):
+        print_status("Python 3.8+ is required", "ERROR")
+        print_status(f"Current version: {version.major}.{version.minor}.{version.micro}", "ERROR")
+        return False
+    
+    print_status(f"Python version: {version.major}.{version.minor}.{version.micro}", "SUCCESS")
+    return True
+
+def create_virtual_environment():
+    """Create a virtual environment."""
+    venv_path = Path("venv")
+    
+    if venv_path.exists():
+        print_status("Virtual environment already exists", "WARNING")
+        response = input("Do you want to recreate it? (y/N): ").strip().lower()
+        if response != 'y':
+            print_status("Using existing virtual environment", "INFO")
+            return True
+        else:
+            print_status("Removing existing virtual environment...", "INFO")
+            shutil.rmtree(venv_path)
+    
+    print_status("Creating virtual environment...", "INFO")
+    python_cmd = get_python_command()
+    
+    try:
+        run_command([python_cmd, "-m", "venv", "venv"])
+        print_status("Virtual environment created successfully", "SUCCESS")
+        return True
+    except subprocess.CalledProcessError:
+        print_status("Failed to create virtual environment", "ERROR")
+        return False
+
+def get_activation_command():
+    """Get the activation command for the current platform."""
+    if platform.system() == "Windows":
+        return "venv\\Scripts\\activate"
+    else:
+        return "source venv/bin/activate"
+
+def get_python_path():
+    """Get the path to the virtual environment's Python executable."""
+    if platform.system() == "Windows":
+        return "venv\\Scripts\\python.exe"
+    else:
+        return "venv/bin/python"
+
+def get_pip_path():
+    """Get the path to the virtual environment's pip executable."""
+    if platform.system() == "Windows":
+        return "venv\\Scripts\\pip.exe"
+    else:
+        return "venv/bin/pip"
+
+def get_requirements_file():
+    """Get the appropriate requirements file based on the platform."""
+    if platform.system() == "Windows":
+        requirements_file = "requirements.win.txt"
+        if Path(requirements_file).exists():
+            print_status(f"Using Windows-specific requirements: {requirements_file}", "INFO")
+            return requirements_file
+        else:
+            print_status("Windows requirements file not found, using main requirements.txt", "WARNING")
+            return "requirements.txt"
+    else:
+        print_status("Using main requirements.txt for Linux/macOS", "INFO")
+        return "requirements.txt"
+
+def install_dependencies():
+    """Install dependencies using the appropriate requirements file."""
+    pip_cmd = get_pip_path()
+    python_cmd = get_python_path()
+    requirements_file = get_requirements_file()
+    
+    print_status("Installing dependencies...", "INFO")
+    
+    # Check if requirements file exists
+    if not Path(requirements_file).exists():
+        print_status(f"Requirements file {requirements_file} not found", "ERROR")
+        return False
+    
+    # Step 1: Upgrade pip using python -m pip
+    print_status("Upgrading pip...", "INFO")
+    try:
+        run_command([python_cmd, "-m", "pip", "install", "--upgrade", "pip"])
+        print_status("Pip upgraded successfully", "SUCCESS")
+    except subprocess.CalledProcessError:
+        print_status("Failed to upgrade pip, continuing...", "WARNING")
+    
+    # Step 2: Install build tools
+    print_status("Installing build tools...", "INFO")
+    try:
+        run_command([pip_cmd, "install", "wheel", "setuptools"])
+    except subprocess.CalledProcessError:
+        print_status("Failed to install build tools, continuing...", "WARNING")
+    
+    # Step 3: Install dependencies from requirements file
+    print_status(f"Installing dependencies from {requirements_file}...", "INFO")
+    try:
+        run_command([pip_cmd, "install", "-r", requirements_file])
+        print_status("All dependencies installed successfully", "SUCCESS")
+        return True
+        
+    except subprocess.CalledProcessError as e:
+        print_status(f"Failed to install dependencies from {requirements_file}", "ERROR")
+        
+        # If Windows requirements failed, try main requirements as fallback
+        if platform.system() == "Windows" and requirements_file == "requirements.win.txt":
+            print_status("Trying main requirements.txt as fallback...", "WARNING")
+            try:
+                run_command([pip_cmd, "install", "-r", "requirements.txt"])
+                print_status("Dependencies installed using main requirements.txt", "SUCCESS")
+                print_status("Note: TensorFlow not installed - sentence-transformers may not work optimally", "WARNING")
+                print_status("To install TensorFlow manually, try:", "INFO")
+                print_status("  pip install tensorflow-cpu", "INFO")
+                print_status("  or", "INFO")
+                print_status("  pip install tensorflow", "INFO")
+                return True
+            except subprocess.CalledProcessError:
+                print_status("Both requirements files failed", "ERROR")
+                return False
+        
+        return False
+
+def verify_installation():
+    """Verify that the installation was successful."""
+    print_status("Verifying installation...", "INFO")
+    
+    python_cmd = get_python_path()
+    
+    # Test imports
+    test_imports = [
+        "numpy",
+        "pandas", 
+        "requests",
+        "google.genai",
+        "langchain",
+        "supabase",
+        "gradio"
+    ]
+    
+    failed_imports = []
+    
+    for module in test_imports:
+        try:
+            run_command([python_cmd, "-c", f"import {module}"], capture_output=True)
+            print_status(f"✓ {module}", "SUCCESS")
+        except subprocess.CalledProcessError:
+            print_status(f"✗ {module}", "ERROR")
+            failed_imports.append(module)
+    
+    if failed_imports:
+        print_status(f"Failed to import: {', '.join(failed_imports)}", "ERROR")
+        return False
+    
+    # Test version info
+    try:
+        result = run_command([python_cmd, "-c", "import pandas as pd; print(f'Pandas version: {pd.__version__}')"], capture_output=True)
+        print_status(result.stdout.strip(), "INFO")
+    except subprocess.CalledProcessError:
+        print_status("Could not get pandas version", "WARNING")
+    
+    print_status("Installation verification completed", "SUCCESS")
+    return True
+
+def main():
+    """Main function."""
+    parser = argparse.ArgumentParser(description="Setup virtual environment and install dependencies")
+    parser.add_argument("--skip-venv", action="store_true", help="Skip virtual environment creation")
+    parser.add_argument("--skip-deps", action="store_true", help="Skip dependency installation")
+    parser.add_argument("--verbose", action="store_true", help="Enable verbose output")
+    
+    args = parser.parse_args()
+    
+    print_status("=" * 60, "INFO")
+    print_status("arterm-sedov Setup Script", "INFO")
+    print_status("=" * 60, "INFO")
+    print_status(f"Platform: {platform.system()} {platform.release()}", "INFO")
+    print_status(f"Python: {sys.executable}", "INFO")
+    print_status("=" * 60, "INFO")
+    
+    # Check Python version
+    if not check_python_version():
+        sys.exit(1)
+    
+    # Create virtual environment
+    if not args.skip_venv:
+        if not create_virtual_environment():
+            sys.exit(1)
+    else:
+        print_status("Skipping virtual environment creation", "INFO")
+    
+    # Install dependencies
+    if not args.skip_deps:
+        if not install_dependencies():
+            sys.exit(1)
+    else:
+        print_status("Skipping dependency installation", "INFO")
+    
+    # Verify installation
+    if not args.skip_deps:
+        if not verify_installation():
+            print_status("Installation verification failed", "ERROR")
+            sys.exit(1)
+    
+    # Print next steps
+    print_status("=" * 60, "INFO")
+    print_status("Setup completed successfully!", "SUCCESS")
+    print_status("=" * 60, "INFO")
+    print_status("Next steps:", "INFO")
+    print_status("1. Activate the virtual environment:", "INFO")
+    print_status(f"   {get_activation_command()}", "INFO")
+    print_status("2. Set up your environment variables in .env file:", "INFO")
+    print_status("   GEMINI_KEY=your_gemini_api_key", "INFO")
+    print_status("   SUPABASE_URL=your_supabase_url", "INFO")
+    print_status("   SUPABASE_KEY=your_supabase_key", "INFO")
+    print_status("3. Run the agent:", "INFO")
+    print_status("   python app.py", "INFO")
+    print_status("=" * 60, "INFO")
+
+if __name__ == "__main__":
+    main() 

system_prompt.json

@@ -0,0 +1,316 @@
+{
+    "role": "You are an agent. You have to answer a question using a set of tools.",
+    "answer_format": {
+        "template": "FINAL ANSWER: [YOUR ANSWER]",
+        "answer_rules": [
+            "Answer must start with 'FINAL ANSWER:' followed by the answer.",
+            "Try to give the final answer as soon as possible.",
+            "Output no explanations, no extra text—just the answer."
+        ],
+        "answer_types": [
+            "A number (no commas, no units unless specified)",
+            "A few words (no articles, no abbreviations)",
+            "A comma-separated list if asked for multiple items",
+            "Number OR as few words as possible OR a comma separated list of numbers and/or strings",
+            "If asked for a number, do not use commas or units unless specified",
+            "If asked for a string, do not use articles or abbreviations, write digits in plain text unless specified",
+            "For comma separated lists, apply the above rules to each element"
+        ]
+    },
+    "length_rules": {
+        "ideal": "1-10 words (or 1 to 30 tokens)",
+        "maximum": "50 words",
+        "not_allowed": "More than 50 words",
+        "if_too_long": "Reiterate, reuse tools, and answer again"
+    },
+    "research_approach": "Act step-by-step. Use your reasoning to the maximum, try various ideas. You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.",
+    "research_steps": [
+        {
+            "step": 0,
+            "action": "Use web_search_deep_research_exa_ai tool — ask directly the original question. Get the FINAL ANSWER candidate and supporting references.",
+            "criteria": "The question is text. Get reference from a deep research tool and then use it in your further reasoning."
+        },
+        {
+            "step": 1,
+            "action": "Consider the question carefully.",
+            "criteria": "If you can answer with your own judgement and the reference you already have from the web_search_deep_research_exa_ai tool."
+        },
+        {
+            "step": 2,
+            "action": "Think in steps, mull the question thoroughly.",
+            "note": "Think very deeply, consider various angles."
+        },
+        {
+            "step": 3,
+            "action": "Consider using additional tools as needed.",
+            "criteria": "Contemplate which tools to select before using."
+        },
+        {
+            "step": 4,
+            "action": "Use or execute code if you need and can.",
+            "criteria": "Check for internal or external code execution capabilities."
+        },
+        {
+            "step": 5,
+            "action": "Call each tool once per question. Then call other tools. Change tool arguments if you call it twice.",
+            "criteria": "Calling different tools with different arguments will give you broader perspective."
+        },
+        {
+            "step": 6,
+            "action": "If you get an empty or error response from a tool, call another tool.",
+            "criteria": "Do not call the same tool repeatedly."
+        },
+        {
+            "step": 7,
+            "action": "If you need multiple tools, call each one once, then analyze the results.",
+            "criteria": "Different search and reference tools give various results for better overview."
+        },
+        {
+            "step": 8,
+            "action": "After getting tool results, analyze them thoroughly and provide your FINAL ANSWER.",
+            "criteria": "Use your judgement to condense the tool results into the FINAL ANSWER."
+        },
+        {
+            "step": 9,
+            "action": "Never call a tool with the same arguments.",
+            "criteria": "Do not make duplicate tool calls or infinite loops."
+        },
+        {
+            "step": 10,
+            "action": "Use tools to gather information, then stop and provide your answer."
+        },
+        {
+            "step": 11,
+            "action": "Do not call the same tool with the same or similar query more than once per question.",
+            "criteria": "Repetitive calls with same arguments will give the no new information."
+        },
+        {
+            "step": 12,
+            "action": "Avoid requesting large outputs.",
+            "criteria": "Always ask for concise or summarized results."
+        },
+        {
+            "step": 13,
+            "action": "If a tool returns a large result, summarize it before further use.",
+            "criteria": "Avoid overloading the LLM."
+        },
+        {
+            "step": 14,
+            "action": "Do not loop or repeat tool calls if the answer is not found.",
+            "criteria": "Provide your best answer based on available information."
+        }
+    ],
+    "tool_usage_strategy": {
+        "web_and_search_tools": {
+            "purpose": "Retrieve up-to-date or external information from the web, Wikipedia, Arxiv, or AI-powered search.",
+            "when_to_use": [
+                "Use when the answer depends on current events, facts, or knowledge not available internally.",
+                "Follow search tool priority: (1) web_search_deep_research_exa_ai, (2) arxiv_search or wiki_search, (3) web_search.",
+                "Use each search tool only once per question and analyze results before proceeding."
+            ]
+        },
+        "math_tools": {
+            "purpose": "Perform basic arithmetic or mathematical operations directly when the question requires calculation.",
+            "when_to_use": [
+                "Use when the answer requires a direct computation (e.g., sum, product, difference, division, modulus, power, square root).",
+                "Prefer these tools over web or code execution for simple math."
+            ]
+        },
+        "code_execution_tools": {
+            "purpose": "Run code in various languages to solve computational, data processing, or logic tasks.",
+            "when_to_use": [
+                "Use when the question requires running code, simulations, or complex calculations not easily handled by math tools.",
+                "Choose the language that best fits the code or task provided.",
+                "Do not use for simple arithmetic—prefer math tools for that."
+            ]
+        },
+        "file_and_data_tools": {
+            "purpose": "Read, analyze, or extract information from files (CSV, Excel, images, downloads).",
+            "when_to_use": [
+                "Use when the question references an attached file or requires data extraction from a file.",
+                "Choose the tool that matches the file type (e.g., analyze_csv_file for CSVs, extract_text_from_image for images).",
+                "Do not process the same file with the same query more than once."
+            ]
+        },
+        "image_and_visual_tools": {
+            "purpose": "Analyze, transform, or generate images, or extract information from visual data.",
+            "when_to_use": [
+                "Use when the question involves image content, visual analysis, or requires image generation or modification.",
+                "Select the tool based on the required operation: analysis, transformation, drawing, or combination."
+            ]
+        },
+        "audio_and_video_tools": {
+            "purpose": "Understand, transcribe, or analyze audio and video content.",
+            "when_to_use": [
+                "Use when the question is about the content of an audio or video file or link.",
+                "Provide the relevant prompt and system instructions to guide the analysis."
+            ]
+        },
+        "chess_tools": {
+            "purpose": "Analyze chess positions, convert notations, or solve chess-related questions.",
+            "when_to_use": [
+                "Use when the question involves chess moves, board analysis, or requires best-move suggestions.",
+                "Choose the tool that matches the required chess operation (e.g., get_best_chess_move, convert_chess_move, solve_chess_position)."
+            ]
+        },
+        "general_strategy": [
+            "Always select the tool category that most directly addresses the question.",
+            "Do not use multiple tools of the same category unless required for multi-step reasoning.",
+            "After using a tool, analyze its output before deciding to use another tool.",
+            "Avoid redundant or duplicate tool calls; do not call the same tool with the same or similar arguments more than once per question.",
+            "If a tool returns an error or empty result, try a different tool or approach."
+        ]
+    },
+    "external_information_needed": {
+        "description": "For questions that may benefit from external information and have no attached files:",
+        "tool_usage_order": [
+            {
+                "order": 1,
+                "tool": "web_search_deep_research_exa_ai",
+                "instruction": "Ask original question and get the answer and references."
+            },
+            {
+                "order": 3,
+                "tools": [
+                    "wiki_search",
+                    "arxiv_search"
+                ],
+                "instruction": "Ask targeted queries to get reference materials."
+            },
+            {
+                "order": 2,
+                "tool": "web_search",
+                "instruction": "Ask original question and get relevant search results."
+            }
+        ],
+        "rule": "Use each tool only once per question, in the specified order."
+    },
+    "other_tools_strategy": {
+        "code_execution": {
+            "when_to_use": [
+                "Use code execution tools if the question requires calculations, data processing, or running code to obtain the answer.",
+                "If you have internal code execution capabilities, use them before considering external tools.",
+                "If external code execution tools are available, use them only if internal execution is not possible or insufficient."
+            ],
+            "how_to_use": [
+                "Prepare the code or command needed to answer the question as concisely as possible.",
+                "Execute the code only once per question.",
+                "If the code execution fails or returns an error, do not retry with the same code; consider alternative approaches or tools.",
+                "After execution, analyze the result and use it directly to form your FINAL ANSWER."
+            ],
+            "additional_notes": [
+                "Do not output intermediate code, logs, or thoughts—only the final result.",
+                "If the code output is too large, summarize it before using it in your answer.",
+                "Always ensure the answer format and length rules are followed, even when using code execution results."
+            ]
+        },
+        "file_tools": {
+            "when_to_use": [
+                "If files are attached to the question, use file tools to extract relevant information before considering web or code tools."
+            ],
+            "how_to_use": [
+                "Access the file using the appropriate tool.",
+                "Extract only the information needed to answer the question.",
+                "Do not process the same file with the same query more than once per question."
+            ]
+        },
+        "link_tools": {
+            "when_to_use": [
+                "If links are included in the question, process the linked content with the relevant tool before considering web search."
+            ],
+            "how_to_use": [
+                "Use the appropriate tool to fetch and summarize the linked content.",
+                "Use the summarized information to answer the question."
+            ]
+        }
+    },
+    "critical": "Finish your answer with the following template in one line: FINAL ANSWER: [YOUR ANSWER]",
+    "final_answer_examples": [
+        {
+            "question": "How many albums?",
+            "answer": "FINAL ANSWER: 3"
+        },
+        {
+            "question": "What is the capital?",
+            "answer": "FINAL ANSWER: Paris"
+        },
+        {
+            "question": "Name the colors",
+            "answer": "FINAL ANSWER: red, blue, green"
+        },
+        {
+            "question": "When was it founded?",
+            "answer": "FINAL ANSWER: 1923"
+        },
+        {
+            "question": "Who discovered this?",
+            "answer": "FINAL ANSWER: Marie Curie"
+        },
+        {
+            "question": "What do you need?",
+            "answer": "FINAL ANSWER: flour, sugar, eggs"
+        },
+        {
+            "question": "What is the output?",
+            "answer": "FINAL ANSWER: 2.718"
+        },
+        {
+            "question": "Who was the leader?",
+            "answer": "FINAL ANSWER: Margaret Thatcher"
+        },
+        {
+            "question": "What does it say?",
+            "answer": "FINAL ANSWER: The end is near"
+        },
+        {
+            "question": "What is the mean?",
+            "answer": "FINAL ANSWER: 15.7"
+        },
+        {
+            "question": "What is the title?",
+            "answer": "FINAL ANSWER: Advanced Machine Learning Techniques"
+        },
+        {
+            "question": "Who predicted this?",
+            "answer": "FINAL ANSWER: Albert Einstein"
+        },
+        {
+            "question": "Which two nations?",
+            "answer": "FINAL ANSWER: Canada, Mexico"
+        },
+        {
+            "question": "Who didn't participate?",
+            "answer": "FINAL ANSWER: Alice"
+        },
+        {
+            "question": "Name three chess pieces",
+            "answer": "FINAL ANSWER: king, queen, bishop"
+        },
+        {
+            "question": "List the vegetables",
+            "answer": "FINAL ANSWER: broccoli, celery, lettuce"
+        }
+    ],
+    "obedience_and_output_format": [
+        "You must always output your answer in the format: FINAL ANSWER: <answer> and nothing else.",
+        "Never output explanations, thoughts, or any text except the FINAL ANSWER line.",
+        "If you are Gemini, you must strictly follow these rules and never ignore the answer format."
+    ],
+    "tool_use_discipline": [
+        "Use each tool at most once per question. Never call web_search or wiki_search more than once with similar query.",
+        "If you have enough information to answer, stop using tools and provide your FINAL ANSWER immediately.",
+        "Never call any tool unless you have a clear, specific reason and have planned your approach."
+    ],
+    "tool_usage_limits": {
+        "default": 3,
+        "wiki_search": 2,
+        "web_search": 3,
+        "arxiv_search": 2,
+        "analyze_excel_file": 2,
+        "analyze_csv_file": 2,
+        "analyze_image": 2,
+        "extract_text_from_image": 2,
+        "exa_ai_helper": 1,
+        "web_search_deep_research_exa_ai": 1
+    }
+}

tools.py

@@ -0,0 +1,2405 @@
+# tools.py - Consolidated tools
+# Dependencies are included
+
+import os
+import io
+import json
+import uuid
+import base64
+import shutil
+import requests
+import tempfile
+import urllib.parse
+import numpy as np
+import pandas as pd
+import subprocess
+import sys
+import sqlite3
+import cmath
+import time
+import re
+from PIL import Image, ImageDraw, ImageFont, ImageEnhance, ImageFilter
+from typing import Any, Dict, List, Optional, Union
+import chess
+
+# Try to import matplotlib, but make it optional
+try:
+    import matplotlib.pyplot as plt
+    MATPLOTLIB_AVAILABLE = True
+except ImportError:
+    MATPLOTLIB_AVAILABLE = False
+    plt = None
+
+# Try to import pytesseract for OCR
+try:
+    import pytesseract
+    PYTESSERACT_AVAILABLE = True
+except ImportError:
+    PYTESSERACT_AVAILABLE = False
+    pytesseract = None
+
+# Try to import chess for chess analysis
+try:
+    import chess
+    import chess.engine
+    CHESS_AVAILABLE = True
+except ImportError:
+    CHESS_AVAILABLE = False
+    chess = None
+
+# Always import the tool decorator - it's essential
+from langchain_core.tools import tool
+
+# Global configuration for search tools
+SEARCH_LIMIT = 5  # Maximum number of results for all search tools (Tavily, Wikipedia, Arxiv)
+
+# LangChain imports for search tools
+try:
+    from langchain_tavily import TavilySearch
+    TAVILY_AVAILABLE = True
+except ImportError:
+    TAVILY_AVAILABLE = False
+    print("Warning: TavilySearch not available. Install with: pip install langchain-tavily")
+
+# Try to import wikipedia-api as it's a common dependency
+try:
+    import wikipedia
+    WIKIPEDIA_AVAILABLE = True
+except ImportError as e:
+    WIKIPEDIA_AVAILABLE = False
+    print(f"Wikipedia search requires additional dependencies. Install with: pip install wikipedia-api. Error: {str(e)}")
+
+try:
+    from langchain_community.document_loaders import WikipediaLoader
+    WIKILOADER_AVAILABLE = True
+except ImportError:
+    WIKILOADER_AVAILABLE = False
+    print("Warning: WikipediaLoader not available. Install with: pip install langchain-community")
+
+# Try to import arxiv as it's a common dependency
+try:
+    import arxiv
+    ARXIV_AVAILABLE = True
+except ImportError as e:
+    ARXIV_AVAILABLE = False
+    print(f"Arxiv search requires additional dependencies. Install with: pip install arxiv. Error: {str(e)}")
+
+try:
+    from langchain_community.document_loaders import ArxivLoader
+    ARXIVLOADER_AVAILABLE = True
+except ImportError:
+    ARXIVLOADER_AVAILABLE = False
+    print("Warning: ArxivLoader not available. Install with: pip install langchain-community")
+
+# Try to import Exa for AI-powered answers
+try:
+    from exa_py import Exa
+    EXA_AVAILABLE = True
+except ImportError:
+    EXA_AVAILABLE = False
+    print("Warning: Exa not available. Install with: pip install exa-py")
+
+# Google Gemini imports for video/audio/chess understanding
+try:
+    from google import genai
+    from google.genai import types
+    GEMINI_AVAILABLE = True
+except ImportError:
+    GEMINI_AVAILABLE = False
+    print("Warning: Google Gemini not available. Install with: pip install google-genai")
+
+
+# ========== GEMINI HELPER FUNCTIONS ==========
+def _get_gemini_client():
+    """
+    Initialize and return a Gemini client with proper error handling.
+    Args:
+        model_name (str, optional): The Gemini model to use. If None, defaults to gemini-2.5-flash.
+    Returns:
+        client or None: The Gemini client if initialization succeeds, None otherwise.
+    """
+    if not GEMINI_AVAILABLE:
+        print("Warning: Google Gemini not available. Install with: pip install google-genai")
+        return None
+    try:
+        gemini_key = os.environ.get("GEMINI_KEY")
+        if not gemini_key:
+            print("Warning: GEMINI_KEY not found in environment variables.")
+            return None
+        client = genai.Client(api_key=gemini_key)
+        return client
+    except Exception as e:
+        print(f"Error initializing Gemini client: {str(e)}")
+        return None
+
+def _get_gemini_response(prompt, error_prefix="Gemini", model_name="gemini-2.5-flash"):
+    """
+    Get a response from Gemini with proper error handling.
+    Args:
+        prompt: The prompt to send to Gemini
+        error_prefix (str): Prefix for error messages to identify the calling context
+        model_name (str, optional): The Gemini model to use.
+    Returns:
+        str: The Gemini response text, or an error message if the request fails.
+    """
+    client = _get_gemini_client()
+    if not client:
+        return f"{error_prefix} client not available. Check installation and API key configuration."
+    try:
+        response = client.models.generate_content(
+            model=model_name,
+            contents=prompt
+        )
+        return response.text
+    except Exception as e:
+        return f"Error in {error_prefix.lower()} request: {str(e)}"
+
+# ========== IMAGE PROCESSING HELPERS ==========
+def encode_image(image_path: str) -> str:
+    """
+    Convert an image file to a base64-encoded string.
+
+    Args:
+        image_path (str): The path to the image file to encode.
+
+    Returns:
+        str: The base64-encoded string representation of the image file.
+    """
+    with open(image_path, "rb") as image_file:
+        return base64.b64encode(image_file.read()).decode("utf-8")
+
+def decode_image(base64_string: str) -> Any:
+    """
+    Convert a base64-encoded string to a PIL Image object.
+
+    Args:
+        base64_string (str): The base64-encoded string representing the image.
+
+    Returns:
+        Any: The decoded PIL Image object.
+    """
+    image_data = base64.b64decode(base64_string)
+    return Image.open(io.BytesIO(image_data))
+
+def save_image(image: Any, directory: str = "image_outputs") -> str:
+    """
+    Save a PIL Image object to disk in the specified directory and return the file path.
+
+    Args:
+        image (Any): The PIL Image object to save.
+        directory (str, optional): The directory to save the image in. Defaults to "image_outputs".
+
+    Returns:
+        str: The file path where the image was saved.
+    """
+    os.makedirs(directory, exist_ok=True)
+    image_id = str(uuid.uuid4())
+    image_path = os.path.join(directory, f"{image_id}.png")
+    image.save(image_path)
+    return image_path
+
+# ========== CODE INTERPRETER ==========
+class CodeInterpreter:
+    """
+    A code interpreter for executing code in various languages (Python, Bash, SQL, C, Java) with safety and resource controls.
+
+    Args:
+        allowed_modules (list, optional): List of allowed module names for Python execution.
+        max_execution_time (int, optional): Maximum execution time in seconds for code blocks.
+        working_directory (str, optional): Directory for temporary files and execution context.
+
+    Attributes:
+        globals (dict): Global variables for code execution.
+        temp_sqlite_db (str): Path to a temporary SQLite database for SQL code.
+    """
+    def __init__(self, allowed_modules=None, max_execution_time=30, working_directory=None):
+        self.allowed_modules = allowed_modules or [
+            "numpy", "pandas", "matplotlib", "scipy", "sklearn", 
+            "math", "random", "statistics", "datetime", "collections",
+            "itertools", "functools", "operator", "re", "json",
+            "sympy", "networkx", "nltk", "PIL", "pytesseract", 
+            "cmath", "uuid", "tempfile", "requests", "urllib"
+        ]
+        self.max_execution_time = max_execution_time
+        self.working_directory = working_directory or os.path.join(os.getcwd()) 
+        if not os.path.exists(self.working_directory):
+            os.makedirs(self.working_directory)
+        
+        # Use global imports that are already available
+        self.globals = {
+            "__builtins__": __builtins__,
+            "np": np,
+            "pd": pd,
+            "Image": Image,
+        }
+        
+        # Only add plt to globals if it's available
+        if MATPLOTLIB_AVAILABLE:
+            self.globals["plt"] = plt
+        
+        self.temp_sqlite_db = os.path.join(tempfile.gettempdir(), "code_exec.db")
+    
+    def execute_code(self, code: str, language: str = "python") -> Dict[str, Any]:
+        """
+        Execute code in the specified language with safety controls.
+        
+        Args:
+            code (str): The source code to execute
+            language (str): The programming language
+            
+        Returns:
+            Dict containing execution results, status, and outputs
+        """
+        try:
+            if language.lower() == "python":
+                return self._execute_python(code)
+            elif language.lower() == "bash":
+                return self._execute_bash(code)
+            elif language.lower() == "sql":
+                return self._execute_sql(code)
+            elif language.lower() == "c":
+                return self._execute_c(code)
+            elif language.lower() == "java":
+                return self._execute_java(code)
+            else:
+                return {"status": "error", "stderr": f"Unsupported language: {language}"}
+        except Exception as e:
+            return {"status": "error", "stderr": str(e)}
+    
+    def _execute_python(self, code: str) -> Dict[str, Any]:
+        """Execute Python code with safety controls."""
+        try:
+            # Capture stdout and stderr
+            # Create string buffers to capture output
+            stdout_buffer = io.StringIO()
+            stderr_buffer = io.StringIO()
+            
+            # Store original stdout/stderr
+            old_stdout = sys.stdout
+            old_stderr = sys.stderr
+            
+            # Redirect stdout/stderr to our buffers
+            sys.stdout = stdout_buffer
+            sys.stderr = stderr_buffer
+            
+            try:
+                # Create a copy of globals for this execution
+                local_globals = self.globals.copy()
+                local_globals['__name__'] = '__main__'
+                
+                # Execute the code
+                exec(code, local_globals)
+                
+                # Get captured output
+                stdout_content = stdout_buffer.getvalue()
+                stderr_content = stderr_buffer.getvalue()
+                
+                # Capture any variables that might be dataframes or plots
+                result = {"status": "success", "stdout": stdout_content, "stderr": stderr_content, "result": None}
+                
+                # Check for dataframes
+                dataframes = []
+                for name, value in local_globals.items():
+                    if isinstance(value, pd.DataFrame):
+                        dataframes.append({
+                            "name": name,
+                            "shape": value.shape,
+                            "head": value.head().to_dict('records')
+                        })
+                if dataframes:
+                    result["dataframes"] = dataframes
+                
+                # Check for plots (only if matplotlib is available)
+                plots = []
+                if MATPLOTLIB_AVAILABLE and plt is not None:
+                    try:
+                        # Save any current plots
+                        if plt.get_fignums():
+                            for fig_num in plt.get_fignums():
+                                fig = plt.figure(fig_num)
+                                plot_path = os.path.join(self.working_directory, f"plot_{fig_num}.png")
+                                fig.savefig(plot_path)
+                                plots.append(plot_path)
+                                plt.close(fig)
+                    except Exception as plot_error:
+                        # If plot handling fails, just continue without plots
+                        print(f"Warning: Plot handling failed: {plot_error}")
+                if plots:
+                    result["plots"] = plots
+                
+                return result
+                
+            finally:
+                # Restore original stdout/stderr
+                sys.stdout = old_stdout
+                sys.stderr = old_stderr
+                stdout_buffer.close()
+                stderr_buffer.close()
+            
+        except Exception as e:
+            return {"status": "error", "stderr": str(e)}
+    
+    def _execute_bash(self, code: str) -> Dict[str, Any]:
+        """Execute Bash code."""
+        try:
+            result = subprocess.run(
+                code, 
+                shell=True, 
+                capture_output=True, 
+                text=True, 
+                timeout=self.max_execution_time
+            )
+            return {
+                "status": "success" if result.returncode == 0 else "error",
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "returncode": result.returncode
+            }
+        except subprocess.TimeoutExpired:
+            return {"status": "error", "stderr": "Execution timed out"}
+        except Exception as e:
+            return {"status": "error", "stderr": str(e)}
+    
+    def _execute_sql(self, code: str) -> Dict[str, Any]:
+        """Execute SQL code using SQLite."""
+        try:
+            conn = sqlite3.connect(self.temp_sqlite_db)
+            cursor = conn.cursor()
+            
+            # Execute SQL
+            cursor.execute(code)
+            
+            # Fetch results if it's a SELECT
+            if code.strip().upper().startswith('SELECT'):
+                results = cursor.fetchall()
+                columns = [description[0] for description in cursor.description]
+                result = {"status": "success", "results": results, "columns": columns}
+            else:
+                conn.commit()
+                result = {"status": "success", "message": f"Executed: {code}"}
+            
+            conn.close()
+            return result
+            
+        except Exception as e:
+            return {"status": "error", "stderr": str(e)}
+    
+    def _execute_c(self, code: str) -> Dict[str, Any]:
+        """Execute C code by compiling and running."""
+        try:
+            # Create temporary C file
+            c_file = os.path.join(self.working_directory, "temp_code.c")
+            with open(c_file, 'w') as f:
+                f.write(code)
+            
+            # Compile
+            compile_result = subprocess.run(
+                ["gcc", "-o", os.path.join(self.working_directory, "temp_program"), c_file],
+                capture_output=True,
+                text=True
+            )
+            
+            if compile_result.returncode != 0:
+                return {"status": "error", "stderr": f"Compilation failed: {compile_result.stderr}"}
+            
+            # Run
+            run_result = subprocess.run(
+                [os.path.join(self.working_directory, "temp_program")],
+                capture_output=True,
+                text=True,
+                timeout=self.max_execution_time
+            )
+            
+            return {
+                "status": "success",
+                "stdout": run_result.stdout,
+                "stderr": run_result.stderr,
+                "returncode": run_result.returncode
+            }
+            
+        except subprocess.TimeoutExpired:
+            return {"status": "error", "stderr": "Execution timed out"}
+        except Exception as e:
+            return {"status": "error", "stderr": str(e)}
+    
+    def _execute_java(self, code: str) -> Dict[str, Any]:
+        """Execute Java code by compiling and running."""
+        try:
+            # Create temporary Java file
+            java_file = os.path.join(self.working_directory, "TempCode.java")
+            with open(java_file, 'w') as f:
+                f.write(code)
+            
+            # Compile
+            compile_result = subprocess.run(
+                ["javac", java_file],
+                capture_output=True,
+                text=True
+            )
+            
+            if compile_result.returncode != 0:
+                return {"status": "error", "stderr": f"Compilation failed: {compile_result.stderr}"}
+            
+            # Run
+            run_result = subprocess.run(
+                ["java", "-cp", self.working_directory, "TempCode"],
+                capture_output=True,
+                text=True,
+                timeout=self.max_execution_time
+            )
+            
+            return {
+                "status": "success",
+                "stdout": run_result.stdout,
+                "stderr": run_result.stderr,
+                "returncode": run_result.returncode
+            }
+            
+        except subprocess.TimeoutExpired:
+            return {"status": "error", "stderr": "Execution timed out"}
+        except Exception as e:
+            return {"status": "error", "stderr": str(e)}
+
+# Create a global instance for use by tools
+interpreter_instance = CodeInterpreter()
+
+@tool
+def execute_code_multilang(code: str, language: str = "python") -> str:
+    """Execute code in multiple languages (Python, Bash, SQL, C, Java) and return results.
+
+    Args:
+        code (str): The source code to execute.
+        language (str): The language of the code. Supported: "python", "bash", "sql", "c", "java".
+
+    Returns:
+        A string summarizing the execution results (stdout, stderr, errors, plots, dataframes if any).
+    """
+    supported_languages = ["python", "bash", "sql", "c", "java"]
+    language = language.lower()
+
+    if language not in supported_languages:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "execute_code_multilang",
+            "error": f"❌ Unsupported language: {language}. Supported languages are: {', '.join(supported_languages)}"
+        })
+
+    result = interpreter_instance.execute_code(code, language=language)
+
+    response = []
+
+    if result["status"] == "success":
+        response.append(f"✅ Code executed successfully in **{language.upper()}**")
+
+        if result.get("stdout"):
+            response.append(
+                "\n**Standard Output:**\n```\n" + result["stdout"].strip() + "\n```"
+            )
+
+        if result.get("stderr"):
+            response.append(
+                "\n**Standard Error (if any):**\n```\n"
+                + result["stderr"].strip()
+                + "\n```"
+            )
+
+        if result.get("result") is not None:
+            response.append(
+                "\n**Execution Result:**\n```\n"
+                + str(result["result"]).strip()
+                + "\n```"
+            )
+
+        if result.get("dataframes"):
+            for df_info in result["dataframes"]:
+                response.append(
+                    f"\n**DataFrame `{df_info['name']}` (Shape: {df_info['shape']})**"
+                )
+                df_preview = pd.DataFrame(df_info["head"])
+                response.append("First 5 rows:\n```\n" + str(df_preview) + "\n```")
+
+        if result.get("plots"):
+            response.append(
+                f"\n**Generated {len(result['plots'])} plot(s)** (Image data returned separately)"
+            )
+
+    else:
+        response.append(f"❌ Code execution failed in **{language.upper()}**")
+        if result.get("stderr"):
+            response.append(
+                "\n**Error Log:**\n```\n" + result["stderr"].strip() + "\n```"
+            )
+
+    return json.dumps({
+        "type": "tool_response",
+        "tool_name": "execute_code_multilang",
+        "result": "\n".join(response)
+    })
+
+# ========== MATH TOOLS ==========
+@tool
+def multiply(a: float, b: float) -> float:
+    """
+    Multiply two numbers and return the result.
+
+    Args:
+        a (float): The first number.
+        b (float): The second number.
+
+    Returns:
+        float: The product of a and b.
+    """
+    return a * b
+
+@tool
+def add(a: float, b: float) -> float:
+    """
+    Add two numbers and return the result.
+
+    Args:
+        a (float): The first number.
+        b (float): The second number.
+
+    Returns:
+        float: The sum of a and b.
+    """
+    return a + b
+
+@tool
+def subtract(a: float, b: float) -> float:
+    """
+    Subtract the second number from the first and return the result.
+
+    Args:
+        a (float): The number to subtract from.
+        b (float): The number to subtract.
+
+    Returns:
+        float: The result of a - b.
+    """
+    return a - b
+
+@tool
+def divide(a: float, b: float) -> float:
+    """
+    Divide the first number by the second and return the result.
+
+    Args:
+        a (float): The numerator.
+        b (float): The denominator. Must not be zero.
+
+    Returns:
+        float: The quotient of a and b.
+    """
+    if b == 0:
+        raise ValueError("Cannot divide by zero")
+    return a / b
+
+@tool
+def modulus(a: int, b: int) -> int:
+    """
+    Compute the modulus (remainder) of two integers.
+
+    Args:
+        a (int): The dividend.
+        b (int): The divisor.
+
+    Returns:
+        int: The remainder when a is divided by b.
+    """
+    if b == 0:
+        raise ValueError("Cannot divide by zero")
+    return a % b
+
+@tool
+def power(a: float, b: float) -> float:
+    """
+    Raise the first number to the power of the second and return the result.
+
+    Args:
+        a (float): The base number.
+        b (float): The exponent.
+
+    Returns:
+        float: a raised to the power of b.
+    """
+    return a ** b
+
+@tool
+def square_root(a: float) -> float:
+    """
+    Compute the square root of a number. Returns a complex number if input is negative.
+
+    Args:
+        a (float): The number to compute the square root of.
+
+    Returns:
+        float or complex: The square root of a. If a < 0, returns a complex number.
+    """
+    if a >= 0:
+        return a ** 0.5
+    return cmath.sqrt(a)
+
+# ========== WEB/SEARCH TOOLS ==========
+@tool
+def wiki_search(input: str) -> str:
+    """
+    Search Wikipedia for a query and return up to 3 results as formatted text.
+
+    Args:
+        input (str): The search query string for Wikipedia.
+
+    Returns:
+        str: Formatted search results from Wikipedia with source information and content.
+    """
+    try:
+        if not WIKILOADER_AVAILABLE:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "wiki_search",
+                "error": "Wikipedia search not available. Install with: pip install langchain-community"
+            })
+        search_docs = WikipediaLoader(query=input, load_max_docs=SEARCH_LIMIT).load()
+        formatted_results = "\n\n---\n\n".join(
+            [
+                f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}'
+                for doc in search_docs
+            ]
+        )
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "wiki_search",
+            "wiki_results": formatted_results
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "wiki_search",
+            "error": f"Error in Wikipedia search: {str(e)}"
+        })
+
+@tool
+def web_search(input: str) -> str:
+    """
+    Search the web using Tavily for a query and return up to 3 results as formatted text.
+    
+    Tavily is a search API that provides real-time web search results. This tool is useful for:
+    - Finding current information about recent events
+    - Searching for specific facts, statistics, or data
+    - Getting up-to-date information from various websites
+    - Researching topics that may not be covered in Wikipedia or academic papers
+
+    Args:
+        input (str): The search query string to search for on the web.
+
+    Returns:
+        str: Formatted search results from Tavily with source URLs and content snippets.
+             Returns an error message if Tavily is not available or if the search fails.
+
+    """
+    if not TAVILY_AVAILABLE:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "web_search",
+            "error": "Tavily search not available. Install with: pip install langchain-tavily"
+        })
+    try:
+        if not os.environ.get("TAVILY_API_KEY"):
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "web_search",
+                "error": "TAVILY_API_KEY not found in environment variables. Please set it in your .env file."
+            })
+        search_result = TavilySearch(max_results=SEARCH_LIMIT).invoke(input)
+        
+        # Handle different response types
+        if isinstance(search_result, str):
+            # If Tavily returned a string (error message or direct answer)
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "web_search",
+                "web_results": search_result
+            })
+        elif isinstance(search_result, list):
+            # If Tavily returned a list of Document objects
+            formatted_results = "\n\n---\n\n".join(
+                [
+                    f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}'
+                    for doc in search_result
+                ]
+            )
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "web_search",
+                "web_results": formatted_results
+            })
+        else:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "web_search",
+                    "web_results": str(search_result)
+            })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "web_search",
+            "error": f"Error in web search: {str(e)}"
+        })
+
+@tool
+def arxiv_search(input: str) -> str:
+    """
+    Search Arxiv for academic papers and return up to 3 results as formatted text.
+
+    Args:
+        input (str): The search query string for academic papers.
+
+    Returns:
+        str: Formatted search results from Arxiv with paper metadata and abstracts.
+    """
+    try:
+        if not ARXIVLOADER_AVAILABLE:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "arxiv_search",
+                "error": "Arxiv search not available. Install with: pip install langchain-community"
+            })
+        search_docs = ArxivLoader(query=input, load_max_docs=SEARCH_LIMIT).load()
+        formatted_results = "\n\n---\n\n".join(
+            [
+                f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}'
+                for doc in search_docs
+            ]
+        )
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "arxiv_search",
+            "arxiv_results": formatted_results
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "arxiv_search",
+            "error": f"Error in Arxiv search: {str(e)}"
+        })
+
+# @tool
+# def exa_ai_helper(question: str) -> str:
+#     """
+#     Prefer web_search_deep_research_exa_ai. It is smarter, and gives more researched results.
+#     Smart AI web-search engine. Gives web references.
+#     Get direct answers + web references.
+#     Do not ask me about attached files or video/audio analysis.
+        
+#     This tool is particularly useful when:
+#     - You need authoritative, up-to-date information on a topic
+#     - You want to double-check your own knowledge or reasoning
+#     - You're dealing with complex questions that require multiple sources
+#     - You need citations and sources to back up your answer
+#     - You're unsure about the accuracy of your response
+    
+#     The tool performs an Exa search and uses an LLM to generate either:
+#     - A direct answer for specific queries (e.g., "What is the capital of France?" returns "Paris")
+#     - A detailed summary with citations for open-ended queries (e.g., "What is the state of AI in healthcare?")
+    
+#     WARNING: Always judge yourself and use additional tools for research.
+    
+#     Args:
+#         question (str): The question to get an answer for and search results. Can be specific or open-ended.
+    
+#     Returns:
+#         str: A well-researched answer with citations and sources, or an error message.
+    
+#     """
+#     if not EXA_AVAILABLE:
+#         return json.dumps({
+#             "type": "tool_response",
+#             "tool_name": "exa_ai_helper",
+#             "error": "Exa AI Helper not available. Install with: pip install exa-py"
+#         })
+#     try:
+#         exa_api_key = os.environ.get("EXA_API_KEY")
+#         if not exa_api_key:
+#             return json.dumps({
+#                 "type": "tool_response",
+#                 "tool_name": "exa_ai_helper",
+#                 "error": "EXA_API_KEY not found in environment variables. Please set it in your .env file."
+#             })
+#         exa = Exa(exa_api_key)
+#         result = exa.stream_answer(
+#             question,
+#             text=True,
+#         )
+#         answer_parts = []
+#         for chunk in result:
+#             # If chunk is a StreamChunk, extract its text/content
+#             if hasattr(chunk, 'text'):
+#                 answer_parts.append(chunk.text)
+#             elif isinstance(chunk, str):
+#                 answer_parts.append(chunk)
+#             else:
+#                 answer_parts.append(str(chunk))
+#         full_answer = ''.join(answer_parts)
+#         return json.dumps({
+#             "type": "tool_response",
+#             "tool_name": "exa_ai_helper",
+#             "answer": full_answer
+#         })
+#     except Exception as e:
+#         return json.dumps({
+#             "type": "tool_response",
+#             "tool_name": "exa_ai_helper",
+#             "error": f"Error getting AI Helper answer: {str(e)}"
+#         })
+
+# ========== FILE/DATA TOOLS ==========
+@tool
+def save_and_read_file(content: str, filename: Optional[str] = None) -> str:
+    """
+    Save the provided content to a file and return the file path.
+
+    Args:
+        content (str): The content to write to the file.
+        filename (str, optional): The name of the file. If not provided, a random file name is generated.
+
+    Returns:
+        str: The file path where the content was saved.
+    """
+    temp_dir = tempfile.gettempdir()
+    if filename is None:
+        temp_file = tempfile.NamedTemporaryFile(delete=False, dir=temp_dir)
+        filepath = temp_file.name
+    else:
+        filepath = os.path.join(temp_dir, filename)
+    with open(filepath, "w") as f:
+        f.write(content)
+    return json.dumps({
+        "type": "tool_response",
+        "tool_name": "save_and_read_file",
+        "result": f"File saved to {filepath}. You can read this file to process its contents."
+    })
+
+@tool
+def download_file_from_url(url: str, filename: Optional[str] = None) -> str:
+    """
+    Download a file from a URL and save it to a temporary location. Returns the file path.
+
+    Args:
+        url (str): The URL of the file to download.
+        filename (str, optional): The name of the file. If not provided, a name is inferred or generated.
+
+    Returns:
+        str: The file path where the file was downloaded.
+    """
+    try:
+        if not filename:
+            from urllib.parse import urlparse
+            path = urlparse(url).path
+            filename = os.path.basename(path)
+            if not filename:
+                filename = f"downloaded_{uuid.uuid4().hex[:8]}"
+        temp_dir = tempfile.gettempdir()
+        filepath = os.path.join(temp_dir, filename)
+        response = requests.get(url, stream=True)
+        response.raise_for_status()
+        with open(filepath, "wb") as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "download_file_from_url",
+            "result": f"File downloaded to {filepath}. You can read this file to process its contents."
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "download_file_from_url",
+            "error": f"Error downloading file: {str(e)}"
+        })
+
+@tool
+def get_task_file(task_id: str, file_name: str) -> str:
+    """
+    Download a file associated with a given task_id from the evaluation API, with a local fallback.
+    
+    This tool is used to download files that are part of CMW Platform Agent benchmark tasks.
+    It first tries to download from the evaluation API, and if that fails
+    (e.g., due to network issues or rate limits),
+    it falls back to local files in the 'files' directory.
+    The file is always saved to a 'downloads' directory.
+
+    Args:
+        task_id (str): The task ID for the file to download.
+        file_name (str): The name of the file to download.
+
+    Returns:
+        str: The absolute file path where the file was downloaded, or an error message if not found.
+    """
+    directory_name = "downloads"
+    os.makedirs(directory_name, exist_ok=True)
+    try:
+        # Try to download from evaluation API
+        evaluation_api_base_url = os.environ.get("EVALUATION_API_BASE_URL", "https://api.gaia-benchmark.com")
+        response = requests.get(f"{evaluation_api_base_url}/files/{task_id}", timeout=15)
+        response.raise_for_status()
+        filepath = os.path.join(directory_name, file_name)
+        with open(filepath, 'wb') as file:
+            file.write(response.content)
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "get_task_file",
+            "result": os.path.abspath(filepath)
+        })
+    except Exception as e:
+        # Fallback to local files
+        try:
+            local_filepath = os.path.join("files", file_name)
+            if os.path.exists(local_filepath):
+                filepath = os.path.join(directory_name, file_name)
+                shutil.copy2(local_filepath, filepath)
+                return json.dumps({
+                    "type": "tool_response",
+                    "tool_name": "get_task_file",
+                    "result": os.path.abspath(filepath)
+                })
+            else:
+                return json.dumps({
+                    "type": "tool_response",
+                    "tool_name": "get_task_file",
+                    "error": f"Error: File {file_name} not found locally or via API"
+                })
+        except Exception as local_error:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "get_task_file",
+                "error": f"Error downloading file: {str(e)}. Local fallback also failed: {str(local_error)}"
+            })
+
+@tool
+def extract_text_from_image(image_path: str) -> str:
+    """
+    Extract text from an image file using OCR (pytesseract) and return the extracted text.
+
+    Args:
+        image_path (str): The path to the image file to process.
+
+    Returns:
+        str: The extracted text, or an error message if extraction fails.
+    """
+    try:
+        image = Image.open(image_path)
+        if PYTESSERACT_AVAILABLE:
+            text = pytesseract.image_to_string(image)
+        else:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "extract_text_from_image",
+                "error": "OCR not available. Install with: pip install pytesseract"
+            })
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "extract_text_from_image",
+            "result": f"Extracted text from image:\n\n{text}"
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "extract_text_from_image",
+            "error": f"Error extracting text from image: {str(e)}"
+        })
+
+@tool
+def analyze_csv_file(file_path: str, query: str) -> str:
+    """
+    Analyze a CSV file using pandas and return summary statistics and column info.
+
+    Args:
+        file_path (str): The path to the CSV file.
+        query (str): A question or description of the analysis to perform (currently unused).
+
+    Returns:
+        str: Summary statistics and column information, or an error message if analysis fails.
+    """
+    try:
+        df = pd.read_csv(file_path)
+        result = f"CSV file loaded with {len(df)} rows and {len(df.columns)} columns.\n"
+        result += f"Columns: {', '.join(df.columns)}\n\n"
+        result += "Summary statistics:\n"
+        result += str(df.describe())
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "analyze_csv_file",
+            "result": result
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "analyze_csv_file",
+            "error": f"Error analyzing CSV file: {str(e)}"
+        })
+
+@tool
+def analyze_excel_file(file_path: str, query: str) -> str:
+    """
+    Analyze an Excel file using pandas and return summary statistics and column info.
+
+    Args:
+        file_path (str): The path to the Excel file.
+        query (str): A question or description of the analysis to perform (currently unused).
+
+    Returns:
+        str: Summary statistics and column information, or an error message if analysis fails.
+    """
+    try:
+        df = pd.read_excel(file_path)
+        result = f"Excel file loaded with {len(df)} rows and {len(df.columns)} columns.\n"
+        result += f"Columns: {', '.join(df.columns)}\n\n"
+        result += "Summary statistics:\n"
+        result += str(df.describe())
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "analyze_excel_file",
+            "result": result
+        })
+    except Exception as e:
+        # Enhanced error reporting: print columns and head if possible
+        try:
+            df = pd.read_excel(file_path)
+            columns = list(df.columns)
+            head = df.head().to_dict('records')
+            error_details = f"Error analyzing Excel file: {str(e)}\nColumns: {columns}\nHead: {head}"
+        except Exception as inner_e:
+            error_details = f"Error analyzing Excel file: {str(e)}\nAdditionally, failed to read columns/head: {str(inner_e)}"
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "analyze_excel_file",
+            "error": error_details
+        })
+
+# ========== IMAGE ANALYSIS/GENERATION TOOLS ==========
+@tool
+def analyze_image(image_base64: str) -> str:
+    """
+    Analyze basic properties of an image (size, mode, color analysis, thumbnail preview) from a base64-encoded image string.
+
+    Args:
+        image_base64 (str): The base64-encoded string of the image to analyze.
+
+    Returns:
+        str: JSON string with analysis results including dimensions, mode, color_analysis, and thumbnail.
+    """
+    try:
+        img = decode_image(image_base64)
+        width, height = img.size
+        mode = img.mode
+        if mode in ("RGB", "RGBA"):
+            arr = np.array(img)
+            avg_colors = arr.mean(axis=(0, 1))
+            dominant = ["Red", "Green", "Blue"][np.argmax(avg_colors[:3])]
+            brightness = avg_colors.mean()
+            color_analysis = {
+                "average_rgb": avg_colors.tolist(),
+                "brightness": brightness,
+                "dominant_color": dominant,
+            }
+        else:
+            color_analysis = {"note": f"No color analysis for mode {mode}"}
+        thumbnail = img.copy()
+        thumbnail.thumbnail((100, 100))
+        thumb_path = save_image(thumbnail, "thumbnails")
+        thumbnail_base64 = encode_image(thumb_path)
+        result = {
+            "dimensions": (width, height),
+            "mode": mode,
+            "color_analysis": color_analysis,
+            "thumbnail": thumbnail_base64,
+        }
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "analyze_image",
+            "result": result
+        }, indent=2)
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "analyze_image",
+            "error": str(e)
+        }, indent=2)
+
+@tool
+def transform_image(image_base64: str, operation: str, params: Optional[Dict[str, Any]] = None) -> str:
+    """
+    Transform an image using various operations like resize, rotate, filter, etc.
+
+    Args:
+        image_base64 (str): The base64-encoded string of the image to transform.
+        operation (str): The transformation operation to apply.
+        params (Dict[str, Any], optional): Parameters for the transformation.
+
+    Returns:
+        str: JSON string with the transformed image as base64 or error message.
+    """
+    try:
+        img = decode_image(image_base64)
+        params = params or {}
+        if operation == "resize":
+            width = params.get("width", img.width)
+            height = params.get("height", img.height)
+            img = img.resize((width, height), Image.Resampling.LANCZOS)
+        elif operation == "rotate":
+            angle = params.get("angle", 0)
+            img = img.rotate(angle, expand=True)
+        elif operation == "flip":
+            direction = params.get("direction", "horizontal")
+            if direction == "horizontal":
+                img = img.transpose(Image.Transpose.FLIP_LEFT_RIGHT)
+            else:
+                img = img.transpose(Image.Transpose.FLIP_TOP_BOTTOM)
+        elif operation == "blur":
+            radius = params.get("radius", 2)
+            img = img.filter(ImageFilter.GaussianBlur(radius=radius))
+        elif operation == "sharpen":
+            img = img.filter(ImageFilter.UnsharpMask(radius=2, percent=150, threshold=3))
+        elif operation == "brightness":
+            factor = params.get("factor", 1.0)
+            enhancer = ImageEnhance.Brightness(img)
+            img = enhancer.enhance(factor)
+        elif operation == "contrast":
+            factor = params.get("factor", 1.0)
+            enhancer = ImageEnhance.Contrast(img)
+            img = enhancer.enhance(factor)
+        else:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "transform_image",
+                "error": f"Unsupported operation: {operation}"
+            }, indent=2)
+        result_path = save_image(img)
+        result_base64 = encode_image(result_path)
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "transform_image",
+            "transformed_image": result_base64
+        }, indent=2)
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "transform_image",
+            "error": str(e)
+        }, indent=2)
+
+@tool
+def draw_on_image(image_base64: str, drawing_type: str, params: Dict[str, Any]) -> str:
+    """
+    Draw shapes, text, or other elements on an image.
+
+    Args:
+        image_base64 (str): The base64-encoded string of the image to draw on.
+        drawing_type (str): The type of drawing to perform.
+        params (Dict[str, Any]): Parameters for the drawing operation.
+
+    Returns:
+        str: JSON string with the modified image as base64 or error message.
+    """
+    try:
+        img = decode_image(image_base64)
+        draw = ImageDraw.Draw(img)
+        if drawing_type == "text":
+            text = params.get("text", "")
+            position = params.get("position", (10, 10))
+            color = params.get("color", "black")
+            size = params.get("size", 20)
+            try:
+                font = ImageFont.truetype("arial.ttf", size)
+            except:
+                font = ImageFont.load_default()
+            draw.text(position, text, fill=color, font=font)
+        elif drawing_type == "rectangle":
+            coords = params.get("coords", [10, 10, 100, 100])
+            color = params.get("color", "red")
+            width = params.get("width", 2)
+            draw.rectangle(coords, outline=color, width=width)
+        elif drawing_type == "circle":
+            center = params.get("center", (50, 50))
+            radius = params.get("radius", 30)
+            color = params.get("color", "blue")
+            width = params.get("width", 2)
+            bbox = [center[0] - radius, center[1] - radius, 
+                   center[0] + radius, center[1] + radius]
+            draw.ellipse(bbox, outline=color, width=width)
+        elif drawing_type == "line":
+            start = params.get("start", (10, 10))
+            end = params.get("end", (100, 100))
+            color = params.get("color", "green")
+            width = params.get("width", 2)
+            draw.line([start, end], fill=color, width=width)
+        else:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "draw_on_image",
+                "error": f"Unsupported drawing type: {drawing_type}"
+            }, indent=2)
+        result_path = save_image(img)
+        result_base64 = encode_image(result_path)
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "draw_on_image",
+            "modified_image": result_base64
+        }, indent=2)
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "draw_on_image",
+            "error": str(e)
+        }, indent=2)
+
+@tool
+def generate_simple_image(image_type: str, width: int = 500, height: int = 500, 
+                         params: Optional[Dict[str, Any]] = None) -> str:
+    """
+    Generate simple images like gradients, solid colors, checkerboard, or noise patterns.
+
+    Args:
+        image_type (str): The type of image to generate.
+        width (int): The width of the generated image.
+        height (int): The height of the generated image.
+        params (Dict[str, Any], optional): Additional parameters for image generation.
+
+    Returns:
+        str: JSON string with the generated image as base64 or error message.
+    """
+    try:
+        params = params or {}
+        if image_type == "solid":
+            color = params.get("color", (255, 255, 255))
+            img = Image.new("RGB", (width, height), color)
+        elif image_type == "gradient":
+            start_color = params.get("start_color", (255, 0, 0))
+            end_color = params.get("end_color", (0, 0, 255))
+            direction = params.get("direction", "horizontal")
+            img = Image.new("RGB", (width, height))
+            draw = ImageDraw.Draw(img)
+            if direction == "horizontal":
+                for x in range(width):
+                    r = int(start_color[0] + (end_color[0] - start_color[0]) * x / width)
+                    g = int(start_color[1] + (end_color[1] - start_color[1]) * x / width)
+                    b = int(start_color[2] + (end_color[2] - start_color[2]) * x / width)
+                    draw.line([(x, 0), (x, height)], fill=(r, g, b))
+            else:
+                for y in range(height):
+                    r = int(start_color[0] + (end_color[0] - start_color[0]) * y / height)
+                    g = int(start_color[1] + (end_color[1] - start_color[1]) * y / height)
+                    b = int(start_color[2] + (end_color[2] - start_color[2]) * y / height)
+                    draw.line([(0, y), (width, y)], fill=(r, g, b))
+        elif image_type == "noise":
+            noise_array = np.random.randint(0, 256, (height, width, 3), dtype=np.uint8)
+            img = Image.fromarray(noise_array, "RGB")
+        elif image_type == "checkerboard":
+            square_size = params.get("square_size", 50)
+            color1 = params.get("color1", "white")
+            color2 = params.get("color2", "black")
+            img = Image.new("RGB", (width, height))
+            for y in range(0, height, square_size):
+                for x in range(0, width, square_size):
+                    color = color1 if ((x // square_size) + (y // square_size)) % 2 == 0 else color2
+                    for dy in range(square_size):
+                        for dx in range(square_size):
+                            if x + dx < width and y + dy < height:
+                                img.putpixel((x + dx, y + dy), color)
+        else:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "generate_simple_image",
+                "error": f"Unsupported image_type {image_type}"
+            }, indent=2)
+        result_path = save_image(img)
+        result_base64 = encode_image(result_path)
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "generate_simple_image",
+            "generated_image": result_base64
+        }, indent=2)
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "generate_simple_image",
+            "error": str(e)
+        }, indent=2)
+
+@tool
+def combine_images(images_base64: List[str], operation: str, 
+                  params: Optional[Dict[str, Any]] = None) -> str:
+    """
+    Combine multiple images using various operations (collage, stack, blend, horizontal, vertical, overlay, etc.).
+
+    Args:
+        images_base64 (List[str]): List of base64-encoded image strings.
+        operation (str): The combination operation to perform.
+        params (Dict[str, Any], optional): Parameters for the combination.
+
+    Returns:
+        str: JSON string with the combined image as base64 or error message.
+    """
+    try:
+        if len(images_base64) < 2:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "combine_images",
+                "error": "At least 2 images required for combination"
+            }, indent=2)
+        images = [decode_image(b64) for b64 in images_base64]
+        params = params or {}
+        if operation == "horizontal":
+            # Combine images side by side
+            total_width = sum(img.width for img in images)
+            max_height = max(img.height for img in images)
+            result = Image.new("RGB", (total_width, max_height))
+            x_offset = 0
+            for img in images:
+                result.paste(img, (x_offset, 0))
+                x_offset += img.width
+        elif operation == "vertical":
+            # Stack images vertically
+            max_width = max(img.width for img in images)
+            total_height = sum(img.height for img in images)
+            result = Image.new("RGB", (max_width, total_height))
+            y_offset = 0
+            for img in images:
+                result.paste(img, (0, y_offset))
+                y_offset += img.height
+        elif operation == "overlay":
+            # Overlay images on top of each other
+            base_img = images[0]
+            for overlay_img in images[1:]:
+                if overlay_img.size != base_img.size:
+                    overlay_img = overlay_img.resize(base_img.size, Image.Resampling.LANCZOS)
+                base_img = Image.alpha_composite(base_img.convert("RGBA"), overlay_img.convert("RGBA"))
+            result = base_img.convert("RGB")
+        elif operation == "stack":
+            # Original stack operation with direction parameter
+            direction = params.get("direction", "horizontal")
+            if direction == "horizontal":
+                total_width = sum(img.width for img in images)
+                max_height = max(img.height for img in images)
+                result = Image.new("RGB", (total_width, max_height))
+                x = 0
+                for img in images:
+                    result.paste(img, (x, 0))
+                    x += img.width
+            else:
+                max_width = max(img.width for img in images)
+                total_height = sum(img.height for img in images)
+                result = Image.new("RGB", (max_width, total_height))
+                y = 0
+                for img in images:
+                    result.paste(img, (0, y))
+                    y += img.height
+        else:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "combine_images",
+                "error": f"Unsupported combination operation: {operation}"
+            }, indent=2)
+        result_path = save_image(result)
+        result_base64 = encode_image(result_path)
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "combine_images",
+            "combined_image": result_base64
+        }, indent=2)
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "combine_images",
+            "error": str(e)
+        }, indent=2)
+
+# ========== VIDEO/AUDIO UNDERSTANDING TOOLS ==========
+@tool
+def understand_video(youtube_url: str, prompt: str, system_prompt: str = None) -> str:
+    """
+    Analyze a YouTube video using Google Gemini's video understanding capabilities.
+    
+    This tool can understand video content, extract information, and answer questions
+    about what happens in the video.
+    It uses the Gemini API and requires the GEMINI_KEY environment variable to be set.
+    
+    Args:
+        youtube_url (str): The URL of the YouTube video to analyze.
+        prompt (str): A question or request regarding the video content.
+        system_prompt (str, optional): System prompt for formatting guidance.
+    
+    Returns:
+        str: Analysis of the video content based on the prompt, or error message.
+    """
+    try:
+        client = _get_gemini_client()
+        
+        # Create enhanced prompt with system prompt if provided
+        if system_prompt:
+            enhanced_prompt = f"{system_prompt}\n\nAnalyze the video at {youtube_url} and answer the following question:\n{prompt}\n\nProvide your answer in the required FINAL ANSWER format."
+        else:
+            enhanced_prompt = prompt
+        
+        video_description = client.models.generate_content(
+            model="gemini-2.5-pro",
+            contents=types.Content(
+                parts=[
+                    types.Part(file_data=types.FileData(file_uri=youtube_url)),
+                    types.Part(text=enhanced_prompt)
+                ]
+            )
+        )
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "understand_video",
+            "result": video_description.text
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "understand_video",
+            "error": f"Error understanding video: {str(e)}"
+        })
+
+@tool
+def understand_audio(file_path: str, prompt: str, system_prompt: str = None) -> str:
+    """
+    Analyze an audio file using Google Gemini's audio understanding capabilities.
+    
+    This tool can transcribe audio, understand spoken content, and answer questions
+    about the audio content.
+    It uses the Gemini API and requires the GEMINI_KEY environment variable to be set.
+    The audio file is uploaded to Gemini and then analyzed with the provided prompt.
+    
+    Args:
+        file_path (str): The path to the local audio file to analyze, or base64 encoded audio data.
+        prompt (str): A question or request regarding the audio content.
+        system_prompt (str, optional): System prompt for formatting guidance.
+    
+    Returns:
+        str: Analysis of the audio content based on the prompt, or error message.
+    """
+    try:
+        client = _get_gemini_client()
+        
+        # Check if file_path is base64 data or actual file path
+        if file_path.startswith('/') or os.path.exists(file_path):
+            # It's a file path
+            mp3_file = client.files.upload(file=file_path)
+        else:
+            # Assume it's base64 data
+            try:
+                # Decode base64 and create temporary file
+                audio_data = base64.b64decode(file_path)
+                with tempfile.NamedTemporaryFile(suffix='.mp3', delete=False) as temp_file:
+                    temp_file.write(audio_data)
+                    temp_file_path = temp_file.name
+                
+                try:
+                    mp3_file = client.files.upload(file=temp_file_path)
+                finally:
+                    # Clean up temporary file
+                    os.unlink(temp_file_path)
+            except Exception as decode_error:
+                return json.dumps({
+                    "type": "tool_response",
+                    "tool_name": "understand_audio",
+                    "error": f"Error processing audio data: {str(decode_error)}. Expected base64 encoded audio data or valid file path."
+                })
+        
+        # Create enhanced prompt with system prompt if provided
+        if system_prompt:
+            enhanced_prompt = f"{system_prompt}\n\nAnalyze the audio file and answer the following question:\n{prompt}\n\nProvide your answer in the required FINAL ANSWER format."
+        else:
+            enhanced_prompt = prompt
+        
+        contents = [enhanced_prompt, mp3_file]
+        try:
+            response = client.models.generate_content(
+                model="gemini-2.5-pro",
+                contents=contents
+            )
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "understand_audio",
+                "result": response.text
+            })
+        except Exception as e:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "understand_audio",
+                "error": f"Error in audio understanding request: {str(e)}"
+            })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "understand_audio",
+            "error": f"Error understanding audio: {str(e)}"
+        })
+
+# ========== CHESS TOOLS ==========
+def _convert_chess_move_internal(piece_placement: str, move: str) -> str:
+    """
+    Internal function to convert chess moves from coordinate notation to algebraic notation.
+    Uses Google Gemini to convert chess moves between different notations.
+    Coordinate notation uses square names (e.g., "e2e4"), while algebraic notation
+    uses piece symbols and square names (e.g., "e4", "Nf3", "O-O").
+    The function constructs a prompt for Gemini and expects 
+    only the algebraic notation as output, with no extra commentary.
+    """
+    prompt = f"""
+    Convert this chess move from coordinate notation to algebraic notation.
+    
+    Piece placement: {piece_placement}
+    Move in coordinate notation: {move}
+    
+    Return only the algebraic notation (e.g., "e4", "Nf3", "O-O", "Qxd5", etc.)
+    """
+    return json.dumps({
+        "type": "tool_response",
+        "tool_name": "convert_chess_move",
+        "result": _get_gemini_response(prompt, "Chess move conversion", "gemini-2.5-pro")
+    })
+
+@tool
+def convert_chess_move(piece_placement: str, move: str) -> str:
+    """
+    Convert a chess move from coordinate notation to algebraic notation using Google Gemini.
+    
+    This tool uses Google Gemini to convert chess moves between different notations.
+    Coordinate notation uses square names (e.g., "e2e4"), while algebraic notation
+    uses piece symbols and square names (e.g., "e4", "Nf3", "O-O").
+    The function constructs a prompt for Gemini and expects 
+    only the algebraic notation as output, with no extra commentary.
+    
+    Args:
+        piece_placement (str): The chess piece placement in plain text or FEN format.
+        move (str): The move in coordinate notation (e.g., "e2e4").
+
+    Returns:
+        str: The move in algebraic notation, or error message.
+    """
+    move_message = (
+        f"Convert this chess move from coordinate notation to algebraic "
+        f"notation: {move}. Use the following piece placement: {piece_placement}. "
+        f"Do not provide any additional thinking or commentary in the response, "
+        f"just the algebraic notation only."
+    )
+    return json.dumps({
+        "type": "tool_response",
+        "tool_name": "convert_chess_move",
+        "result": _get_gemini_response(move_message, "Chess move conversion", "gemini-2.5-pro")
+    })
+
+# --- Lichess Cloud Evaluation API Helper ---
+def _get_lichess_cloud_eval_candidates(fen: str, depth: int = 15) -> list:
+    """
+    Query the Lichess Cloud Evaluation API for candidate moves.
+    Returns a list of dicts, each with move, full_line, cp, mate, depth, multipv, and explanation.
+    """
+    candidates = []
+    chess_eval_url = os.environ.get("CHESS_EVAL_URL", "https://lichess.org/api/cloud-eval")
+    url = f"{chess_eval_url}?fen={urllib.parse.quote(fen)}&depth={depth}"
+    headers = {}
+    lichess_key = os.environ.get("LICHESS_KEY")
+    if lichess_key:
+        headers["Authorization"] = f"Bearer {lichess_key}"
+    try:
+        response = requests.get(url, timeout=15, headers=headers)
+        if response.status_code == 200:
+            data = response.json()
+            if 'pvs' in data and len(data['pvs']) > 0:
+                for pv in data['pvs']:
+                    moves_string = pv.get('moves', '')
+                    if moves_string:
+                        first_move = moves_string.split()[0]
+                        candidates.append({
+                            "source": "lichess_api",
+                            "move": first_move,
+                            "full_line": moves_string,
+                            "cp": pv.get("cp"),
+                            "mate": pv.get("mate"),
+                            "depth": pv.get("depth"),
+                            "multipv": pv.get("multipv"),
+                            "explanation": "Move suggested by Lichess Cloud Evaluation API (principal variation)."
+                        })
+                    else:
+                        candidates.append({
+                            "source": "lichess_api",
+                            "move": None,
+                            "explanation": "Lichess API returned a PV with no moves."
+                        })
+            else:
+                candidates.append({
+                    "source": "lichess_api",
+                    "move": None,
+                    "explanation": "Lichess API returned no pvs data in response."
+                })
+        else:
+            candidates.append({
+                "source": "lichess_api",
+                "move": None,
+                "explanation": f"Lichess API error: HTTP {response.status_code}"
+            })
+    except Exception as e:
+        candidates.append({
+            "source": "lichess_api",
+            "move": None,
+            "explanation": f"Lichess API exception: {str(e)}"
+        })
+    return candidates
+
+# --- Stockfish Online API Helper ---
+def _get_stockfish_online_candidate(fen: str, depth: int = 15, _retry: int = 0) -> dict:
+    """
+    Query the Stockfish Online API for the best move for a given FEN.
+    Returns a dict with move, full_line, evaluation (cp), mate, and explanation.
+    Retries once on timeout (443) errors, waits 30 seconds before retrying, then fails gracefully.
+    """
+    api_url = "https://stockfish.online/api/s/v2.php"
+    params = {'fen': fen, 'depth': depth}
+    try:
+        response = requests.get(api_url, params=params, timeout=15)
+        if response.status_code == 200:
+            data = response.json()
+            if data.get('success'):
+                bestmove = data.get('bestmove', '')
+                move = None
+                if bestmove:
+                    move_parts = bestmove.split()
+                    if len(move_parts) >= 2 and move_parts[0] == 'bestmove':
+                        move = move_parts[1]
+                # Extract useful fields
+                return {
+                    "source": "stockfish_online_api",
+                    "move": move,
+                    "full_line": data.get("continuation"),
+                    "cp": data.get("evaluation"),
+                    "mate": data.get("mate"),
+                    "explanation": "Move suggested by Stockfish Online API v2." if move else f"Stockfish Online API error: {data}"
+                }
+            else:
+                return {
+                    "source": "stockfish_online_api",
+                    "move": None,
+                    "explanation": f"Stockfish API failed: {data.get('data', 'Unknown error')}"
+                }
+        else:
+            return {
+                "source": "stockfish_online_api",
+                "move": None,
+                "explanation": f"Stockfish API HTTP error: {response.status_code}"
+            }
+    except Exception as e:
+        # Simple retry on timeout/443 error, then fail gracefully
+        if _retry < 1 and ("443" in str(e) or "timed out" in str(e).lower() or "timeout" in str(e).lower()):
+            time.sleep(30)
+            return _get_stockfish_online_candidate(fen, depth, _retry=_retry+1)
+        return {
+            "source": "stockfish_online_api",
+            "move": None,
+            "explanation": f"Stockfish API exception: {str(e)}"
+        }
+
+def _get_python_chess_stockfish_candidate(fen: str, depth: int = 15) -> dict:
+    """
+    Try to get a move using local python-chess Stockfish engine. If not available, fallback to Stockfish Online API.
+    Returns a dict with move and explanation.
+    """
+    try:
+        if 'CHESS_AVAILABLE' in globals() and CHESS_AVAILABLE:
+            import chess
+            import chess.engine
+            board = chess.Board(fen)
+            try:
+                engine = chess.engine.SimpleEngine.popen_uci("stockfish")
+                result = engine.play(board, chess.engine.Limit(time=2.0))
+                engine.quit()
+                if result.move:
+                    move = chess.square_name(result.move.from_square) + chess.square_name(result.move.to_square)
+                    return {
+                        "source": "python_chess_stockfish",
+                        "move": move,
+                        "explanation": "Move suggested by local Stockfish engine via python-chess."
+                    }
+                else:
+                    return {
+                        "source": "python_chess_stockfish",
+                        "move": None,
+                        "explanation": "python-chess Stockfish engine returned no move."
+                    }
+            except FileNotFoundError as e:
+                # Fallback to Stockfish Online API if local binary is missing
+                online = _get_stockfish_online_candidate(fen, depth)
+                online["source"] = "python_chess_stockfish (online fallback)"
+                online["explanation"] = "Local Stockfish not found, used Stockfish Online API as fallback. " + online.get("explanation", "")
+                return online
+            except Exception as e:
+                return {
+                    "source": "python_chess_stockfish",
+                    "move": None,
+                    "explanation": f"python-chess Stockfish engine exception: {str(e)}"
+                }
+        else:
+            return {
+                "source": "python_chess_stockfish",
+                "move": None,
+                "explanation": "python-chess or Stockfish engine not available."
+            }
+    except Exception as e:
+        return {
+            "source": "python_chess_stockfish",
+            "move": None,
+            "explanation": f"python-chess Stockfish engine import/availability exception: {str(e)}"
+        }
+
+# --- Main Internal Move Candidate Function ---
+def _get_best_chess_move_internal(fen: str) -> dict:
+    """
+    Internal function to get the best chess move for a given FEN position.
+    Tries multiple sources (Lichess, Stockfish Online, python-chess, heuristics) and returns all candidates with explanations for LLM selection.
+    Returns a Python dict, not a JSON string.
+    """
+    move_candidates = []
+    # 1. Lichess API (all PVs)
+    move_candidates.extend(_get_lichess_cloud_eval_candidates(fen))
+    # 2. Stockfish Online API (single best move)
+    move_candidates.append(_get_stockfish_online_candidate(fen))
+    # 3. python-chess local engine, with online fallback
+    move_candidates.append(_get_python_chess_stockfish_candidate(fen))
+    # 4. _get_best_move_simple_heuristic
+    try:
+        heuristic_move = _get_best_move_simple_heuristic(fen)
+        move = None
+        if isinstance(heuristic_move, str) and len(heuristic_move) in [4, 5]:
+            move = heuristic_move
+        move_candidates.append({
+            "source": "simple_heuristic",
+            "move": move,
+            "explanation": "Move suggested by simple FEN-based heuristic." if move else f"Heuristic error: {heuristic_move}"
+        })
+    except Exception as e:
+        move_candidates.append({
+            "source": "simple_heuristic",
+            "move": None,
+            "explanation": f"Simple heuristic exception: {str(e)}"
+        })
+    # 5. _evaluate_moves_simple
+    try:
+        if 'CHESS_AVAILABLE' in globals() and CHESS_AVAILABLE:
+            import chess
+            board = chess.Board(fen)
+            legal_moves = list(board.legal_moves)
+            best_move = _evaluate_moves_simple(board, legal_moves)
+            move = None
+            if best_move:
+                move = chess.square_name(best_move.from_square) + chess.square_name(best_move.to_square)
+            move_candidates.append({
+                "source": "evaluate_moves_simple",
+                "move": move,
+                "explanation": "Move suggested by simple move evaluation (captures, checks, center, development)." if move else "No move found by simple evaluation."
+            })
+    except Exception as e:
+        move_candidates.append({
+            "source": "evaluate_moves_simple",
+            "move": None,
+            "explanation": f"Simple evaluation exception: {str(e)}"
+        })
+    return {
+        "fen": fen,
+        "candidates": move_candidates
+    }
+
+def _get_best_move_fallback(fen: str) -> str:
+    """
+    Fallback function to get best move when Lichess API returns 404.
+    Uses alternative APIs, local chess engine, and intelligent heuristics.
+    """
+    try:
+        # Try alternative chess API (Stockfish Online API v2)
+        try:
+            stockfish_result = _try_stockfish_online_api_v2(fen)
+            if not stockfish_result.startswith("Error"):
+                return stockfish_result
+        except:
+            pass
+        
+        # Try using Stockfish via python-chess if available
+        try:
+            if CHESS_AVAILABLE:
+                board = chess.Board(fen)
+                
+                # Use Stockfish if available
+                try:
+                    engine = chess.engine.SimpleEngine.popen_uci("stockfish")
+                    result = engine.play(board, chess.engine.Limit(time=2.0))
+                    engine.quit()
+                    if result.move:
+                        return chess.square_name(result.move.from_square) + chess.square_name(result.move.to_square)
+                except:
+                    pass
+                
+                # Fallback: use legal moves and simple evaluation
+                legal_moves = list(board.legal_moves)
+                if legal_moves:
+                    # Try to find a good move using simple evaluation
+                    best_move = _evaluate_moves_simple(board, legal_moves)
+                    if best_move:
+                        return chess.square_name(best_move.from_square) + chess.square_name(best_move.to_square)
+                    else:
+                        # Return first legal move as fallback
+                        move = legal_moves[0]
+                        return chess.square_name(move.from_square) + chess.square_name(move.to_square)
+                else:
+                    return json.dumps({
+                        "type": "tool_response",
+                        "tool_name": "get_best_chess_move",
+                        "error": "Error: No legal moves available"
+                    })
+                
+        except ImportError:
+            # python-chess not available, use simple heuristic
+            return _get_best_move_simple_heuristic(fen)
+            
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "get_best_chess_move",
+            "error": f"Error in fallback chess evaluation: {str(e)}"
+        })
+
+def _try_stockfish_online_api_v2(fen: str, depth: int = 15) -> str:
+    """
+    Try to get best move using Stockfish Online API v2 (https://stockfish.online/api/s/v2.php).
+    Based on the official documentation. Adds debug output for troubleshooting.
+    """
+    try:
+        # Use Stockfish Online API v2
+        api_url = "https://stockfish.online/api/s/v2.php"
+        params = {
+            'fen': fen,
+            'depth': depth
+        }
+        print(f"[DEBUG] Requesting Stockfish API: {api_url}")
+        print(f"[DEBUG] Params: {params}")
+        response = requests.get(api_url, params=params, timeout=15)
+        print(f"[DEBUG] Status code: {response.status_code}")
+        print(f"[DEBUG] Response text: {response.text}")
+        if response.status_code == 200:
+            data = response.json()
+            # Check if request was successful
+            if data.get('success') == True:
+                bestmove = data.get('bestmove', '')
+                if bestmove:
+                    # Extract the actual move from the bestmove string
+                    # Format: "bestmove b7b6 ponder f3e5" -> extract "b7b6"
+                    move_parts = bestmove.split()
+                    if len(move_parts) >= 2 and move_parts[0] == 'bestmove':
+                        return move_parts[1]  # Return the actual move
+                    else:
+                        return bestmove  # Return full string if parsing fails
+                else:
+                    return json.dumps({
+                        "type": "tool_response",
+                        "tool_name": "get_best_chess_move",
+                        "error": "Error: No bestmove in Stockfish API response",
+                        "api_response": data
+                    })
+            else:
+                error_msg = data.get('data', 'Unknown error')
+                return json.dumps({
+                    "type": "tool_response",
+                    "tool_name": "get_best_chess_move",
+                    "error": f"Error: Stockfish API failed - {error_msg}",
+                    "api_response": data
+                })
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "get_best_chess_move",
+            "error": f"Error: Stockfish API returned status {response.status_code}",
+            "response_text": response.text
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "get_best_chess_move",
+            "error": f"Error accessing Stockfish Online API v2: {str(e)}"
+        })
+
+def _evaluate_moves_simple(board, legal_moves):
+    """
+    Simple move evaluation for when no chess engine is available.
+    """
+    try:
+        best_move = None
+        best_score = float('-inf')
+        
+        for move in legal_moves:
+            score = 0
+            
+            # Check if move captures a piece
+            if board.is_capture(move):
+                captured_piece = board.piece_at(move.to_square)
+                if captured_piece:
+                    # Piece values: Q=9, R=5, B=3, N=3, P=1
+                    piece_values = {'Q': 9, 'R': 5, 'B': 3, 'N': 3, 'P': 1}
+                    score += piece_values.get(captured_piece.symbol().upper(), 1)
+            
+            # Check if move gives check
+            board.push(move)
+            if board.is_check():
+                score += 2
+            board.pop()
+            
+            # Prefer center moves for pawns
+            if board.piece_at(move.from_square) and board.piece_at(move.from_square).symbol().upper() == 'P':
+                center_files = ['d', 'e']
+                if chr(ord('a') + move.to_square % 8) in center_files:
+                    score += 1
+            
+            # Prefer developing moves (moving pieces from back rank)
+            if move.from_square // 8 in [0, 7]:  # Back ranks
+                score += 0.5
+            
+            if score > best_score:
+                best_score = score
+                best_move = move
+        
+        return best_move
+        
+    except Exception as e:
+        return None
+
+def _get_best_move_simple_heuristic(fen: str) -> str:
+    """
+    Simple heuristic-based move selection when no chess engine is available.
+    This analyzes the position and makes intelligent move decisions.
+    """
+    try:
+        # Parse FEN to understand the position
+        parts = fen.split()
+        if len(parts) < 1:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "get_best_chess_move",
+                "error": "Error: Invalid FEN format"
+            })
+        
+        board_part = parts[0]
+        side_to_move = parts[1] if len(parts) > 1 else 'w'
+        ranks = board_part.split('/')
+        
+        # Convert FEN to a more analyzable format
+        board = []
+        for rank in ranks:
+            row = []
+            for char in rank:
+                if char.isdigit():
+                    row.extend([''] * int(char))
+                else:
+                    row.append(char)
+            board.append(row)
+        
+        # Find all pieces for the side to move
+        pieces = []
+        for rank_idx, rank in enumerate(board):
+            for file_idx, piece in enumerate(rank):
+                if piece:
+                    # Determine if piece belongs to side to move
+                    is_white_piece = piece.isupper()
+                    is_black_piece = piece.islower()
+                    
+                    if (side_to_move == 'w' and is_white_piece) or (side_to_move == 'b' and is_black_piece):
+                        pieces.append({
+                            'piece': piece.lower(),
+                            'rank': rank_idx,
+                            'file': file_idx,
+                            'square': chr(ord('a') + file_idx) + str(8 - rank_idx)
+                        })
+        
+        # Simple move selection based on piece values and position
+        # Priority: Queen > Rook > Bishop > Knight > Pawn
+        piece_values = {'q': 9, 'r': 5, 'b': 3, 'n': 3, 'p': 1}
+        
+        # Sort pieces by value (highest first)
+        pieces.sort(key=lambda p: piece_values.get(p['piece'], 0), reverse=True)
+        
+        # For now, return a move from the highest value piece
+        # This is a simplified approach - in reality you'd want to analyze legal moves
+        if pieces:
+            piece = pieces[0]
+            # Create a simple move (this is just a placeholder)
+            # In a real implementation, you'd generate legal moves for this piece
+            from_square = piece['square']
+            
+            # Simple heuristic: try to move towards center or capture
+            if piece['piece'] == 'p':  # Pawn
+                # Move pawn forward
+                if side_to_move == 'w':
+                    to_rank = piece['rank'] - 1
+                else:
+                    to_rank = piece['rank'] + 1
+                
+                if 0 <= to_rank < 8:
+                    to_square = chr(ord('a') + piece['file']) + str(8 - to_rank)
+                    return from_square + to_square
+            
+            elif piece['piece'] == 'q':  # Queen
+                # Try to move queen to center or capture
+                center_squares = ['d4', 'e4', 'd5', 'e5']
+                for center in center_squares:
+                    if center != from_square:
+                        return from_square + center
+            
+            elif piece['piece'] == 'r':  # Rook
+                # Try to move rook to open file or rank
+                return from_square + 'd' + str(8 - piece['rank'])
+            
+            elif piece['piece'] == 'b':  # Bishop
+                # Try to move bishop to long diagonal
+                return from_square + 'd4'
+            
+            elif piece['piece'] == 'n':  # Knight
+                # Try to move knight towards center
+                return from_square + 'd4'
+            
+            elif piece['piece'] == 'k':  # King
+                # Try to castle or move king to safety
+                return from_square + 'g1' if side_to_move == 'w' else from_square + 'g8'
+        
+        # Fallback: return a basic move
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "get_best_chess_move",
+            "result": "e2e4" if side_to_move == 'w' else "e7e5"
+        })
+        
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "get_best_chess_move",
+            "error": f"Error in simple heuristic: {str(e)}"
+        })
+
+# ========== FEN HELPER FUNCTIONS ==========
+
+@tool
+def get_best_chess_move(fen: str, original_input: str = None) -> str:
+    """
+    Get the best chess move candidates in coordinate notation based on a FEN representation using multiple chess evaluation sources.
+    The result is a structured object containing:
+      - The FEN string used for evaluation
+      - The original input (if provided)
+      - A list of candidate moves, each with its source and explanation
+    The LLM should analyze the candidates and explanations to decide which move is best for the context.
+    The FEN (Forsyth-Edwards Notation) describes the current chess position.
+    Eg. rn1q1rk1/pp2b1pp/2p2n2/3p1pB1/3P4/1QP2N2/PP1N1PPP/R4RK1 b - - 1 11
+    This tool tries several candidate sources (Lichess cloud eval, Stockfish Online API, local python-chess Stockfish, simple heuristics)
+
+    Args:
+        fen (str): The chess position in FEN (Forsyth-Edwards Notation) format.
+        original_input (str, optional): The original chess problem or input details.
+
+    Returns:
+        str: JSON string with all move candidates and their explanations, for LLM reasoning.
+    """
+    result = _get_best_chess_move_internal(fen)
+    # Attach original_input if provided
+    if isinstance(result, dict):
+        result["original_input"] = original_input
+    return json.dumps({
+        "type": "tool_response",
+        "tool_name": "get_best_chess_move",
+        "fen": result.get("fen"),
+        "original_input": result.get("original_input"),
+        "candidates": result.get("candidates", [])
+    })
+
+@tool
+def solve_chess_position(image_path: str, player_turn: str, question: str = "") -> str:
+    """
+    Solve a chess position by analyzing the board image and finding the best move.
+    This tool returns a structured object containing:
+      - The extracted FEN (with explanation)
+      - The original input details (image path, player turn, question)
+      - A list of candidate moves (with explanations)
+    The LLM should analyze the candidates and explanations to decide which move is best for the context.
+
+    Args:
+        image_path (str): The path to the chess board image file or base64-encoded image data.
+        player_turn (str): The player with the next turn ("black" or "white").
+        question (str): Optional question about the position (e.g., "guarantees a win").
+
+    Returns:
+        str: JSON string with all details and move candidates for LLM reasoning.
+    """
+    # Step 1: Get FEN from image
+    fen_explanation = ""
+    fen = None
+    try:
+        fen_result = _get_chess_board_fen_internal(image_path)
+        if isinstance(fen_result, str) and fen_result.startswith("Error"):
+            fen_explanation = fen_result
+            fen = None
+        else:
+            fen = fen_result
+            fen_explanation = "FEN extracted successfully from image."
+    except Exception as e:
+        fen_explanation = f"Error extracting FEN: {str(e)}"
+        fen = None
+    # Step 2: Get best move candidates (if FEN available)
+    candidates = []
+    if fen:
+        best_move_result = _get_best_chess_move_internal(fen)
+        if isinstance(best_move_result, dict):
+            candidates = best_move_result.get('candidates', [])
+        else:
+            candidates = []
+    return json.dumps({
+        'type': 'tool_response',
+        'tool_name': 'solve_chess_position',
+        'fen': fen,
+        'fen_explanation': fen_explanation,
+        'original_input': {
+            'image_path': image_path,
+            'player_turn': player_turn,
+            'question': question
+        },
+        'candidates': candidates
+    })
+
+# ========== FEN PROCESSING HELPERS ==========
+def _add_fen_game_state(board_placement,
+                    side_to_move,
+                    castling="-",
+                    en_passant="-",
+                    halfmove_clock=0,
+                    fullmove_number=1):
+    """
+    Appends standard game state information to a FEN board placement string.
+
+    Args:
+        board_placement (str): The board layout part of the FEN string
+                            (e.g., "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR").
+        side_to_move (str): The active color ('w' for White, 'b' for Black).
+                            Case-insensitive, will be converted to lowercase.
+        castling (str, optional): Castling availability string (e.g., "KQkq", "-").
+                                Defaults to "-".
+        en_passant (str, optional): En passant target square string (e.g., "e3", "-").
+                                    Defaults to "-".
+        halfmove_clock (int, optional): The number of halfmoves since the last
+                                    capture or pawn advance. Defaults to 0.
+        fullmove_number (int, optional): The number of the full move. Starts at 1
+                                    and increments after Black's move. Defaults to 1.
+
+    Returns:
+        str: The complete FEN string including the game state,
+            or an error message string if inputs are invalid.
+    """
+    # Validate side_to_move
+    side_to_move_lower = str(side_to_move).lower()
+    if side_to_move_lower not in ['w', 'b']:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "add_fen_game_state",
+            "error": f"Error: side_to_move must be 'w' or 'b', received '{side_to_move}'"
+        })
+
+    # Validate clock values (should be non-negative integers, fullmove >= 1)
+    try:
+        halfmove_clock = int(halfmove_clock)
+        fullmove_number = int(fullmove_number)
+        if halfmove_clock < 0:
+            raise ValueError("halfmove_clock cannot be negative.")
+        if fullmove_number < 1:
+            raise ValueError("fullmove_number must be 1 or greater.")
+    except (ValueError, TypeError):
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "add_fen_game_state",
+            "error": f"Error: halfmove_clock ('{halfmove_clock}') and "
+                    f"fullmove_number ('{fullmove_number}') must be valid integers "
+                    f"(non-negative and positive respectively)."
+        })
+
+    # Assemble the full FEN string using the validated/defaulted values
+    # Note: castling and en_passant strings are used directly as passed or defaulted.
+    # More complex validation could be added for them if needed.
+    full_fen = (f"{board_placement} {side_to_move_lower} {castling} "
+                f"{en_passant} {halfmove_clock} {fullmove_number}")
+
+    return json.dumps({
+        "type": "tool_response",
+        "tool_name": "add_fen_game_state",
+        "result": full_fen
+    })
+
+def _fen_normalize(fen: str, default_side='w'):
+    """
+    Normalize and validate a FEN string. Always return a best-effort valid FEN.
+    - If only the board part is present, append default fields.
+    - If FEN is valid, return as is.
+    - If not valid, try to fix or return a clear error FEN.
+    """
+    fen = fen.strip()
+    parts = fen.split()
+    # If only board part, append defaults
+    if len(parts) == 1 and parts[0].count('/') == 7:
+        fen = f"{fen} {default_side} - - 0 1"
+    # Validate using python-chess
+    try:
+        board = chess.Board(fen)
+        return board.fen()
+    except Exception as e:
+        return f"8/8/8/8/8/8/8/8 w - - 0 1"  # Return an empty board as a fallback
+
+def _get_chess_board_fen_internal(image_input: str) -> str:
+    """
+    Internal function to get the FEN representation from an image of a chess board.
+    Uses the DerekLiu35-ImageToFen Hugging Face Space API.
+    Args:
+        image_input (str): Path to the chessboard image file or base64-encoded image data.
+    Returns:
+        str: The FEN string predicted by the recognizer, or an error message.
+    """
+    api_url = "https://DerekLiu35-ImageToFen.hf.space/api/predict"
+    try:
+        # Detect if input is a file path or base64 data
+        if os.path.exists(image_input):
+            with open(image_input, "rb") as f:
+                img_b64 = base64.b64encode(f.read()).decode("utf-8")
+        else:
+            img_b64 = image_input
+        payload = {"data": [img_b64]}
+        response = requests.post(api_url, json=payload, timeout=60)
+        if response.ok:
+            result = response.json()
+            data = result.get("data", [])
+            if data:
+                # FEN is usually the last string in the list
+                fen_candidate = data[-1]
+                if isinstance(fen_candidate, str) and fen_candidate.count('/') == 7:
+                    return _fen_normalize(fen_candidate)
+                # Fallback: search for a line with 7 slashes
+                for item in data:
+                    if isinstance(item, str) and item.count('/') == 7:
+                        return _fen_normalize(item)
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "get_chess_board_fen",
+                "error": f"Error: FEN not found in API response: {result}"
+            })
+        else:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "get_chess_board_fen",
+                "error": f"Error: API call failed: {response.text}"
+            })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "get_chess_board_fen",
+            "error": f"Error running image-to-FEN API: {str(e)}"
+        })
+@tool
+def get_chess_board_fen(image_path: str, player_turn: str) -> str:
+    """
+    Get the FEN representation from an image of a chess board.
+    This tool uses computer vision to analyze a chess board image and convert it
+    to FEN (Forsyth-Edwards Notation) format.
+    Args:
+        image_path (str): The path to the chess board image file.
+        player_turn (str): The player with the next turn ("black" or "white").
+    Returns:
+        str: The FEN representation of the chess position, or error message.
+    """
+    fen = _get_chess_board_fen_internal(image_path)
+    # If the result is a JSON error, pass it through
+    try:
+        import json
+        data = json.loads(fen)
+        if isinstance(data, dict) and 'error' in data:
+            return fen
+    except Exception:
+        pass
+    # Otherwise, return the normalized FEN in the required structure
+    return json.dumps({
+        "type": "tool_response",
+        "tool_name": "get_chess_board_fen",
+        "result": _fen_normalize(fen, default_side='b' if player_turn.lower().startswith('b') else 'w')
+    })
+
+@tool
+def web_search_deep_research_exa_ai(instructions: str) -> str:
+    """
+    Search the web and site content using deep research tool.
+    Ask a query and get a well-researched answer with references.
+    Can provide FINAL ANSWER candidate.
+    Ideal for research tasks on any topic that require fact searching.
+    Can find answers and reference about science, scholars, sports, events, books, films, movies, mems, citations, etc.
+
+    The tool researches a topic, verifies facts and outputs a structured answer.
+    It deeply crawls websites to find the right answer, results and links.
+    
+    RESPONSE STRUCTURE:
+    The tool returns a structured response with the following format:
+    1. Task ID and Status
+    2. Original Instructions
+    3. Inferred Schema (JSON schema describing the response data structure)
+    4. Data (JSON object containing the answer according to the schema)
+    5. Citations (source references)
+    
+    SCHEMA INFERENCE:
+    The tool automatically infers the appropriate schema based on your question.
+    For example, a schema might include:
+    - Person data: {"firstName", "lastName", "nationality", "year", etc.}
+    - Event data: {"event", "date", "location", "participants", etc.}
+    - Fact data: {"fact", "source", "context", etc.}
+    
+    DATA EXTRACTION:
+    To extract the answer from the response:
+    1. Look for the "Data" section in the response
+    2. Parse the JSON object in the "Data" field  according to the schema
+    3. Extract the relevant fields based on your question
+    
+    Args:
+        instructions (str): Direct question or research instructions.
+
+    Returns:
+        str: The research result as a structured JSON string with schema, data, and citations, or an error message.
+    """
+    if not EXA_AVAILABLE:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "web_search_deep_research_exa_ai",
+            "error": "Exa not available. Install with: pip install exa-py"
+        })
+    try:
+        exa_api_key = os.environ.get("EXA_API_KEY")
+        if not exa_api_key:
+            return json.dumps({
+                "type": "tool_response",
+                "tool_name": "web_search_deep_research_exa_ai",
+                "error": "EXA_API_KEY not found in environment variables. Please set it in your .env file."
+            })
+        exa = Exa(exa_api_key)
+        task_stub = exa.research.create_task(
+            instructions=instructions,
+            model="exa-research-pro",
+            output_infer_schema = True
+        )
+        task = exa.research.poll_task(task_stub.id)
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "web_search_deep_research_exa_ai",
+            "result": str(task)
+        })
+    except Exception as e:
+        return json.dumps({
+            "type": "tool_response",
+            "tool_name": "web_search_deep_research_exa_ai",
+            "error": f"Error in Exa research: {str(e)}"
+        })
+
+# ========== END OF TOOLS.PY ========== 

utils.py

@@ -0,0 +1,347 @@
+import os
+import datetime
+import json
+from typing import Optional, Union, Dict, Any, List
+from pathlib import Path
+
+# Global constants
+TRACES_DIR = "traces"  # Directory for uploading trace files (won't trigger Space restarts)
+
+# Dataset constants
+DATASET_ID = "arterm-sedov/agent-course-final-assignment"
+DATASET_CONFIG_PATH = "dataset_config.json"  # Local copy of dataset config
+
+# Import huggingface_hub components for API-based file operations
+try:
+    from huggingface_hub import HfApi, CommitOperationAdd
+    HF_HUB_AVAILABLE = True
+except ImportError:
+    HF_HUB_AVAILABLE = False
+    print("Warning: huggingface_hub not available. Install with: pip install huggingface_hub")
+
+def load_dataset_schema() -> Optional[Dict]:
+    """
+    Load dataset schema from local dataset_config.json file.
+    Tries multiple possible locations for robustness.
+    """
+    possible_paths = [
+        Path("dataset_config.json"),  # Current working directory (root)
+        Path("./dataset_config.json"),
+        Path("../dataset_config.json"),  # Parent directory (if run from misc_files)
+        Path(__file__).parent / "dataset_config.json",
+        Path(__file__).parent.parent / "dataset_config.json"
+    ]
+    for path in possible_paths:
+        if path.exists():
+            with open(path, "r", encoding="utf-8") as f:
+                return json.load(f)
+    print("Warning: Dataset config file not found: dataset_config.json")
+    return None
+
+def get_dataset_features(split: str) -> Optional[Dict]:
+    """
+    Get features schema for a specific dataset split.
+    
+    Args:
+        split (str): Dataset split name (init or runs)
+        
+    Returns:
+        Dict: Features schema for the split or None if not found
+    """
+    schema = load_dataset_schema()
+    if schema and "features" in schema and split in schema["features"]:
+        features = schema["features"][split]
+        print(f"🔍 Loaded schema for {split}: {list(features.keys())}")
+        return features
+    print(f"❌ No schema found for {split}")
+    return None
+
+def validate_data_structure(data: Dict, split: str) -> bool:
+    """
+    Validate that data matches the expected schema for the split.
+    
+    Args:
+        data (Dict): Data to validate
+        split (str): Dataset split name
+        
+    Returns:
+        bool: True if data structure is valid
+    """
+    features = get_dataset_features(split)
+    if not features:
+        print(f"Warning: No schema found for split '{split}', skipping validation")
+        return True
+        
+    # Debug: Print what we're checking
+    print(f"🔍 Validating {split} split:")
+    print(f"   Expected fields: {list(features.keys())}")
+    print(f"   Actual fields: {list(data.keys())}")
+        
+    # Check that all required fields are present
+    required_fields = set(features.keys())
+    data_fields = set(data.keys())
+    
+    missing_fields = required_fields - data_fields
+    if missing_fields:
+        print(f"Warning: Missing required fields for {split} split: {missing_fields}")
+        return False
+    
+    # Enhanced validation: Check nullable fields and data types
+    for field_name, field_spec in features.items():
+        if field_name in data:
+            value = data[field_name]
+            
+            # Check nullable fields
+            is_nullable = field_spec.get("nullable", False)
+            if value is None and not is_nullable:
+                print(f"Warning: Field '{field_name}' is not nullable but contains None")
+                return False
+            
+            # Check data types for non-null values
+            if value is not None:
+                expected_dtype = field_spec.get("dtype", "string")
+                if expected_dtype == "float64" and not isinstance(value, (int, float)):
+                    print(f"Warning: Field '{field_name}' should be float64 but got {type(value)}")
+                    return False
+                elif expected_dtype == "int64" and not isinstance(value, int):
+                    print(f"Warning: Field '{field_name}' should be int64 but got {type(value)}")
+                    return False
+                elif expected_dtype == "string" and not isinstance(value, str):
+                    print(f"Warning: Field '{field_name}' should be string but got {type(value)}")
+                    return False
+        
+    return True
+
+def get_hf_api_client(token: Optional[str] = None):
+    """
+    Create and configure an HfApi client for repository operations.
+    
+    Args:
+        token (str, optional): HuggingFace token. If None, uses environment variable.
+        
+    Returns:
+        HfApi: Configured API client or None if not available
+    """
+    if not HF_HUB_AVAILABLE:
+        return None
+        
+    try:
+        # Get token from parameter or environment
+        hf_token = token or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACEHUB_API_TOKEN")
+        if not hf_token:
+            print("Warning: No HuggingFace token found. API operations will fail.")
+            return None
+            
+        # Create API client
+        api = HfApi(token=hf_token)
+        return api
+    except Exception as e:
+        print(f"Error creating HfApi client: {e}")
+        return None
+
+
+
+def upload_to_dataset(
+    dataset_id: str,
+    data: Union[Dict, List[Dict]],
+    split: str = "train",
+    token: Optional[str] = None
+) -> bool:
+    """
+    Upload structured data to HuggingFace dataset.
+    
+    Args:
+        dataset_id (str): Dataset repository ID (e.g., "username/dataset-name")
+        data (Union[Dict, List[Dict]]): Data to upload (single dict or list of dicts)
+        split (str): Dataset split name (default: "train")
+        token (str, optional): HuggingFace token
+        
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    if not HF_HUB_AVAILABLE:
+        print("Error: huggingface_hub not available for dataset operations")
+        return False
+        
+    try:
+        # Get API client
+        api = get_hf_api_client(token)
+        if not api:
+            return False
+            
+        # Prepare data as list
+        if isinstance(data, dict):
+            data_list = [data]
+        else:
+            data_list = data
+            
+        # Validate data structure against local schema only
+        # Note: HuggingFace may show warnings about remote schema mismatch, but uploads still work
+        for i, item in enumerate(data_list):
+            if not validate_data_structure(item, split):
+                print(f"Warning: Data item {i} does not match local schema for split '{split}'")
+                # Continue anyway, but log the warning
+            
+        # Convert to JSONL format with proper serialization
+        jsonl_content = ""
+        for item in data_list:
+            # Ensure all complex objects are serialized as strings
+            serialized_item = {}
+            for key, value in item.items():
+                if isinstance(value, (dict, list)):
+                    serialized_item[key] = json.dumps(value, ensure_ascii=False)
+                else:
+                    serialized_item[key] = value
+            jsonl_content += json.dumps(serialized_item, ensure_ascii=False) + "\n"
+            
+        # Create file path for dataset
+        timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        file_path = f"{split}-{timestamp}.jsonl"
+        
+        # Upload to dataset
+        operation = CommitOperationAdd(
+            path_in_repo=file_path,
+            path_or_fileobj=jsonl_content.encode('utf-8')
+        )
+        
+        commit_message = f"Add {split} data at {timestamp}"
+        
+        # Commit to dataset repository
+        commit_info = api.create_commit(
+            repo_id=dataset_id,
+            repo_type="dataset",
+            operations=[operation],
+            commit_message=commit_message
+        )
+        
+        print(f"✅ Data uploaded to dataset: {dataset_id}")
+        print(f"   File: {file_path}")
+        print(f"   Records: {len(data_list)}")
+        return True
+        
+    except Exception as e:
+        print(f"❌ Error uploading to dataset: {e}")
+        return False
+
+def upload_init_summary(
+    init_data: Dict,
+    token: Optional[str] = None
+) -> bool:
+    """
+    Upload agent initialization summary to init split.
+    
+    Args:
+        init_data (Dict): Initialization data including LLM config, model status, etc.
+        token (str, optional): HuggingFace token
+        
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    return upload_to_dataset(DATASET_ID, init_data, "init", token)
+
+def upload_run_data(
+    run_data: Dict,
+    split: str = "runs_new",
+    token: Optional[str] = None
+) -> bool:
+    """
+    Upload evaluation run data to specified split.
+    
+    Args:
+        run_data (Dict): Evaluation run data including results, stats, etc.
+        split (str): Dataset split name (default: "runs_new" for current schema)
+        token (str, optional): HuggingFace token
+        
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    return upload_to_dataset(DATASET_ID, run_data, split, token)
+
+def get_dataset_info() -> Optional[Dict]:
+    """
+    Get dataset information from the local config file.
+    
+    Returns:
+        Dict: Dataset info including splits and features, or None if not found
+    """
+    schema = load_dataset_schema()
+    if schema and "dataset_info" in schema:
+        return schema["dataset_info"]
+    return None
+
+def print_dataset_schema():
+    """
+    Print the dataset schema for debugging purposes.
+    """
+    schema = load_dataset_schema()
+    if schema:
+        print("📊 Dataset Schema:")
+        print(f"   Dataset: {schema.get('dataset_info', {}).get('dataset_name', 'Unknown')}")
+        print(f"   Splits: {list(schema.get('features', {}).keys())}")
+        for split_name, features in schema.get('features', {}).items():
+            print(f"   {split_name} split fields: {list(features.keys())}")
+    else:
+        print("❌ No dataset schema found")
+
+def ensure_valid_answer(answer: Any) -> str:
+    """
+    Ensure the answer is a valid string, never None or empty.
+    
+    Args:
+        answer (Any): The answer to validate
+        
+    Returns:
+        str: A valid string answer, defaulting to "No answer provided" if invalid
+    """
+    if answer is None:
+        return "No answer provided"
+    elif not isinstance(answer, str):
+        return str(answer)
+    elif answer.strip() == "":
+        return "No answer provided"
+    else:
+        return answer
+
+def get_nullable_field_value(value: Any, field_name: str, default: Any = None) -> Any:
+    """
+    Get a value for a nullable field, handling None values appropriately.
+    
+    Args:
+        value (Any): The value to process
+        field_name (str): Name of the field for logging
+        default (Any): Default value if None
+        
+    Returns:
+        Any: The processed value or default
+    """
+    if value is None:
+        print(f"📝 Field '{field_name}' is None, using default: {default}")
+        return default
+    return value
+
+def validate_nullable_field(value: Any, field_name: str, expected_type: str) -> bool:
+    """
+    Validate a nullable field against expected type.
+    
+    Args:
+        value (Any): The value to validate
+        field_name (str): Name of the field
+        expected_type (str): Expected data type (string, float64, int64)
+        
+    Returns:
+        bool: True if valid
+    """
+    if value is None:
+        return True  # Null is always valid for nullable fields
+    
+    if expected_type == "float64" and not isinstance(value, (int, float)):
+        print(f"❌ Field '{field_name}' should be float64 but got {type(value)}")
+        return False
+    elif expected_type == "int64" and not isinstance(value, int):
+        print(f"❌ Field '{field_name}' should be int64 but got {type(value)}")
+        return False
+    elif expected_type == "string" and not isinstance(value, str):
+        print(f"❌ Field '{field_name}' should be string but got {type(value)}")
+        return False
+    
+    return True