ft: add basic agent

README.md

@@ -1,12 +1,13 @@
 ---
-title: AgentCourseU4
-emoji: 💻
-colorFrom: red
-colorTo: green
+title: FinalTest
+emoji: ⚡
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
 sdk_version: 5.29.1
 app_file: app.py
 pinned: false
+short_description: this space will host the code for the unit 4 ofthe HF course
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

agent.py

@@ -0,0 +1,65 @@
+from se_agents.agent import Agent
+from config import Config
+from se_agents.tools import *
+from tools import *
+from se_agents.runner import Runner
+from pydantic import BaseModel
+
+
+class Task(BaseModel):
+    task_id: str
+    question: str
+    Level: str
+    file_name: str
+
+
+async def run_agent(query):
+    agent = Agent(
+        api_key=Config.get_openrouter_api_key(),
+        base_url=Config.get_openrouter_api_url(),
+        model=Config.get_model(),
+        tools=[
+            ExaSearch(Config.get_exa_api_key()),
+            ExaCrawl(Config.get_exa_api_key()),
+            ExaSearchBase(Config.get_exa_api_key()),
+            ExaSearchContent(Config.get_exa_api_key()),
+            ExaSearchHighlights(Config.get_exa_api_key()),
+            OpenAIVisionTool(),
+            ThinkTool(),
+            FinalOutput(),
+            YoutubeVideoInterpreter(),
+            TaskFileDownloader(),
+            RetriveInfoTaskFile(),
+            SpeechToText(),
+            CodeInterpreter(),
+        ],
+        description="You are a general AI assistant. You are direct and concise.",
+        rules="""Answer with the following template: [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, you do not explain your answer, you just provided it in the least amount of characters as possible.
+    For every task that is given to you first think about it using the 'think' tool.
+    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, do not write the number as a string instead used the number notation. Example: Not Sixty three, Do 63. 
+    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.
+    If the task at hand has any file associated with it you never give a direct answer, first use the think tool, to process the request, once the thinking is complete you must first download using the task_file_downloader tool, and the use the proper tool to analyze the file.
+    If the task as any audio file associated with it, you must use the speech_to_text tool to convert it to a .txt file.
+    If the task involves the interpretation of code, you must use the code_interpreter tool to get the content of the code file.""",
+        add_default_rules=False,
+        add_think_instructions=True,
+        add_final_output_instructions=True,
+    )
+    runner = Runner(agent, enforce_final=True)
+    final_response = ""
+    async for response in runner.run(query):
+        if response.type == "response":
+            # This will typically contain the final output when enforce_final=True,
+            # or intermediate text otherwise.
+            final_response += response.content
+            return final_response
+        # Note: 'thinking' is now handled via ThinkTool, resulting in 'tool_call' and 'tool_response' events.
+        elif response.type == "tool_call":
+            # Includes calls to ThinkTool, FinalOutput, and others.
+            print(f"\n\n\033[92m🟡 Tool Call:\n{response.content}\033[0m\n")
+        elif response.type == "tool_response":
+            print(f"\n\n\033[94m🟢 Tool Response:\n{response.content}\033[0m\n")
+        elif response.type == "tool_error":
+            print(f"\n\n\033[91m🔴 Tool Error:\n{response.content}\033[0m\n")

app.py

@@ -0,0 +1,161 @@
+import os
+import requests
+import pandas as pd
+import se_agents as se
+from config import Config
+from agent import run_agent
+import asyncio
+from colorama import Fore, Style, init
+
+init()
+
+USERNAME = "kaladin4"
+
+
+async def run_and_submit_all():
+    """
+    Fetches all questions, runs the BasicAgent on them, submits all answers,
+    and displays the results.
+    """
+    # --- Determine HF Space Runtime URL and Repo URL ---
+    questions_url = f"{Config.get_default_api_url()}/questions"
+    submit_url = f"{Config.get_default_api_url()}/submit"
+
+    # 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/Kaladin4/FinalTest/tree/main"
+
+    # 2. Fetch Questions
+    print(f"Fetching questions from: {questions_url}")
+    try:
+        response = requests.get(questions_url, timeout=15)
+        response.raise_for_status()
+        questions_data = response.json()
+        if not questions_data:
+            print("Fetched questions list is empty.")
+            return "Fetched questions list is empty or invalid format.", None
+        print(f"Fetched {len(questions_data)} questions.")
+    except requests.exceptions.RequestException as e:
+        print(f"Error fetching questions: {e}")
+        return f"Error fetching questions: {e}", None
+    except requests.exceptions.JSONDecodeError as e:
+        print(f"Error decoding JSON response from questions endpoint: {e}")
+        print(f"Response text: {response.text[:500]}")
+        return f"Error decoding server response for questions: {e}", None
+    except Exception as e:
+        print(f"An unexpected error occurred fetching questions: {e}")
+        return f"An unexpected error occurred fetching questions: {e}", None
+
+    # 3. Run your Agent
+    results_log = []
+    answers_payload = []
+    print(f"Running agent on {len(questions_data)} questions...")
+    for item in questions_data:
+        task_id = item.get("task_id")
+        question_text = (
+            f"{Fore.GREEN}Task Id:{Style.RESET_ALL} {task_id}\n"
+            f"{Fore.BLUE}Task:{Style.RESET_ALL} {item.get('question')}\n"
+            f"{Fore.YELLOW}File:{Style.RESET_ALL} {item.get('file_name')}"
+        )
+        print(question_text)
+        if not task_id or question_text is None:
+            print(f"Skipping item with missing task_id or question: {item}")
+            continue
+        try:
+            submitted_answer = await run_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 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)
+
+    # 4. Prepare Submission
+    submission_data = {
+        "username": USERNAME,
+        "agent_code": agent_code,
+        "answers": answers_payload,
+    }
+    status_update = f"Agent finished. Submitting {len(answers_payload)} answers for user '{USERNAME}'..."
+    print(status_update)
+
+    # 5. Submit
+    print(f"Submitting {len(answers_payload)} answers to: {submit_url}")
+    try:
+        response = requests.post(submit_url, json=submission_data, timeout=60)
+        response.raise_for_status()
+        result_data = response.json()
+        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:
+        status_message = f"An unexpected error occurred during submission: {e}"
+        print(status_message)
+        results_df = pd.DataFrame(results_log)
+        return status_message, results_df
+
+
+async def main():
+    print("\n" + "-" * 30 + " App Starting " + "-" * 30)
+    # Check for SPACE_HOST and SPACE_ID at startup for information
+
+    print("-" * (60 + len(" App Starting ")) + "\n")
+
+    print("Starting agent evaluation process...")
+    final_status, results_df = await run_and_submit_all()
+
+    print("\n" + "=" * 50)
+    print("FINAL STATUS:")
+    print(final_status)
+    print("=" * 50 + "\n")
+
+    print("Results Summary:")
+    print(results_df)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

config.py

@@ -0,0 +1,58 @@
+from dotenv import load_dotenv
+import os
+from urllib.parse import unquote
+
+load_dotenv()
+
+
+class Config:
+    @staticmethod
+    def get_gemini_api_key():
+        return os.getenv("GEMINI_API_KEY")
+
+    @staticmethod
+    def get_model():
+        return os.getenv("OPENROUTER_MODEL")
+
+    @staticmethod
+    def get_exa_api_key():
+        return os.getenv("EXA_API_KEY")
+
+    @staticmethod
+    def get_openrouter_api_key():
+        return os.getenv("OPENROUTER_API_KEY_1")
+
+    @staticmethod
+    def get_default_api_url():
+        url = os.getenv("DEFAULT_API_URL")
+        if url:
+            if "\\x3a" in url:
+                return url.replace("\\x3a", ":")
+            return url
+        return None
+
+    @staticmethod
+    def get_openrouter_api_url():
+        url = os.getenv("OPENROUTER_BASE_URL")
+        if url:
+            if "\\x3a" in url:
+                return url.replace("\\x3a", ":")
+            return url
+        return None
+
+    @staticmethod
+    def get_task_file_folder():
+        return os.getenv("TASK_FILES_FOLDER")
+
+    @staticmethod
+    def get_openai_api_key():
+        return os.getenv("OPENAI_API_KEY")
+
+    @staticmethod
+    def get_defaulassociatedt_api_url():
+        url = os.getenv("DEFAULT_API_URL")
+        if url:
+            if "\\x3a" in url:
+                return url.replace("\\x3a", ":")
+            return url
+        return None

requirements.txt

@@ -0,0 +1,184 @@
+aiofiles==24.1.0
+aiohappyeyeballs==2.6.1
+aiohttp==3.11.18
+aiosignal==1.3.2
+annotated-types==0.7.0
+anyio==4.9.0
+asgiref==3.8.1
+asyncer==0.0.8
+attrs==25.3.0
+Authlib==1.5.2
+backoff==2.2.1
+bcrypt==4.3.0
+beautifulsoup4==4.13.4
+build==1.2.2.post1
+cachetools==5.5.2
+certifi==2025.4.26
+cffi==1.17.1
+chardet==5.2.0
+charset-normalizer==3.4.2
+chromadb==1.0.9
+click==8.1.8
+coloredlogs==15.0.1
+cryptography==44.0.3
+dataclasses-json==0.6.7
+datasets==3.6.0
+Deprecated==1.2.18
+dill==0.3.8
+distro==1.9.0
+duckduckgo_search==8.0.1
+durationpy==0.9
+emoji==2.14.1
+et_xmlfile==2.0.0
+eval_type_backport==0.2.2
+exa-py==1.12.1
+fastapi==0.115.9
+ffmpy==0.5.0
+filelock==3.18.0
+filetype==1.2.0
+firecrawl-py==2.5.3
+flatbuffers==25.2.10
+frozenlist==1.6.0
+fsspec==2025.3.0
+google-auth==2.40.1
+google-genai==1.14.0
+googleapis-common-protos==1.70.0
+gradio==5.29.0
+gradio_client==1.10.0
+greenlet==3.2.2
+groovy==0.1.2
+grpcio==1.71.0
+h11==0.16.0
+html5lib==1.1
+httpcore==1.0.9
+httptools==0.6.4
+httpx==0.28.1
+httpx-sse==0.4.0
+huggingface-hub==0.30.2
+humanfriendly==10.0
+idna==3.10
+importlib_metadata==8.6.1
+importlib_resources==6.5.2
+iniconfig==2.1.0
+itsdangerous==2.2.0
+Jinja2==3.1.6
+jiter==0.9.0
+joblib==1.5.0
+jsonpatch==1.33
+jsonpointer==3.0.0
+jsonschema==4.23.0
+jsonschema-specifications==2025.4.1
+kubernetes==32.0.1
+langchain==0.3.25
+langchain-community==0.3.23
+langchain-core==0.3.59
+langchain-openai==0.3.17
+langchain-text-splitters==0.3.8
+langdetect==1.0.9
+langsmith==0.3.42
+lxml==5.4.0
+markdown-it-py==3.0.0
+MarkupSafe==3.0.2
+marshmallow==3.26.1
+mdurl==0.1.2
+mmh3==5.1.0
+mpmath==1.3.0
+multidict==6.4.3
+multiprocess==0.70.16
+mypy_extensions==1.1.0
+nest-asyncio==1.6.0
+networkx==3.4.2
+nltk==3.9.1
+numpy==2.2.5
+oauthlib==3.2.2
+olefile==0.47
+onnxruntime==1.22.0
+openai==1.77.0
+openpyxl==3.1.5
+opentelemetry-api==1.33.0
+opentelemetry-exporter-otlp-proto-common==1.33.0
+opentelemetry-exporter-otlp-proto-grpc==1.33.0
+opentelemetry-instrumentation==0.54b0
+opentelemetry-instrumentation-asgi==0.54b0
+opentelemetry-instrumentation-fastapi==0.54b0
+opentelemetry-proto==1.33.0
+opentelemetry-sdk==1.33.0
+opentelemetry-semantic-conventions==0.54b0
+opentelemetry-util-http==0.54b0
+orjson==3.10.18
+overrides==7.7.0
+packaging==24.2
+pandas==2.2.3
+pillow==11.2.1
+pluggy==1.5.0
+posthog==4.0.1
+primp==0.15.0
+propcache==0.3.1
+protobuf==5.29.4
+psutil==7.0.0
+pyarrow==20.0.0
+pyasn1==0.6.1
+pyasn1_modules==0.4.2
+pycparser==2.22
+pydantic==2.11.4
+pydantic-settings==2.9.1
+pydantic_core==2.33.2
+pydub==0.25.1
+Pygments==2.19.1
+pypdf==5.4.0
+PyPika==0.48.9
+pyproject_hooks==1.2.0
+pytest==8.3.5
+pytest-mock==3.14.0
+python-dateutil==2.9.0.post0
+python-dotenv==1.1.0
+python-iso639==2025.2.18
+python-magic==0.4.27
+python-multipart==0.0.20
+python-oxmsg==0.0.2
+pytz==2025.2
+PyYAML==6.0.2
+RapidFuzz==3.13.0
+referencing==0.36.2
+regex==2024.11.6
+requests==2.32.3
+requests-oauthlib==2.0.0
+requests-toolbelt==1.0.0
+rich==14.0.0
+rpds-py==0.25.0
+rsa==4.9.1
+ruff==0.11.8
+safehttpx==0.1.6
+se-agents @ git+https://github.com/generalsoftwareinc/SE-Agents.git@ac05cdf08c06eef8d9dd8abe9933ed372d25e414
+semantic-version==2.10.0
+shellingham==1.5.4
+six==1.17.0
+sniffio==1.3.1
+soupsieve==2.7
+SQLAlchemy==2.0.40
+starlette==0.45.3
+sympy==1.14.0
+tenacity==9.1.2
+tiktoken==0.9.0
+tokenizers==0.21.1
+tomlkit==0.13.2
+tqdm==4.67.1
+typer==0.15.3
+typing-inspect==0.9.0
+typing-inspection==0.4.0
+typing_extensions==4.13.2
+tzdata==2025.2
+unstructured==0.17.2
+unstructured-client==0.34.0
+urllib3==2.4.0
+uvicorn==0.34.2
+uvloop==0.21.0
+watchfiles==1.0.5
+webencodings==0.5.1
+websocket-client==1.8.0
+websockets==15.0.1
+wrapt==1.17.2
+xxhash==3.5.0
+yarl==1.20.0
+zipp==3.21.0
+zstandard==0.23.0

tools.py

@@ -0,0 +1,211 @@
+"""Custom tools go in here"""
+
+from google import genai
+from se_agents.tools import Tool
+from se_agents.agent import Agent
+from se_agents.runner import Runner
+from openai import OpenAI
+import types
+import requests
+from config import Config
+from langchain_community.document_loaders import (
+    UnstructuredExcelLoader,
+    TextLoader,
+    PyPDFLoader,
+)
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_openai import OpenAIEmbeddings
+from langchain_community.vectorstores import Chroma
+from openai import Client
+from pathlib import Path
+from utils import read_file_content
+from google.genai import types
+
+
+class YoutubeVideoInterpreter(Tool):
+    def __init__(self):
+        super().__init__(
+            name="youtube_video_interpreter",
+            description="Given a certain youtube video url, it analyzes the video and response any question asked by the user",
+            parameters={
+                "query": {
+                    "type": "string",
+                    "description": "question about the video",
+                    "required": True,
+                },
+                "video_url": {
+                    "type": "string",
+                    "description": "the url of the video",
+                    "required": True,
+                },
+            },
+        )
+
+    def execute(self, **kwargs) -> str:
+        params = self._process_parameters(**kwargs)
+        query = params.get("query")
+        video_url = params.get("video_url")
+        client = genai.Client(api_key=Config.get_gemini_api_key())
+        response = client.models.generate_content(
+            model="models/gemini-2.0-flash",
+            contents=types.Content(
+                parts=[
+                    types.Part(file_data=types.FileData(file_uri=video_url)),
+                    types.Part(text=query),
+                ]
+            ),
+        )
+        return response.text
+
+
+class TaskFileDownloader(Tool):
+    def __init__(self):
+        super().__init__(
+            name="task_file_downloader",
+            description="Given a certain Taks id, it downloads the complementary file, outputs the path of the file",
+            parameters={
+                "task_id": {
+                    "type": "string",
+                    "description": "the id of the task",
+                    "required": True,
+                },
+                "complementary_file": {
+                    "type": "string",
+                    "description": "the name with extension of the file",
+                    "required": True,
+                },
+            },
+        )
+
+    def execute(self, **kwargs) -> str:
+        params = self._process_parameters(**kwargs)
+        task_id = params.get("task_id")
+        complementary_file_ext = params.get("complementary_file").split(".")[-1]
+        response = requests.get(f"{Config.get_default_api_url()}/files/{task_id}")
+        # Verify the request was successful
+        if response.status_code == 200:
+            # Save the file
+            with open(
+                f"{Config.get_task_file_folder()}/{task_id}_complementary_file.{complementary_file_ext}",
+                "wb",
+            ) as file:
+                file.write(response.content)
+            return f"{Config.get_task_file_folder()}/{task_id}_complementary_file.{complementary_file_ext}"
+        else:
+            return f"Failed to retrieve file. Status code: {response.status_code}"
+
+
+class RetriveInfoTaskFile(Tool):
+
+    def __init__(self):
+        super().__init__(
+            name="retrive_info_task_file",
+            description="Given a certain Taks file path, outputs info related to the file",
+            parameters={
+                "complementary_file": {
+                    "type": "string",
+                    "description": "the path with extension of the file",
+                    "required": True,
+                },
+                "query": {
+                    "type": "string",
+                    "description": "question about the file",
+                    "required": True,
+                },
+            },
+        )
+        self.retriver = {
+            ".xlsx": UnstructuredExcelLoader,
+            ".pdf": PyPDFLoader,
+            ".txt": TextLoader,
+        }
+
+    def execute(self, **kwargs) -> str:
+        params = self._process_parameters(**kwargs)
+        complementary_file = params.get("complementary_file")
+        query = params.get("query")
+        complementary_file_path = Path(complementary_file)
+
+        # Validate file format
+        if complementary_file_path.suffix not in self.retriver:
+            return f"Unsupported file format: {complementary_file_path.suffix}"
+
+        # Load and process the document
+        loader = self.retriver[complementary_file_path.suffix](complementary_file_path)
+        documents = loader.load()
+        text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=1000, chunk_overlap=100
+        )
+        docs = text_splitter.split_documents(documents)
+
+        # Embed and retrieve relevant information
+        embeddings = OpenAIEmbeddings()
+        vectorstore = Chroma.from_documents(docs, embeddings)
+        retriever = vectorstore.as_retriever()
+        results = retriever.invoke(query)
+
+        # Return formatted results or a fallback message
+        return (
+            "\n\n".join([doc.page_content for doc in results[:3]])
+            if results
+            else "No relevant information found."
+        )
+
+
+class SpeechToText(Tool):
+    def __init__(self):
+        super().__init__(
+            name="speech_to_text",
+            description="Given a certain audio file path, outputs the path to a .txt file with the transcription",
+            parameters={
+                "audio_file_path": {
+                    "type": "string",
+                    "description": "the name with extension of the file",
+                    "required": True,
+                },
+            },
+        )
+
+    async def execute(self, **kwargs) -> str:
+        params = self._process_parameters(**kwargs)
+        audio_file_path = params.get("audio_file_path")
+        client = OpenAI(api_key=Config.get_openai_api_key())
+        if Path(audio_file_path).exists():
+            with open(audio_file_path, "rb") as audio_file:
+                transcription = client.audio.transcriptions.create(
+                    model="gpt-4o-transcribe", file=audio_file
+                )
+
+                # Write transcription to a .txt file
+                txt_file_path = Path(audio_file_path).with_suffix(".txt")
+                with open(txt_file_path, "w") as txt_file:
+                    txt_file.write(transcription.text)
+
+                return f"Transcription saved to {txt_file_path}"
+        else:
+            return "Audio file does not exist"
+
+
+class CodeInterpreter(Tool):
+    def __init__(self):
+        super().__init__(
+            name="code_interpreter",
+            description="Given a certain code file path, outputs the content of the file",
+            parameters={
+                "code_file_path": {
+                    "type": "string",
+                    "description": "the name with extension of the file",
+                    "required": True,
+                },
+            },
+        )
+
+    async def execute(self, **kwargs) -> str:
+        params = self._process_parameters(**kwargs)
+        code_file_path = params.get("code_file_path")
+        client = OpenAI(api_key=Config.get_openai_api_key())
+        if Path(code_file_path).exists():
+            content = read_file_content(code_file_path)
+            return content
+        else:
+            return "Code file does not exist"

utils.py

@@ -0,0 +1,22 @@
+def read_file_content(file_path: str) -> str:
+    """
+    Reads and returns the content of a file.
+
+    Args:
+        file_path (str): The path to the file to read.
+
+    Returns:
+        str: The content of the file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        IOError: If the file cannot be read.
+    """
+    try:
+        with open(file_path, "r") as file:
+            content = file.read()
+        return content
+    except FileNotFoundError:
+        raise FileNotFoundError(f"The file '{file_path}' does not exist.")
+    except IOError:
+        raise IOError(f"Unable to read the file '{file_path}'.")