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

gaia/database/agent.py

@@ -0,0 +1,176 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""DatabaseAgent - Agent with built-in database tools."""
+
+from typing import Any, Dict, Optional
+
+from gaia.agents.base import Agent, tool
+from gaia.database.mixin import DatabaseMixin
+
+
+class DatabaseAgent(Agent, DatabaseMixin):
+    """
+    Agent with built-in SQLite database tools.
+
+    Extends Agent with database capabilities, automatically registering
+    tools that allow the LLM to query and modify the database.
+
+    Example:
+        class PatientAgent(DatabaseAgent):
+            def __init__(self, **kwargs):
+                super().__init__(db_path="data/patients.db", **kwargs)
+
+                if not self.table_exists("patients"):
+                    self.execute('''
+                        CREATE TABLE patients (
+                            id INTEGER PRIMARY KEY,
+                            name TEXT NOT NULL,
+                            dob TEXT
+                        )
+                    ''')
+
+            def _get_system_prompt(self) -> str:
+                return "You help manage patient records."
+
+        # LLM can now use: db_query, db_insert, db_update, db_delete
+
+    Security Note:
+        The db_query tool allows the LLM to execute arbitrary SELECT queries.
+        For production use, consider overriding _register_db_tools() to expose
+        only domain-specific, validated operations.
+    """
+
+    def __init__(
+        self,
+        db_path: str = ":memory:",
+        **kwargs,
+    ):
+        """
+        Initialize DatabaseAgent.
+
+        Args:
+            db_path: Path to SQLite database file, or ":memory:" for in-memory.
+                     Parent directories are created automatically.
+            **kwargs: Additional arguments passed to Agent.
+        """
+        super().__init__(**kwargs)
+        self.init_db(db_path)
+        self._register_db_tools()
+
+    def _register_db_tools(self) -> None:
+        """Register database tools for LLM use."""
+        agent = self
+
+        @tool
+        def db_query(sql: str, params: Optional[Dict[str, Any]] = None) -> Dict:
+            """
+            Execute a SELECT query and return results.
+
+            Args:
+                sql: SQL SELECT query with :param placeholders
+                params: Optional dictionary of parameter values
+
+            Returns:
+                Dictionary with 'rows' (list of row dicts) and 'count'
+
+            Example:
+                db_query("SELECT * FROM users WHERE age > :min_age", {"min_age": 18})
+            """
+            rows = agent.query(sql, params or {})
+            return {"rows": rows, "count": len(rows)}
+
+        @tool
+        def db_insert(table: str, data: Dict[str, Any]) -> Dict:
+            """
+            Insert a row into a table.
+
+            Args:
+                table: Table name
+                data: Dictionary of column names to values
+
+            Returns:
+                Dictionary with 'id' (the inserted row's ID) and 'success'
+
+            Example:
+                db_insert("users", {"name": "Alice", "email": "alice@example.com"})
+            """
+            row_id = agent.insert(table, data)
+            return {"id": row_id, "success": True}
+
+        @tool
+        def db_update(
+            table: str, data: Dict[str, Any], where: str, params: Dict[str, Any]
+        ) -> Dict:
+            """
+            Update rows matching a condition.
+
+            Args:
+                table: Table name
+                data: Dictionary of column names to new values
+                where: WHERE clause with :param placeholders (without WHERE keyword)
+                params: Dictionary of parameter values for WHERE clause
+
+            Returns:
+                Dictionary with 'updated' (number of rows affected)
+
+            Example:
+                db_update("users", {"email": "new@example.com"}, "id = :id", {"id": 42})
+            """
+            count = agent.update(table, data, where, params)
+            return {"updated": count}
+
+        @tool
+        def db_delete(table: str, where: str, params: Dict[str, Any]) -> Dict:
+            """
+            Delete rows matching a condition.
+
+            Args:
+                table: Table name
+                where: WHERE clause with :param placeholders (without WHERE keyword)
+                params: Dictionary of parameter values for WHERE clause
+
+            Returns:
+                Dictionary with 'deleted' (number of rows deleted)
+
+            Example:
+                db_delete("sessions", "expires_at < :now", {"now": "2024-01-01"})
+            """
+            count = agent.delete(table, where, params)
+            return {"deleted": count}
+
+        @tool
+        def db_tables() -> Dict:
+            """
+            List all tables in the database.
+
+            Returns:
+                Dictionary with 'tables' (list of table names)
+            """
+            rows = agent.query(
+                "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+            )
+            return {"tables": [row["name"] for row in rows]}
+
+        @tool
+        def db_schema(table: str) -> Dict:
+            """
+            Get the schema of a table.
+
+            Args:
+                table: Table name
+
+            Returns:
+                Dictionary with 'columns' (list of column info dicts)
+            """
+            rows = agent.query(f"PRAGMA table_info({table})")
+            columns = [
+                {
+                    "name": row["name"],
+                    "type": row["type"],
+                    "nullable": not row["notnull"],
+                    "primary_key": bool(row["pk"]),
+                }
+                for row in rows
+            ]
+            return {"table": table, "columns": columns}

gaia/database/mixin.py

@@ -0,0 +1,290 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""SQLite database mixin for GAIA agents."""
+
+import logging
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseMixin:
+    """
+    Mixin providing SQLite database access for GAIA agents.
+
+    A lean, zero-dependency mixin that uses Python's built-in sqlite3 module.
+
+    Example:
+        class MyAgent(Agent, DatabaseMixin):
+            def __init__(self, **kwargs):
+                super().__init__(**kwargs)
+                self.init_db("data/app.db")
+
+                if not self.table_exists("items"):
+                    self.execute('''
+                        CREATE TABLE items (
+                            id INTEGER PRIMARY KEY,
+                            name TEXT NOT NULL
+                        )
+                    ''')
+
+            def _register_tools(self):
+                @tool
+                def add_item(name: str) -> dict:
+                    item_id = self.insert("items", {"name": name})
+                    return {"id": item_id}
+    """
+
+    _db: Optional[sqlite3.Connection] = None
+    _in_tx: bool = False
+
+    def init_db(self, path: str = ":memory:") -> None:
+        """
+        Initialize SQLite database.
+
+        Args:
+            path: Database file path, or ":memory:" for in-memory database.
+                  Parent directories are created automatically.
+
+        Example:
+            self.init_db("data/myagent.db")  # File-based
+            self.init_db()                    # In-memory (for testing)
+        """
+        if self._db:
+            self.close_db()
+
+        if path != ":memory:":
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        self._db.row_factory = sqlite3.Row
+        self._db.execute("PRAGMA foreign_keys = ON")
+        self._in_tx = False
+        logger.info("Database initialized: %s", path)
+
+    def close_db(self) -> None:
+        """
+        Close database connection.
+
+        Safe to call multiple times.
+        """
+        if self._db:
+            self._db.close()
+            self._db = None
+            self._in_tx = False
+
+    @property
+    def db_ready(self) -> bool:
+        """True if database is initialized."""
+        return self._db is not None
+
+    def _require_db(self) -> None:
+        """Raise RuntimeError if database not initialized."""
+        if not self._db:
+            raise RuntimeError("Database not initialized. Call init_db() first.")
+
+    def query(
+        self,
+        sql: str,
+        params: Optional[Dict[str, Any]] = None,
+        one: bool = False,
+    ) -> Union[List[Dict[str, Any]], Optional[Dict[str, Any]]]:
+        """
+        Execute SELECT query and return results as dicts.
+
+        Args:
+            sql: SQL query with :param_name placeholders
+            params: Dictionary of parameter values
+            one: If True, return single row dict or None
+
+        Returns:
+            List of row dicts, or single dict/None if one=True
+
+        Example:
+            # Get all
+            users = self.query("SELECT * FROM users")
+
+            # Get one
+            user = self.query(
+                "SELECT * FROM users WHERE id = :id",
+                {"id": 42},
+                one=True
+            )
+        """
+        self._require_db()
+        cursor = self._db.execute(sql, params or {})
+        rows = [dict(row) for row in cursor.fetchall()]
+        if one:
+            return rows[0] if rows else None
+        return rows
+
+    def insert(self, table: str, data: Dict[str, Any]) -> int:
+        """
+        Insert a row and return its ID.
+
+        Args:
+            table: Table name
+            data: Column-value dictionary
+
+        Returns:
+            The inserted row's ID (lastrowid)
+
+        Example:
+            user_id = self.insert("users", {
+                "name": "Alice",
+                "email": "alice@example.com"
+            })
+        """
+        self._require_db()
+        cols = ", ".join(data.keys())
+        placeholders = ", ".join(f":{k}" for k in data.keys())
+        sql = f"INSERT INTO {table} ({cols}) VALUES ({placeholders})"
+        cursor = self._db.execute(sql, data)
+        if not self._in_tx:
+            self._db.commit()
+        return cursor.lastrowid
+
+    def update(
+        self,
+        table: str,
+        data: Dict[str, Any],
+        where: str,
+        params: Dict[str, Any],
+    ) -> int:
+        """
+        Update rows matching condition and return affected count.
+
+        Args:
+            table: Table name
+            data: Column-value dictionary to update
+            where: WHERE clause with :param placeholders (without WHERE keyword)
+            params: Parameters for WHERE clause
+
+        Returns:
+            Number of rows affected
+
+        Example:
+            count = self.update(
+                "users",
+                {"email": "new@example.com"},
+                "id = :id",
+                {"id": 42}
+            )
+        """
+        self._require_db()
+        # Prefix data params with __set_ to avoid collision with where params
+        set_clause = ", ".join(f"{k} = :__set_{k}" for k in data.keys())
+        merged_params = {f"__set_{k}": v for k, v in data.items()}
+        merged_params.update(params)
+        sql = f"UPDATE {table} SET {set_clause} WHERE {where}"
+        cursor = self._db.execute(sql, merged_params)
+        if not self._in_tx:
+            self._db.commit()
+        return cursor.rowcount
+
+    def delete(self, table: str, where: str, params: Dict[str, Any]) -> int:
+        """
+        Delete rows matching condition and return deleted count.
+
+        Args:
+            table: Table name
+            where: WHERE clause with :param placeholders (without WHERE keyword)
+            params: Parameters for WHERE clause
+
+        Returns:
+            Number of rows deleted
+
+        Example:
+            count = self.delete("sessions", "expires_at < :now", {"now": now})
+        """
+        self._require_db()
+        sql = f"DELETE FROM {table} WHERE {where}"
+        cursor = self._db.execute(sql, params)
+        if not self._in_tx:
+            self._db.commit()
+        return cursor.rowcount
+
+    @contextmanager
+    def transaction(self):
+        """
+        Execute operations atomically.
+
+        Auto-commits on success, rolls back on exception.
+
+        Example:
+            with self.transaction():
+                user_id = self.insert("users", {"name": "Alice"})
+                self.insert("profiles", {"user_id": user_id, "bio": "Hello"})
+                # If any operation fails, all are rolled back
+        """
+        self._require_db()
+        self._in_tx = True
+        try:
+            yield
+            self._db.commit()
+        except Exception:
+            self._db.rollback()
+            raise
+        finally:
+            self._in_tx = False
+
+    def execute(self, sql: str) -> None:
+        """
+        Execute raw SQL (CREATE TABLE, etc).
+
+        Supports multiple statements separated by semicolons.
+
+        WARNING: Do NOT call inside a transaction() block. This method uses
+        executescript() which auto-commits any pending transaction.
+
+        Args:
+            sql: SQL statement(s) to execute
+
+        Raises:
+            RuntimeError: If called inside a transaction() block
+
+        Example:
+            self.execute('''
+                CREATE TABLE users (
+                    id INTEGER PRIMARY KEY,
+                    name TEXT NOT NULL
+                );
+                CREATE TABLE posts (
+                    id INTEGER PRIMARY KEY,
+                    user_id INTEGER REFERENCES users(id),
+                    content TEXT
+                );
+            ''')
+        """
+        self._require_db()
+        if self._in_tx:
+            raise RuntimeError(
+                "execute() cannot be called inside a transaction() block. "
+                "Use query() for SELECT or individual insert/update/delete calls."
+            )
+        self._db.executescript(sql)
+
+    def table_exists(self, name: str) -> bool:
+        """
+        Check if a table exists in the database.
+
+        Args:
+            name: Table name to check
+
+        Returns:
+            True if table exists, False otherwise
+
+        Example:
+            if not self.table_exists("users"):
+                self.execute("CREATE TABLE users (...)")
+        """
+        result = self.query(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name=:name",
+            {"name": name},
+            one=True,
+        )
+        return result is not None

gaia/database/testing.py

@@ -0,0 +1,64 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Database testing utilities for GAIA SDK users."""
+
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Optional
+
+from gaia.database.mixin import DatabaseMixin
+
+
+class _TempDB(DatabaseMixin):
+    """Internal helper for temp_db fixture."""
+
+
+@contextmanager
+def temp_db(schema: Optional[str] = None):
+    """
+    Create a temporary SQLite database for testing.
+
+    Creates a temporary database file that is automatically cleaned up
+    after the context exits. Useful for testing agents that use DatabaseMixin.
+
+    Args:
+        schema: Optional SQL to execute on the database (CREATE TABLE, etc.)
+
+    Yields:
+        str: Path to the temporary database file
+
+    Example:
+        from gaia.database import temp_db
+
+        def test_my_agent():
+            schema = '''
+                CREATE TABLE users (
+                    id INTEGER PRIMARY KEY,
+                    name TEXT NOT NULL
+                )
+            '''
+
+            with temp_db(schema) as db_path:
+                agent = MyAgent(skip_lemonade=True)
+                agent.init_db(db_path)  # Use temp database
+                agent.insert("users", {"name": "Alice"})
+                assert len(agent.query("SELECT * FROM users")) == 1
+
+        def test_empty_db():
+            with temp_db() as db_path:
+                agent = MyAgent(skip_lemonade=True)
+                agent.init_db(db_path)
+                # Agent can create its own schema
+    """
+    with tempfile.TemporaryDirectory() as tmpdir:
+        db_path = str(Path(tmpdir) / "test.db")
+
+        if schema:
+            db = _TempDB()
+            db.init_db(db_path)
+            db.execute(schema)
+            db.close_db()
+
+        yield db_path

gaia/eval/batch_experiment.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 json
@@ -155,7 +155,7 @@ class BatchExperimentRunner:
         if PdfReader is None:
             raise ImportError(
                 "PDF reading library not found. Please install pypdf:\n"
-                "  pip install pypdf"
+                "  uv pip install pypdf"
             )
 
         try:

gaia/eval/claude.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 base64
@@ -41,9 +41,9 @@ class ClaudeClient:
             error_msg = (
                 "\n❌ Error: Missing required package 'anthropic'\n\n"
                 "Please install the eval dependencies:\n"
-                "  pip install -e .[eval]\n\n"
+                '  uv pip install -e ".[eval]"\n\n'
                 "Or install anthropic directly:\n"
-                "  pip install anthropic\n"
+                "  uv pip install anthropic\n"
             )
             raise ImportError(error_msg)
 
@@ -51,9 +51,9 @@ class ClaudeClient:
             error_msg = (
                 "\n❌ Error: Missing required package 'bs4' (BeautifulSoup4)\n\n"
                 "Please install the eval dependencies:\n"
-                "  pip install -e .[eval]\n\n"
+                '  uv pip install -e ".[eval]"\n\n'
                 "Or install beautifulsoup4 directly:\n"
-                "  pip install beautifulsoup4\n"
+                "  uv pip install beautifulsoup4\n"
             )
             raise ImportError(error_msg)
 

gaia/eval/config.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/eval/email_generator.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 argparse

gaia/eval/eval.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 json

gaia/eval/groundtruth.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 argparse

gaia/eval/transcript_generator.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 argparse

gaia/eval/webapp/public/app.js

@@ -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
 
 class EvaluationVisualizer {

gaia/eval/webapp/server.js

@@ -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
 
 const express = require('express');

gaia/eval/webapp/test-setup.js

@@ -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
 
 const fs = require('fs');

gaia/llm/__init__.py

@@ -1,2 +1,2 @@
-# 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