tools/agent_tools.py

"""Adapters exposing deterministic helpers to current smolagents APIs."""

from __future__ import annotations

import os

from smolagents import tool

from .image_chess import analyze_chess_fen
from .markdown_logic import analyze_markdown_operation
from .spreadsheet import inspect_spreadsheet
from .web import fetch_url
from .youtube import fetch_youtube_transcript


@tool
def youtube_transcript(url: str) -> str:
    """Fetch a timestamped transcript for a YouTube URL.

    Args:
        url: Full YouTube watch or short URL.
    """
    return fetch_youtube_transcript(url)


@tool
def spreadsheet_contents(path: str) -> str:
    """Read all sheets in an Excel workbook as structured JSON.

    Args:
        path: Local path to an xlsx or xls file.
    """
    return inspect_spreadsheet(path)


@tool
def markdown_operation_analysis(markdown: str) -> str:
    """Compute algebraic properties of a finite operation in a Markdown table.

    Args:
        markdown: Question text containing a Markdown Cayley table.
    """
    return analyze_markdown_operation(markdown)


@tool
def chess_fen_analysis(fen: str) -> str:
    """Validate and calculate checks and mates for a chess position in FEN.

    Args:
        fen: A complete Forsyth-Edwards Notation chess position.
    """
    return analyze_chess_fen(fen, stockfish_path=os.getenv("STOCKFISH_PATH") or None)


@tool
def fetch_research_url(url: str) -> str:
    """Fetch a webpage or PDF and return bounded clean Markdown/text.

    Args:
        url: Absolute HTTP or HTTPS URL to retrieve.
    """
    return fetch_url(url)


def custom_agent_tools() -> list:
    return [
        youtube_transcript,
        spreadsheet_contents,
        markdown_operation_analysis,
        chess_fen_analysis,
        fetch_research_url,
    ]