gaard-api 0.1.0__py3-none-any.whl

gaard_api/api/v1/schema.py

@@ -0,0 +1,60 @@
+from fastapi import APIRouter
+
+from gaard_connectors.sqlalchemy.introspector import SQLAlchemySchemaIntrospector
+from gaard_core.schema.context import SchemaContextService
+from gaard_core.schema.models import DatabaseSchema
+
+from gaard_api.admin.services import (
+    get_datasource_schema_context_safe,
+    selected_schema_from_cache,
+)
+from gaard_api.core.schema_cache import schema_context_cache
+from gaard_api.core.settings import settings
+
+router = APIRouter()
+
+
+def get_schema_cache_key(database_url: str | None = None, sql_dialect: str | None = None) -> str:
+    return (
+        f"{sql_dialect or settings.gaard_sql_dialect}:"
+        f"{database_url or settings.gaard_datasource_url}"
+    )
+
+
+@router.get("/schema", response_model=DatabaseSchema)
+def get_schema() -> DatabaseSchema:
+    datasource_context = get_datasource_schema_context_safe()
+
+    if datasource_context is not None:
+        _connector, schema_cache = datasource_context
+        return selected_schema_from_cache(schema_cache)
+
+    introspector = SQLAlchemySchemaIntrospector(
+        database_url=settings.gaard_datasource_url,
+    )
+
+    service = SchemaContextService(
+        introspector=introspector,
+        cache=schema_context_cache,
+    )
+
+    context = service.get_schema_context(get_schema_cache_key())
+
+    return context.database_schema
+
+
+@router.delete("/schema/cache")
+def invalidate_schema_cache() -> dict[str, str]:
+    datasource_context = get_datasource_schema_context_safe()
+
+    if datasource_context is not None:
+        connector, _schema_cache = datasource_context
+        schema_context_cache.invalidate(
+            get_schema_cache_key(connector.database_url, connector.sql_dialect)
+        )
+    else:
+        schema_context_cache.invalidate(get_schema_cache_key())
+
+    return {
+        "status": "invalidated",
+    }

gaard_api/cli.py

@@ -0,0 +1,19 @@
+import argparse
+from importlib.metadata import entry_points
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="gaard")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    commands = {}
+
+    for ep in entry_points(group="gaard.commands"):
+        command_func = ep.load()
+        commands[ep.name] = command_func
+        command_func(subparsers)
+
+    args = parser.parse_args()
+
+    if args.command in commands:
+        args.func(args)

gaard_api/cli_commands.py

@@ -0,0 +1,18 @@
+import uvicorn
+
+
+def register(subparsers):
+    parser = subparsers.add_parser("admin")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--reload", action="store_true")
+    parser.set_defaults(func=run_admin)
+
+
+def run_admin(args):
+    uvicorn.run(
+        "gaard_api.main:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )

gaard_api/core/error_handlers.py

@@ -0,0 +1,18 @@
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from gaard_core.errors import GaardError
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    @app.exception_handler(GaardError)
+    async def handle_gaard_error(request: Request, exc: GaardError) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": {
+                    "code": exc.code,
+                    "message": exc.message,
+                }
+            },
+        )

gaard_api/core/schema_cache.py

@@ -0,0 +1,7 @@
+from gaard_core.schema.cache import SchemaContextCache
+
+from gaard_api.core.settings import settings
+
+schema_context_cache = SchemaContextCache(
+    ttl_seconds=settings.gaard_schema_cache_ttl_seconds,
+)

gaard_api/core/settings.py

@@ -0,0 +1,103 @@
+from dataclasses import dataclass, field
+import json
+import os
+from typing import Any
+
+
+def env_value(name: str, default: str) -> str:
+    return os.environ.get(name, default)
+
+
+def env_int_value(name: str, default: int) -> int:
+    value = os.environ.get(name)
+
+    if value is None:
+        return default
+
+    try:
+        return int(value)
+    except ValueError:
+        return default
+
+
+def env_dict_value(name: str, default: dict[str, Any]) -> dict[str, Any]:
+    value = os.environ.get(name)
+
+    if value is None:
+        return dict(default)
+
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError:
+        return dict(default)
+
+    return parsed if isinstance(parsed, dict) else dict(default)
+
+
+@dataclass
+class Settings:
+    gaard_metadata_database_url: str = "sqlite:///./metadata.db"
+    gaard_datasource_url: str = field(
+        default_factory=lambda: env_value(
+            "GAARD_DATASOURCE_URL",
+            "sqlite:///./examples/medical-poc/demo.db",
+        )
+    )
+    gaard_query_max_rows: int = field(
+        default_factory=lambda: env_int_value("GAARD_QUERY_MAX_ROWS", 100)
+    )
+    gaard_query_timeout_seconds: int = field(
+        default_factory=lambda: env_int_value("GAARD_QUERY_TIMEOUT_SECONDS", 30)
+    )
+
+    gaard_schema_cache_ttl_seconds: int = field(
+        default_factory=lambda: env_int_value("GAARD_SCHEMA_CACHE_TTL_SECONDS", 300)
+    )
+    gaard_audit_retention_days: int = field(
+        default_factory=lambda: env_int_value("GAARD_AUDIT_RETENTION_DAYS", 90)
+    )
+
+    gaard_intent_classification_mode: str = field(
+        default_factory=lambda: env_value("GAARD_INTENT_CLASSIFICATION_MODE", "auto")
+    )
+    gaard_sql_generation_mode: str = field(
+        default_factory=lambda: env_value("GAARD_SQL_GENERATION_MODE", "llm")
+    )
+    gaard_result_interpretation_mode: str = field(
+        default_factory=lambda: env_value("GAARD_RESULT_INTERPRETATION_MODE", "llm")
+    )
+    gaard_output_classification_mode: str = field(
+        default_factory=lambda: env_value("GAARD_OUTPUT_CLASSIFICATION_MODE", "auto")
+    )
+    gaard_investigation_mode: str = field(
+        default_factory=lambda: env_value("GAARD_INVESTIGATION_MODE", "llm")
+    )
+    gaard_investigation_ambiguity_mode: str = field(
+        default_factory=lambda: env_value("GAARD_INVESTIGATION_AMBIGUITY_MODE", "clarify")
+    )
+
+    gaard_llm_provider: str = field(
+        default_factory=lambda: env_value("GAARD_LLM_PROVIDER", "openai-compatible")
+    )
+    gaard_llm_base_url: str = field(
+        default_factory=lambda: env_value("GAARD_LLM_BASE_URL", "https://api.openai.com/v1")
+    )
+    gaard_llm_api_key: str = field(
+        default_factory=lambda: env_value("GAARD_LLM_API_KEY", "change-me")
+    )
+    gaard_llm_model: str = field(
+        default_factory=lambda: env_value("GAARD_LLM_MODEL", "gpt-4.1-mini")
+    )
+    gaard_llm_extra_body: dict[str, Any] = field(
+        default_factory=lambda: env_dict_value("GAARD_LLM_EXTRA_BODY", {})
+    )
+    gaard_llm_timeout_seconds: int = field(
+        default_factory=lambda: env_int_value("GAARD_LLM_TIMEOUT_SECONDS", 60)
+    )
+
+    gaard_sql_dialect: str = field(
+        default_factory=lambda: env_value("GAARD_SQL_DIALECT", "sqlite")
+    )
+
+
+settings = Settings()

gaard_api/main.py

@@ -0,0 +1,53 @@
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from gaard_api.api.v1.admin import router as admin_router
+from gaard_api.api.v1.prompts import router as prompts_router
+from gaard_api.api.v1.query import router as query_router
+from gaard_api.api.v1.schema import router as schema_router
+from gaard_api.core.error_handlers import register_error_handlers
+from importlib.resources import files
+
+app = FastAPI(
+    title="GAARD API",
+    version="0.1.0",
+    description="Self-hosted AI SQL Gateway for governed natural-language access to relational data.",
+)
+
+register_error_handlers(app)
+
+ADMIN_WEB_DIR = files("gaard_api").joinpath("admin-web")
+
+if ADMIN_WEB_DIR.exists():
+    app.mount(
+        "/admin/assets",
+        StaticFiles(directory=ADMIN_WEB_DIR / "assets"),
+        name="admin-assets",
+    )
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/api/v1/health")
+def api_health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+app.include_router(query_router, prefix="/api/v1", tags=["query"])
+app.include_router(schema_router, prefix="/api/v1", tags=["schema"])
+app.include_router(prompts_router, prefix="/api/v1", tags=["prompts"])
+app.include_router(admin_router, prefix="/api/v1/admin", tags=["admin"])
+
+
+@app.get("/admin", include_in_schema=False)
+def admin_index() -> FileResponse:
+    return FileResponse(ADMIN_WEB_DIR / "index.html")
+
+
+@app.get("/admin/{path:path}", include_in_schema=False)
+def admin_spa(path: str) -> FileResponse:
+    return FileResponse(ADMIN_WEB_DIR / "index.html")

gaard_api/server_cli.py

@@ -0,0 +1,25 @@
+import argparse
+from collections.abc import Sequence
+
+from gaard_api.cli_commands import run_admin
+
+
+def create_parser(prog: str | None = None) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        description="Run the GAARD API and admin application.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    start_parser = subparsers.add_parser("start", help="Start the API server.")
+    start_parser.add_argument("--host", default="127.0.0.1")
+    start_parser.add_argument("--port", type=int, default=8000)
+    start_parser.add_argument("--reload", action="store_true")
+    start_parser.set_defaults(func=run_admin)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    args = create_parser().parse_args(argv)
+    args.func(args)

gaard_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: gaard-api
+Version: 0.1.0
+Summary: GAARD backend web services providing admin interface
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: gaard-core==0.1.0
+Requires-Dist: gaard-connectors==0.1.0
+Requires-Dist: gaard-llm==0.1.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: httpx>=0.27.0
+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"
+Requires-Dist: psycopg[binary]>=3.2.0; extra == "dev"
+Requires-Dist: pymysql>=1.2.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
+
+`gaard-api` provides the GAARD FastAPI backend and bundled admin application.
+
+After installation, start it with:
+
+```bash
+gaard-core start
+```
+
+The command accepts `--host`, `--port`, and `--reload`. By default the API is
+available at `http://localhost:8000` and the admin application at
+`http://localhost:8000/admin`.
+
+`gaard-api start` is an alias. `gaard admin` remains available for compatibility.

gaard_api-0.1.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+gaard_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gaard_api/cli.py,sha256=ygIcIdT2kb4bU7cuabViaGmYFiIQHk9MljFTu_oJt2Q,471
+gaard_api/cli_commands.py,sha256=mXwE7zSN4nqd6XvT3lu2h3xw7AC3myDrAGfzZB7rO7s,449
+gaard_api/main.py,sha256=JFsv6ZIiRaZRPEMfMtWTjG_CRpSYIGzoLq53OdEVum0,1617
+gaard_api/server_cli.py,sha256=YHwostkBN51MqxkFamjcukfTYhNiNbvwrlhC_fnXmlU,822
+gaard_api/admin/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+gaard_api/admin/database.py,sha256=cWQoPku5D8sP3pakUNorPIO7mTThofuuTluC3QMAo4w,17087
+gaard_api/admin/defaults.py,sha256=V5E27anqHhXvsclqL65ddq8q6R9RuVEg5lhetot-5Mc,11112
+gaard_api/admin/models.py,sha256=WBJPEixHn9CvacDphpWcFEM27Ux33N3M5oBto35Nkm4,10281
+gaard_api/admin/prompt_runtime.py,sha256=RQz-h8eFKoUXkq7ymN6cG4F2N6HF9LZYAmmcywycSo8,8476
+gaard_api/admin/security.py,sha256=4reNbtO7aNmf_5j6cuARirzAT0TSzqbCeOpRgE8WRAw,1030
+gaard_api/admin/services.py,sha256=0yEVcL1RS5ZWPMZN1d8q5UdL_jnIw5jXIqrEopYOlBM,68720
+gaard_api/admin-web/index.html,sha256=VNt4pS4u85BHM3-U8PAyGUmlYI-uiRg7kSlZhl-Zb-I,373
+gaard_api/admin-web/assets/main.js,sha256=zb5VQiXDSaUOmSZ7Clhb2Wgn4caPyd6rb0O3kzzWPhQ,93625
+gaard_api/admin-web/assets/styles.css,sha256=92iCON8Vsd2MU7leyKG1uC7PSt_4MeiW8t7X1JV_ehM,15984
+gaard_api/admin-web/src/main.ts,sha256=p7sesHn8egEYvGUvcjc4S8X9P5afhP28zGv4tubZi60,95982
+gaard_api/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gaard_api/api/v1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gaard_api/api/v1/admin.py,sha256=uSCY5v8TUX4qAQeV9rhaRrIonkjuq749kNhIChgyINk,67950
+gaard_api/api/v1/prompts.py,sha256=BCdv-5yuQIIMmIo9_JWxsXUSN2JOB4RmkCFQov5g-Q4,2153
+gaard_api/api/v1/query.py,sha256=V_erMKxQucN1JTle4wXG60UrgpxaJXuhJL8RWOyR4aQ,39045
+gaard_api/api/v1/schema.py,sha256=cJ5JxapZtXCfp_AUzviO8EGRPoCfuLrRdOr4zTAjZL4,1825
+gaard_api/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gaard_api/core/error_handlers.py,sha256=FM_6rETSeGqJSH3n9i_ozbvgUdptMDtdKRWOAaQyVlY,542
+gaard_api/core/schema_cache.py,sha256=Ho1JFciVUltNeu9FaFeEp9Z2lc51YKl1MwutEWECNwY,203
+gaard_api/core/settings.py,sha256=jO8hNptzivUOxaFtr6oi4zEPXVrPvAKv9Lq535OUjzs,3266
+gaard_api/dependencies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gaard_api/schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gaard_api/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gaard_api-0.1.0.dist-info/METADATA,sha256=zhyABdJtSlLcERSryIXuzee-a0AQKBCfsw6ddILprmQ,1541
+gaard_api-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gaard_api-0.1.0.dist-info/entry_points.txt,sha256=5k8GFr1LdALDBBf42i2VgxyHJ2Gkml8qU8TtsZRQAkE,180
+gaard_api-0.1.0.dist-info/top_level.txt,sha256=5g2-WOFGbK-SoVjsJniCaQH1bwSHF6SWPJVYNH4bjfc,10
+gaard_api-0.1.0.dist-info/RECORD,,

gaard_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gaard_api-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,7 @@
+[console_scripts]
+gaard = gaard_api.cli:main
+gaard-api = gaard_api.server_cli:main
+gaard-core = gaard_api.server_cli:main
+
+[gaard.commands]
+admin = gaard_api.cli_commands:register

gaard_api-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gaard_api