Set up LangGraph GAIA agent skeleton

.env.example

@@ -0,0 +1,15 @@
+# Copy this file to .env for local development.
+# Do not commit real secrets.
+
+# LLM provider
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4o-mini
+
+# Langfuse tracing
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+LANGFUSE_HOST=https://cloud.langfuse.com
+
+# Optional assignment/runtime settings
+SPACE_ID=
+GAIA_API_URL=https://agents-course-unit4-scoring.hf.space

.gitignore

@@ -0,0 +1,8 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/

app.py

@@ -1,27 +1,17 @@
 import os
 import gradio as gr
 import requests
-import inspect
 import pandas as pd
 
-# (Keep Constants as is)
+from gaia_agent import GaiaAgent
+from gaia_agent.config import settings
+
 # --- Constants ---
-DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
-
-# --- Basic Agent Definition ---
-# ----- 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 = "Julien test"
-        print(f"Agent returning fixed answer: {fixed_answer}")
-        return fixed_answer
+DEFAULT_API_URL = settings.gaia_api_url
 
 def run_and_submit_all( profile: gr.OAuthProfile | None):
     """
-    Fetches all questions, runs the BasicAgent on them, submits all answers,
+    Fetches all questions, runs the GaiaAgent on them, submits all answers,
     and displays the results.
     """
     # --- Determine HF Space Runtime URL and Repo URL ---
@@ -40,7 +30,7 @@ def run_and_submit_all( profile: gr.OAuthProfile | None):
 
     # 1. Instantiate Agent ( modify this part to create your agent)
     try:
-        agent = BasicAgent()
+        agent = GaiaAgent()
     except Exception as e:
         print(f"Error instantiating agent: {e}")
         return f"Error initializing agent: {e}", None

gaia_agent/__init__.py

@@ -0,0 +1,3 @@
+from gaia_agent.agent import GaiaAgent
+
+__all__ = ["GaiaAgent"]

gaia_agent/agent.py

@@ -0,0 +1,16 @@
+from gaia_agent.graph import build_graph
+from gaia_agent.observability import trace_agent_run
+
+
+class GaiaAgent:
+    def __init__(self):
+        print("GaiaAgent initialized.")
+
+    def __call__(self, question: str) -> str:
+        print(f"Agent received question (first 80 chars): {question[:80]}...")
+        with trace_agent_run(question) as trace:
+            graph = build_graph(trace=trace)
+            result = graph.invoke({"question": question})
+        final_answer = result["final_answer"]
+        print(f"Agent returning answer: {final_answer}")
+        return final_answer

gaia_agent/answer.py

@@ -0,0 +1,3 @@
+def normalize_answer(answer: str) -> str:
+    """Apply minimal GAIA answer cleanup without changing meaning."""
+    return answer.strip()

gaia_agent/config.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+import os
+
+from dotenv import load_dotenv
+
+
+load_dotenv()
+
+
+@dataclass(frozen=True)
+class Settings:
+    openai_api_key: str | None = os.getenv("OPENAI_API_KEY")
+    openai_model: str = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+    langfuse_public_key: str | None = os.getenv("LANGFUSE_PUBLIC_KEY")
+    langfuse_secret_key: str | None = os.getenv("LANGFUSE_SECRET_KEY")
+    langfuse_host: str = os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com")
+    gaia_api_url: str = os.getenv(
+        "GAIA_API_URL",
+        "https://agents-course-unit4-scoring.hf.space",
+    )
+
+
+settings = Settings()

gaia_agent/graph.py

@@ -0,0 +1,32 @@
+from langgraph.graph import END, StateGraph
+
+from gaia_agent.answer import normalize_answer
+from gaia_agent.observability import traced_step
+from gaia_agent.state import GaiaState
+
+
+PLACEHOLDER_ANSWER = "Julien test"
+
+
+def build_graph(trace=None):
+    graph = StateGraph(GaiaState)
+
+    def draft_answer(state: GaiaState) -> GaiaState:
+        def run() -> dict[str, str]:
+            return {"draft_answer": PLACEHOLDER_ANSWER}
+
+        return traced_step(trace, "draft_answer", run)
+
+    def normalize_final_answer(state: GaiaState) -> GaiaState:
+        def run() -> dict[str, str]:
+            return {"final_answer": normalize_answer(state["draft_answer"])}
+
+        return traced_step(trace, "normalize_final_answer", run)
+
+    graph.add_node("draft_answer", draft_answer)
+    graph.add_node("normalize_final_answer", normalize_final_answer)
+    graph.set_entry_point("draft_answer")
+    graph.add_edge("draft_answer", "normalize_final_answer")
+    graph.add_edge("normalize_final_answer", END)
+
+    return graph.compile()

gaia_agent/observability.py

@@ -0,0 +1,52 @@
+from collections.abc import Callable
+from contextlib import contextmanager
+from typing import Any
+
+from gaia_agent.config import settings
+
+
+def langfuse_enabled() -> bool:
+    return bool(settings.langfuse_public_key and settings.langfuse_secret_key)
+
+
+@contextmanager
+def trace_agent_run(question: str):
+    """Create a Langfuse trace when credentials are configured.
+
+    This keeps local development and HF Space startup working before secrets are set.
+    """
+    if not langfuse_enabled():
+        yield None
+        return
+
+    from langfuse import Langfuse
+
+    client = Langfuse(
+        public_key=settings.langfuse_public_key,
+        secret_key=settings.langfuse_secret_key,
+        host=settings.langfuse_host,
+    )
+    with client.start_as_current_observation(
+        name="gaia-agent-run",
+        as_type="agent",
+        input={"question": question},
+        metadata={"component": "GaiaAgent"},
+    ) as observation:
+        try:
+            yield observation
+        finally:
+            client.flush()
+
+
+def traced_step(trace: Any, name: str, fn: Callable[[], dict[str, Any]]) -> dict[str, Any]:
+    if trace is None:
+        return fn()
+
+    span = trace.start_observation(name=name, as_type="span")
+    try:
+        output = fn()
+        span.end(output=output)
+        return output
+    except Exception as exc:
+        span.end(level="ERROR", status_message=str(exc))
+        raise

gaia_agent/prompts.py

@@ -0,0 +1,5 @@
+GAIA_FINAL_ANSWER_INSTRUCTIONS = """
+Return only the final answer.
+The answer should be a number, as few words as possible, or a comma-separated
+list of numbers and/or strings.
+""".strip()

gaia_agent/state.py

@@ -0,0 +1,7 @@
+from typing import TypedDict
+
+
+class GaiaState(TypedDict, total=False):
+    question: str
+    draft_answer: str
+    final_answer: str

gaia_agent/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool modules will be added incrementally as the GAIA agent grows."""

gaia_agent/tools/files.py

@@ -0,0 +1 @@
+"""File-reading tools will live here."""

gaia_agent/tools/python_repl.py

@@ -0,0 +1 @@
+"""Python execution tools will live here."""

gaia_agent/tools/search.py

@@ -0,0 +1 @@
+"""Search tools will live here."""

gaia_agent/tools/web.py

@@ -0,0 +1 @@
+"""Web browsing tools will live here."""

pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "gaia-final-assignment-agent"
+version = "0.1.0"
+description = "LangGraph agent for the Hugging Face GAIA final assignment."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "gradio[oauth]==5.25.2",
+    "requests>=2.32.0",
+    "pandas>=2.2.0",
+    "python-dotenv>=1.0.1",
+    "langchain>=0.3.0",
+    "langchain-openai>=0.3.0",
+    "langgraph>=0.2.60",
+    "langfuse>=2.57.0",
+]
+
+[build-system]
+requires = ["setuptools>=80.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["gaia_agent*"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

requirements.txt

@@ -1,2 +1,8 @@
-gradio
-requests
+gradio[oauth]==5.25.2
+requests>=2.32.0
+pandas>=2.2.0
+python-dotenv>=1.0.1
+langchain>=0.3.0
+langchain-openai>=0.3.0
+langgraph>=0.2.60
+langfuse>=2.57.0

scripts/run_one.py

@@ -0,0 +1,11 @@
+from gaia_agent import GaiaAgent
+
+
+def main() -> None:
+    question = "What is the capital of France?"
+    answer = GaiaAgent()(question)
+    print(answer)
+
+
+if __name__ == "__main__":
+    main()

scripts/run_smoke.py

@@ -0,0 +1,17 @@
+from gaia_agent import GaiaAgent
+
+
+QUESTIONS = [
+    "What is the capital of France?",
+    "Return the word test.",
+]
+
+
+def main() -> None:
+    agent = GaiaAgent()
+    for question in QUESTIONS:
+        print({"question": question, "answer": agent(question)})
+
+
+if __name__ == "__main__":
+    main()

tests/test_answer.py

@@ -0,0 +1,5 @@
+from gaia_agent.answer import normalize_answer
+
+
+def test_normalize_answer_strips_whitespace():
+    assert normalize_answer("  Paris  \n") == "Paris"

tests/test_graph_smoke.py

@@ -0,0 +1,7 @@
+from gaia_agent.agent import GaiaAgent
+
+
+def test_agent_returns_placeholder_answer():
+    agent = GaiaAgent()
+
+    assert agent("What is the answer?") == "Julien test"