truthound-dashboard 1.0.0__py3-none-any.whl

truthound_dashboard/__init__.py

@@ -0,0 +1,11 @@
+"""Truthound Dashboard - Open-source data quality dashboard.
+
+A GX Cloud alternative that provides:
+- Data source management
+- Automated schema learning
+- Data validation and profiling
+- Real-time monitoring dashboard
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

truthound_dashboard/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m truthound_dashboard."""
+
+from truthound_dashboard.cli import app
+
+if __name__ == "__main__":
+    app()

truthound_dashboard/api/__init__.py

@@ -0,0 +1,15 @@
+"""API module.
+
+This module contains all API endpoints organized by domain.
+
+Routers:
+    - health: Health and readiness checks
+    - sources: Data source CRUD operations
+    - schemas: Schema learning and management
+    - validations: Validation execution and history
+    - profile: Data profiling
+"""
+
+from .router import api_router
+
+__all__ = ["api_router"]

truthound_dashboard/api/deps.py

@@ -0,0 +1,153 @@
+"""API dependencies for dependency injection.
+
+This module provides FastAPI dependencies for injecting services
+and database sessions into route handlers.
+
+Example:
+    @router.get("/sources")
+    async def list_sources(
+        service: SourceService = Depends(get_source_service)
+    ):
+        return await service.list()
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from typing import Annotated
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from truthound_dashboard.core import (
+    DriftService,
+    HistoryService,
+    ProfileService,
+    RuleService,
+    ScheduleService,
+    SchemaService,
+    SourceService,
+    ValidationService,
+)
+from truthound_dashboard.db import get_db_session
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    """Get database session dependency.
+
+    Yields:
+        AsyncSession for database operations.
+    """
+    async for session in get_db_session():
+        yield session
+
+
+# Type alias for session dependency
+SessionDep = Annotated[AsyncSession, Depends(get_session)]
+
+
+async def get_source_service(session: SessionDep) -> SourceService:
+    """Get source service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        SourceService instance.
+    """
+    return SourceService(session)
+
+
+async def get_validation_service(session: SessionDep) -> ValidationService:
+    """Get validation service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        ValidationService instance.
+    """
+    return ValidationService(session)
+
+
+async def get_schema_service(session: SessionDep) -> SchemaService:
+    """Get schema service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        SchemaService instance.
+    """
+    return SchemaService(session)
+
+
+async def get_profile_service(session: SessionDep) -> ProfileService:
+    """Get profile service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        ProfileService instance.
+    """
+    return ProfileService(session)
+
+
+async def get_rule_service(session: SessionDep) -> RuleService:
+    """Get rule service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        RuleService instance.
+    """
+    return RuleService(session)
+
+
+async def get_history_service(session: SessionDep) -> HistoryService:
+    """Get history service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        HistoryService instance.
+    """
+    return HistoryService(session)
+
+
+async def get_drift_service(session: SessionDep) -> DriftService:
+    """Get drift service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        DriftService instance.
+    """
+    return DriftService(session)
+
+
+async def get_schedule_service(session: SessionDep) -> ScheduleService:
+    """Get schedule service dependency.
+
+    Args:
+        session: Database session.
+
+    Returns:
+        ScheduleService instance.
+    """
+    return ScheduleService(session)
+
+
+# Type aliases for service dependencies
+SourceServiceDep = Annotated[SourceService, Depends(get_source_service)]
+ValidationServiceDep = Annotated[ValidationService, Depends(get_validation_service)]
+SchemaServiceDep = Annotated[SchemaService, Depends(get_schema_service)]
+ProfileServiceDep = Annotated[ProfileService, Depends(get_profile_service)]
+RuleServiceDep = Annotated[RuleService, Depends(get_rule_service)]
+HistoryServiceDep = Annotated[HistoryService, Depends(get_history_service)]
+DriftServiceDep = Annotated[DriftService, Depends(get_drift_service)]
+ScheduleServiceDep = Annotated[ScheduleService, Depends(get_schedule_service)]

truthound_dashboard/api/drift.py

@@ -0,0 +1,179 @@
+"""Drift detection API endpoints.
+
+Provides endpoints for drift comparison between datasets.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from truthound_dashboard.core import DriftService
+from truthound_dashboard.schemas import (
+    DriftCompareRequest,
+    DriftComparisonListResponse,
+)
+
+from .deps import SessionDep
+
+router = APIRouter()
+
+
+async def get_drift_service(session: SessionDep) -> DriftService:
+    """Get drift service dependency."""
+    return DriftService(session)
+
+
+DriftServiceDep = Annotated[DriftService, Depends(get_drift_service)]
+
+
+@router.post(
+    "/drift/compare",
+    response_model=dict,
+    summary="Compare datasets for drift",
+    description="Compare two datasets to detect data drift.",
+)
+async def compare_datasets(
+    request: DriftCompareRequest,
+    service: DriftServiceDep,
+) -> dict:
+    """Compare two datasets for drift detection.
+
+    Args:
+        request: Comparison request with source IDs and options.
+        service: Drift service.
+
+    Returns:
+        Drift comparison results.
+    """
+    try:
+        comparison = await service.compare(
+            baseline_source_id=request.baseline_source_id,
+            current_source_id=request.current_source_id,
+            columns=request.columns,
+            method=request.method,
+            threshold=request.threshold,
+            sample_size=request.sample_size,
+        )
+
+        return {
+            "success": True,
+            "data": {
+                "id": comparison.id,
+                "baseline_source_id": comparison.baseline_source_id,
+                "current_source_id": comparison.current_source_id,
+                "has_drift": comparison.has_drift,
+                "has_high_drift": comparison.has_high_drift,
+                "total_columns": comparison.total_columns,
+                "drifted_columns": comparison.drifted_columns,
+                "drift_percentage": comparison.drift_percentage,
+                "result": comparison.result_json,
+                "config": comparison.config,
+                "created_at": (
+                    comparison.created_at.isoformat() if comparison.created_at else None
+                ),
+            },
+        }
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get(
+    "/drift/comparisons",
+    response_model=DriftComparisonListResponse,
+    summary="List drift comparisons",
+    description="List all drift comparisons with optional filters.",
+)
+async def list_comparisons(
+    service: DriftServiceDep,
+    baseline_source_id: str | None = Query(
+        None, description="Filter by baseline source"
+    ),
+    current_source_id: str | None = Query(None, description="Filter by current source"),
+    limit: int = Query(20, ge=1, le=100, description="Maximum results"),
+) -> DriftComparisonListResponse:
+    """List drift comparisons.
+
+    Args:
+        service: Drift service.
+        baseline_source_id: Optional baseline source ID filter.
+        current_source_id: Optional current source ID filter.
+        limit: Maximum results to return.
+
+    Returns:
+        List of drift comparisons.
+    """
+    comparisons = await service.list_comparisons(
+        baseline_source_id=baseline_source_id,
+        current_source_id=current_source_id,
+        limit=limit,
+    )
+
+    return DriftComparisonListResponse(
+        success=True,
+        data=[
+            {
+                "id": c.id,
+                "baseline_source_id": c.baseline_source_id,
+                "current_source_id": c.current_source_id,
+                "has_drift": c.has_drift,
+                "has_high_drift": c.has_high_drift,
+                "total_columns": c.total_columns,
+                "drifted_columns": c.drifted_columns,
+                "drift_percentage": c.drift_percentage,
+                "created_at": c.created_at.isoformat() if c.created_at else None,
+                "updated_at": c.updated_at.isoformat() if c.updated_at else None,
+            }
+            for c in comparisons
+        ],
+        total=len(comparisons),
+    )
+
+
+@router.get(
+    "/drift/comparisons/{comparison_id}",
+    response_model=dict,
+    summary="Get drift comparison",
+    description="Get a specific drift comparison by ID.",
+)
+async def get_comparison(
+    comparison_id: str,
+    service: DriftServiceDep,
+) -> dict:
+    """Get a drift comparison by ID.
+
+    Args:
+        comparison_id: Comparison ID.
+        service: Drift service.
+
+    Returns:
+        Drift comparison details.
+    """
+    comparison = await service.get_comparison(comparison_id)
+    if comparison is None:
+        raise HTTPException(status_code=404, detail="Comparison not found")
+
+    return {
+        "success": True,
+        "data": {
+            "id": comparison.id,
+            "baseline_source_id": comparison.baseline_source_id,
+            "current_source_id": comparison.current_source_id,
+            "has_drift": comparison.has_drift,
+            "has_high_drift": comparison.has_high_drift,
+            "total_columns": comparison.total_columns,
+            "drifted_columns": comparison.drifted_columns,
+            "drift_percentage": comparison.drift_percentage,
+            "result": comparison.result_json,
+            "config": comparison.config,
+            "created_at": (
+                comparison.created_at.isoformat() if comparison.created_at else None
+            ),
+            "updated_at": (
+                comparison.updated_at.isoformat() if comparison.updated_at else None
+            ),
+        },
+    }

truthound_dashboard/api/error_handlers.py

@@ -0,0 +1,287 @@
+"""Global error handlers for FastAPI application.
+
+This module provides centralized error handling with consistent
+response formats and proper logging.
+
+Features:
+- Maps custom exceptions to HTTP responses
+- Handles unexpected errors gracefully
+- Provides consistent error response format
+- Logs errors appropriately
+
+Example:
+    from truthound_dashboard.api.error_handlers import setup_error_handlers
+
+    app = FastAPI()
+    setup_error_handlers(app)
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError as PydanticValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from truthound_dashboard.core.exceptions import (
+    ErrorCode,
+    TruthoundDashboardError,
+    get_error_message,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def create_error_response(
+    code: str,
+    message: str,
+    details: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Create standardized error response.
+
+    Args:
+        code: Error code string.
+        message: Human-readable error message.
+        details: Additional error details.
+
+    Returns:
+        Dictionary suitable for JSON response.
+    """
+    response = {
+        "success": False,
+        "error": {
+            "code": code,
+            "message": message,
+        },
+    }
+    if details:
+        response["error"]["details"] = details
+    return response
+
+
+def setup_error_handlers(app: FastAPI) -> None:
+    """Configure global error handlers for FastAPI application.
+
+    Registers handlers for:
+    - TruthoundDashboardError and subclasses
+    - Pydantic validation errors
+    - FastAPI request validation errors
+    - Starlette HTTP exceptions
+    - Generic exceptions (catch-all)
+
+    Args:
+        app: FastAPI application instance.
+    """
+
+    @app.exception_handler(TruthoundDashboardError)
+    async def handle_dashboard_error(
+        request: Request,
+        exc: TruthoundDashboardError,
+    ) -> JSONResponse:
+        """Handle custom dashboard exceptions.
+
+        Logs the error and returns a structured response.
+        """
+        # Log at appropriate level based on HTTP status
+        if exc.http_status >= 500:
+            logger.error(
+                f"Dashboard error: {exc.code.value} - {exc.message}",
+                extra={"details": exc.details, "path": request.url.path},
+            )
+        else:
+            logger.warning(
+                f"Dashboard error: {exc.code.value} - {exc.message}",
+                extra={"details": exc.details, "path": request.url.path},
+            )
+
+        return JSONResponse(
+            status_code=exc.http_status,
+            content=exc.to_response(),
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def handle_request_validation_error(
+        request: Request,
+        exc: RequestValidationError,
+    ) -> JSONResponse:
+        """Handle FastAPI request validation errors.
+
+        Converts Pydantic validation errors to user-friendly format.
+        """
+        errors = []
+        for error in exc.errors():
+            location = ".".join(str(loc) for loc in error["loc"])
+            errors.append({
+                "field": location,
+                "message": error["msg"],
+                "type": error["type"],
+            })
+
+        logger.warning(
+            f"Request validation error: {request.url.path}",
+            extra={"errors": errors},
+        )
+
+        return JSONResponse(
+            status_code=422,
+            content=create_error_response(
+                code=ErrorCode.VALIDATION_ERROR.value,
+                message="Request validation failed",
+                details={"validation_errors": errors},
+            ),
+        )
+
+    @app.exception_handler(PydanticValidationError)
+    async def handle_pydantic_validation_error(
+        request: Request,
+        exc: PydanticValidationError,
+    ) -> JSONResponse:
+        """Handle Pydantic validation errors."""
+        errors = []
+        for error in exc.errors():
+            location = ".".join(str(loc) for loc in error["loc"])
+            errors.append({
+                "field": location,
+                "message": error["msg"],
+                "type": error["type"],
+            })
+
+        logger.warning(
+            f"Pydantic validation error: {request.url.path}",
+            extra={"errors": errors},
+        )
+
+        return JSONResponse(
+            status_code=422,
+            content=create_error_response(
+                code=ErrorCode.VALIDATION_ERROR.value,
+                message="Data validation failed",
+                details={"validation_errors": errors},
+            ),
+        )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def handle_http_exception(
+        request: Request,
+        exc: StarletteHTTPException,
+    ) -> JSONResponse:
+        """Handle Starlette HTTP exceptions."""
+        # Map common HTTP status codes to error codes
+        status_code_map = {
+            400: ErrorCode.VALIDATION_ERROR,
+            401: ErrorCode.AUTHENTICATION_REQUIRED,
+            403: ErrorCode.AUTHORIZATION_FAILED,
+            404: ErrorCode.SOURCE_NOT_FOUND,
+            429: ErrorCode.RATE_LIMIT_EXCEEDED,
+            500: ErrorCode.INTERNAL_ERROR,
+            502: ErrorCode.SOURCE_CONNECTION_FAILED,
+            503: ErrorCode.DATABASE_CONNECTION_FAILED,
+        }
+
+        error_code = status_code_map.get(exc.status_code, ErrorCode.UNKNOWN_ERROR)
+        message = str(exc.detail) if exc.detail else get_error_message(error_code)
+
+        if exc.status_code >= 500:
+            logger.error(
+                f"HTTP error {exc.status_code}: {message}",
+                extra={"path": request.url.path},
+            )
+        else:
+            logger.warning(
+                f"HTTP error {exc.status_code}: {message}",
+                extra={"path": request.url.path},
+            )
+
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=create_error_response(
+                code=error_code.value,
+                message=message,
+            ),
+        )
+
+    @app.exception_handler(ValueError)
+    async def handle_value_error(
+        request: Request,
+        exc: ValueError,
+    ) -> JSONResponse:
+        """Handle ValueError as 400 Bad Request."""
+        logger.warning(
+            f"ValueError: {exc}",
+            extra={"path": request.url.path},
+        )
+
+        return JSONResponse(
+            status_code=400,
+            content=create_error_response(
+                code=ErrorCode.VALIDATION_ERROR.value,
+                message=str(exc),
+            ),
+        )
+
+    @app.exception_handler(FileNotFoundError)
+    async def handle_file_not_found_error(
+        request: Request,
+        exc: FileNotFoundError,
+    ) -> JSONResponse:
+        """Handle FileNotFoundError as 404 Not Found."""
+        logger.warning(
+            f"FileNotFoundError: {exc}",
+            extra={"path": request.url.path},
+        )
+
+        return JSONResponse(
+            status_code=404,
+            content=create_error_response(
+                code=ErrorCode.SOURCE_NOT_FOUND.value,
+                message=str(exc),
+            ),
+        )
+
+    @app.exception_handler(PermissionError)
+    async def handle_permission_error(
+        request: Request,
+        exc: PermissionError,
+    ) -> JSONResponse:
+        """Handle PermissionError as 403 Forbidden."""
+        logger.warning(
+            f"PermissionError: {exc}",
+            extra={"path": request.url.path},
+        )
+
+        return JSONResponse(
+            status_code=403,
+            content=create_error_response(
+                code=ErrorCode.SOURCE_ACCESS_DENIED.value,
+                message="Access denied to the requested resource",
+            ),
+        )
+
+    @app.exception_handler(Exception)
+    async def handle_generic_exception(
+        request: Request,
+        exc: Exception,
+    ) -> JSONResponse:
+        """Handle unexpected exceptions.
+
+        Logs the full traceback but returns a safe error message
+        to avoid exposing internal details.
+        """
+        logger.error(
+            f"Unexpected error: {type(exc).__name__}: {exc}\n"
+            f"{traceback.format_exc()}",
+            extra={"path": request.url.path},
+        )
+
+        return JSONResponse(
+            status_code=500,
+            content=create_error_response(
+                code=ErrorCode.INTERNAL_ERROR.value,
+                message=get_error_message(ErrorCode.INTERNAL_ERROR),
+            ),
+        )