Split into manager + 3 subagents + answer normalizer

Architecture:
BasicAgent (manager)
├── web_research -> WebResearchAgent (Tavily + fetch_url)
├── file_analysis -> FileAnalysisAgent (PDF/XLSX/CSV/TXT/JSON)
├── media_analysis -> MediaAgent (VLM/Whisper/YouTube/video)
├── python_exec -> direct
├── calculator -> direct
└── AnswerNormalizer -> GAIA-style final formatting

agents.py: replace flat ResearchAgent with WebResearchAgent,
FileAnalysisAgent, MediaAgent (all via langchain.agents.create_agent
with topic-specific system prompts) and AnswerNormalizer (single LLM
call enforcing GAIA answer format).

tools.py: add read_text_file. Wrap each subagent as a @tool
(web_research / file_analysis / media_analysis). ALL_TOOLS now
exposes only the 5 manager-level tools; low-level tools stay
declared for the subagents to import.

app.py: BasicAgent gets a manager system prompt describing routing
rules, and answer() pipes the raw output through AnswerNormalizer
before returning.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ryPUj8AtsFopnufGRSc4L

agents.py

@@ -1,40 +1,158 @@
 import os
 
-from langchain_groq import ChatGroq
 from langchain.agents import create_agent
+from langchain_core.messages import HumanMessage, SystemMessage
+from langchain_groq import ChatGroq
+
 
+def _make_llm(model: str = "openai/gpt-oss-120b", temperature: float = 0.1) -> ChatGroq:
+    return ChatGroq(
+        model=model,
+        temperature=temperature,
+        api_key=os.getenv("GROQ_API_KEY"),
+    )
 
-RESEARCH_SYSTEM_PROMPT = """You are a research specialist.
+
+WEB_RESEARCH_PROMPT = """You are a web research specialist.
 
 For each question:
-1. Mentally break it into sub-questions if it has multiple parts.
-2. Use the search tool to find sources. When the fact is not obvious,
-   cross-check across at least 2 independent sources before concluding.
-3. Return a concise, factual answer. If the question asks for a specific
-   value (number, name, date, list), give ONLY that value in the final
-   answer. Otherwise, keep the answer under 3 sentences.
-4. Never guess. If you cannot verify, say "unknown".
-"""
+1. Break it into sub-questions if needed.
+2. Use `search_tool` to find candidate sources. When a search snippet is
+   ambiguous or truncated, call `fetch_url` on the most relevant hit to
+   read the actual page.
+3. Cross-check facts across at least 2 independent sources before concluding
+   when the answer is not obvious.
+4. Return a concise, factual answer. If the question asks for a specific
+   value (number, name, date, list), give ONLY that value. Otherwise, keep
+   the answer under 3 sentences.
+5. Never guess. If you cannot verify, say "unknown"."""
+
+
+FILE_ANALYSIS_PROMPT = """You are a document analysis specialist.
+
+You handle questions that reference a task_id, URL, or file path pointing to
+a document (PDF, XLSX, CSV, TXT, JSON, MD).
+
+Workflow:
+1. If given a task_id (no extension, no slash), call `download_task_file`
+   to fetch the file and get its local path.
+2. Route by extension:
+   - .pdf -> read_pdf
+   - .xlsx / .xls -> read_excel
+   - .csv -> read_csv
+   - anything else textual -> read_text_file
+3. Answer the user's question from the extracted content. Quote values
+   verbatim when possible. Do not speculate."""
+
+
+MEDIA_ANALYSIS_PROMPT = """You are a media analysis specialist (image, audio, video).
+
+You handle questions that reference a task_id, URL, or file path pointing to
+media, or a YouTube URL.
 
+Workflow:
+1. If given a task_id, call `download_task_file` first to get a local path.
+2. Route by content type:
+   - Image (.jpg/.png/.webp/...) -> analyze_image
+   - Audio (.mp3/.wav/.m4a/.flac/...) -> transcribe_audio, then reason on the text
+   - Video file or non-YouTube video URL -> analyze_video; if audio matters, also transcribe_audio on the same file
+   - YouTube URL -> try `youtube_transcript` first; if captions are missing or
+     the question is about visuals, also call `analyze_video`
+3. Give ONLY the answer the question asks for. No preamble."""
 
-class ResearchAgent:
+
+GAIA_NORMALIZER_PROMPT = """You are a strict answer normalizer for the GAIA benchmark.
+
+You receive a QUESTION and a RAW answer produced by an agent. Return ONLY the
+final answer in exactly the format the question requires:
+
+- Numbers: digits only, no thousand separators, no units unless the question
+  explicitly asks for units. "3,141" -> "3141". "42 seconds" -> "42" unless
+  the question asked for a unit.
+- Names / entities: just the name, no articles ("the"), no titles, no
+  explanatory prefix like "The answer is".
+- Yes/No: exactly "Yes" or "No".
+- Lists: comma-separated, in the order the question asks (alphabetical,
+  chronological, ...). No trailing "and".
+- Dates: match the format the question asks for; if unspecified, use
+  YYYY-MM-DD.
+
+Never explain, never apologize, never quote the answer.
+Output ONLY the normalized answer, on a single line, nothing else."""
+
+
+class WebResearchAgent:
     def __init__(self):
-        llm = ChatGroq(
-            model="openai/gpt-oss-120b",
-            temperature=0.1,
-            api_key=os.getenv("GROQ_API_KEY"),
+        from tools import fetch_url, search_tool  # lazy: avoids circular import
+
+        self.graph = create_agent(
+            _make_llm(),
+            tools=[search_tool, fetch_url],
+            system_prompt=WEB_RESEARCH_PROMPT,
+        )
+
+    def __call__(self, question: str) -> str:
+        result = self.graph.invoke({"messages": [("user", question)]})
+        return result["messages"][-1].content
+
+
+class FileAnalysisAgent:
+    def __init__(self):
+        from tools import (
+            download_task_file,
+            read_csv,
+            read_excel,
+            read_pdf,
+            read_text_file,
         )
-        from tools import search_tool  # lazy: avoids circular import with tools.py
 
         self.graph = create_agent(
-            llm,
-            tools=[search_tool],
-            system_prompt=RESEARCH_SYSTEM_PROMPT,
+            _make_llm(),
+            tools=[download_task_file, read_pdf, read_excel, read_csv, read_text_file],
+            system_prompt=FILE_ANALYSIS_PROMPT,
         )
 
     def __call__(self, question: str) -> str:
-        return self.answer(question)
+        result = self.graph.invoke({"messages": [("user", question)]})
+        return result["messages"][-1].content
+
+
+class MediaAgent:
+    def __init__(self):
+        from tools import (
+            analyze_image,
+            analyze_video,
+            download_task_file,
+            transcribe_audio,
+            youtube_transcript,
+        )
+
+        self.graph = create_agent(
+            _make_llm(),
+            tools=[
+                download_task_file,
+                analyze_image,
+                analyze_video,
+                transcribe_audio,
+                youtube_transcript,
+            ],
+            system_prompt=MEDIA_ANALYSIS_PROMPT,
+        )
 
-    def answer(self, question: str) -> str:
+    def __call__(self, question: str) -> str:
         result = self.graph.invoke({"messages": [("user", question)]})
         return result["messages"][-1].content
+
+
+class AnswerNormalizer:
+    def __init__(self):
+        self.llm = _make_llm(temperature=0.0)
+
+    def __call__(self, question: str, raw_answer: str) -> str:
+        response = self.llm.invoke([
+            SystemMessage(content=GAIA_NORMALIZER_PROMPT),
+            HumanMessage(
+                content=f"QUESTION:\n{question}\n\nRAW ANSWER:\n{raw_answer}"
+            ),
+        ])
+        return response.content.strip()

app.py

@@ -8,11 +8,34 @@ from langchain_groq import ChatGroq
 from typing import TypedDict, Annotated
 from langgraph.graph.message import add_messages
 from langgraph.graph import START, StateGraph
-from langchain_core.messages import AnyMessage, HumanMessage
+from langchain_core.messages import AnyMessage, HumanMessage, SystemMessage
 from tools import ALL_TOOLS
+from agents import AnswerNormalizer
 from langgraph.prebuilt import tools_condition
 from langgraph.prebuilt import ToolNode
 
+
+MANAGER_SYSTEM_PROMPT = """You are a QA agent for the GAIA benchmark.
+
+You have five tools:
+- web_research(question): factual/current world knowledge (people, dates, events).
+- file_analysis(question): question about an attached document
+  (pdf/xlsx/csv/txt/json). Include the task_id or URL in your question.
+- media_analysis(question): question about an image, audio, or video (also
+  YouTube URLs). Include the task_id or URL in your question.
+- python_exec(code): run Python for computation, list ops, date math,
+  string parsing. You must print() the result.
+- calculator(expression): plain math expressions.
+
+Rules:
+1. When a task has an attached file (mentioned by task_id), route to
+   file_analysis or media_analysis with the task_id embedded in the question.
+2. Ask each specialist ONE precise question at a time.
+3. Chain tools when needed (e.g. web_research to find a number, then
+   calculator to combine).
+4. Final answer: give ONLY the value the question asks for. No preamble,
+   no explanation."""
+
 # (Keep Constants as is)
 # --- Constants ---
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
@@ -45,6 +68,7 @@ class BasicAgent:
         )
         self.chat = self.chat.bind_tools(self.tools)
         self.agent = self.__init__agent__()
+        self.normalizer = AnswerNormalizer()
 
     def __call__(self, question: str) -> str:
         return self.answer(question)
@@ -59,14 +83,18 @@ class BasicAgent:
         return builder.compile()
 
     def assitant(self, state: AgentState):
+        messages = state["messages"]
+        if not messages or not isinstance(messages[0], SystemMessage):
+            messages = [SystemMessage(content=MANAGER_SYSTEM_PROMPT)] + list(messages)
         return {
-            "messages": [self.chat.invoke(state["messages"])],
+            "messages": [self.chat.invoke(messages)],
         }
 
     def answer(self, question):
         messages = [HumanMessage(content=question)]
         response = self.agent.invoke({"messages": messages})
-        return response["messages"][-1].content
+        raw = response["messages"][-1].content
+        return self.normalizer(question, raw)
 
 
 def run_and_submit_all(profile: gr.OAuthProfile | None):

tools.py

@@ -13,7 +13,7 @@ from langchain_core.tools import tool
 from langchain_groq import ChatGroq
 from tavily import TavilyClient
 
-from agents import ResearchAgent
+from agents import FileAnalysisAgent, MediaAgent, WebResearchAgent
 
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
 
@@ -150,6 +150,16 @@ def read_csv(path: str) -> str:
     return pd.read_csv(path).to_string()
 
 
+@tool
+def read_text_file(path: str) -> str:
+    """Read a plain-text file (txt, json, md, py, ...) and return its contents.
+
+    Args:
+        path: Local file path.
+    """
+    return Path(path).read_text(encoding="utf-8", errors="replace")
+
+
 @tool
 def python_exec(code: str) -> str:
     """Execute Python code in a subprocess and return stdout (and stderr).
@@ -368,37 +378,63 @@ def youtube_transcript(url_or_id: str) -> str:
     return " ".join(e["text"] for e in entries)
 
 
-research_agent = ResearchAgent()
+_web_agent = WebResearchAgent()
+_file_agent = FileAnalysisAgent()
+_media_agent = MediaAgent()
 
 
 @tool
-def research(request: str) -> str:
-    """Answer factual questions using web research.
+def web_research(question: str) -> str:
+    """Answer a factual question using web search and page reading.
 
-    Use this when the user asks for information that requires up-to-date or
-    external knowledge — names, dates, events, statistics, biographies, or
-    anything that depends on the current state of the world. Handles query
-    decomposition, web search, cross-checking and synthesis.
+    Delegates to a specialist that searches (Tavily), visits pages when
+    snippets are insufficient, and cross-checks. Use for anything requiring
+    up-to-date or external world knowledge: people, dates, events, statistics,
+    biographies, current affairs.
+
+    Args:
+        question: Natural-language research question.
+    """
+    return _web_agent(question)
+
+
+@tool
+def file_analysis(question: str) -> str:
+    """Answer a question about an attached document (PDF, XLSX, CSV, TXT, JSON).
 
-    Input: Natural language research question (e.g., 'who won the 2024 Nobel
-    Prize in Physics?')
+    Delegates to a specialist that downloads the file (given a task_id, URL,
+    or local path), routes to the right reader by extension, and answers.
+
+    Include the file reference in your question, e.g.:
+    "Given task_id abc-123, what is the total revenue in Q3?"
+
+    Args:
+        question: Natural-language question mentioning the task_id / URL / path.
+    """
+    return _file_agent(question)
+
+
+@tool
+def media_analysis(question: str) -> str:
+    """Answer a question about media (image, audio, or video).
+
+    Delegates to a specialist that downloads if needed, then routes to VLM /
+    Whisper / video frame sampling / YouTube captions.
+
+    Include the media reference in your question, e.g.:
+    "For task_id abc-123, what animal is shown?"
+    "Watch https://youtube.com/watch?v=... and tell me the speaker's main claim."
+
+    Args:
+        question: Natural-language question mentioning the task_id / URL / path.
     """
-    return research_agent(request)
+    return _media_agent(question)
 
 
 ALL_TOOLS = [
-    search_tool,
-    fetch_url,
-    wikipedia_lookup,
-    download_task_file,
-    read_pdf,
-    read_excel,
-    read_csv,
+    web_research,
+    file_analysis,
+    media_analysis,
     python_exec,
     calculator,
-    analyze_image,
-    analyze_video,
-    transcribe_audio,
-    youtube_transcript,
-    search_tool,
 ]