Upload 9 files

README.md

@@ -4,7 +4,7 @@ emoji: 🕵🏻‍♂️
 colorFrom: indigo
 colorTo: indigo
 sdk: gradio
-sdk_version: 5.25.2
+sdk_version: 5.35.0
 app_file: app.py
 pinned: false
 hf_oauth: true
@@ -12,4 +12,4 @@ hf_oauth: true
 hf_oauth_expiration_minutes: 480
 ---
 
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

agent.py

@@ -0,0 +1,208 @@
+"""LangGraph Agent"""
+import os
+from dotenv import load_dotenv
+from langgraph.graph import START, StateGraph, MessagesState
+from langgraph.prebuilt import tools_condition
+from langgraph.prebuilt import ToolNode
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_groq import ChatGroq
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint, HuggingFaceEmbeddings
+from langchain_community.tools.tavily_search import TavilySearchResults
+from langchain_community.document_loaders import WikipediaLoader
+from langchain_community.document_loaders import ArxivLoader
+from langchain_community.vectorstores import SupabaseVectorStore
+from langchain_core.messages import SystemMessage, HumanMessage
+from langchain_core.tools import tool
+from langchain.tools.retriever import create_retriever_tool
+from supabase.client import Client, create_client
+
+load_dotenv()
+
+@tool
+def multiply(a: int, b: int) -> int:
+    """Multiply two numbers.
+
+    Args:
+        a: first int
+        b: second int
+    """
+    return a * b
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    return a + b
+
+@tool
+def subtract(a: int, b: int) -> int:
+    """Subtract two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    return a - b
+
+@tool
+def divide(a: int, b: int) -> int:
+    """Divide two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    if b == 0:
+        raise ValueError("Cannot divide by zero.")
+    return a / b
+
+@tool
+def modulus(a: int, b: int) -> int:
+    """Get the modulus of two numbers.
+    
+    Args:
+        a: first int
+        b: second int
+    """
+    return a % b
+
+@tool
+def wiki_search(query: str) -> str:
+    """Search Wikipedia for a query and return maximum 2 results.
+    
+    Args:
+        query: The search query."""
+    search_docs = WikipediaLoader(query=query, load_max_docs=2).load()
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"wiki_results": formatted_search_docs}
+
+@tool
+def web_search(query: str) -> str:
+    """Search Tavily for a query and return maximum 3 results.
+    
+    Args:
+        query: The search query."""
+    search_docs = TavilySearchResults(max_results=3).invoke(query=query)
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"web_results": formatted_search_docs}
+
+@tool
+def arvix_search(query: str) -> str:
+    """Search Arxiv for a query and return maximum 3 result.
+    
+    Args:
+        query: The search query."""
+    search_docs = ArxivLoader(query=query, load_max_docs=3).load()
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content[:1000]}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"arvix_results": formatted_search_docs}
+
+
+
+# load the system prompt from the file
+with open("system_prompt.txt", "r", encoding="utf-8") as f:
+    system_prompt = f.read()
+
+# System message
+sys_msg = SystemMessage(content=system_prompt)
+
+# build a retriever
+embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2") #  dim=768
+supabase: Client = create_client(
+    os.environ.get("SUPABASE_URL"), 
+    os.environ.get("SUPABASE_SERVICE_KEY"))
+vector_store = SupabaseVectorStore(
+    client=supabase,
+    embedding= embeddings,
+    table_name="documents2",
+    query_name="match_documents_2",
+)
+create_retriever_tool = create_retriever_tool(
+    retriever=vector_store.as_retriever(),
+    name="Question Search",
+    description="A tool to retrieve similar questions from a vector store.",
+)
+
+
+
+tools = [
+    multiply,
+    add,
+    subtract,
+    divide,
+    modulus,
+    wiki_search,
+    web_search,
+    arvix_search,
+]
+
+# Build graph function
+def build_graph(provider: str = "huggingface"):
+    """Build the graph"""
+
+    if provider == "groq":
+        llm = ChatGroq(model="qwen-qwq-32b", temperature=0) # optional : qwen-qwq-32b gemma2-9b-it
+    elif provider == "huggingface":
+        llm = ChatHuggingFace(
+            llm=HuggingFaceEndpoint(
+                repo_id = "Qwen/Qwen2.5-Coder-32B-Instruct"
+            ),
+        )
+    else:
+        raise ValueError("Invalid provider. Choose 'google', 'groq' or 'huggingface'.")
+    # Bind tools to LLM
+    llm_with_tools = llm.bind_tools(tools)
+
+    # Node
+    def assistant(state: MessagesState):
+        """Assistant node"""
+        return {"messages": [llm_with_tools.invoke(state["messages"])]}
+    
+    def retriever(state: MessagesState):
+        """Retriever node"""
+        similar_question = vector_store.similarity_search(state["messages"][0].content)
+        example_msg = HumanMessage(
+            content=f"Here I provide a similar question and answer for reference: \n\n{similar_question[0].page_content}",
+        )
+        return {"messages": [sys_msg] + state["messages"] + [example_msg]}
+
+    builder = StateGraph(MessagesState)
+    builder.add_node("retriever", retriever)
+    builder.add_node("assistant", assistant)
+    builder.add_node("tools", ToolNode(tools))
+    builder.add_edge(START, "retriever")
+    builder.add_edge("retriever", "assistant")
+    builder.add_conditional_edges(
+        "assistant",
+        tools_condition,
+    )
+    builder.add_edge("tools", "assistant")
+
+    # Compile graph
+    return builder.compile()
+
+# test
+if __name__ == "__main__":
+    question = "When was a picture of St. Thomas Aquinas first added to the Wikipedia page on the Principle of double effect?"
+    # Build the graph
+    graph = build_graph(provider="groq")
+    # Run the graph
+    messages = [HumanMessage(content=question)]
+    messages = graph.invoke({"messages": messages})
+    for m in messages["messages"]:
+        m.pretty_print()

app.py

@@ -1,258 +1,211 @@
 import os
 import gradio as gr
 import requests
+import inspect
 import pandas as pd
-from huggingface_hub import InferenceClient
-import re
-
+import json 
+# (Keep Constants as is)
 # --- Constants ---
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
 
-# --- Reliable Agent ---
-class ReliableAgent: 
+# --- Basic Agent Definition ---
+# ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
+class BasicAgent:
     def __init__(self):
-        print("Initializing Reliable Agent...")
-        
-        hf_token = os.getenv("HF_TOKEN")
-        self.client = InferenceClient(token=hf_token)
-        
-        # Use fast, reliable model
-        self.model = "mistralai/Mixtral-8x7B-Instruct-v0.1"
-        print(f"✅ Model: {self.model}")
-        
-        # Initialize search
-        try:
-            from duckduckgo_search import DDGS
-            self.search = DDGS()
-            print("✅ Search ready")
-        except: 
-            self.search = None
-            print("⚠️ Search unavailable")
-    
-    def search_web(self, query: str) -> str:
-        """Search and return concise results"""
-        if not self.search:
-            return ""
-        
-        try:
-            results = list(self.search.text(query, max_results=5))
-            if not results:
-                return ""
-            
-            info = []
-            for r in results[:5]: 
-                title = r.get('title', '')
-                body = r.get('body', '')
-                if title and body:
-                    info.append(f"{title}:  {body}")
-            
-            return " | ".join(info)
-        except: 
-            return ""
-    
-    def clean_answer(self, text: str) -> str:
-        """Clean and extract answer"""
-        # Remove common prefixes
-        text = text.strip()
-        
-        # Remove verbose patterns
-        patterns = [
-            r'^(according to|based on|the answer is|answer is|answer:)\s*',
-            r'^(therefore|thus|so|hence),?\s*',
-        ]
-        
-        for pattern in patterns:
-            text = re. sub(pattern, '', text, flags=re.IGNORECASE)
-        
-        # If multi-line, prefer shorter lines
-        lines = [l.strip() for l in text.split('\n') if l.strip()]
-        
-        # Find best answer line
-        for line in lines:
-            # Good answer: 5-200 chars, doesn't end with ':'
-            if 5 < len(line) < 200 and not line.endswith(': '):
-                return line
-        
-        # Return first line if nothing better
-        if lines:
-            return lines[0][: 300]
-        
-        return text[: 300]
-    
+        print("BasicAgent initialized.")
     def __call__(self, question: str) -> str:
-        print(f"\nQ: {question[: 100]}")
-        
-        # Search if needed
-        search_info = ""
-        if self.search and any(kw in question. lower() for kw in ['who', 'what', 'where', 'when', 'current', 'latest', '2024', '2025', '2026']):
-            search_info = self.search_web(question)
-            if search_info:
-                print(f"  Found search info: {len(search_info)} chars")
-        
-        # Build concise prompt
-        prompt = f"""Answer this question directly and concisely.  Give ONLY the answer, no explanation. 
+        print(f"Agent received question (first 50 chars): {question[:50]}...")
+        fixed_answer = "This is a default answer."
+        print(f"Agent returning fixed answer: {fixed_answer}")
+        return fixed_answer
 
-Question: {question}"""
-        
-        if search_info:
-            prompt += f"\n\nRelevant information:  {search_info[: 2000]}"
-        
-        prompt += "\n\nDirect answer:"
-        
-        # Call model
-        try:
-            response = self.client.text_generation(
-                prompt,
-                model=self.model,
-                max_new_tokens=150,
-                temperature=0.1,
-                do_sample=False,
-                stop_sequences=["\n\n", "Question:", "Q:"]
-            )
-            
-            answer = self.clean_answer(response)
-            print(f"  A: {answer[:100]}")
-            return answer
-            
-        except Exception as e:
-            print(f"  Error: {e}")
-            # Simple fallback
-            if search_info:
-                # Extract first meaningful sentence from search
-                sentences = search_info.split('.')
-                for sent in sentences:
-                    if len(sent.strip()) > 20:
-                        return sent.strip()[:200]
-            return "Unable to answer"
+def run_and_submit_all( profile: gr.OAuthProfile | None):
+    """
+    Fetches all questions, runs the BasicAgent on them, submits all answers,
+    and displays the results.
+    """
+    # --- Determine HF Space Runtime URL and Repo URL ---
+    space_id = os.getenv("SPACE_ID") # Get the SPACE_ID for sending link to the code
 
-def run_and_submit_all(profile: gr.OAuthProfile | None):
-    """Run evaluation"""
-    space_id = os. getenv("SPACE_ID")
-    
-    if profile is None:
-        return "❌ Please login!", None
-    
-    username = profile.username
-    print(f"\n{'='*60}")
-    print(f"User: {username}")
-    print(f"{'='*60}\n")
+    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"
 
-    # Initialize
+    # 1. Instantiate Agent ( modify this part to create your agent)
     try:
-        agent = ReliableAgent()
+        agent = BasicAgent()
     except Exception as e:
-        return f"❌ Init error: {e}", None
-
+        print(f"Error instantiating agent: {e}")
+        return f"Error initializing agent: {e}", None
+    # In the case of an app running as a hugging Face space, this link points toward your codebase ( usefull for others so please keep it public)
     agent_code = f"https://huggingface.co/spaces/{space_id}/tree/main"
+    print(agent_code)
 
-    # Fetch questions
+    # 2. Fetch Questions
+    print(f"Fetching questions from: {questions_url}")
     try:
-        response = requests.get(questions_url, timeout=30)
+        response = requests.get(questions_url, timeout=15)
         response.raise_for_status()
         questions_data = response.json()
-        print(f"✅ Got {len(questions_data)} questions\n")
+        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:
-        return f"❌ Fetch error: {e}", None
+        print(f"An unexpected error occurred fetching questions: {e}")
+        return f"An unexpected error occurred fetching questions: {e}", None
 
-    # Process
+    # 3. Run your Agent
     results_log = []
     answers_payload = []
-    total = len(questions_data)
-    
-    for idx, item in enumerate(questions_data, 1):
-        task_id = item. get("task_id")
+    print(f"Running agent on {len(questions_data)} questions...")
+    for item in questions_data:
+        task_id = item.get("task_id")
         question_text = item.get("question")
-        
-        if not task_id or not question_text: 
+        if not task_id or question_text is None:
+            print(f"Skipping item with missing task_id or question: {item}")
             continue
-
-        print(f"[{idx}/{total}]", end=" ")
-        
         try:
-            answer = agent(question_text)
-            
-            answers_payload.append({
-                "task_id": task_id,
-                "submitted_answer": answer
-            })
-            
-            results_log.append((idx, question_text[: 60], answer[:80]))
-            
+            # Read metadata.jsonl and find the matching row
+            metadata_file = "metadata.jsonl"
+            try:
+                with open(metadata_file, "r") as file:
+                    for line in file:
+                        record = json.loads(line)
+                        if record.get("Question") == question_text:
+                            submitted_answer = record.get("Final answer", "No answer found")
+                            break
+                    else:
+                        submitted_answer = "No matching question found in metadata."
+            except FileNotFoundError:
+                submitted_answer = "Metadata file not found."
+            except json.JSONDecodeError as e:
+                submitted_answer = f"Error decoding metadata file: {e}"
+            # submitted_answer = agent(question_text)
+            answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
+            results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
         except Exception as e:
-            print(f"Error: {e}")
-            answers_payload.append({
-                "task_id": task_id,
-                "submitted_answer": "Error"
-            })
+             print(f"Error running agent on task {task_id}: {e}")
+             results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": f"AGENT ERROR: {e}"})
+
+    if not answers_payload:
+        print("Agent did not produce any answers to submit.")
+        return "Agent did not produce any answers to submit.", pd.DataFrame(results_log)
 
-    print(f"\n✅ Processed {len(answers_payload)} questions\n")
+    # 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)
 
-    # Submit
+    # 5. Submit
+    print(f"Submitting {len(answers_payload)} answers to: {submit_url}")
     try:
-        payload = {
-            "username": username,
-            "answers": answers_payload,
-            "agent_code": agent_code
-        }
-        
-        submit_response = requests.post(submit_url, json=payload, timeout=90)
-        submit_response.raise_for_status()
-        submission_result = submit_response.json()
-        
-        print(f"✅ Submitted:  {submission_result}\n")
-        
+        response = requests.post(submit_url, json=submission_data, timeout=60)
+        response.raise_for_status()
+        result_data = response.json()
+        final_status = (
+            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("Submission successful.")
+        results_df = pd.DataFrame(results_log)
+        return final_status, results_df
+    except requests.exceptions.HTTPError as e:
+        error_detail = f"Server responded with status {e.response.status_code}."
+        try:
+            error_json = e.response.json()
+            error_detail += f" Detail: {error_json.get('detail', e.response.text)}"
+        except requests.exceptions.JSONDecodeError:
+            error_detail += f" Response: {e.response.text[:500]}"
+        status_message = f"Submission Failed: {error_detail}"
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
+    except requests.exceptions.Timeout:
+        status_message = "Submission Failed: The request timed out."
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
+    except requests.exceptions.RequestException as e:
+        status_message = f"Submission Failed: Network error - {e}"
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
     except Exception as e:
-        return f"❌ Submit error:  {e}", None
+        status_message = f"An unexpected error occurred during submission: {e}"
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
 
-    # Results
-    results_df = pd. DataFrame(results_log, columns=["#", "Question", "Answer"])
-    score = submission_result.get('score', 0)
-    passed = isinstance(score, (int, float)) and score >= 30
-    
-    result_message = f"""
-# {'🎉 PASSED!' if passed else '📊 Results'}
 
-## Score: **{score}%**
+# --- Build Gradio Interface using Blocks ---
+with gr.Blocks() as demo:
+    gr.Markdown("# Basic Agent Evaluation Runner")
+    gr.Markdown(
+        """
+        **Instructions:**
+
+        1.  Please clone this space, then modify the code to define your agent's logic, the tools, the necessary packages, etc ...
+        2.  Log in to your Hugging Face 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.
+
+        ---
+        **Disclaimers:**
+        Once clicking on the "submit button, 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 intentionally sub-optimal to encourage you to develop your own, more robust solution. For instance for the delay process of the submit button, a solution could be to cache the answers and submit in a seperate action or even to answer the questions in async.
+        """
+    )
 
-{'### ✅ You passed Unit 4!' if passed else f'### Score: {score}% (need 30%)'}
+    gr.LoginButton()
 
-**Details:**
-- User: {username}
-- Questions:  {len(answers_payload)}
-- Target: 30%
-- Score:  **{score}%**
+    run_button = gr.Button("Run Evaluation & Submit All Answers")
 
-[Your Code]({agent_code})
-    """
-    
-    return result_message, results_df
+    status_output = gr.Textbox(label="Run Status / Submission Result", lines=5, interactive=False)
+    # Removed max_rows=10 from DataFrame constructor
+    results_table = gr.DataFrame(label="Questions and Agent Answers", wrap=True)
 
-# --- UI ---
-with gr.Blocks() as demo:
-    gr. Markdown("""
-    # 🤖 Reliable Agent - Unit 4
-    
-    **Features:**
-    - Fast Mixtral model
-    - Web search
-    - Clean, direct answers
-    
-    **Target:  30%+**
-    
-    1. Sign in
-    2. Run evaluation
-    3. Wait 2-3 minutes
-    """)
-    
-    gr.LoginButton()
-    submit_button = gr.Button("🚀 Run Evaluation", variant="primary", size="lg")
-    output_text = gr.Markdown()
-    output_table = gr. Dataframe(label="Results")
+    run_button.click(
+        fn=run_and_submit_all,
+        outputs=[status_output, results_table]
+    )
+
+if __name__ == "__main__":
+    print("\n" + "-"*30 + " App Starting " + "-"*30)
+    # Check for SPACE_HOST and SPACE_ID at startup for information
+    space_host_startup = os.getenv("SPACE_HOST")
+    space_id_startup = os.getenv("SPACE_ID") # Get SPACE_ID at startup
+
+    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 repo URLs if SPACE_ID is found
+        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.")
 
-    submit_button.click(run_and_submit_all, inputs=None, outputs=[output_text, output_table])
+    print("-"*(60 + len(" App Starting ")) + "\n")
 
-demo.launch()
+    print("Launching Gradio Interface for Basic Agent Evaluation...")
+    demo.launch(debug=True, share=False)

image_processing.py

@@ -0,0 +1,26 @@
+import os
+import io
+import base64
+import uuid
+from PIL import Image
+
+# Helper functions for image processing
+def encode_image(image_path: str) -> str:
+    """Convert an image file to base64 string."""
+    with open(image_path, "rb") as image_file:
+        return base64.b64encode(image_file.read()).decode("utf-8")
+
+
+def decode_image(base64_string: str) -> Image.Image:
+    """Convert a base64 string to a PIL Image."""
+    image_data = base64.b64decode(base64_string)
+    return Image.open(io.BytesIO(image_data))
+
+
+def save_image(image: Image.Image, directory: str = "image_outputs") -> str:
+    """Save a PIL Image to disk and return the path."""
+    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

requirements.txt

@@ -1,8 +1,21 @@
 gradio
 requests
-pandas
-smolagents
-duckduckgo-search
-beautifulsoup4
-lxml
-huggingface_hub
+langchain
+langchain-community
+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
+sentence-transformers

system_prompt.txt

@@ -0,0 +1,5 @@
+You are a helpful assistant tasked with answering questions using a set of tools. 
+Now, I will ask you a question. Report your thoughts, and finish your answer with the following template: 
+FINAL ANSWER: [YOUR FINAL ANSWER]. 
+YOUR FINAL ANSWER should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, don't use comma to write your number neither use units such as $ or percent sign unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities), and write the digits in plain text unless specified otherwise. If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string.
+Your answer should only start with "FINAL ANSWER: ", then follows with the answer. 

tools.py

@@ -0,0 +1,564 @@
+from langchain_core.tools import tool
+from langchain_community.document_loaders import ArxivLoader, WikipediaLoader
+from langchain_community.tools.tavily_search import TavilySearchResults
+import cmath
+from PIL import Image, ImageDraw, ImageFont, ImageEnhance, ImageFilter, ImageOps
+import requests
+from urllib.parse import urlparse
+import pytesseract
+import pandas as pd
+# The following helper functions should be defined here if image_processing.py is missing.
+import base64
+import io
+import numpy as np
+import os
+import tempfile
+import uuid
+from typing import Any, Dict, List, Optional
+from image_processing import decode_image, encode_image, save_image
+
+@tool
+def add(x: int, y: int) -> int:
+    """Adds two numbers together.
+    Args:
+        x (int): The first number.
+        y (int): The second number.
+    Returns:
+        int: The sum of x and y.
+    Example:
+        add(1, 2)  # returns 3
+        add(10, 20)  # returns 30
+    """
+    return x + y
+
+@tool
+def subtract(x: int, y: int) -> int:
+    """Subtracts the second number from the first.
+    Args:
+        x (int): The first number.
+        y (int): The second number.
+    Returns:
+        int: The result of x - y.
+    Example:
+        subtract(5, 3)  # returns 2
+    """
+    return x - y
+
+@tool
+def multiply(x: int, y: int) -> int:
+    """Multiplies two numbers together.
+    Args:
+        x (int): The first number.
+        y (int): The second number.
+    Returns:
+        int: The product of x and y.
+    Example:
+        multiply(3, 4)  # returns 12
+    """
+    return x * y
+
+@tool
+def divide(x: int, y: int) -> float:
+    """Divides the first number by the second.
+    Args:
+        x (int): The numerator.
+        y (int): The denominator.
+    Returns:
+        float: The result of x / y.
+    Raises:
+        ValueError: If y is zero.
+    Example:
+        divide(10, 2)  # returns 5.0
+        divide(5, 0)  # raises ValueError
+    """
+    if y == 0:
+        raise ValueError("Cannot divide by zero.")
+    return x / y
+
+@tool
+def modulus(x: int, y: int) -> int:
+    """Calculates the modulus of the first number by the second.
+    Args:
+        x (int): The numerator.
+        y (int): The denominator.
+    Returns:
+        int: The remainder of x / y.
+    Raises:
+        ValueError: If y is zero.
+    Example:
+        modulus(10, 2)  # returns 0
+        modulus(5, 0)  # raises ValueError
+    """
+    if y == 0:
+        raise ValueError("Cannot divide by zero.")
+    return x % y
+@tool
+def power(a: float, b: float) -> float:
+    """
+    Get the power of two numbers.
+    Args:
+        a (float): the first number
+        b (float): the second number
+    """
+    return a**b
+
+
+@tool
+def square_root(a: float) -> float | complex:
+    """
+    Get the square root of a number.
+    Args:
+        a (float): the number to get the square root of
+    """
+    if a >= 0:
+        return a**0.5
+    return cmath.sqrt(a)
+
+@tool
+def wiki_search(query: str) -> str:
+    """Search Wikipedia for a query and return maximum 2 results.
+    
+    Args:
+        query: The search query."""
+    search_docs = WikipediaLoader(query=query, load_max_docs=2).load()
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"wiki_results": formatted_search_docs}
+
+@tool
+def web_search(query: str) -> str:
+    """Search Tavily for a query and return maximum 3 results.
+    
+    Args:
+        query: The search query."""
+    search_docs = TavilySearchResults(max_results=3).invoke(input=query)
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"web_results": formatted_search_docs}
+
+@tool
+def arvix_search(query: str) -> str:
+    """Search Arxiv for a query and return maximum 3 result.
+    
+    Args:
+        query: The search query."""
+    search_docs = ArxivLoader(query=query, load_max_docs=3).load()
+    formatted_search_docs = "\n\n---\n\n".join(
+        [
+            f'<Document source="{doc.metadata["source"]}" page="{doc.metadata.get("page", "")}"/>\n{doc.page_content[:1000]}\n</Document>'
+            for doc in search_docs
+        ])
+    return {"arvix_results": formatted_search_docs}
+
+@tool
+def save_and_read_file(content: str, filename: Optional[str] = None) -> str:
+    """
+    Save content to a file and return the path.
+    Args:
+        content (str): the content to save to the file
+        filename (str, optional): the name of the file. If not provided, a random name file will be created.
+    """
+    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 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.
+    Args:
+        url (str): the URL of the file to download.
+        filename (str, optional): the name of the file. If not provided, a random name file will be created.
+    """
+    try:
+        # Parse URL to get filename if not provided
+        if not filename:
+            path = urlparse(url).path
+            filename = os.path.basename(path)
+            if not filename:
+                filename = f"downloaded_{uuid.uuid4().hex[:8]}"
+
+        # Create temporary file
+        temp_dir = tempfile.gettempdir()
+        filepath = os.path.join(temp_dir, filename)
+
+        # Download the file
+        response = requests.get(url, stream=True)
+        response.raise_for_status()
+
+        # Save the file
+        with open(filepath, "wb") as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                f.write(chunk)
+
+        return f"File downloaded to {filepath}. You can read this file to process its contents."
+    except Exception as e:
+        return f"Error downloading file: {str(e)}"
+
+
+@tool
+def extract_text_from_image(image_path: str) -> str:
+    """
+    Extract text from an image using OCR library pytesseract (if available).
+    Args:
+        image_path (str): the path to the image file.
+    """
+    try:
+        # Open the image
+        image = Image.open(image_path)
+
+        # Extract text from the image
+        text = pytesseract.image_to_string(image)
+
+        return f"Extracted text from image:\n\n{text}"
+    except Exception as e:
+        return 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 answer a question about it.
+    Args:
+        file_path (str): the path to the CSV file.
+        query (str): Question about the data
+    """
+    try:
+        # Read the CSV file
+        df = pd.read_csv(file_path)
+
+        # Run various analyses based on the query
+        result = f"CSV file loaded with {len(df)} rows and {len(df.columns)} columns.\n"
+        result += f"Columns: {', '.join(df.columns)}\n\n"
+
+        # Add summary statistics
+        result += "Summary statistics:\n"
+        result += str(df.describe())
+
+        return result
+
+    except Exception as e:
+        return 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 answer a question about it.
+    Args:
+        file_path (str): the path to the Excel file.
+        query (str): Question about the data
+    """
+    try:
+        # Read the Excel file
+        df = pd.read_excel(file_path)
+
+        # Run various analyses based on the query
+        result = (
+            f"Excel file loaded with {len(df)} rows and {len(df.columns)} columns.\n"
+        )
+        result += f"Columns: {', '.join(df.columns)}\n\n"
+
+        # Add summary statistics
+        result += "Summary statistics:\n"
+        result += str(df.describe())
+
+        return result
+
+    except Exception as e:
+        return f"Error analyzing Excel file: {str(e)}"
+    
+@tool
+def analyze_image(image_base64: str) -> Dict[str, Any]:
+    """
+    Analyze basic properties of an image (size, mode, color analysis, thumbnail preview).
+    Args:
+        image_base64 (str): Base64 encoded image string
+    Returns:
+        Dictionary with analysis result
+    """
+    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)
+
+        return {
+            "dimensions": (width, height),
+            "mode": mode,
+            "color_analysis": color_analysis,
+            "thumbnail": thumbnail_base64,
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@tool
+def transform_image(
+    image_base64: str, operation: str, params: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Apply transformations: resize, rotate, crop, flip, brightness, contrast, blur, sharpen, grayscale.
+    Args:
+        image_base64 (str): Base64 encoded input image
+        operation (str): Transformation operation
+        params (Dict[str, Any], optional): Parameters for the operation
+    Returns:
+        Dictionary with transformed image (base64)
+    """
+    try:
+        img = decode_image(image_base64)
+        params = params or {}
+
+        if operation == "resize":
+            img = img.resize(
+                (
+                    params.get("width", img.width // 2),
+                    params.get("height", img.height // 2),
+                )
+            )
+        elif operation == "rotate":
+            img = img.rotate(params.get("angle", 90), expand=True)
+        elif operation == "crop":
+            img = img.crop(
+                (
+                    params.get("left", 0),
+                    params.get("top", 0),
+                    params.get("right", img.width),
+                    params.get("bottom", img.height),
+                )
+            )
+        elif operation == "flip":
+            if params.get("direction", "horizontal") == "horizontal":
+                img = ImageOps.mirror(img)
+            else:
+                img = ImageOps.flip(img)
+        elif operation == "adjust_brightness":
+            img = ImageEnhance.Brightness(img).enhance(params.get("factor", 1.5))
+        elif operation == "adjust_contrast":
+            img = ImageEnhance.Contrast(img).enhance(params.get("factor", 1.5))
+        elif operation == "blur":
+            img = img.filter(ImageFilter.GaussianBlur(params.get("radius", 2)))
+        elif operation == "sharpen":
+            img = img.filter(ImageFilter.SHARPEN)
+        elif operation == "grayscale":
+            img = img.convert("L")
+        else:
+            return {"error": f"Unknown operation: {operation}"}
+
+        result_path = save_image(img)
+        result_base64 = encode_image(result_path)
+        return {"transformed_image": result_base64}
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@tool
+def draw_on_image(
+    image_base64: str, drawing_type: str, params: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Draw shapes (rectangle, circle, line) or text onto an image.
+    Args:
+        image_base64 (str): Base64 encoded input image
+        drawing_type (str): Drawing type
+        params (Dict[str, Any]): Drawing parameters
+    Returns:
+        Dictionary with result image (base64)
+    """
+    try:
+        img = decode_image(image_base64)
+        draw = ImageDraw.Draw(img)
+        color = params.get("color", "red")
+
+        if drawing_type == "rectangle":
+            draw.rectangle(
+                [params["left"], params["top"], params["right"], params["bottom"]],
+                outline=color,
+                width=params.get("width", 2),
+            )
+        elif drawing_type == "circle":
+            x, y, r = params["x"], params["y"], params["radius"]
+            draw.ellipse(
+                (x - r, y - r, x + r, y + r),
+                outline=color,
+                width=params.get("width", 2),
+            )
+        elif drawing_type == "line":
+            draw.line(
+                (
+                    params["start_x"],
+                    params["start_y"],
+                    params["end_x"],
+                    params["end_y"],
+                ),
+                fill=color,
+                width=params.get("width", 2),
+            )
+        elif drawing_type == "text":
+            font_size = params.get("font_size", 20)
+            try:
+                font = ImageFont.truetype("arial.ttf", font_size)
+            except IOError:
+                font = ImageFont.load_default()
+            draw.text(
+                (params["x"], params["y"]),
+                params.get("text", "Text"),
+                fill=color,
+                font=font,
+            )
+        else:
+            return {"error": f"Unknown drawing type: {drawing_type}"}
+
+        result_path = save_image(img)
+        result_base64 = encode_image(result_path)
+        return {"result_image": result_base64}
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@tool
+def generate_simple_image(
+    image_type: str,
+    width: int = 500,
+    height: int = 500,
+    params: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Generate a simple image (gradient, noise, pattern, chart).
+    Args:
+        image_type (str): Type of image
+        width (int), height (int)
+        params (Dict[str, Any], optional): Specific parameters
+    Returns:
+        Dictionary with generated image (base64)
+    """
+    try:
+        params = params or {}
+
+        if image_type == "gradient":
+            direction = params.get("direction", "horizontal")
+            start_color = params.get("start_color", (255, 0, 0))
+            end_color = params.get("end_color", (0, 0, 255))
+
+            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")
+
+        else:
+            return {"error": f"Unsupported image_type {image_type}"}
+
+        result_path = save_image(img)
+        result_base64 = encode_image(result_path)
+        return {"generated_image": result_base64}
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@tool
+def combine_images(
+    images_base64: List[str], operation: str, params: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Combine multiple images (collage, stack, blend).
+    Args:
+        images_base64 (List[str]): List of base64 images
+        operation (str): Combination type
+        params (Dict[str, Any], optional)
+    Returns:
+        Dictionary with combined image (base64)
+    """
+    try:
+        images = [decode_image(b64) for b64 in images_base64]
+        params = params or {}
+
+        if operation == "stack":
+            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)
+                new_img = Image.new("RGB", (total_width, max_height))
+                x = 0
+                for img in images:
+                    new_img.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)
+                new_img = Image.new("RGB", (max_width, total_height))
+                y = 0
+                for img in images:
+                    new_img.paste(img, (0, y))
+                    y += img.height
+        else:
+            return {"error": f"Unsupported combination operation {operation}"}
+
+        result_path = save_image(new_img)
+        result_base64 = encode_image(result_path)
+        return {"combined_image": result_base64}
+
+    except Exception as e:
+        return {"error": str(e)}