Initial project structure

.gitignore

@@ -0,0 +1,130 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Sphinx documentation
+docs/_build/
+
+# mkdocs documentation
+/site
+docs/*.png
+
+# mypy
+.mypy_cache/
+
+# vscode cache
+.vscode
+
+# Pycharm files
+.idea
+
+### macOS template
+*.DS_Store
+.AppleDouble
+.LSOverride
+
+# serverless
+**/.serverless
+**/node_modules
+
+# terraform
+**/.terraform
+*.tfstate*
+
+# exclude temp files from source control
+temp/
+tmp/
+
+# exclude data from source control by default
+/data/*
+
+!/data/sat2023-sample/
+!/data/cnf-sample/
+
+!/data/sat2023-cos-similarity-dataset/
+/data/sat2023-cos-similarity-dataset/*
+!/data/sat2023-cos-similarity-dataset/results_main_detailed.csv
+
+# Configurations
+/config/
+
+# Logs
+lightning_logs/
+
+# Models
+/models/
+
+
+# Poetry code artifact settings
+.poetry/
+poetry.toml
+
+# Mise
+.mise.toml
+mise.toml

.pre-commit-config.yaml

@@ -0,0 +1,118 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.4.0
+    hooks:
+      - id: requirements-txt-fixer
+        files: requirements.txt|requirements-dev.txt|requirements-test.txt
+      - id: trailing-whitespace
+        exclude: |
+          (?x)^(
+            notebooks/
+          )
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer
+        exclude: |
+          (?x)^(
+            notebooks/
+          )
+      - id: check-yaml
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=1000"]
+  - repo: https://github.com/asottile/add-trailing-comma
+    rev: v3.1.0
+    hooks:
+      - id: add-trailing-comma
+  - repo: https://github.com/psf/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+        exclude: |
+          (?x)^(
+            notebooks/
+          )
+  - repo: https://github.com/pycqa/isort
+    rev: "5.12.0"
+    hooks:
+      - id: isort
+        exclude: |
+          (?x)^(
+            notebooks/
+          )
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.7
+    hooks:
+      - id: ruff # linter
+        exclude: |
+          (?x)^(
+            scripts/|
+            notebooks/
+          )
+      # - id: ruff-format
+  - repo: local
+    hooks:
+      - id: update-req
+        name: Update requirements.txt
+        stages: [pre-commit]
+        language: system
+        entry: uv
+        files: uv.lock|requirements.txt
+        pass_filenames: false
+        args:
+          [
+            "export",
+            "--format",
+            "requirements-txt",
+            "--no-hashes",
+            "--no-dev",
+            "-o",
+            "requirements.txt",
+          ]
+      - id: update-dev-req
+        name: Update requirements-dev.txt
+        stages: [pre-commit]
+        language: system
+        entry: uv
+        files: uv.lock|requirements-dev.txt
+        pass_filenames: false
+        args:
+          [
+            "export",
+            "--format",
+            "requirements-txt",
+            "--no-hashes",
+            "--group",
+            "dev",
+            "--group",
+            "test",
+            "-o",
+            "requirements-dev.txt",
+          ]
+      - id: mypy
+        name: Running mypy
+        stages: [commit]
+        language: system
+        entry: uv run mypy
+        args: [--install-types, --non-interactive]
+        types: [python]
+        exclude: |
+          (?x)^(
+            scripts/|
+            notebooks/
+          )
+
+      # - id: pytest
+      #   name: pytest
+      #   stages: [commit]
+      #   language: system
+      #   entry: poetry run pytest
+      #   types: [python]
+
+      # - id: pytest-cov
+      #   name: pytest
+      #   stages: [push]
+      #   language: system
+      #   entry: poetry run pytest --cov --cov-fail-under=100
+      #   types: [python]
+      #   pass_filenames: false

README.md

@@ -7,7 +7,92 @@ sdk: gradio
 sdk_version: 5.0.1
 app_file: app.py
 pinned: false
-short_description: TBD
+license: apache-2.0
+short_description: tdb
 ---
 
-An example chatbot using [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+# TDA Agent Tools
+
+# Development setup
+
+To start developing you need the following tools:
+
+ * [uv](https://docs.astral.sh/uv/)
+
+To start, sync all the dependencies with `uv sync --all-groups`.
+Then, install the pre-commit hooks (`uv run pre-commit install`) to
+ensure that future commits comply with the bare minimum to keep
+code _readable_.
+
+Once `uv` has installed all the dependencies, install the `pre-commit`
+hooks to run linting and requirement files update, etc., before creating
+new commits:
+
+```bash
+uv run pre-commit install
+```
+
+# Adding new tools
+
+For the sake of clarity, we organize tools under the directory
+`tdagent/tools/`, and then add them to the `app.py` list of
+interfaces.
+
+As an example, let's create a tool that adds up two numbers. First,
+we create a new file `tdagent/tools/calc_tool.py` with the following
+content:
+
+```Python
+import gradio as gr
+
+
+def add_numbers(num1: float, num2: str) -> float:
+    """Compute the addition of two numbers `num1 + num2`.
+
+    Args:
+        num1: First number to add.
+        num2: Second number to add.
+
+    Returns:
+        The result of computing `num1 + num2`.
+    """
+    return num1 + num2
+
+
+gr_add_numbers = gr.Interface(
+    fn=add_numbers,
+    inputs=["number", "number"],
+    outputs="number",
+    title="Add two numbers",
+    description="Compute the addition of two numbers",
+)
+```
+
+Naming the file `calc_tool.py` is convenient as it let us add
+additional tools to calculate operations inside the same Python
+module.
+
+Then, we modify the `app.py` file to include our new tool.
+
+```Python
+import gradio as gr
+
+from tdagent.tools.get_url_content import gr_get_url_http_content
+...  # Other tools already present before
+from tdagent.tools.calc_tool import gr_add_numbers
+
+
+gr_app = gr.TabbedInterface(
+    [
+        gr_get_url_http_content,
+        ...,  # Other tools already present before
+        gr_add_numbers
+    ],
+)
+
+if __name__ == "__main__":
+    gr_app.launch(mcp_server=True)
+```
+
+In future updates we might change the `app.py` to automatically
+include any `gr.Interface`, but for now this works just fine.

app.py

@@ -1,64 +1,15 @@
 import gradio as gr
-from huggingface_hub import InferenceClient
 
-"""
-For more information on `huggingface_hub` Inference API support, please check the docs: https://huggingface.co/docs/huggingface_hub/v0.22.2/en/guides/inference
-"""
-client = InferenceClient("HuggingFaceH4/zephyr-7b-beta")
+from tdagent.tools.get_url_content import gr_get_url_http_content
+from tdagent.tools.letter_counter import gr_letter_counter
 
 
-def respond(
-    message,
-    history: list[tuple[str, str]],
-    system_message,
-    max_tokens,
-    temperature,
-    top_p,
-):
-    messages = [{"role": "system", "content": system_message}]
-
-    for val in history:
-        if val[0]:
-            messages.append({"role": "user", "content": val[0]})
-        if val[1]:
-            messages.append({"role": "assistant", "content": val[1]})
-
-    messages.append({"role": "user", "content": message})
-
-    response = ""
-
-    for message in client.chat_completion(
-        messages,
-        max_tokens=max_tokens,
-        stream=True,
-        temperature=temperature,
-        top_p=top_p,
-    ):
-        token = message.choices[0].delta.content
-
-        response += token
-        yield response
-
-
-"""
-For information on how to customize the ChatInterface, peruse the gradio docs: https://www.gradio.app/docs/chatinterface
-"""
-demo = gr.ChatInterface(
-    respond,
-    additional_inputs=[
-        gr.Textbox(value="You are a friendly Chatbot.", label="System message"),
-        gr.Slider(minimum=1, maximum=2048, value=512, step=1, label="Max new tokens"),
-        gr.Slider(minimum=0.1, maximum=4.0, value=0.7, step=0.1, label="Temperature"),
-        gr.Slider(
-            minimum=0.1,
-            maximum=1.0,
-            value=0.95,
-            step=0.05,
-            label="Top-p (nucleus sampling)",
-        ),
+gr_app = gr.TabbedInterface(
+    [
+        gr_get_url_http_content,
+        gr_letter_counter,
     ],
 )
 
-
 if __name__ == "__main__":
-    demo.launch()
+    gr_app.launch(mcp_server=True)

pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "tdagent"
+version = "0.1.0"
+description = "TDA Agent Tools implemented for huggingface hackathon."
+authors = [
+    { name = "Pedro Completo Bento", email = "[email protected]" },
+    { name = "Josep Pon Farreny", email = "[email protected]" },
+    { name = "Miguel Rodin Rodriguez", email = "[email protected]" },
+    { name = "Sofia Jeronimo dos Santos", email = "[email protected]" },
+    { name = "Rodrigo Dominguez Sanz", email = "[email protected]" },
+]
+requires-python = ">=3.10,<4"
+readme = "README.md"
+license = ""
+dependencies = ["gradio[mcp]>=5.32.1", "requests>=2.32.3"]
+
+[project.scripts]
+
+
+[dependency-groups]
+dev = ["mypy~=1.14", "ruff>=0.9,<1", "pre-commit~=3.4", "pip-audit>=2.9.0"]
+test = [
+    "pytest>=7.4.4,<8",
+    "pytest-cov>=4.1.0,<5",
+    "pytest-randomly>=3.15.0,<4",
+    "xdoctest>=1.1.2,<2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+package = false
+default-groups = ["dev", "test"]
+
+[tool.uv.workspace]
+members = ["test"]
+
+[tool.black]
+target-version = ["py39", "py310", "py311"]
+line-length = 88
+
+[tool.isort]
+profile = "black"
+lines_after_imports = 2
+
+[tool.mypy]
+cache_dir = ".cache/mypy/"
+ignore_missing_imports = true
+no_implicit_optional = true
+check_untyped_defs = true
+strict_equality = true
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+exclude = "docs/"
+plugins = ["pydantic.mypy"]        # ["numpy.typing.mypy_plugin"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+
+[tool.pytest.ini_options]
+cache_dir = ".cache"
+testpaths = ["tests", "tda_agent"]
+addopts = [
+    "--strict",
+    "-r sxX",
+    "--cov-report=html",
+    "--cov-report=term-missing:skip-covered",
+    "--no-cov-on-fail",
+    "--xdoc",
+]
+console_output_style = "count"
+markers = ""
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+cache-dir = ".cache/ruff"
+exclude = [
+    ".git",
+    "__pycache__",
+    "docs/source/conf.py",
+    "old",
+    "build",
+    "dist",
+    ".venv",
+    "scripts",
+]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D100", "D104", "D107", "D401", "EM102", "ERA001", "TRY003"]
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "double"
+
+[tool.ruff.lint.flake8-bugbear]
+# Allow default arguments like, e.g., `data: List[str] = fastapi.Query(None)`.
+extend-immutable-calls = ["typer.Argument", "typer.Option"]
+
+[tool.ruff.lint.pep8-naming]
+ignore-names = ["F", "L"]
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2
+
+[tool.ruff.lint.mccabe]
+max-complexity = 18
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"*/__init__.py" = ["F401"]
+"tdagent/cli/**/*.py" = ["D103", "T201"]
+"tests/*.py" = ["D103", "PLR2004", "S101"]

requirements-dev.txt

@@ -0,0 +1,97 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --format requirements-txt --no-hashes --group dev --group test -o requirements-dev.txt
+aiofiles==24.1.0
+annotated-types==0.7.0
+anyio==4.9.0
+audioop-lts==0.2.1 ; python_full_version >= '3.13'
+boolean-py==5.0
+cachecontrol==0.14.3
+certifi==2025.4.26
+cfgv==3.4.0
+charset-normalizer==3.4.2
+click==8.2.1 ; sys_platform != 'emscripten'
+colorama==0.4.6 ; sys_platform == 'win32'
+coverage==7.8.2
+cyclonedx-python-lib==9.1.0
+defusedxml==0.7.1
+distlib==0.3.9
+exceptiongroup==1.3.0 ; python_full_version < '3.11'
+fastapi==0.115.12
+ffmpy==0.6.0
+filelock==3.18.0
+fsspec==2025.5.1
+gradio==5.32.1
+gradio-client==1.10.2
+groovy==0.1.2
+h11==0.16.0
+hf-xet==1.1.2 ; platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+httpcore==1.0.9
+httpx==0.28.1
+httpx-sse==0.4.0
+huggingface-hub==0.32.4
+identify==2.6.12
+idna==3.10
+iniconfig==2.1.0
+jinja2==3.1.6
+license-expression==30.4.1
+markdown-it-py==3.0.0
+markupsafe==3.0.2
+mcp==1.9.0
+mdurl==0.1.2
+msgpack==1.1.0
+mypy==1.16.0
+mypy-extensions==1.1.0
+nodeenv==1.9.1
+numpy==2.2.6
+orjson==3.10.18
+packageurl-python==0.16.0
+packaging==25.0
+pandas==2.2.3
+pathspec==0.12.1
+pillow==11.2.1
+pip==25.1.1
+pip-api==0.0.34
+pip-audit==2.9.0
+pip-requirements-parser==32.0.1
+platformdirs==4.3.8
+pluggy==1.6.0
+pre-commit==3.8.0
+py-serializable==2.0.0
+pydantic==2.11.5
+pydantic-core==2.33.2
+pydantic-settings==2.9.1
+pydub==0.25.1
+pygments==2.19.1
+pyparsing==3.2.3
+pytest==7.4.4
+pytest-cov==4.1.0
+pytest-randomly==3.16.0
+python-dateutil==2.9.0.post0
+python-dotenv==1.1.0
+python-multipart==0.0.20
+pytz==2025.2
+pyyaml==6.0.2
+requests==2.32.3
+rich==14.0.0
+ruff==0.11.12
+safehttpx==0.1.6
+semantic-version==2.10.0
+shellingham==1.5.4 ; sys_platform != 'emscripten'
+six==1.17.0
+sniffio==1.3.1
+sortedcontainers==2.4.0
+sse-starlette==2.3.6
+starlette==0.46.2
+toml==0.10.2
+tomli==2.2.1 ; python_full_version <= '3.11'
+tomlkit==0.13.2
+tqdm==4.67.1
+typer==0.16.0 ; sys_platform != 'emscripten'
+typing-extensions==4.14.0
+typing-inspection==0.4.1
+tzdata==2025.2
+urllib3==2.4.0
+uvicorn==0.34.3 ; sys_platform != 'emscripten'
+virtualenv==20.31.2
+websockets==15.0.1
+xdoctest==1.2.0

requirements.txt

@@ -1 +1,72 @@
-huggingface_hub==0.25.2
+# This file was autogenerated by uv via the following command:
+#    uv export --format requirements-txt --no-hashes --no-dev -o requirements.txt
+aiofiles==24.1.0
+annotated-types==0.7.0
+anyio==4.9.0
+audioop-lts==0.2.1 ; python_full_version >= '3.13'
+certifi==2025.4.26
+charset-normalizer==3.4.2
+click==8.2.1 ; sys_platform != 'emscripten'
+colorama==0.4.6 ; sys_platform == 'win32'
+coverage==7.8.2
+exceptiongroup==1.3.0 ; python_full_version < '3.11'
+fastapi==0.115.12
+ffmpy==0.6.0
+filelock==3.18.0
+fsspec==2025.5.1
+gradio==5.32.1
+gradio-client==1.10.2
+groovy==0.1.2
+h11==0.16.0
+hf-xet==1.1.2 ; platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+httpcore==1.0.9
+httpx==0.28.1
+httpx-sse==0.4.0
+huggingface-hub==0.32.4
+idna==3.10
+iniconfig==2.1.0
+jinja2==3.1.6
+markdown-it-py==3.0.0 ; sys_platform != 'emscripten'
+markupsafe==3.0.2
+mcp==1.9.0
+mdurl==0.1.2 ; sys_platform != 'emscripten'
+numpy==2.2.6
+orjson==3.10.18
+packaging==25.0
+pandas==2.2.3
+pillow==11.2.1
+pluggy==1.6.0
+pydantic==2.11.5
+pydantic-core==2.33.2
+pydantic-settings==2.9.1
+pydub==0.25.1
+pygments==2.19.1 ; sys_platform != 'emscripten'
+pytest==7.4.4
+pytest-cov==4.1.0
+pytest-randomly==3.16.0
+python-dateutil==2.9.0.post0
+python-dotenv==1.1.0
+python-multipart==0.0.20
+pytz==2025.2
+pyyaml==6.0.2
+requests==2.32.3
+rich==14.0.0 ; sys_platform != 'emscripten'
+ruff==0.11.12 ; sys_platform != 'emscripten'
+safehttpx==0.1.6
+semantic-version==2.10.0
+shellingham==1.5.4 ; sys_platform != 'emscripten'
+six==1.17.0
+sniffio==1.3.1
+sse-starlette==2.3.6
+starlette==0.46.2
+tomli==2.2.1 ; python_full_version <= '3.11'
+tomlkit==0.13.2
+tqdm==4.67.1
+typer==0.16.0 ; sys_platform != 'emscripten'
+typing-extensions==4.14.0
+typing-inspection==0.4.1
+tzdata==2025.2
+urllib3==2.4.0
+uvicorn==0.34.3 ; sys_platform != 'emscripten'
+websockets==15.0.1
+xdoctest==1.2.0

tdagent/tools/get_url_content.py

@@ -0,0 +1,65 @@
+import enum
+from collections.abc import Sequence
+
+import gradio as gr
+import requests
+
+
+class HttpContentType(str, enum.Enum):
+    """Http content type values."""
+
+    HTML = "text/html"
+    JSON = "application/json"
+
+
+def get_url_http_content(
+    url: str,
+    content_type: Sequence[HttpContentType] | None = None,
+    timeout: int = 30,
+) -> tuple[str, str]:
+    """Get the content of a URL using an HTTP GET request.
+
+    Args:
+        url: The URL to fetch the content from.
+        content_type: If given it should contain the expected
+            content types in the response body. The server may
+            not honor the requested content types.
+        timeout: Request timeout in seconds. Defaults to 30.
+
+    Returns:
+        A pair of strings (content, error_message). If there is an
+        error getting content from the URL the `content` will be
+        empty and `error_message` will, usually, contain the error
+        cause. Otherwise, `error_message` will be empty and the
+        content will be filled with data fetched from the URL.
+    """
+    headers = {}
+
+    if content_type:
+        headers["Accept"] = ",".join(content_type)
+    response = requests.get(
+        url,
+        headers=headers,
+        timeout=timeout,
+    )
+
+    try:
+        response.raise_for_status()
+    except requests.HTTPError as err:
+        return "", str(err)
+
+    return response.text, ""
+
+
+gr_get_url_http_content = gr.Interface(
+    fn=get_url_http_content,
+    inputs=["text", "text"],
+    outputs="text",
+    title="Get the content of a URL using an HTTP GET request.",
+    description=(
+        "Get the content of a URL in one of the specified content types."
+        " The server may not honor the content type and if it fails the"
+        " reason should also be returned with the corresponding HTTP"
+        " error code."
+    ),
+)

tdagent/tools/letter_counter.py

@@ -0,0 +1,23 @@
+import gradio as gr
+
+
+def letter_counter(word: str, letter: str) -> int:
+    """Count the occurrences of a specific letter in a word.
+
+    Args:
+        word: The word or phrase to analyze
+        letter: The letter to count occurrences of
+
+    Returns:
+        The number of times the letter appears in the word
+    """
+    return word.lower().count(letter.lower())
+
+
+gr_letter_counter = gr.Interface(
+    fn=letter_counter,
+    inputs=["text", "text"],
+    outputs="number",
+    title="Letter Counter",
+    description="Count how many times a letter appears in a word",
+)