create chess tools and refactor tests and tools via domains

tools/__init__.py → __init__.py

@@ -5,7 +5,14 @@ This package contains custom tools for the agent, including YouTube video analys
 and audio transcription capabilities.
 """
 
-from .youtube_tools import analyze_youtube_video, get_youtube_video_info
-from .transcription_tools import transcribe_audio
+from libs.youtube.youtube_tools import analyze_youtube_video, get_youtube_video_info
+from libs.transcription.transcription_tools import transcribe_audio
+from libs.chess.chess_tools import analyze_chess_image, analyze_chess_position
 
-__all__ = ["analyze_youtube_video", "get_youtube_video_info", "transcribe_audio"]
+__all__ = [
+    "analyze_youtube_video",
+    "get_youtube_video_info",
+    "transcribe_audio",
+    "analyze_chess_image",
+    "analyze_chess_position",
+]

app.py

@@ -15,9 +15,10 @@ from smolagents import (
     WikipediaSearchTool,
     SpeechToTextTool,
     LiteLLMModel,
-    tool,
 )
-from tools import analyze_youtube_video, get_youtube_video_info, transcribe_audio
+from libs.chess.chess_tools import analyze_chess_image, analyze_chess_position
+from libs.transcription.transcription_tools import transcribe_audio
+from libs.youtube.youtube_tools import analyze_youtube_video, get_youtube_video_info
 
 
 # (Keep Constants as is)
@@ -192,6 +193,8 @@ class BasicAgent:
                 transcribe_audio,
                 analyze_youtube_video,
                 get_youtube_video_info,
+                analyze_chess_position,
+                analyze_chess_image
             ],
             model=model,
             max_steps=20,

libs/chess/chess_tools.py

@@ -0,0 +1,241 @@
+"""
+Chess analysis tools for the Agents Course Final Assignment
+
+Provides two tools for the agent:
+ - analyze_chess_position: analyze a chess position provided as FEN or PGN text
+ - analyze_chess_image: try to extract a FEN from an image (best-effort) and analyze it
+
+The analysis uses python-chess for parsing and a small heuristic evaluation
+so the tools do not require a native engine like Stockfish. If pytesseract is
+available, the image tool will attempt OCR to find a FEN string inside the image.
+"""
+
+from smolagents import tool
+import io
+import json
+import tempfile
+import re
+
+try:
+    import chess
+    import chess.pgn
+except Exception:
+    chess = None
+
+try:
+    import cv2
+    import numpy as np
+except Exception:
+    cv2 = None
+    np = None
+
+try:
+    from PIL import Image
+except Exception:
+    Image = None
+
+try:
+    import pytesseract
+except Exception:
+    pytesseract = None
+
+
+PIECE_VALUES = (
+    {
+        chess.PAWN if chess else "p": 1,
+        chess.KNIGHT if chess else "n": 3,
+        chess.BISHOP if chess else "b": 3,
+        chess.ROOK if chess else "r": 5,
+        chess.QUEEN if chess else "q": 9,
+        chess.KING if chess else "k": 0,
+    }
+    if chess
+    else {}
+)
+
+
+def _simple_material_evaluation(board):
+    """Return material balance from White's perspective and a short breakdown."""
+    if chess is None:
+        raise RuntimeError("python-chess is required for position analysis")
+
+    values = {
+        chess.PAWN: 1,
+        chess.KNIGHT: 3,
+        chess.BISHOP: 3,
+        chess.ROOK: 5,
+        chess.QUEEN: 9,
+        chess.KING: 0,
+    }
+    white = 0
+    black = 0
+    counts = {}
+    for piece_type in values:
+        w = len(board.pieces(piece_type, chess.WHITE))
+        b = len(board.pieces(piece_type, chess.BLACK))
+        counts[piece_type] = (w, b)
+        white += w * values[piece_type]
+        black += b * values[piece_type]
+
+    balance = white - black
+    breakdown = {
+        chess.piece_name(pt): {
+            "white": counts[pt][0],
+            "black": counts[pt][1],
+            "value": values[pt],
+        }
+        for pt in counts
+    }
+    return balance, breakdown
+
+
+def _format_moves(moves, max_moves=8):
+    return ", ".join([m for m in moves[:max_moves]])
+
+
+@tool
+def analyze_chess_position(position_text: str, max_moves: int = 8) -> str:
+    """
+    Analyze a chess position provided as FEN or PGN (single-game). Returns a JSON string
+    with basic diagnostics: legality, side to move, check/checkmate/stalemate, material
+    balance, and a short list of legal moves.
+
+    Args:
+        position_text: A FEN string, or a PGN string containing at least one game.
+        max_moves: How many top legal moves to list in the output (default 8).
+
+    Returns:
+        JSON string with analysis results.
+    """
+    try:
+        if chess is None:
+            return json.dumps(
+                {"status": "error", "error": "python-chess is not installed"}, indent=2
+            )
+
+        position_text = position_text.strip()
+
+        board = None
+
+        # Detect FEN: a FEN contains 6 space-separated fields (piece placement + side to move + ...)
+        if len(position_text.split()) >= 2 and "/" in position_text.split()[0]:
+            # Likely a FEN
+            try:
+                board = chess.Board(position_text.splitlines()[0])
+            except Exception:
+                # try using the full string
+                board = chess.Board(position_text)
+        else:
+            # Try PGN parsing (look for move text or headers)
+            try:
+                pgn_io = io.StringIO(position_text)
+                game = chess.pgn.read_game(pgn_io)
+                if game is None:
+                    # Maybe the input is FEN without fields
+                    board = chess.Board(position_text)
+                else:
+                    # get the final position after the game
+                    node = game
+                    while node.variations:
+                        node = node.variations[0]
+                    board = node.board()
+            except Exception:
+                # Fallback: try to construct from the text directly
+                try:
+                    board = chess.Board(position_text)
+                except Exception as e:
+                    return json.dumps(
+                        {"status": "error", "error": f"Could not parse FEN/PGN: {e}"},
+                        indent=2,
+                    )
+
+        # Now we have a board
+        legal_moves = [board.san(m) for m in board.legal_moves]
+        balance, breakdown = _simple_material_evaluation(board)
+
+        result = {
+            "status": "success",
+            "fen": board.fen(),
+            "turn": "white" if board.turn == chess.WHITE else "black",
+            "is_check": board.is_check(),
+            "is_checkmate": board.is_checkmate(),
+            "is_stalemate": board.is_stalemate(),
+            "is_insufficient_material": board.is_insufficient_material(),
+            "material_balance_white_minus_black": balance,
+            "material_breakdown": breakdown,
+            "legal_moves_count": (
+                board.legal_moves.count()
+                if hasattr(board.legal_moves, "count")
+                else len(list(board.legal_moves))
+            ),
+            "legal_moves_sample": _format_moves(legal_moves, max_moves=max_moves),
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        return json.dumps({"status": "error", "error": str(e)}, indent=2)
+
+
+@tool
+def analyze_chess_image(image_bytes: bytes) -> str:
+    """
+    Best-effort: try to extract a FEN string from an image using OCR (if available),
+    and then analyze the position. If OCR is unavailable or fails, save the image to a
+    temporary file and return a helpful message describing how to use the `analyze_chess_position` tool.
+
+    Args:
+        image_bytes: Raw image bytes (PNG/JPEG/etc.)
+
+    Returns:
+        JSON string. If a FEN was found and parsed, returns the same output as `analyze_chess_position`.
+        Otherwise returns a helpful error/message and a temporary path where the image was saved.
+    """
+    try:
+        # First try OCR if pytesseract is available
+        if pytesseract and Image:
+            try:
+                img = Image.open(io.BytesIO(image_bytes)).convert("L")
+                text = pytesseract.image_to_string(img)
+                # Search for a FEN-like pattern: 8 ranks separated by '/'
+                fen_match = re.search(
+                    r"([prnbqkPRNBQK1-8]+\/){7}[prnbqkPRNBQK1-8]+(?:\s[bBqQrRkK-]+.*)?",
+                    text,
+                )
+                if fen_match:
+                    fen_candidate = fen_match.group(0).strip()
+                    # Try to analyze
+                    return analyze_chess_position(fen_candidate)
+                # If no fen, maybe the OCR returns lines; attempt to find FEN in any line
+                for line in text.splitlines():
+                    line = line.strip()
+                    if not line:
+                        continue
+                    if "/" in line and len(line) >= 17:
+                        # try parse
+                        try:
+                            return analyze_chess_position(line)
+                        except Exception:
+                            continue
+                # No FEN found via OCR
+            except Exception:
+                # OCR step failed; we'll fall back to saving image
+                pass
+
+        # Save image to temp file so a human (or another automated step) can inspect it
+        tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".png")
+        tmp.write(image_bytes)
+        tmp.flush()
+        tmp.close()
+
+        message = {
+            "status": "no_fen_found",
+            "message": "Could not automatically extract a FEN from the provided image."
+            " If the image includes a FEN string, install pytesseract and tesseract-ocr, or provide the FEN/PGN text directly",
+            "saved_image_path": tmp.name,
+            "how_to_use": "Call analyze_chess_position(fen_or_pgn) with a FEN string or PGN to get an analysis.",
+        }
+        return json.dumps(message, indent=2)
+
+    except Exception as e:
+        return json.dumps({"status": "error", "error": str(e)}, indent=2)

{tests → libs/transcription}/test_transcription_tools.py

@@ -13,11 +13,14 @@ import struct
 import unittest
 from unittest.mock import Mock, patch, MagicMock
 
-# Add the parent directory to the path to import from tools
-sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+# Add the project root to the path so 'libs' can be imported (was appending 'libs' itself)
+# This uses the directory three levels up from this test file (project root).
+sys.path.append(
+    os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+)
 
 # Import the transcription tool directly to avoid YouTube tool dependencies
-from tools.transcription_tools import transcribe_audio
+from libs.transcription.transcription_tools import transcribe_audio
 
 
 class TestTranscriptionTools(unittest.TestCase):
@@ -55,7 +58,7 @@ class TestTranscriptionTools(unittest.TestCase):
 
         return wav_buffer.getvalue()
 
-    @patch("tools.transcription_tools.SpeechToTextTool")
+    @patch("libs.transcription.transcription_tools.SpeechToTextTool")
     def test_transcribe_audio_success(self, mock_speech_tool_class):
         """Test successful audio transcription."""
         # Setup mock
@@ -73,7 +76,7 @@ class TestTranscriptionTools(unittest.TestCase):
         mock_speech_tool_class.assert_called_once()
         mock_speech_tool.transcribe.assert_called_once_with(self.sample_audio_bytes)
 
-    @patch("tools.transcription_tools.SpeechToTextTool")
+    @patch("libs.transcription.transcription_tools.SpeechToTextTool")
     def test_transcribe_audio_empty_bytes(self, mock_speech_tool_class):
         """Test transcription with empty audio bytes."""
         # Setup mock
@@ -88,7 +91,7 @@ class TestTranscriptionTools(unittest.TestCase):
         self.assertEqual(result, "")
         mock_speech_tool.transcribe.assert_called_once_with(b"")
 
-    @patch("tools.transcription_tools.SpeechToTextTool")
+    @patch("libs.transcription.transcription_tools.SpeechToTextTool")
     def test_transcribe_audio_tool_exception(self, mock_speech_tool_class):
         """Test transcription when SpeechToTextTool raises an exception."""
         # Setup mock to raise exception
@@ -105,7 +108,7 @@ class TestTranscriptionTools(unittest.TestCase):
         self.assertIn("Failed to transcribe audio", str(context.exception))
         self.assertIn("Transcription service unavailable", str(context.exception))
 
-    @patch("tools.transcription_tools.SpeechToTextTool")
+    @patch("libs.transcription.transcription_tools.SpeechToTextTool")
     def test_transcribe_audio_invalid_format(self, mock_speech_tool_class):
         """Test transcription with invalid audio format."""
         # Setup mock to raise exception for invalid format
@@ -140,7 +143,7 @@ class TestTranscriptionTools(unittest.TestCase):
         # The function should at least be callable
         self.assertTrue(callable(transcribe_audio))
 
-    @patch("tools.transcription_tools.SpeechToTextTool")
+    @patch("libs.transcription.transcription_tools.SpeechToTextTool")
     def test_transcribe_audio_with_various_formats_description(
         self, mock_speech_tool_class
     ):
@@ -170,7 +173,7 @@ def test_basic_functionality():
 
     try:
         # Import the function to make sure it exists and imports work
-        from tools.transcription_tools import transcribe_audio
+        from libs.transcription.transcription_tools import transcribe_audio
 
         print("✅ Successfully imported transcribe_audio function")
 

{tests → libs/transcription}/test_transcription_tools_standalone.py

@@ -14,8 +14,11 @@ import struct
 import unittest
 from unittest.mock import Mock, patch
 
-# Add the parent directory to the path to import from tools
-sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+# Add the project root to the path so 'libs' can be imported (was appending 'libs' itself)
+# This uses the directory three levels up from this test file (project root).
+sys.path.append(
+    os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+)
 
 
 def test_basic_functionality():
@@ -24,7 +27,7 @@ def test_basic_functionality():
 
     try:
         # Import the function directly to make sure it exists and imports work
-        from tools.transcription_tools import transcribe_audio
+        from libs.transcription.transcription_tools import transcribe_audio
 
         print("✅ Successfully imported transcribe_audio function")
 
@@ -56,7 +59,7 @@ def test_transcribe_with_mock():
 
     try:
         # Import the function
-        from tools.transcription_tools import transcribe_audio
+        from libs.transcription.transcription_tools import transcribe_audio
 
         # Create sample audio bytes (simple WAV file structure)
         sample_rate = 44100
@@ -81,7 +84,7 @@ def test_transcribe_with_mock():
 
         # Mock the SpeechToTextTool
         with patch(
-            "tools.transcription_tools.SpeechToTextTool"
+            "libs.transcription.transcription_tools.SpeechToTextTool"
         ) as mock_speech_tool_class:
             mock_speech_tool = Mock()
             mock_speech_tool.transcribe.return_value = (
@@ -115,11 +118,11 @@ def test_error_handling():
     print("Testing error handling...")
 
     try:
-        from tools.transcription_tools import transcribe_audio
+        from libs.transcription.transcription_tools import transcribe_audio
 
         # Mock the SpeechToTextTool to raise an exception
         with patch(
-            "tools.transcription_tools.SpeechToTextTool"
+            "libs.transcription.transcription_tools.SpeechToTextTool"
         ) as mock_speech_tool_class:
             mock_speech_tool = Mock()
             mock_speech_tool.transcribe.side_effect = Exception(

{tests → libs/youtube}/test_youtube_tools.py

@@ -10,7 +10,7 @@ import os
 
 sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
-from tools.youtube_tools import get_youtube_video_info, analyze_youtube_video
+from libs.youtube.youtube_tools import get_youtube_video_info, analyze_youtube_video
 
 
 def test_video_info():

{tools → libs/youtube}/youtube_tools.py

@@ -7,7 +7,7 @@ by extracting frames at intervals and analyzing their content.
 
 import json
 from smolagents import tool
-from tools.youtube_video_analyzer import (
+from libs.youtube.youtube_video_analyzer import (
     analyze_youtube_video_frames,
     get_video_metadata,
 )

{tools → libs/youtube}/youtube_video_analyzer.py

@@ -58,7 +58,7 @@ def extract_video_frames(
             # Find the downloaded video file
             video_files = list(Path(temp_dir).glob("video.*"))
             if not video_files:
-                raise Exception("No video file found after download")
+                raise Exception("No video file found after download. The download may have failed or the video may be unavailable.")
 
             actual_video_path = str(video_files[0])
 
@@ -66,13 +66,15 @@ def extract_video_frames(
             cap = cv2.VideoCapture(actual_video_path)
 
             if not cap.isOpened():
-                raise Exception("Could not open video file")
+                raise Exception(f"Could not open video file: {actual_video_path}")
 
             fps = cap.get(cv2.CAP_PROP_FPS)
             total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
             duration = total_frames / fps if fps > 0 else 0
 
             frame_interval = int(fps * interval_seconds)
+            if frame_interval == 0:
+                frame_interval = 1
             frame_count = 0
             extracted_count = 0
 

requirements.txt

@@ -14,4 +14,6 @@ yt-dlp
 openai-whisper
 torch
 transformers
-opencv-python
+opencv-python
+python-chess>=1.9.0
+pytesseract