basic agent implementation

.gitignore

@@ -0,0 +1,5 @@
+.env
+*.ipynb
+.venv
+files
+__pycache__/

agent.py

@@ -0,0 +1,146 @@
+from langchain.chat_models import init_chat_model
+from urllib.parse import urlparse
+import os
+import base64
+import pandas as pd
+import requests
+from io import BytesIO, StringIO
+from typing import Annotated
+from tools import *
+from typing_extensions import TypedDict
+
+from langgraph.graph import StateGraph, START, END
+from langgraph.graph.message import add_messages
+from langchain_core.messages import SystemMessage
+
+from langgraph.prebuilt import ToolNode, tools_condition
+
+SUPPORTING_FILES_URL = "https://huggingface.co/datasets/gaia-benchmark/GAIA/resolve/main/2023/validation/"
+
+system_prompt = """You are a general AI assistant. I will ask you a question.
+
+You must:
+1. Think step-by-step (invisibly to the user).
+2. End your visible answer with the final answer only — nothing else.
+
+Rules for the final answer:
+- If the answer is a number:
+  • No commas in the number.
+  • No units (e.g., $, %, km) unless the question explicitly asks for them.
+- If the answer is a string:
+  • No articles ("a", "an", "the").
+  • No abbreviations (e.g., for city names).
+  • Write digits as plain words unless instructed otherwise.
+- If the answer is a comma-separated list:
+  • Apply the above rules individually to each element.
+
+IMPORTANT:
+- Do not add any extra words before or after the final answer.
+- Do not explain your reasoning to the user — keep it hidden.
+- The output must be exactly the final answer following the above rules.
+
+Examples:
+Q: Who wrote the novel 1984?
+A: George Orwell
+
+Q: How many plays did Shakespeare write?
+A: 38
+"""
+
+
+class State(TypedDict):
+    messages: Annotated[list, add_messages]
+    uploaded_filename: str
+    uploaded_file: str
+
+def _is_url(path_or_url: str) -> bool:
+    try:
+        result = urlparse(path_or_url)
+        return result.scheme in ("http", "https")
+    except:
+        return False
+
+def _process_uploaded_file(file_name: str, file_path: str) -> str:
+    """Process a single local file or file URL and return context for the question."""
+    try:
+        if _is_url(file_path):
+            response = requests.get(file_path)
+            response.raise_for_status()
+
+            file_ext = os.path.splitext(file_name)[1].lower()
+            content_bytes = response.content
+
+            if file_ext in ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp']:
+                return f"[UPLOADED IMAGE: {file_name}] - URL: {file_path}"
+
+            elif file_ext in ['.txt', '.md', '.py', '.js', '.html', '.css', '.json', '.xml']:
+                content_text = content_bytes.decode('utf-8')
+                return f"[Code Content:\n{content_text}"
+
+            elif file_ext == '.csv':
+                df = pd.read_csv(StringIO(content_bytes.decode('utf-8')))
+                return f"[UPLOADED CSV FILE: {file_name}] : {df}"
+
+            elif file_ext in ['.xlsx', '.xls']:
+                df = pd.read_excel(BytesIO(content_bytes))
+                return f"[EXCEL FILE DATAFRAME: {df}"
+
+            else:
+                return f"[UPLOADED FILE: {file_name}] - URL: {file_path}"
+
+    except Exception as e:
+        print(f"Error processing file {file_path}: {e}")
+        return f"[ERROR PROCESSING FILE: {os.path.basename(file_path)}] - {str(e)}"
+
+def build_and_compile():
+    graph_builder = StateGraph(State)
+    tools = [
+    web_search,
+    wiki_search,
+    academic_search,
+    python_code,
+    image_info,
+    read_mp3_transcript,
+    pdf_text_extractor,
+    ocr_image,
+    math_solver,
+    plot_data_tool,
+    unit_converter,
+    date_time_calculator,
+    api_request_tool,
+    html_table_extractor,
+    multiply,
+    add,
+    subtract,
+    divide,
+    modulus,
+    power,
+    square_root
+    ]
+
+
+    llm = init_chat_model("openai:gpt-4.1-mini",temperature=0, seed=42)
+    llm_with_tools = llm.bind_tools(tools)
+
+    def chatbot(state: State):
+        file_context = ""
+        if "uploaded_file" in state and state["uploaded_file"]:
+            file_context = "\n\nAdditional file context:\n" + _process_uploaded_file(file_name=state["uploaded_filename"],file_path=state["uploaded_file"])
+        final_prompt = system_prompt + file_context
+        return {"messages": [llm_with_tools.invoke([SystemMessage(final_prompt)] + state["messages"])]}
+
+
+    graph_builder.add_node("chatbot", chatbot)
+
+    tool_node = ToolNode(tools=tools)
+    graph_builder.add_node("tools", tool_node)
+
+    graph_builder.add_conditional_edges(
+        "chatbot",
+        tools_condition,
+    )
+    # Any time a tool is called, we return to the chatbot to decide the next step
+    graph_builder.add_edge("tools", "chatbot")
+    graph_builder.add_edge(START, "chatbot")
+    graph = graph_builder.compile()
+    return graph

app.py

@@ -3,6 +3,7 @@ import gradio as gr
 import requests
 import inspect
 import pandas as pd
+from agent import build_and_compile
 
 # (Keep Constants as is)
 # --- Constants ---
@@ -12,12 +13,19 @@ DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
 # ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
 class BasicAgent:
     def __init__(self):
-        print("BasicAgent initialized.")
-    def __call__(self, question: str) -> str:
-        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
+        self.graph = build_and_compile()
+    def __call__(self, question: str, file_name: str = "", file_path: str = "", debug: bool = False) -> str:
+        if file_path != "":
+            state = {"messages": [{"role": "user", "content": question}],
+                     "uploaded_filename" : file_name, "uploaded_file": file_path}
+        else:
+            state = {"messages": [{"role": "user", "content": question}]}
+
+        full_answer = self.graph.invoke(state, {"recursion_limit": 100})['messages']
+        if debug == True:
+            return full_answer
+        else:
+            return full_answer[-1].content
 
 def run_and_submit_all( profile: gr.OAuthProfile | None):
     """
@@ -76,11 +84,13 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
     for item in questions_data:
         task_id = item.get("task_id")
         question_text = item.get("question")
+        file_name = item.get("file_name")
+        file_path = f'https://agents-course-unit4-scoring.hf.space/files/{task_id}'
         if not task_id or question_text is None:
             print(f"Skipping item with missing task_id or question: {item}")
             continue
         try:
-            submitted_answer = agent(question_text)
+            submitted_answer = agent(question=question_text, file_name=file_name, file_path=file_path)
             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:
@@ -91,7 +101,7 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
         print("Agent did not produce any answers to submit.")
         return "Agent did not produce any answers to submit.", pd.DataFrame(results_log)
 
-    # 4. Prepare Submission 
+    # 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)
@@ -193,4 +203,4 @@ if __name__ == "__main__":
     print("-"*(60 + len(" App Starting ")) + "\n")
 
     print("Launching Gradio Interface for Basic Agent Evaluation...")
-    demo.launch(debug=True, share=False)
+    demo.launch(debug=True, share=False)

requirements.txt

@@ -1,2 +1,152 @@
-gradio
-requests
+aiofiles==24.1.0
+aiohappyeyeballs==2.6.1
+aiohttp==3.12.15
+aiosignal==1.4.0
+annotated-types==0.7.0
+anyio==4.10.0
+appnope==0.1.4
+arxiv==2.2.0
+asttokens==3.0.0
+async-timeout==4.0.3
+attrs==25.3.0
+beautifulsoup4==4.13.4
+Brotli==1.1.0
+certifi==2025.8.3
+cffi==1.17.1
+charset-normalizer==3.4.3
+click==8.2.1
+comm==0.2.3
+contourpy==1.3.2
+cryptography==45.0.6
+cycler==0.12.1
+dataclasses-json==0.6.7
+datasets==2.14.6
+debugpy==1.8.16
+decorator==5.2.1
+dill==0.3.7
+distro==1.9.0
+et_xmlfile==2.0.0
+exceptiongroup==1.3.0
+executing==2.2.0
+fastapi==0.116.1
+feedparser==6.0.11
+ffmpy==0.6.1
+filelock==3.18.0
+flexcache==0.3
+flexparser==0.4
+fonttools==4.59.0
+frozenlist==1.7.0
+fsspec==2023.10.0
+gradio==5.42.0
+gradio_client==1.11.1
+greenlet==3.2.4
+groovy==0.1.2
+h11==0.16.0
+hf-xet==1.1.7
+httpcore==1.0.9
+httpx==0.28.1
+httpx-sse==0.4.1
+huggingface-hub==0.34.4
+idna==3.10
+ipykernel==6.30.1
+ipython==8.37.0
+jedi==0.19.2
+Jinja2==3.1.6
+jiter==0.10.0
+jsonpatch==1.33
+jsonpointer==3.0.0
+jupyter_client==8.6.3
+jupyter_core==5.8.1
+kiwisolver==1.4.9
+langchain==0.3.27
+langchain-community==0.3.27
+langchain-core==0.3.74
+langchain-experimental==0.3.4
+langchain-openai==0.3.29
+langchain-tavily==0.2.11
+langchain-text-splitters==0.3.9
+langgraph==0.6.4
+langgraph-checkpoint==2.1.1
+langgraph-prebuilt==0.6.4
+langgraph-sdk==0.2.0
+langsmith==0.4.13
+markdown-it-py==3.0.0
+MarkupSafe==3.0.2
+marshmallow==3.26.1
+matplotlib==3.10.5
+matplotlib-inline==0.1.7
+mdurl==0.1.2
+multidict==6.6.3
+multiprocess==0.70.15
+mypy_extensions==1.1.0
+nest-asyncio==1.6.0
+numpy==1.26.4
+openai==1.99.6
+openpyxl==3.1.5
+orjson==3.11.1
+ormsgpack==1.10.0
+packaging==25.0
+pandas==2.3.1
+parso==0.8.4
+pdfminer.six==20250506
+pdfplumber==0.11.7
+pexpect==4.9.0
+pillow==11.3.0
+Pint==0.24.4
+platformdirs==4.3.8
+prompt_toolkit==3.0.51
+propcache==0.3.2
+psutil==7.0.0
+ptyprocess==0.7.0
+pure_eval==0.2.3
+pyarrow==14.0.1
+pycparser==2.22
+pydantic==2.11.7
+pydantic-settings==2.10.1
+pydantic_core==2.33.2
+pydub==0.25.1
+Pygments==2.19.2
+PyMuPDF==1.26.3
+pyparsing==3.2.3
+pypdfium2==4.30.0
+pytesseract==0.3.13
+python-dateutil==2.9.0.post0
+python-dotenv==1.1.1
+python-multipart==0.0.20
+pytz==2025.2
+PyYAML==6.0.2
+pyzmq==27.0.1
+regex==2025.7.34
+requests==2.32.4
+requests-toolbelt==1.0.0
+rich==14.1.0
+ruff==0.12.8
+safehttpx==0.1.6
+semantic-version==2.10.0
+sgmllib3k==1.0.0
+shellingham==1.5.4
+six==1.17.0
+sniffio==1.3.1
+soupsieve==2.7
+SQLAlchemy==2.0.42
+stack-data==0.6.3
+starlette==0.47.2
+tenacity==9.1.2
+tiktoken==0.11.0
+tomlkit==0.13.3
+tornado==6.5.2
+tqdm==4.67.1
+traitlets==5.14.3
+typer==0.16.0
+typing-inspect==0.9.0
+typing-inspection==0.4.1
+typing_extensions==4.14.1
+tzdata==2025.2
+urllib3==2.5.0
+uvicorn==0.35.0
+wcwidth==0.2.13
+websockets==15.0.1
+wikipedia==1.4.0
+xxhash==3.5.0
+yarl==1.20.1
+zstandard==0.23.0

tools.py

@@ -0,0 +1,510 @@
+from __future__ import annotations
+
+import os
+import io
+import re
+import json
+import base64
+import traceback
+from typing import Optional, List, Dict, Any
+import cmath
+
+import requests
+import pandas as pd
+from PIL import Image
+
+# Optional deps
+try:
+    import pdfplumber
+except Exception:
+    pdfplumber = None
+
+try:
+    import pytesseract
+except Exception:
+    pytesseract = None
+
+try:
+    import sympy as sp
+except Exception:
+    sp = None
+
+try:
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+except Exception:
+    plt = None
+
+try:
+    from pint import UnitRegistry
+    _ureg = UnitRegistry()
+except Exception:
+    _ureg = None
+
+try:
+    from dateutil import parser as dtparser
+    from dateutil.relativedelta import relativedelta
+except Exception:
+    dtparser = None
+    relativedelta = None
+
+
+# LangChain bits
+from langchain_core.tools import tool
+from langchain_tavily.tavily_search import TavilySearch
+from langchain_community.document_loaders import WikipediaLoader, ArxivLoader
+from langchain_experimental.utilities import PythonREPL
+
+
+# ------------ helpers (formatting, env, truncation, errors) ------------
+
+def _env(name: str, default: Optional[str] = None) -> Optional[str]:
+    return os.getenv(name, default)
+
+def _truncate(txt: str, max_len: int = 4000) -> str:
+    if txt is None:
+        return ""
+    if len(txt) <= max_len:
+        return txt
+    head = max_len - 200
+    return txt[:head] + f"\n... [truncated {len(txt) - head} chars]"
+
+def _fmt_block(tag: str, attrs: Dict[str, Any] | None, body: str) -> str:
+    attrs = attrs or {}
+    attr_str = " ".join(f'{k}="{attrs[k] if attrs[k] is not None else ""}"' for k in attrs)
+    if attr_str:
+        return f"<{tag} {attr_str}>\n{body}\n</{tag}>"
+    return f"<{tag}>\n{body}\n</{tag}>"
+
+def _fmt_error(tool_name: str, err: Exception) -> str:
+    return _fmt_block(
+        "ToolError",
+        {"tool": tool_name, "type": err.__class__.__name__},
+        _truncate(f"{err}\n{traceback.format_exc()}", 1600),
+    )
+
+
+
+@tool("web_search")
+def web_search(query: str) -> str:
+    """Search the web (Tavily). Returns up to 3 results in <Document> blocks + optional <Answer>."""
+    try:
+        api_key = _env("TAVILY_API_KEY")
+        tavily = TavilySearch(
+            tavily_api_key=api_key,
+            max_results=3,
+            include_answer=True,
+            search_depth="advanced",
+            topic="general",
+            include_raw_content=False,
+        )
+        res = tavily._run(query=query)
+        docs = res.get("results", []) or []
+        blocks: List[str] = []
+        for d in docs:
+            blocks.append(
+                _fmt_block(
+                    "Document",
+                    {"source": d.get("url", ""), "title": d.get("title", "")},
+                    _truncate(d.get("content", "") or ""),
+                )
+            )
+        parts = []
+        ans = res.get("answer")
+        if ans:
+            parts.append(_fmt_block("Answer", {}, _truncate(str(ans), 1000)))
+        if blocks:
+            parts.append("\n\n---\n\n".join(blocks))
+        if not parts:
+            return _fmt_block("WebResults", {"query": query}, "No results.")
+        return _fmt_block("WebResults", {"query": query}, "\n\n".join(parts))
+    except Exception as e:
+        return _fmt_error("web_search", e)
+
+
+@tool("wiki_search")
+def wiki_search(query: str) -> str:
+    """Search Wikipedia and return up to 2 articles as <Document> blocks."""
+    try:
+        loader = WikipediaLoader(query=query, load_max_docs=2)
+        docs = loader.load()
+        blocks = []
+        for doc in docs:
+            meta = getattr(doc, "metadata", {}) or {}
+            blocks.append(
+                _fmt_block(
+                    "Document",
+                    {"source": meta.get("source", ""), "page": str(meta.get("page", ""))},
+                    _truncate(doc.page_content or "", 4000),
+                )
+            )
+        if not blocks:
+            return _fmt_block("WikiResults", {"query": query}, "No results.")
+        return _fmt_block("WikiResults", {"query": query}, "\n\n---\n\n".join(blocks))
+    except Exception as e:
+        return _fmt_error("wiki_search", e)
+
+
+@tool("academic_search")
+def academic_search(query: str) -> str:
+    """Search arXiv and return up to 3 papers as <Document> blocks."""
+    try:
+        loader = ArxivLoader(query=query, load_max_docs=3)
+        docs = loader.load()
+        blocks = []
+        for doc in docs:
+            meta = getattr(doc, "metadata", {}) or {}
+            title = meta.get("Title") or meta.get("title") or ""
+            published = meta.get("Published") or meta.get("published") or ""
+            blocks.append(
+                _fmt_block(
+                    "Document",
+                    {"title": str(title), "date": str(published)},
+                    _truncate(doc.page_content or "", 3000),
+                )
+            )
+        if not blocks:
+            return _fmt_block("ArxivResults", {"query": query}, "No results.")
+        return _fmt_block("ArxivResults", {"query": query}, "\n\n---\n\n".join(blocks))
+    except Exception as e:
+        return _fmt_error("academic_search", e)
+
+
+@tool("python_code")
+def python_code(code: str) -> str:
+    """
+    Execute Python code in a sandboxed REPL.
+    Input should be valid Python code.
+    """
+    try:
+        if code is None:
+            return "<ToolError>No code provided to python_code tool.</ToolError>"
+        python_repl = PythonREPL()
+        code_str = str(code)
+        output = python_repl.run(code_str)
+        if output is None:
+            return "(no output)"
+        return str(output).strip("\n")
+    except Exception as e:
+        return f"<ToolError>{type(e).__name__}: {e}</ToolError>"
+
+
+
+@tool("image_info")
+def image_info(path: str) -> str:
+    """Return basic info about an image (width x height, format)."""
+    try:
+        with Image.open(path) as img:
+            w, h, fmt = img.width, img.height, img.format
+        return _fmt_block("ImageInfo", {"path": path}, f"{w}x{h} ({fmt})")
+    except Exception as e:
+        return _fmt_error("image_info", e)
+
+
+@tool("read_mp3_transcript")
+def read_mp3_transcript(path: str) -> str:
+    """Transcribe an MP3 file (placeholder). Replace with actual ASR."""
+    try:
+        return _fmt_block("AudioTranscript", {"path": path}, "Transcription not implemented.")
+    except Exception as e:
+        return _fmt_error("read_mp3_transcript", e)
+
+
+@tool("pdf_text_extractor")
+def pdf_text_extractor(args: str) -> str:
+    """Extract text from a PDF. Usage:
+    - 'path/to/file.pdf'
+    - 'path/to/file.pdf|pages=1-3' (1-indexed inclusive range)
+    Returns a concatenated text excerpt (truncated)."""
+    try:
+        if pdfplumber is None:
+            raise RuntimeError("pdfplumber not installed")
+        path, start, end = args, None, None
+        m = re.search(r"\|pages=(\d+)-(\d+)$", args.strip())
+        if m:
+            path = args[: args.rfind("|pages=")]
+            start, end = int(m.group(1)), int(m.group(2))
+        text_parts: List[str] = []
+        with pdfplumber.open(path) as pdf:
+            total = len(pdf.pages)
+            s = max(1, start) if start else 1
+            e = min(end, total) if end else total
+            for p in range(s - 1, e):
+                page = pdf.pages[p]
+                text_parts.append(page.extract_text() or "")
+        text = "\n".join(text_parts).strip()
+        if not text:
+            text = "(no extractable text)"
+        meta = {"path": path, "pages": f"{start or 1}-{end or 'end'}"}
+        return _fmt_block("PDFText", meta, _truncate(text, 4000))
+    except Exception as e:
+        return _fmt_error("pdf_text_extractor", e)
+
+
+@tool("ocr_image")
+def ocr_image(path: str) -> str:
+    """Run OCR on an image and return extracted text (requires pytesseract + Tesseract installed)."""
+    try:
+        if pytesseract is None:
+            raise RuntimeError("pytesseract not installed or tesseract binary missing")
+        with Image.open(path) as img:
+            txt = pytesseract.image_to_string(img)
+        return _fmt_block("OCRText", {"path": path}, _truncate(txt.strip() or "(no text)", 4000))
+    except Exception as e:
+        return _fmt_error("ocr_image", e)
+
+
+@tool("math_solver")
+def math_solver(expr: str) -> str:
+    """Solve/compute a math expression with SymPy. Examples:
+    - 'integrate(sin(x)/x, (x, 0, 1))'
+    - 'solve(x**2 - 5*x + 6, x)'
+    - 'simplify((x**2 - 1)/(x - 1))'"""
+    try:
+        if sp is None:
+            raise RuntimeError("sympy not installed")
+        # Safe-ish sympify (no symbols defined → define common ones)
+        symbols = {s: sp.symbols(s) for s in list("abcdefghijklmnopqrstuvwxyz")}
+        res = sp.sympify(expr, locals=symbols)
+        # Try evalf if numeric
+        out = res.evalf() if hasattr(res, "evalf") else res
+        return _fmt_block("MathResult", {}, _truncate(str(out), 4000))
+    except Exception as e:
+        return _fmt_error("math_solver", e)
+
+
+@tool("plot_data_tool")
+def plot_data_tool(args: str) -> str:
+    """Create a simple plot from CSV.
+    Usage (JSON string):
+    {
+      "path": "data.csv",
+      "x": "col_x",       # optional if data has index
+      "y": "col_y",       # required
+      "kind": "line"      # 'line' or 'scatter'
+    }
+    Returns <ImageBase64> PNG."""
+    try:
+        if plt is None:
+            raise RuntimeError("matplotlib not available")
+        cfg = json.loads(args)
+        path = cfg.get("path")
+        xcol = cfg.get("x")
+        ycol = cfg["y"]
+        kind = (cfg.get("kind") or "line").lower()
+        df = pd.read_csv(path)
+        fig, ax = plt.subplots(figsize=(6, 4))
+        if kind == "scatter":
+            ax.scatter(df[xcol] if xcol else range(len(df[ycol])), df[ycol])
+        else:
+            ax.plot(df[xcol] if xcol else range(len(df[ycol])), df[ycol])
+        ax.set_xlabel(xcol or "index")
+        ax.set_ylabel(ycol)
+        ax.set_title(f"{os.path.basename(path)}: {ycol} vs {xcol or 'index'}")
+        buf = io.BytesIO()
+        fig.tight_layout()
+        fig.savefig(buf, format="png")
+        plt.close(fig)
+        b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
+        return _fmt_block("ImageBase64", {"format": "png"}, b64)
+    except Exception as e:
+        return _fmt_error("plot_data_tool", e)
+
+
+@tool("unit_converter")
+def unit_converter(query: str) -> str:
+    """Convert units. Examples:
+    - '12 inch to cm'
+    - '5 miles to kilometer'
+    - '32 degF to degC'"""
+    try:
+        if _ureg is None:
+            raise RuntimeError("pint not installed")
+        m = re.match(r"\s*([\-0-9\.]+)\s+([A-Za-z\/\^\*\s]+)\s+to\s+([A-Za-z\/\^\*\s]+)\s*$", query)
+        if not m:
+            raise ValueError("Format: '<value> <from_units> to <to_units>'")
+        val = float(m.group(1))
+        from_u = m.group(2).strip()
+        to_u = m.group(3).strip()
+        qty = val * _ureg(from_u)
+        conv = qty.to(to_u)
+        return _fmt_block("UnitConversion", {"from": from_u, "to": to_u}, f"{conv.magnitude} {conv.units}")
+    except Exception as e:
+        return _fmt_error("unit_converter", e)
+
+
+@tool("date_time_calculator")
+def date_time_calculator(query: str) -> str:
+    """Date/time math. Examples:
+    - 'diff 2024-01-01 2025-08-14'  → difference (y,m,d)
+    - 'add 2025-08-14 + 3 days'     → add delta
+    - 'add 2025-08-14 - 2 weeks'    → subtract delta
+    Accepts ISO dates; units: years, months, weeks, days, hours, minutes."""
+    try:
+        if dtparser is None or relativedelta is None:
+            raise RuntimeError("python-dateutil not installed")
+        s = query.strip()
+        if s.lower().startswith("diff"):
+            parts = s.split()
+            if len(parts) != 3:
+                raise ValueError("Use: diff YYYY-MM-DD YYYY-MM-DD")
+            d1 = dtparser.parse(parts[1])
+            d2 = dtparser.parse(parts[2])
+            rd = relativedelta(d2, d1)
+            return _fmt_block(
+                "DateDiff",
+                {"from": parts[1], "to": parts[2]},
+                f"{rd.years} years, {rd.months} months, {rd.days} days, "
+                f"{rd.hours} hours, {rd.minutes} minutes",
+            )
+        elif s.lower().startswith("add"):
+            # e.g., "add 2025-08-14 + 3 days" or "add 2025-08-14 - 2 weeks"
+            m = re.match(r"add\s+(\S+)\s*([+-])\s*(\d+)\s+(years?|months?|weeks?|days?|hours?|minutes?)", s, re.I)
+            if not m:
+                raise ValueError("Use: add <date> +/- <n> <unit>")
+            base = dtparser.parse(m.group(1))
+            sign = 1 if m.group(2) == "+" else -1
+            n = int(m.group(3)) * sign
+            unit = m.group(4).lower()
+            kwargs = {}
+            if "year" in unit: kwargs["years"] = n
+            elif "month" in unit: kwargs["months"] = n
+            elif "week" in unit: kwargs["weeks"] = n
+            elif "day" in unit: kwargs["days"] = n
+            elif "hour" in unit: kwargs["hours"] = n
+            elif "minute" in unit: kwargs["minutes"] = n
+            res = base + relativedelta(**kwargs)
+            return _fmt_block("DateAdd", {"base": base.isoformat(), "delta": f"{n} {unit}"}, res.isoformat())
+        else:
+            raise ValueError("Start with 'diff' or 'add'.")
+    except Exception as e:
+        return _fmt_error("date_time_calculator", e)
+
+
+@tool("api_request_tool")
+def api_request_tool(args: str) -> str:
+    """Call a JSON REST API.
+    Usage (JSON string):
+    {
+      "method": "GET",
+      "url": "https://api.example.com/items",
+      "headers": {"Authorization": "Bearer ..."},
+      "params": {"q": "search"},
+      "json": {"k": "v"},
+      "timeout": 20
+    }"""
+    try:
+        cfg = json.loads(args)
+        method = (cfg.get("method") or "GET").upper()
+        url = cfg["url"]
+        headers = cfg.get("headers") or {}
+        params = cfg.get("params") or {}
+        json_body = cfg.get("json")
+        timeout = cfg.get("timeout", 20)
+        resp = requests.request(method, url, headers=headers, params=params, json=json_body, timeout=timeout)
+        meta = {"status": resp.status_code, "url": url}
+        text = resp.text
+        # Try to pretty JSON if possible
+        try:
+            text = json.dumps(resp.json(), indent=2)[:4000]
+        except Exception:
+            text = _truncate(text, 4000)
+        return _fmt_block("APIResponse", meta, text)
+    except Exception as e:
+        return _fmt_error("api_request_tool", e)
+
+
+@tool("html_table_extractor")
+def html_table_extractor(url: str) -> str:
+    """Extract the first HTML table from a webpage and return CSV preview."""
+    try:
+        tables = pd.read_html(url)
+        if not tables:
+            return _fmt_block("HTMLTable", {"url": url}, "No tables found.")
+        df = tables[0]
+        buf = io.StringIO()
+        df.head(15).to_csv(buf, index=False)
+        summary = f"Shape: {df.shape[0]} rows x {df.shape[1]} cols\nColumns: {list(df.columns)}\n\nHead(15):\n{buf.getvalue()}"
+        return _fmt_block("HTMLTable", {"url": url}, _truncate(summary, 4000))
+    except Exception as e:
+        return _fmt_error("html_table_extractor", e)
+
+@tool
+def multiply(a: float, b: float) -> float:
+    """
+    Multiplies two numbers.
+    Args:
+        a (float): the first number
+        b (float): the second number
+    """
+    return a * b
+
+
+@tool
+def add(a: float, b: float) -> float:
+    """
+    Adds two numbers.
+    Args:
+        a (float): the first number
+        b (float): the second number
+    """
+    return a + b
+
+
+@tool
+def subtract(a: float, b: float) -> int:
+    """
+    Subtracts two numbers.
+    Args:
+        a (float): the first number
+        b (float): the second number
+    """
+    return a - b
+
+
+@tool
+def divide(a: float, b: float) -> float:
+    """
+    Divides two numbers.
+    Args:
+        a (float): the first float number
+        b (float): the second float number
+    """
+    if b == 0:
+        raise ValueError("Cannot divided by zero.")
+    return a / b
+
+
+@tool
+def modulus(a: int, b: int) -> int:
+    """
+    Get the modulus of two numbers.
+    Args:
+        a (int): the first number
+        b (int): the second number
+    """
+    return a % b
+
+
+@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)