amd-gaia 0.14.1__py3-none-any.whl → 0.14.3__py3-none-any.whl

gaia/agents/base/errors.py

@@ -0,0 +1,237 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Generic error formatting for user-facing error messages.
+
+This module provides utilities to format exceptions in a user-friendly way,
+showing the user's code with a visual pointer to the error line while
+filtering out framework internals.
+"""
+
+import json
+import linecache
+import textwrap
+import traceback
+from typing import List, Optional, Set
+
+# Paths to filter out (framework internals)
+FRAMEWORK_PATHS: Set[str] = {
+    "gaia/agents/base",
+    "gaia/agents/blender",
+    "gaia/agents/chat",
+    "gaia/agents/code",
+    "gaia/agents/docker",
+    "gaia/agents/jira",
+    "gaia/agents/routing",
+    "gaia/agents/tools",
+    "site-packages/",
+}
+
+
+def format_user_error(
+    exception: Exception,
+    context_lines: int = 2,
+) -> str:
+    """
+    Format an exception to show user's code with visual pointer.
+
+    Filters out framework internals, shows only user code frames
+    with source context around the error line.
+
+    Args:
+        exception: The caught exception
+        context_lines: Lines of code context before/after error
+
+    Returns:
+        Formatted error string with traceback and code pointer
+
+    Example output:
+        KeyError: 'data'
+
+        Traceback (most recent call last):
+          File "my_agent.py", line 39, in get_big_llms
+              37 | url = f"{base_url}/models?show_all=true"
+              38 | response = requests.get(url, timeout=60)
+          >>> 39 | models = response.json()["data"]
+              40 |
+              41 | top_5_models = sorted(
+    """
+    lines = []
+    lines.append(f"{type(exception).__name__}: {exception}")
+    lines.append("")
+
+    # Extract traceback frames
+    tb = traceback.extract_tb(exception.__traceback__)
+    user_frames = _filter_user_frames(tb)
+
+    if not user_frames:
+        # No user frames found, show last frame as fallback
+        if tb:
+            user_frames = [tb[-1]]
+        else:
+            return "\n".join(lines)
+
+    lines.append("Traceback (most recent call last):")
+
+    for frame in user_frames:
+        lines.append(f'  File "{frame.filename}", line {frame.lineno}, in {frame.name}')
+
+        # Show code context
+        code_context = _get_code_context(frame.filename, frame.lineno, context_lines)
+        if code_context:
+            lines.append(code_context)
+
+    return "\n".join(lines)
+
+
+def format_execution_trace(
+    exception: Exception,
+    query: Optional[str] = None,
+    plan_step: Optional[int] = None,
+    total_steps: Optional[int] = None,
+    tool_name: Optional[str] = None,
+    tool_args: Optional[dict] = None,
+    context_lines: int = 5,
+) -> str:
+    """
+    Format an exception with full execution trace for debugging.
+
+    Shows the agent's execution path (Query → Plan → Tool → Error)
+    along with the user's code context.
+
+    Args:
+        exception: The caught exception
+        query: The original user query
+        plan_step: Current step number in the plan (1-based)
+        total_steps: Total number of steps in the plan
+        tool_name: Name of the tool that failed
+        tool_args: Arguments passed to the tool
+        context_lines: Lines of code context before/after error
+
+    Returns:
+        Formatted error string with execution trace and code pointer
+    """
+    sep = "═" * 63
+    lines = []
+
+    # Header
+    lines.append(sep)
+    lines.append("AGENT ERROR - Tool execution failed")
+    lines.append(sep)
+    lines.append("")
+
+    # Execution trace section
+    lines.append("Execution Trace:")
+    if query:
+        # Truncate long queries
+        display_query = query[:80] + "..." if len(query) > 80 else query
+        lines.append(f'  Query: "{display_query}"')
+    if plan_step is not None and total_steps is not None:
+        lines.append(f"  Plan Step: {plan_step}/{total_steps}")
+    if tool_name:
+        lines.append(f"  Tool: {tool_name}")
+    if tool_args:
+        args_str = _truncate_args(tool_args)
+        lines.append(f"  Args: {args_str}")
+    lines.append("")
+
+    # Error section
+    lines.append("Error:")
+    error_msg = f"{type(exception).__name__}: {exception}"
+    # Word wrap long error messages (word-aware wrapping)
+    wrapped_lines = textwrap.wrap(error_msg, width=70)
+    for line in wrapped_lines:
+        lines.append(f"  {line}")
+    lines.append("")
+
+    # Your Code section
+    tb = traceback.extract_tb(exception.__traceback__)
+    user_frames = _filter_user_frames(tb)
+
+    if not user_frames and tb:
+        # No user frames found, use last frame as fallback
+        user_frames = [tb[-1]]
+
+    if user_frames:
+        lines.append("Your Code:")
+        for frame in user_frames:
+            lines.append(
+                f'  File "{frame.filename}", line {frame.lineno}, in {frame.name}'
+            )
+            lines.append("")
+
+            # Show code context with more lines
+            code_context = _get_code_context(
+                frame.filename, frame.lineno, context_lines
+            )
+            if code_context:
+                lines.append(code_context)
+
+    lines.append("")
+    lines.append(sep)
+
+    return "\n".join(lines)
+
+
+def _filter_user_frames(
+    frames: List[traceback.FrameSummary],
+) -> List[traceback.FrameSummary]:
+    """Filter out framework internal frames, keep user code."""
+    return [
+        f for f in frames if not any(path in f.filename for path in FRAMEWORK_PATHS)
+    ]
+
+
+def _get_code_context(
+    filename: str,
+    error_line: int,
+    context: int = 2,
+) -> Optional[str]:
+    """Get source code context around error line with pointer."""
+    lines = []
+
+    for line_num in range(error_line - context, error_line + context + 1):
+        if line_num < 1:
+            continue
+
+        code = linecache.getline(filename, line_num).rstrip()
+        if not code and line_num != error_line:
+            continue
+
+        if line_num == error_line:
+            # Visual pointer to error line
+            lines.append(f"      >>> {line_num:4d} | {code}")
+        else:
+            lines.append(f"          {line_num:4d} | {code}")
+
+    return "\n".join(lines) if lines else None
+
+
+def _truncate_args(tool_args: Optional[dict], max_length: int = 100) -> str:
+    """Truncate tool args while preserving structure where possible.
+
+    Uses JSON formatting for cleaner output and truncates at character
+    boundary with ellipsis indicator.
+
+    Args:
+        tool_args: Dictionary of tool arguments
+        max_length: Maximum string length before truncation
+
+    Returns:
+        Formatted string representation of the arguments
+    """
+    if not tool_args:
+        return "{}"
+
+    try:
+        # Use JSON for cleaner, more readable output
+        args_str = json.dumps(tool_args, default=str)
+    except (TypeError, ValueError):
+        # Fallback to str() if JSON fails
+        args_str = str(tool_args)
+
+    if len(args_str) <= max_length:
+        return args_str
+
+    # Truncate but indicate it's truncated
+    return args_str[: max_length - 3] + "..."

gaia/agents/base/mcp_agent.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 """

gaia/agents/base/tools.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Tool registry and decorator for agent tools.

gaia/agents/blender/agent.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Blender-specific agent for creating and modifying 3D scenes.

gaia/agents/blender/agent_simple.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 from typing import Any, Dict, Optional, Tuple

gaia/agents/blender/app.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Main application entry point for the Blender Agent.

gaia/agents/blender/app_simple.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 from gaia.agents.blender.agent_simple import BlenderAgentSimple

gaia/agents/blender/core/__init__.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 from .materials import MaterialManager

gaia/agents/blender/core/materials.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 from typing import Dict

gaia/agents/blender/core/objects.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 import math

gaia/agents/blender/core/rendering.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 from typing import Dict

gaia/agents/blender/core/scene.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 from typing import Dict

gaia/agents/blender/core/view.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 
 from typing import Dict

gaia/agents/chat/__init__.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Chat Agent with RAG and file search capabilities.

gaia/agents/chat/agent.py

@@ -1,23 +1,17 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Chat Agent - Interactive chat with RAG and file search capabilities.
 """
 
 import os
-import time
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 try:
-    from watchdog.events import FileSystemEventHandler
     from watchdog.observers import Observer
 except ImportError:
-    # Create dummy base class when watchdog is not available
-    class FileSystemEventHandler:
-        """Dummy base class when watchdog is not installed."""
-
     Observer = None
 
 from gaia.agents.base.agent import Agent
@@ -28,6 +22,7 @@ from gaia.agents.tools import FileSearchToolsMixin  # Shared file search tools
 from gaia.logger import get_logger
 from gaia.rag.sdk import RAGSDK, RAGConfig
 from gaia.security import PathValidator
+from gaia.utils.file_watcher import FileChangeHandler, check_watchdog_available
 
 logger = get_logger(__name__)
 
@@ -67,150 +62,6 @@ class ChatAgentConfig:
     allowed_paths: Optional[List[str]] = None
 
 
-class FileChangeHandler(FileSystemEventHandler):
-    """Handler for file system changes to trigger re-indexing and removal."""
-
-    def __init__(self, agent):
-        self.agent = agent
-        self.last_indexed = {}
-        self.debounce_time = 2.0  # seconds
-        self.telemetry = {
-            "files_added": 0,
-            "files_modified": 0,
-            "files_deleted": 0,
-            "files_moved": 0,
-            "total_events": 0,
-            "last_event_time": None,
-        }
-
-    def on_created(self, event):
-        """Handle file creation."""
-        if not event.is_directory and self._should_index(event.src_path):
-            self._schedule_reindex(event.src_path)
-            self._update_telemetry("files_added", event.src_path)
-
-    def on_modified(self, event):
-        """Handle file modification."""
-        if not event.is_directory and self._should_index(event.src_path):
-            self._schedule_reindex(event.src_path)
-            self._update_telemetry("files_modified", event.src_path)
-
-    def on_deleted(self, event):
-        """Handle file deletion."""
-        if not event.is_directory and self._should_index(event.src_path):
-            self._handle_deletion(event.src_path)
-            self._update_telemetry("files_deleted", event.src_path)
-
-    def on_moved(self, event):
-        """Handle file move/rename."""
-        if not event.is_directory:
-            # Remove old path if it was indexed
-            if self._should_index(event.src_path):
-                self._handle_deletion(event.src_path)
-            # Add new path if it should be indexed
-            if self._should_index(event.dest_path):
-                self._schedule_reindex(event.dest_path)
-            self._update_telemetry(
-                "files_moved", f"{event.src_path} -> {event.dest_path}"
-            )
-
-    def _should_index(self, file_path: str) -> bool:
-        """Check if file should be indexed based on supported extensions."""
-        # List of supported document extensions for auto-indexing
-        supported_extensions = [
-            ".pdf",  # PDF documents
-            ".txt",
-            ".md",
-            ".markdown",  # Text documents
-            ".csv",  # CSV files
-            ".json",  # JSON files
-            ".py",
-            ".js",
-            ".ts",  # Code files (Python, JavaScript, TypeScript)
-            ".java",
-            ".cpp",
-            ".c",  # More code files
-            ".html",
-            ".css",  # Web files
-            ".yaml",
-            ".yml",  # Config files
-            ".xml",  # XML files
-            ".rst",  # ReStructuredText
-            ".log",  # Log files
-        ]
-        file_lower = file_path.lower()
-        return any(file_lower.endswith(ext) for ext in supported_extensions)
-
-    def _schedule_reindex(self, file_path: str):
-        """Schedule file for reindexing with debouncing and memory management."""
-        current_time = time.time()
-        last_time = self.last_indexed.get(file_path, 0)
-
-        if current_time - last_time > self.debounce_time:
-            self.last_indexed[file_path] = current_time
-            logger.info(f"Scheduling reindex for: {file_path}")
-            self.agent.reindex_file(file_path)
-
-            # Memory leak prevention: Limit cache size with LRU eviction
-            MAX_CACHE_SIZE = 1000
-            if len(self.last_indexed) > MAX_CACHE_SIZE:
-                # Remove oldest 10% of entries (LRU eviction)
-                num_to_remove = MAX_CACHE_SIZE // 10
-                sorted_items = sorted(self.last_indexed.items(), key=lambda x: x[1])
-                for path, _ in sorted_items[:num_to_remove]:
-                    del self.last_indexed[path]
-                logger.debug(
-                    f"Cleaned up {num_to_remove} old entries from debounce cache"
-                )
-
-    def _handle_deletion(self, file_path: str):
-        """Handle file deletion by removing it from the index."""
-        try:
-            file_abs_path = str(Path(file_path).absolute())
-            if file_abs_path in self.agent.indexed_files:
-                logger.info(f"File deleted, removing from index: {file_path}")
-                if self.agent.rag.remove_document(file_abs_path):
-                    self.agent.indexed_files.discard(file_abs_path)
-                    logger.info(
-                        f"Successfully removed deleted file from index: {file_path}"
-                    )
-                else:
-                    logger.warning(
-                        f"Failed to remove deleted file from index: {file_path}"
-                    )
-            # Clean up from last_indexed tracker if present
-            if file_path in self.last_indexed:
-                del self.last_indexed[file_path]
-        except Exception as e:
-            logger.error(f"Error handling file deletion {file_path}: {e}")
-
-    def _update_telemetry(
-        self, event_type: str, file_path: str
-    ):  # pylint: disable=unused-argument
-        """Update telemetry statistics for file events."""
-        self.telemetry[event_type] += 1
-        self.telemetry["total_events"] += 1
-        self.telemetry["last_event_time"] = time.time()
-
-        # Log telemetry every 10 events or significant events
-        if self.telemetry["total_events"] % 10 == 0 or event_type in [
-            "files_deleted",
-            "files_moved",
-        ]:
-            logger.info(
-                f"📊 File Watch Telemetry: "
-                f"Added: {self.telemetry['files_added']}, "
-                f"Modified: {self.telemetry['files_modified']}, "
-                f"Deleted: {self.telemetry['files_deleted']}, "
-                f"Moved: {self.telemetry['files_moved']}, "
-                f"Total: {self.telemetry['total_events']}"
-            )
-
-    def get_telemetry(self) -> Dict[str, Any]:
-        """Get current telemetry statistics."""
-        return self.telemetry.copy()
-
-
 class ChatAgent(
     Agent, RAGToolsMixin, FileToolsMixin, ShellToolsMixin, FileSearchToolsMixin
 ):
@@ -411,13 +262,8 @@ No documents are currently indexed.
 """
 
         # Build the prompt with indexed documents section
-        base_prompt = """You are a helpful AI assistant that responds ONLY in valid JSON format.
-
-**CRITICAL RULES:**
-1. ALWAYS output valid JSON - every single response
-2. Do NOT add text before or after the JSON
-3. Do NOT use markdown code blocks
-4. Your entire response must be parseable as JSON
+        # NOTE: Base agent now provides JSON format rules, so we only add ChatAgent-specific guidance
+        base_prompt = """You are a helpful AI assistant with document search and RAG capabilities.
 """
 
         # Add indexed documents section
@@ -425,25 +271,7 @@ No documents are currently indexed.
             base_prompt
             + indexed_docs_section
             + """
-
-**JSON RESPONSE FORMATS:**
-
-Format 1 - Direct Answer (for general conversation):
-{
-  "thought": "brief reasoning",
-  "goal": "what you're trying to achieve",
-  "answer": "your response text here"
-}
-
-Format 2 - Tool Call (to get data or perform actions):
-{
-  "thought": "why you need this tool",
-  "goal": "what you're trying to achieve",
-  "tool": "tool_name",
-  "tool_args": {}
-}
-
-**WHEN TO USE EACH FORMAT:**
+**WHEN TO USE TOOLS VS DIRECT ANSWERS:**
 
 Use Format 1 (answer) for:
 - Greetings: {"answer": "Hello! How can I help?"}
@@ -842,20 +670,26 @@ When user asks to "index my data folder" or similar:
 
     def _watch_directory(self, directory: str) -> None:
         """Watch a directory for file changes."""
-        if Observer is None:
+        if not check_watchdog_available():
             error_msg = (
                 "\n❌ Error: Missing required package 'watchdog'\n\n"
                 "File watching requires the watchdog package.\n"
                 "Please install the required dependencies:\n"
-                "  pip install -e .[dev]\n\n"
+                '  uv pip install -e ".[dev]"\n\n'
                 "Or install watchdog directly:\n"
-                "  pip install watchdog>=2.1.0\n"
+                '  uv pip install "watchdog>=2.1.0"\n'
             )
             logger.error(error_msg)
             raise ImportError(error_msg)
 
         try:
-            event_handler = FileChangeHandler(self)
+            # Use generic FileChangeHandler with callbacks
+            event_handler = FileChangeHandler(
+                on_created=self.reindex_file,
+                on_modified=self.reindex_file,
+                on_deleted=self._handle_file_deletion,
+                on_moved=self._handle_file_move,
+            )
             observer = Observer()
             observer.schedule(event_handler, directory, recursive=True)
             observer.start()
@@ -864,6 +698,32 @@ When user asks to "index my data folder" or similar:
         except Exception as e:
             logger.error(f"Failed to watch {directory}: {e}")
 
+    def _handle_file_deletion(self, file_path: str) -> None:
+        """Handle file deletion by removing it from the index."""
+        if not self.rag:
+            return
+
+        try:
+            file_abs_path = str(Path(file_path).absolute())
+            if file_abs_path in self.indexed_files:
+                logger.info(f"File deleted, removing from index: {file_path}")
+                if self.rag.remove_document(file_abs_path):
+                    self.indexed_files.discard(file_abs_path)
+                    logger.info(
+                        f"Successfully removed deleted file from index: {file_path}"
+                    )
+                else:
+                    logger.warning(
+                        f"Failed to remove deleted file from index: {file_path}"
+                    )
+        except Exception as e:
+            logger.error(f"Error handling file deletion {file_path}: {e}")
+
+    def _handle_file_move(self, src_path: str, dest_path: str) -> None:
+        """Handle file move by removing old path and indexing new path."""
+        self._handle_file_deletion(src_path)
+        self.reindex_file(dest_path)
+
     def reindex_file(self, file_path: str) -> None:
         """Reindex a file that was modified or created."""
         if not self.rag:

gaia/agents/chat/app.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Chat Agent Application - Interactive chat with RAG and file search.

gaia/agents/chat/session.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Session management for Chat Agent with path validation and history.

gaia/agents/chat/tools/__init__.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Chat Agent Tools - Mixins for RAG, file operations, and shell commands.

gaia/agents/chat/tools/file_tools.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 File Tools Mixin for Chat Agent.

gaia/agents/chat/tools/rag_tools.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 RAG Tools Mixin for Chat Agent.

gaia/agents/chat/tools/shell_tools.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """
 Shell Tools Mixin for Chat Agent.

gaia/agents/code/__init__.py

@@ -1,4 +1,4 @@
-# Copyright(C) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
 # SPDX-License-Identifier: MIT
 """Code Agent for GAIA."""