genxai-framework 0.1.0__py3-none-any.whl

genxai/tools/builtin/database/__init__.py

@@ -0,0 +1,15 @@
+"""Database tools for GenXAI."""
+
+from genxai.tools.builtin.database.sql_query import SQLQueryTool
+from genxai.tools.builtin.database.redis_cache import RedisCacheTool
+from genxai.tools.builtin.database.mongodb_query import MongoDBQueryTool
+from genxai.tools.builtin.database.vector_search import VectorSearchTool
+from genxai.tools.builtin.database.database_inspector import DatabaseInspectorTool
+
+__all__ = [
+    "SQLQueryTool",
+    "RedisCacheTool",
+    "MongoDBQueryTool",
+    "VectorSearchTool",
+    "DatabaseInspectorTool",
+]

genxai/tools/builtin/database/database_inspector.py

@@ -0,0 +1,157 @@
+"""Database inspector tool for examining database schemas."""
+
+from typing import Any, Dict, List
+import logging
+
+from genxai.tools.base import Tool, ToolMetadata, ToolParameter, ToolCategory
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseInspectorTool(Tool):
+    """Inspect database schemas, tables, and metadata."""
+
+    def __init__(self) -> None:
+        """Initialize database inspector tool."""
+        metadata = ToolMetadata(
+            name="database_inspector",
+            description="Inspect database schemas, tables, columns, and indexes",
+            category=ToolCategory.DATABASE,
+            tags=["database", "schema", "inspect", "metadata", "tables"],
+            version="1.0.0",
+        )
+
+        parameters = [
+            ToolParameter(
+                name="connection_string",
+                type="string",
+                description="Database connection string",
+                required=True,
+            ),
+            ToolParameter(
+                name="operation",
+                type="string",
+                description="Inspection operation",
+                required=True,
+                enum=["list_tables", "describe_table", "list_indexes", "database_info"],
+            ),
+            ToolParameter(
+                name="table_name",
+                type="string",
+                description="Table name (for describe_table and list_indexes)",
+                required=False,
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+
+    async def _execute(
+        self,
+        connection_string: str,
+        operation: str,
+        table_name: str = None,
+    ) -> Dict[str, Any]:
+        """Execute database inspection.
+
+        Args:
+            connection_string: Database connection string
+            operation: Inspection operation
+            table_name: Table name
+
+        Returns:
+            Dictionary containing inspection results
+        """
+        engine = None
+        try:
+            from sqlalchemy import create_engine, inspect
+            from sqlalchemy.exc import SQLAlchemyError
+        except ImportError:
+            raise ImportError(
+                "sqlalchemy package not installed. Install with: pip install sqlalchemy"
+            )
+
+        result: Dict[str, Any] = {
+            "operation": operation,
+            "success": False,
+        }
+
+        try:
+            # Create engine and inspector
+            engine = create_engine(connection_string)
+            inspector = inspect(engine)
+
+            if operation == "list_tables":
+                tables = inspector.get_table_names()
+                result.update({
+                    "tables": tables,
+                    "count": len(tables),
+                    "success": True,
+                })
+
+            elif operation == "describe_table":
+                if not table_name:
+                    raise ValueError("table_name required for describe_table operation")
+                
+                columns = inspector.get_columns(table_name)
+                column_info = [
+                    {
+                        "name": col["name"],
+                        "type": str(col["type"]),
+                        "nullable": col.get("nullable", True),
+                        "default": str(col.get("default")) if col.get("default") else None,
+                        "primary_key": col.get("primary_key", False),
+                    }
+                    for col in columns
+                ]
+                
+                result.update({
+                    "table": table_name,
+                    "columns": column_info,
+                    "column_count": len(column_info),
+                    "success": True,
+                })
+
+            elif operation == "list_indexes":
+                if not table_name:
+                    raise ValueError("table_name required for list_indexes operation")
+                
+                indexes = inspector.get_indexes(table_name)
+                index_info = [
+                    {
+                        "name": idx["name"],
+                        "columns": idx["column_names"],
+                        "unique": idx.get("unique", False),
+                    }
+                    for idx in indexes
+                ]
+                
+                result.update({
+                    "table": table_name,
+                    "indexes": index_info,
+                    "index_count": len(index_info),
+                    "success": True,
+                })
+
+            elif operation == "database_info":
+                tables = inspector.get_table_names()
+                views = inspector.get_view_names()
+                
+                result.update({
+                    "tables": tables,
+                    "table_count": len(tables),
+                    "views": views,
+                    "view_count": len(views),
+                    "dialect": engine.dialect.name,
+                    "success": True,
+                })
+
+        except SQLAlchemyError as e:
+            result["error"] = f"Database error: {str(e)}"
+        except Exception as e:
+            result["error"] = str(e)
+        finally:
+            if engine is not None:
+                engine.dispose()
+
+        logger.info(f"Database inspection ({operation}) completed: success={result['success']}")
+        return result

genxai/tools/builtin/database/mongodb_query.py

@@ -0,0 +1,196 @@
+"""MongoDB query tool for NoSQL database operations."""
+
+from typing import Any, Dict, List, Optional
+import logging
+
+from genxai.tools.base import Tool, ToolMetadata, ToolParameter, ToolCategory
+
+logger = logging.getLogger(__name__)
+
+
+class MongoDBQueryTool(Tool):
+    """Query and manipulate MongoDB collections."""
+
+    def __init__(self) -> None:
+        """Initialize MongoDB query tool."""
+        metadata = ToolMetadata(
+            name="mongodb_query",
+            description="Query MongoDB collections with find, insert, update, delete operations",
+            category=ToolCategory.DATABASE,
+            tags=["mongodb", "nosql", "database", "query", "document"],
+            version="1.0.0",
+        )
+
+        parameters = [
+            ToolParameter(
+                name="operation",
+                type="string",
+                description="MongoDB operation",
+                required=True,
+                enum=["find", "find_one", "insert", "update", "delete", "count"],
+            ),
+            ToolParameter(
+                name="connection_string",
+                type="string",
+                description="MongoDB connection string",
+                required=True,
+            ),
+            ToolParameter(
+                name="database",
+                type="string",
+                description="Database name",
+                required=True,
+            ),
+            ToolParameter(
+                name="collection",
+                type="string",
+                description="Collection name",
+                required=True,
+            ),
+            ToolParameter(
+                name="filter",
+                type="object",
+                description="Query filter (for find, update, delete, count)",
+                required=False,
+            ),
+            ToolParameter(
+                name="document",
+                type="object",
+                description="Document to insert or update data",
+                required=False,
+            ),
+            ToolParameter(
+                name="limit",
+                type="number",
+                description="Maximum number of documents to return",
+                required=False,
+                default=100,
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+
+    async def _execute(
+        self,
+        operation: str,
+        connection_string: str,
+        database: str,
+        collection: str,
+        filter: Optional[Dict[str, Any]] = None,
+        document: Optional[Dict[str, Any]] = None,
+        limit: int = 100,
+    ) -> Dict[str, Any]:
+        """Execute MongoDB operation.
+
+        Args:
+            operation: Operation to perform
+            connection_string: MongoDB connection string
+            database: Database name
+            collection: Collection name
+            filter: Query filter
+            document: Document data
+            limit: Result limit
+
+        Returns:
+            Dictionary containing operation results
+        """
+        try:
+            from pymongo import MongoClient
+            from pymongo.errors import PyMongoError
+        except ImportError:
+            raise ImportError(
+                "pymongo package not installed. Install with: pip install pymongo"
+            )
+
+        result: Dict[str, Any] = {
+            "operation": operation,
+            "database": database,
+            "collection": collection,
+            "success": False,
+        }
+
+        try:
+            # Connect to MongoDB
+            client = MongoClient(connection_string)
+            db = client[database]
+            coll = db[collection]
+
+            if operation == "find":
+                query_filter = filter or {}
+                cursor = coll.find(query_filter).limit(limit)
+                documents = list(cursor)
+                
+                # Convert ObjectId to string
+                for doc in documents:
+                    if "_id" in doc:
+                        doc["_id"] = str(doc["_id"])
+                
+                result.update({
+                    "documents": documents,
+                    "count": len(documents),
+                    "success": True,
+                })
+
+            elif operation == "find_one":
+                query_filter = filter or {}
+                doc = coll.find_one(query_filter)
+                
+                if doc and "_id" in doc:
+                    doc["_id"] = str(doc["_id"])
+                
+                result.update({
+                    "document": doc,
+                    "found": doc is not None,
+                    "success": True,
+                })
+
+            elif operation == "insert":
+                if not document:
+                    raise ValueError("document parameter required for insert operation")
+                
+                insert_result = coll.insert_one(document)
+                result.update({
+                    "inserted_id": str(insert_result.inserted_id),
+                    "success": True,
+                })
+
+            elif operation == "update":
+                if not filter:
+                    raise ValueError("filter parameter required for update operation")
+                if not document:
+                    raise ValueError("document parameter required for update operation")
+                
+                update_result = coll.update_many(filter, {"$set": document})
+                result.update({
+                    "matched_count": update_result.matched_count,
+                    "modified_count": update_result.modified_count,
+                    "success": True,
+                })
+
+            elif operation == "delete":
+                if not filter:
+                    raise ValueError("filter parameter required for delete operation")
+                
+                delete_result = coll.delete_many(filter)
+                result.update({
+                    "deleted_count": delete_result.deleted_count,
+                    "success": True,
+                })
+
+            elif operation == "count":
+                query_filter = filter or {}
+                count = coll.count_documents(query_filter)
+                result.update({
+                    "count": count,
+                    "success": True,
+                })
+
+            client.close()
+
+        except PyMongoError as e:
+            result["error"] = f"MongoDB error: {str(e)}"
+        except Exception as e:
+            result["error"] = str(e)
+
+        logger.info(f"MongoDB {operation} completed: success={result['success']}")
+        return result

genxai/tools/builtin/database/redis_cache.py

@@ -0,0 +1,167 @@
+"""Redis cache tool for caching operations."""
+
+from typing import Any, Dict, Optional
+import logging
+
+from genxai.tools.base import Tool, ToolMetadata, ToolParameter, ToolCategory
+
+logger = logging.getLogger(__name__)
+
+
+class RedisCacheTool(Tool):
+    """Interact with Redis cache for get/set/delete operations."""
+
+    def __init__(self) -> None:
+        """Initialize Redis cache tool."""
+        metadata = ToolMetadata(
+            name="redis_cache",
+            description="Perform Redis cache operations (get, set, delete, exists)",
+            category=ToolCategory.DATABASE,
+            tags=["redis", "cache", "key-value", "memory", "storage"],
+            version="1.0.0",
+        )
+
+        parameters = [
+            ToolParameter(
+                name="operation",
+                type="string",
+                description="Cache operation to perform",
+                required=True,
+                enum=["get", "set", "delete", "exists", "keys", "ttl"],
+            ),
+            ToolParameter(
+                name="key",
+                type="string",
+                description="Cache key",
+                required=True,
+            ),
+            ToolParameter(
+                name="value",
+                type="string",
+                description="Value to set (for set operation)",
+                required=False,
+            ),
+            ToolParameter(
+                name="ttl",
+                type="number",
+                description="Time to live in seconds (for set operation)",
+                required=False,
+            ),
+            ToolParameter(
+                name="host",
+                type="string",
+                description="Redis host",
+                required=False,
+                default="localhost",
+            ),
+            ToolParameter(
+                name="port",
+                type="number",
+                description="Redis port",
+                required=False,
+                default=6379,
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+
+    async def _execute(
+        self,
+        operation: str,
+        key: str,
+        value: Optional[str] = None,
+        ttl: Optional[int] = None,
+        host: str = "localhost",
+        port: int = 6379,
+    ) -> Dict[str, Any]:
+        """Execute Redis cache operation.
+
+        Args:
+            operation: Operation to perform
+            key: Cache key
+            value: Value to set
+            ttl: Time to live
+            host: Redis host
+            port: Redis port
+
+        Returns:
+            Dictionary containing operation results
+        """
+        try:
+            import redis
+        except ImportError:
+            raise ImportError(
+                "redis package not installed. Install with: pip install redis"
+            )
+
+        result: Dict[str, Any] = {
+            "operation": operation,
+            "key": key,
+            "success": False,
+        }
+
+        try:
+            # Connect to Redis
+            client = redis.Redis(host=host, port=port, decode_responses=True)
+
+            if operation == "get":
+                cached_value = client.get(key)
+                result.update({
+                    "value": cached_value,
+                    "exists": cached_value is not None,
+                    "success": True,
+                })
+
+            elif operation == "set":
+                if value is None:
+                    raise ValueError("value parameter required for set operation")
+                
+                if ttl:
+                    client.setex(key, ttl, value)
+                else:
+                    client.set(key, value)
+                
+                result.update({
+                    "value": value,
+                    "ttl": ttl,
+                    "success": True,
+                })
+
+            elif operation == "delete":
+                deleted_count = client.delete(key)
+                result.update({
+                    "deleted": deleted_count > 0,
+                    "success": True,
+                })
+
+            elif operation == "exists":
+                exists = client.exists(key) > 0
+                result.update({
+                    "exists": exists,
+                    "success": True,
+                })
+
+            elif operation == "keys":
+                # Use key as pattern
+                matching_keys = client.keys(key)
+                result.update({
+                    "keys": matching_keys,
+                    "count": len(matching_keys),
+                    "success": True,
+                })
+
+            elif operation == "ttl":
+                ttl_value = client.ttl(key)
+                result.update({
+                    "ttl": ttl_value,
+                    "exists": ttl_value >= 0,
+                    "success": True,
+                })
+
+        except redis.RedisError as e:
+            result["error"] = f"Redis error: {str(e)}"
+        except Exception as e:
+            result["error"] = str(e)
+
+        logger.info(f"Redis {operation} completed: success={result['success']}")
+        return result

genxai/tools/builtin/database/sql_query.py

@@ -0,0 +1,145 @@
+"""SQL query tool for executing database queries."""
+
+from typing import Any, Dict, List, Optional
+import logging
+
+from genxai.tools.base import Tool, ToolMetadata, ToolParameter, ToolCategory
+
+logger = logging.getLogger(__name__)
+
+
+class SQLQueryTool(Tool):
+    """Execute SQL queries on databases with safety controls."""
+
+    def __init__(self) -> None:
+        """Initialize SQL query tool."""
+        metadata = ToolMetadata(
+            name="sql_query",
+            description="Execute SQL queries on databases (PostgreSQL, MySQL, SQLite)",
+            category=ToolCategory.DATABASE,
+            tags=["sql", "database", "query", "postgres", "mysql", "sqlite"],
+            version="1.0.0",
+        )
+
+        parameters = [
+            ToolParameter(
+                name="query",
+                type="string",
+                description="SQL query to execute",
+                required=True,
+            ),
+            ToolParameter(
+                name="connection_string",
+                type="string",
+                description="Database connection string (e.g., postgresql://user:pass@host/db)",
+                required=True,
+            ),
+            ToolParameter(
+                name="read_only",
+                type="boolean",
+                description="Restrict to read-only queries (SELECT only)",
+                required=False,
+                default=True,
+            ),
+            ToolParameter(
+                name="max_rows",
+                type="number",
+                description="Maximum number of rows to return",
+                required=False,
+                default=1000,
+                min_value=1,
+                max_value=10000,
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+
+    async def _execute(
+        self,
+        query: str,
+        connection_string: str,
+        read_only: bool = True,
+        max_rows: int = 1000,
+    ) -> Dict[str, Any]:
+        """Execute SQL query.
+
+        Args:
+            query: SQL query
+            connection_string: Database connection string
+            read_only: Read-only mode flag
+            max_rows: Maximum rows to return
+
+        Returns:
+            Dictionary containing query results
+        """
+        engine = None
+        try:
+            from sqlalchemy import create_engine, text
+            from sqlalchemy.exc import SQLAlchemyError
+        except ImportError:
+            raise ImportError(
+                "sqlalchemy package not installed. Install with: pip install sqlalchemy"
+            )
+
+        result: Dict[str, Any] = {
+            "query": query,
+            "read_only": read_only,
+            "success": False,
+        }
+
+        try:
+            # Validate read-only mode
+            if read_only:
+                query_upper = query.strip().upper()
+                if not query_upper.startswith("SELECT"):
+                    raise ValueError(
+                        "Only SELECT queries allowed in read-only mode"
+                    )
+                # Check for dangerous keywords
+                dangerous_keywords = ["DROP", "DELETE", "UPDATE", "INSERT", "ALTER", "CREATE"]
+                if any(keyword in query_upper for keyword in dangerous_keywords):
+                    raise ValueError(
+                        f"Query contains forbidden keywords in read-only mode"
+                    )
+
+            # Create engine
+            engine = create_engine(connection_string)
+
+            # Execute query
+            with engine.connect() as connection:
+                query_result = connection.execute(text(query))
+                
+                # Fetch results for SELECT queries
+                if query_upper.startswith("SELECT"):
+                    rows = query_result.fetchmany(max_rows)
+                    columns = list(query_result.keys())
+                    
+                    # Convert to list of dictionaries
+                    data = [dict(zip(columns, row)) for row in rows]
+                    
+                    result.update({
+                        "data": data,
+                        "columns": columns,
+                        "row_count": len(data),
+                        "truncated": len(data) == max_rows,
+                    })
+                else:
+                    # For non-SELECT queries
+                    result.update({
+                        "rows_affected": query_result.rowcount,
+                    })
+                
+                result["success"] = True
+
+        except SQLAlchemyError as e:
+            result["error"] = f"Database error: {str(e)}"
+        except ValueError as e:
+            result["error"] = str(e)
+        except Exception as e:
+            result["error"] = f"Unexpected error: {str(e)}"
+        finally:
+            if engine is not None:
+                engine.dispose()
+
+        logger.info(f"SQL query executed: success={result['success']}")
+        return result