gaard-connectors 0.1.0__tar.gz

gaard_connectors-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: gaard-connectors
+Version: 0.1.0
+Summary: Database connectors for GAARD based on SQLAlchemy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: gaard-core==0.1.0
+Requires-Dist: sqlalchemy>=2.0.0
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2.0; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1.0; extra == "mysql"
+Provides-Extra: mssql
+Requires-Dist: pyodbc>=5.1.0; extra == "mssql"
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.0.0; extra == "oracle"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# GAARD - Governed AI Access to Relational Data
+
+GAARD is a self-hosted AI SQL Gateway for governed natural-language access to relational data.
+
+GAARD allows applications and users to ask questions about relational databases using natural language while keeping SQL generation, validation, execution, prompts, connectors, and auditability under control.
+
+For more informacion see https://github.com/pkroliszewski/gaard
+
+# This package
+Package gaard-connectors extends gaard functionality by adding support for various database connection schemes

gaard_connectors-0.1.0/README.md

@@ -0,0 +1,10 @@
+# GAARD - Governed AI Access to Relational Data
+
+GAARD is a self-hosted AI SQL Gateway for governed natural-language access to relational data.
+
+GAARD allows applications and users to ask questions about relational databases using natural language while keeping SQL generation, validation, execution, prompts, connectors, and auditability under control.
+
+For more informacion see https://github.com/pkroliszewski/gaard
+
+# This package
+Package gaard-connectors extends gaard functionality by adding support for various database connection schemes

gaard_connectors-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gaard-connectors"
+version = "0.1.0"
+description = "Database connectors for GAARD based on SQLAlchemy"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "gaard-core==0.1.0",
+    "sqlalchemy>=2.0.0",
+]
+
+[project.optional-dependencies]
+postgres = ["psycopg[binary]>=3.2.0"]
+mysql = ["pymysql>=1.1.0"]
+mssql = ["pyodbc>=5.1.0"]
+oracle = ["oracledb>=2.0.0"]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.5.0",
+    "mypy>=1.10.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gaard_connectors-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gaard_connectors-0.1.0/src/gaard_connectors/sqlalchemy/executor.py

@@ -0,0 +1,51 @@
+import re
+from collections.abc import Mapping
+from typing import Any, cast
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine, RowMapping
+from sqlalchemy.exc import SQLAlchemyError
+
+from gaard_core.errors import QueryExecutionError
+from gaard_core.json_utils import to_jsonable
+from gaard_core.query_pipeline.models import QueryResult
+
+
+class SQLAlchemyQueryExecutor:
+    def __init__(self, database_url: str, max_rows: int = 100) -> None:
+        self.database_url = database_url
+        self.max_rows = max_rows
+        self.engine: Engine = create_engine(database_url)
+
+    def execute(self, sql: str) -> QueryResult:
+        limited_sql = self._apply_limit(sql)
+
+        try:
+            with self.engine.connect() as connection:
+                result = connection.execute(text(limited_sql))
+                rows = result.mappings().fetchall()
+        except SQLAlchemyError as exc:
+            raise QueryExecutionError(
+                f"Query execution failed. SQL: {limited_sql}. Error: {exc}",
+                sql=limited_sql,
+                error_detail=str(exc),
+            ) from exc
+
+        normalized_rows = [self._normalize_row(row) for row in rows]
+        columns = list(normalized_rows[0].keys()) if normalized_rows else []
+
+        return QueryResult(
+            columns=columns,
+            rows=normalized_rows,
+        )
+
+    def _apply_limit(self, sql: str) -> str:
+        normalized = sql.strip().rstrip(";")
+
+        if re.search(r"\blimit\s+\d+\b", normalized, flags=re.IGNORECASE):
+            return normalized
+
+        return f"{normalized} LIMIT {self.max_rows}"
+
+    def _normalize_row(self, row: Mapping[str, Any] | RowMapping) -> dict[str, Any]:
+        return cast(dict[str, Any], to_jsonable(dict(row)))

gaard_connectors-0.1.0/src/gaard_connectors/sqlalchemy/introspector.py

@@ -0,0 +1,62 @@
+from typing import Literal
+
+from sqlalchemy import create_engine, inspect
+from sqlalchemy.engine import Engine
+from sqlalchemy.engine.reflection import Inspector
+
+from gaard_core.schema.models import ColumnInfo, DatabaseSchema, ForeignKeyInfo, TableInfo
+
+
+class SQLAlchemySchemaIntrospector:
+    def __init__(self, database_url: str) -> None:
+        self.database_url = database_url
+        self.engine: Engine = create_engine(database_url)
+
+    def introspect(self) -> DatabaseSchema:
+        inspector = inspect(self.engine)
+
+        tables: list[TableInfo] = []
+
+        for table_name in inspector.get_table_names():
+            tables.append(self._introspect_table(inspector, table_name, "table"))
+
+        for view_name in inspector.get_view_names():
+            tables.append(self._introspect_table(inspector, view_name, "view"))
+
+        return DatabaseSchema(tables=tables)
+
+    def _introspect_table(
+        self,
+        inspector: Inspector,
+        name: str,
+        object_type: Literal["table", "view"],
+    ) -> TableInfo:
+        columns = [
+            ColumnInfo(
+                name=column["name"],
+                type=str(column["type"]),
+                nullable=bool(column.get("nullable", True)),
+                primary_key=bool(column.get("primary_key", False)),
+            )
+            for column in inspector.get_columns(name)
+        ]
+
+        foreign_keys = []
+
+        if object_type == "table":
+            foreign_keys = [
+                ForeignKeyInfo(
+                    constrained_columns=list(foreign_key.get("constrained_columns") or []),
+                    referred_table=str(foreign_key.get("referred_table")),
+                    referred_columns=list(foreign_key.get("referred_columns") or []),
+                )
+                for foreign_key in inspector.get_foreign_keys(name)
+                if foreign_key.get("referred_table")
+            ]
+
+        return TableInfo(
+            name=name,
+            object_type=object_type,
+            columns=columns,
+            foreign_keys=foreign_keys,
+        )

gaard_connectors-0.1.0/src/gaard_connectors.egg-info/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: gaard-connectors
+Version: 0.1.0
+Summary: Database connectors for GAARD based on SQLAlchemy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: gaard-core==0.1.0
+Requires-Dist: sqlalchemy>=2.0.0
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2.0; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1.0; extra == "mysql"
+Provides-Extra: mssql
+Requires-Dist: pyodbc>=5.1.0; extra == "mssql"
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.0.0; extra == "oracle"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# GAARD - Governed AI Access to Relational Data
+
+GAARD is a self-hosted AI SQL Gateway for governed natural-language access to relational data.
+
+GAARD allows applications and users to ask questions about relational databases using natural language while keeping SQL generation, validation, execution, prompts, connectors, and auditability under control.
+
+For more informacion see https://github.com/pkroliszewski/gaard
+
+# This package
+Package gaard-connectors extends gaard functionality by adding support for various database connection schemes

gaard_connectors-0.1.0/src/gaard_connectors.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/gaard_connectors/__init__.py
+src/gaard_connectors.egg-info/PKG-INFO
+src/gaard_connectors.egg-info/SOURCES.txt
+src/gaard_connectors.egg-info/dependency_links.txt
+src/gaard_connectors.egg-info/requires.txt
+src/gaard_connectors.egg-info/top_level.txt
+src/gaard_connectors/mssql/__init__.py
+src/gaard_connectors/mysql/__init__.py
+src/gaard_connectors/oracle/__init__.py
+src/gaard_connectors/postgres/__init__.py
+src/gaard_connectors/sqlalchemy/__init__.py
+src/gaard_connectors/sqlalchemy/executor.py
+src/gaard_connectors/sqlalchemy/introspector.py
+src/gaard_connectors/sqlite/__init__.py
+tests/test_sqlalchemy_executor_errors.py
+tests/test_sqlalchemy_introspector.py

gaard_connectors-0.1.0/src/gaard_connectors.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gaard_connectors-0.1.0/src/gaard_connectors.egg-info/requires.txt

@@ -0,0 +1,19 @@
+gaard-core==0.1.0
+sqlalchemy>=2.0.0
+
+[dev]
+pytest>=8.0.0
+ruff>=0.5.0
+mypy>=1.10.0
+
+[mssql]
+pyodbc>=5.1.0
+
+[mysql]
+pymysql>=1.1.0
+
+[oracle]
+oracledb>=2.0.0
+
+[postgres]
+psycopg[binary]>=3.2.0

gaard_connectors-0.1.0/src/gaard_connectors.egg-info/top_level.txt

@@ -0,0 +1 @@
+gaard_connectors

gaard_connectors-0.1.0/tests/test_sqlalchemy_executor_errors.py

@@ -0,0 +1,85 @@
+from datetime import date, datetime
+from decimal import Decimal
+from pathlib import Path
+import sqlite3
+
+import pytest
+
+from gaard_connectors.sqlalchemy.executor import SQLAlchemyQueryExecutor
+from gaard_core.errors import QueryExecutionError
+
+
+def test_sqlalchemy_executor_wraps_database_errors(tmp_path: Path) -> None:
+    db_path = tmp_path / "test.db"
+
+    connection = sqlite3.connect(db_path)
+    try:
+        connection.execute("CREATE TABLE patients (id INTEGER PRIMARY KEY)")
+        connection.commit()
+    finally:
+        connection.close()
+
+    executor = SQLAlchemyQueryExecutor(
+        database_url=f"sqlite:///{db_path}",
+        max_rows=100,
+    )
+
+    with pytest.raises(QueryExecutionError):
+        executor.execute("SELECT missing_column FROM patients")
+
+
+def test_sqlalchemy_executor_normalizes_database_values_to_jsonable_rows() -> None:
+    executor = SQLAlchemyQueryExecutor(
+        database_url="sqlite:///:memory:",
+        max_rows=100,
+    )
+
+    row = executor._normalize_row(
+        {
+            "total_minutes": Decimal("42"),
+            "ratio": Decimal("12.5"),
+            "created_on": date(2026, 5, 24),
+            "created_at": datetime(2026, 5, 24, 10, 15, 30),
+            "payload": b"hello",
+            "binary_payload": b"\xff",
+            "nested": {"amount": Decimal("7.25")},
+        }
+    )
+
+    assert row == {
+        "total_minutes": 42,
+        "ratio": 12.5,
+        "created_on": "2026-05-24",
+        "created_at": "2026-05-24T10:15:30",
+        "payload": "hello",
+        "binary_payload": "ff",
+        "nested": {"amount": 7.25},
+    }
+
+
+def test_sqlalchemy_executor_does_not_add_duplicate_limit_with_newline(tmp_path: Path) -> None:
+    db_path = tmp_path / "test.db"
+
+    connection = sqlite3.connect(db_path)
+    try:
+        connection.execute("CREATE TABLE patients (id INTEGER PRIMARY KEY, status TEXT NOT NULL)")
+        connection.execute("INSERT INTO patients (status) VALUES ('active')")
+        connection.commit()
+    finally:
+        connection.close()
+
+    executor = SQLAlchemyQueryExecutor(
+        database_url=f"sqlite:///{db_path}",
+        max_rows=100,
+    )
+
+    result = executor.execute(
+        """
+        SELECT COUNT(*) AS total_active_patients
+        FROM patients
+        WHERE status = 'active'
+        LIMIT 100
+        """
+    )
+
+    assert result.rows == [{"total_active_patients": 1}]

gaard_connectors-0.1.0/tests/test_sqlalchemy_introspector.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+import sqlite3
+
+from gaard_connectors.sqlalchemy.introspector import SQLAlchemySchemaIntrospector
+
+
+def test_sqlalchemy_introspector_reads_tables_columns_and_foreign_keys(tmp_path: Path) -> None:
+    db_path = tmp_path / "test.db"
+
+    connection = sqlite3.connect(db_path)
+    try:
+        connection.executescript(
+            """
+            CREATE TABLE patients (
+                id INTEGER PRIMARY KEY,
+                status TEXT NOT NULL
+            );
+
+            CREATE TABLE appointments (
+                id INTEGER PRIMARY KEY,
+                patient_id INTEGER NOT NULL,
+                status TEXT NOT NULL,
+                FOREIGN KEY (patient_id) REFERENCES patients(id)
+            );
+
+            CREATE VIEW active_patients AS
+            SELECT id, status
+            FROM patients
+            WHERE status = 'active';
+            """
+        )
+        connection.commit()
+    finally:
+        connection.close()
+
+    introspector = SQLAlchemySchemaIntrospector(
+        database_url=f"sqlite:///{db_path}",
+    )
+
+    schema = introspector.introspect()
+
+    table_names = {table.name for table in schema.tables}
+
+    assert "patients" in table_names
+    assert "appointments" in table_names
+    assert "active_patients" in table_names
+
+    patients = next(table for table in schema.tables if table.name == "patients")
+    patient_columns = {column.name for column in patients.columns}
+
+    assert patients.object_type == "table"
+    assert "id" in patient_columns
+    assert "status" in patient_columns
+
+    appointments = next(table for table in schema.tables if table.name == "appointments")
+
+    assert len(appointments.foreign_keys) == 1
+    assert appointments.foreign_keys[0].referred_table == "patients"
+    assert appointments.foreign_keys[0].constrained_columns == ["patient_id"]
+
+    active_patients = next(table for table in schema.tables if table.name == "active_patients")
+    active_patient_columns = {column.name for column in active_patients.columns}
+
+    assert active_patients.object_type == "view"
+    assert active_patient_columns == {"id", "status"}
+    assert active_patients.foreign_keys == []