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

gaia/llm/lemonade_manager.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
 """
 Lazy Lemonade Server Manager for GAIA.
@@ -10,6 +10,7 @@ Operates at the LLM level (not agent level) for flexibility with community agent
 import os
 import sys
 import threading
+from enum import Enum
 from typing import Optional
 
 from gaia.llm.lemonade_client import LemonadeClient
@@ -20,6 +21,13 @@ DEFAULT_CONTEXT_SIZE = 32768
 DEFAULT_LEMONADE_URL = "http://localhost:8000"
 
 
+class MessageType(Enum):
+    """Message type for context size notifications."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
 class LemonadeManager:
     """Singleton manager for lazy Lemonade server initialization.
 
@@ -110,17 +118,30 @@ class LemonadeManager:
             print("Then try your command again.", file=sys.stderr)
 
     @classmethod
-    def print_context_error(cls, current_size: int, required_size: int):
-        """Print error when context size is insufficient.
+    def print_context_message(
+        cls,
+        current_size: int,
+        required_size: int,
+        message_type: MessageType = MessageType.ERROR,
+    ):
+        """Print message when context size is insufficient.
 
-        Shared by CLI and SDK for consistent error messages.
+        Shared by CLI and SDK for consistent messages.
 
         Args:
             current_size: Current server context size in tokens.
             required_size: Required context size in tokens.
+            message_type: MessageType.WARNING for warning, MessageType.ERROR for error.
         """
+        if message_type == MessageType.WARNING:
+            symbol = "⚠️ "
+            label = "Context size below recommended"
+        else:
+            symbol = "❌"
+            label = "Insufficient context size"
+
         print("", file=sys.stderr)
-        print("❌ Insufficient context size.", file=sys.stderr)
+        print(f"{symbol} {label}.", file=sys.stderr)
         print(
             f"   Current: {current_size} tokens, Required: {required_size} tokens",
             file=sys.stderr,
@@ -182,15 +203,17 @@ class LemonadeManager:
                     )
                     return True
                 else:
-                    # Context size insufficient - error and fail
+                    # Context size insufficient - warn and continue
                     cls._log.warning(
                         f"Lemonade running with {cls._context_size} tokens, "
                         f"but {min_context_size} requested. "
                         f"Restart with: lemonade-server serve --ctx-size {min_context_size}"
                     )
                     if not quiet:
-                        cls.print_context_error(cls._context_size, min_context_size)
-                    return False
+                        cls.print_context_message(
+                            cls._context_size, min_context_size, MessageType.WARNING
+                        )
+                    return True
 
             cls._log.debug(f"Initializing Lemonade (min context: {min_context_size})")
 
@@ -223,15 +246,17 @@ class LemonadeManager:
                     f"(context: {cls._context_size} tokens)"
                 )
 
-                # Verify context size - fail if insufficient
+                # Verify context size - warn if insufficient
                 if cls._context_size < min_context_size:
                     cls._log.warning(
                         f"Context size {cls._context_size} is less than "
                         f"requested {min_context_size}. Some features may not work correctly."
                     )
                     if not quiet:
-                        cls.print_context_error(cls._context_size, min_context_size)
-                    return False
+                        cls.print_context_message(
+                            cls._context_size, min_context_size, MessageType.WARNING
+                        )
+                    return True
 
                 return True
 

gaia/llm/llm_client.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
 
 # Standard library imports

gaia/llm/vlm_client.py

@@ -23,20 +23,54 @@ DEFAULT_LEMONADE_URL = "http://localhost:8000/api/v1"
 
 logger = logging.getLogger(__name__)
 
+# Magic bytes for common image formats
+IMAGE_SIGNATURES = {
+    b"\x89PNG\r\n\x1a\n": "image/png",
+    b"\xff\xd8\xff": "image/jpeg",
+    b"GIF87a": "image/gif",
+    b"GIF89a": "image/gif",
+    b"RIFF": "image/webp",  # WebP starts with RIFF...WEBP
+    b"BM": "image/bmp",
+}
+
+
+def detect_image_mime_type(image_bytes: bytes) -> str:
+    """
+    Detect MIME type from image bytes using magic number signatures.
+
+    Args:
+        image_bytes: Raw image bytes
+
+    Returns:
+        MIME type string (e.g., "image/jpeg", "image/png")
+        Defaults to "image/png" if format not detected.
+    """
+    for signature, mime_type in IMAGE_SIGNATURES.items():
+        if image_bytes.startswith(signature):
+            # Special case: WebP needs additional check for WEBP marker
+            if signature == b"RIFF" and len(image_bytes) >= 12:
+                if image_bytes[8:12] != b"WEBP":
+                    continue
+            return mime_type
+
+    # Default to PNG if format not detected
+    logger.debug("Could not detect image format, defaulting to image/png")
+    return "image/png"
+
 
 class VLMClient:
     """
     VLM client for extracting text from images using Lemonade server.
 
     Handles:
-    - Model loading (Qwen2.5-VL-7B-Instruct-GGUF)
+    - Model loading (default: Qwen3-VL-4B-Instruct-GGUF)
     - Image-to-markdown conversion
     - State tracking for VLM processing
     """
 
     def __init__(
         self,
-        vlm_model: str = "Qwen2.5-VL-7B-Instruct-GGUF",
+        vlm_model: str = "Qwen3-VL-4B-Instruct-GGUF",
         base_url: Optional[str] = None,
         auto_load: bool = True,
     ):
@@ -70,7 +104,7 @@ class VLMClient:
         self.auto_load = auto_load
         self.vlm_loaded = False
 
-        logger.info(f"VLM Client initialized: {self.vlm_model} at {self.server_url}")
+        logger.debug(f"VLM Client initialized: {self.vlm_model} at {self.server_url}")
 
     def check_availability(self) -> bool:
         """
@@ -86,7 +120,7 @@ class VLMClient:
             ]
 
             if self.vlm_model in available_models:
-                logger.info(f"✅ VLM model available: {self.vlm_model}")
+                logger.debug(f"VLM model available: {self.vlm_model}")
                 return True
             else:
                 logger.warning(f"❌ VLM model not found: {self.vlm_model}")
@@ -126,11 +160,11 @@ class VLMClient:
             return False
 
         try:
-            logger.info(f"📥 Loading VLM model: {self.vlm_model}")
+            logger.debug(f"Loading VLM model: {self.vlm_model}")
             # Load model (auto-download handled by lemonade_client, may take hours)
             self.client.load_model(self.vlm_model, timeout=60, auto_download=True)
             self.vlm_loaded = True
-            logger.info(f"✅ VLM model loaded: {self.vlm_model}")
+            logger.debug(f"VLM model loaded: {self.vlm_model}")
             return True
 
         except Exception as e:
@@ -165,10 +199,10 @@ class VLMClient:
             logger.error(error_msg)
             return f"[VLM extraction failed: {error_msg}]"
 
-        # Encode image as base64
+        # Encode image as base64 and detect MIME type
         # Note: Image size optimization happens in pdf_utils.py during extraction
         image_b64 = base64.b64encode(image_bytes).decode("utf-8")
-        _image_size_kb = len(image_bytes) / 1024
+        mime_type = detect_image_mime_type(image_bytes)
 
         # Default prompt for text extraction
         if not prompt:
@@ -192,7 +226,7 @@ Output format: Clean markdown with the ACTUAL text from the image."""
                     {"type": "text", "text": prompt},
                     {
                         "type": "image_url",
-                        "image_url": {"url": f"data:image/png;base64,{image_b64}"},
+                        "image_url": {"url": f"data:{mime_type};base64,{image_b64}"},
                     },
                 ],
             }
@@ -203,11 +237,11 @@ Output format: Clean markdown with the ACTUAL text from the image."""
 
             start_time = time.time()
 
-            logger.info(
-                f"   🔍 VLM extracting from image {image_num} on page {page_num}..."
+            logger.debug(
+                f"VLM extracting from image {image_num} on page {page_num} ({mime_type})..."
             )
             logger.debug(
-                f"   Image size: {len(image_b64)} chars base64 ({len(image_bytes)} bytes raw)"
+                f"   Image: {mime_type}, {len(image_b64)} chars base64 ({len(image_bytes)} bytes raw)"
             )
 
             # Call VLM using chat completions endpoint
@@ -216,7 +250,7 @@ Output format: Clean markdown with the ACTUAL text from the image."""
                 messages=messages,
                 temperature=0.1,  # Low temp for accurate extraction
                 max_completion_tokens=2048,  # Allow detailed extraction
-                timeout=60,  # VLM may be slower than text models
+                timeout=300,  # VLM needs more time for complex forms (5 min)
             )
 
             elapsed = time.time() - start_time
@@ -228,14 +262,17 @@ Output format: Clean markdown with the ACTUAL text from the image."""
                 and len(response["choices"]) > 0
             ):
                 extracted_text = response["choices"][0]["message"]["content"]
-                logger.info(
-                    f"   ✅ Extracted {len(extracted_text)} chars from image {image_num} "
-                    f"in {elapsed:.2f}s ({len(image_bytes)/1024:.0f}KB image)"
+                size_kb = len(image_bytes) / 1024
+                logger.debug(
+                    f"Extracted {len(extracted_text)} chars from image {image_num} "
+                    f"in {elapsed:.2f}s ({size_kb:.0f}KB image)"
                 )
                 return extracted_text
             else:
-                logger.error(f"Unexpected VLM response format: {response}")
-                return "[VLM extraction failed: unexpected response format]"
+                # Check for specific error types and provide helpful messages
+                error_msg = self._parse_vlm_error(response)
+                logger.error(error_msg)
+                return f"[VLM extraction failed: {error_msg}]"
 
         except Exception as e:
             logger.error(
@@ -246,6 +283,44 @@ Output format: Clean markdown with the ACTUAL text from the image."""
             logger.debug(traceback.format_exc())
             return f"[VLM extraction failed: {str(e)}]"
 
+    def _parse_vlm_error(self, response: dict) -> str:
+        """Parse VLM error response and return a helpful error message."""
+        if not isinstance(response, dict):
+            return f"Unexpected response type: {type(response)}"
+
+        # Check for nested error structure from Lemonade
+        error = response.get("error", {})
+        if isinstance(error, dict):
+            details = error.get("details", {})
+            inner_response = (
+                details.get("response", {}) if isinstance(details, dict) else {}
+            )
+            inner_error = (
+                inner_response.get("error", {})
+                if isinstance(inner_response, dict)
+                else {}
+            )
+
+            # Context size error
+            if inner_error.get("type") == "exceed_context_size_error":
+                n_ctx = inner_error.get("n_ctx", "unknown")
+                n_prompt = inner_error.get("n_prompt_tokens", "unknown")
+                return (
+                    f"Context size too small! Image requires {n_prompt} tokens "
+                    f"but model context is only {n_ctx}. "
+                    f"To fix: Right-click Lemonade tray icon → Settings → "
+                    f"set Context Size to 32768, then restart the model."
+                )
+
+            # Other backend errors
+            if error.get("type") == "backend_error":
+                msg = inner_error.get(
+                    "message", error.get("message", "Unknown backend error")
+                )
+                return f"Backend error: {msg}"
+
+        return f"Unexpected response format: {response}"
+
     def extract_from_page_images(self, images: list, page_num: int) -> list:
         """
         Extract text from multiple images on a page.

gaia/logger.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 io

gaia/mcp/agent_mcp_server.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/mcp/blender_mcp_client.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
 
 # This Blender MCP client is a simplified and modified version of the BlenderMCP project from https://github.com/BlenderMCP/blender-mcp

gaia/mcp/blender_mcp_server.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
 
 # This Blender MCP client is a simplified and modified version of the BlenderMCP project from https://github.com/BlenderMCP/blender-mcp

gaia/mcp/context7_cache.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
 """Persistent cache and rate protection for Context7 API calls."""
 

gaia/mcp/servers/__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
 
 """

gaia/mcp/servers/docker_mcp.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/security.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
 """
 Security utilities for GAIA.

gaia/testing/__init__.py

@@ -0,0 +1,87 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""
+GAIA Testing Utilities
+
+Provides mocks, fixtures, and assertions for testing GAIA agents
+without requiring real LLM/VLM services or databases.
+
+Example:
+    from gaia.testing import (
+        MockLLMProvider,
+        MockVLMClient,
+        create_test_agent,
+        temp_directory,
+        assert_llm_called,
+    )
+
+    def test_my_agent():
+        agent = create_test_agent(
+            MyAgent,
+            mock_responses=["I'll search for that", "Found results"],
+        )
+
+        result = agent.process_query("Find data")
+
+        assert_llm_called(agent._mock_llm)
+        assert "results" in result["answer"].lower()
+"""
+
+# Assertions
+from gaia.testing.assertions import (
+    assert_agent_completed,
+    assert_llm_called,
+    assert_llm_prompt_contains,
+    assert_no_errors,
+    assert_result_has_keys,
+    assert_result_value,
+    assert_tool_args,
+    assert_tool_called,
+    assert_vlm_called,
+)
+
+# Fixtures
+from gaia.testing.fixtures import (
+    AgentTestContext,
+    create_test_agent,
+    temp_directory,
+    temp_file,
+)
+
+# Mocks
+from gaia.testing.mocks import (
+    MockLLMProvider,
+    MockToolExecutor,
+    MockVLMClient,
+)
+
+# Re-export temp_db from database.testing for convenience
+try:
+    from gaia.database.testing import temp_db
+except ImportError:
+    # Database module may not be available
+    temp_db = None
+
+__all__ = [
+    # Mocks
+    "MockLLMProvider",
+    "MockVLMClient",
+    "MockToolExecutor",
+    # Fixtures
+    "create_test_agent",
+    "temp_directory",
+    "temp_file",
+    "temp_db",
+    "AgentTestContext",
+    # Assertions
+    "assert_llm_called",
+    "assert_llm_prompt_contains",
+    "assert_vlm_called",
+    "assert_tool_called",
+    "assert_tool_args",
+    "assert_result_has_keys",
+    "assert_result_value",
+    "assert_agent_completed",
+    "assert_no_errors",
+]