truthound-dashboard 1.0.0__py3-none-any.whl

truthound_dashboard/config.py

@@ -0,0 +1,132 @@
+"""Configuration settings with validation and extensibility.
+
+This module provides a centralized configuration management system using
+pydantic-settings for type-safe environment variable handling.
+
+Example:
+    # Get settings singleton
+    settings = get_settings()
+
+    # Access configuration
+    print(settings.database_path)
+
+    # Override via environment variables
+    # TRUTHOUND_DATA_DIR=/custom/path
+    # TRUTHOUND_PORT=9000
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Dashboard configuration settings.
+
+    All settings can be overridden via environment variables with
+    the TRUTHOUND_ prefix.
+
+    Attributes:
+        data_dir: Directory for storing database and cache files.
+        host: Server host address.
+        port: Server port number.
+        log_level: Logging verbosity level.
+        auth_enabled: Whether authentication is required.
+        auth_password: Password for basic auth (if enabled).
+        sample_size: Default sample size for validation.
+        max_failed_rows: Maximum failed rows to store.
+        default_timeout: Default timeout for operations in seconds.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="TRUTHOUND_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Data storage
+    data_dir: Path = Field(
+        default_factory=lambda: Path.home() / ".truthound",
+        description="Directory for database and cache files",
+    )
+
+    # Server configuration
+    host: str = Field(default="127.0.0.1", description="Server host address")
+    port: int = Field(default=8765, ge=1, le=65535, description="Server port")
+    log_level: Literal["debug", "info", "warning", "error"] = Field(
+        default="info", description="Logging level"
+    )
+
+    # Authentication (optional)
+    auth_enabled: bool = Field(default=False, description="Enable authentication")
+    auth_password: str | None = Field(
+        default=None, description="Password for basic auth"
+    )
+
+    # Validation defaults
+    sample_size: int = Field(
+        default=10000, ge=100, description="Default sample size for validation"
+    )
+    max_failed_rows: int = Field(
+        default=1000, ge=10, description="Maximum failed rows to store"
+    )
+    default_timeout: int = Field(
+        default=300, ge=10, description="Default operation timeout in seconds"
+    )
+
+    # Worker configuration
+    max_workers: int = Field(
+        default=4, ge=1, le=32, description="Maximum worker threads"
+    )
+
+    @field_validator("data_dir", mode="before")
+    @classmethod
+    def expand_data_dir(cls, v: str | Path) -> Path:
+        """Expand user home directory and resolve path."""
+        return Path(v).expanduser().resolve()
+
+    @property
+    def database_path(self) -> Path:
+        """Get SQLite database file path."""
+        return self.data_dir / "dashboard.db"
+
+    @property
+    def cache_dir(self) -> Path:
+        """Get cache directory path."""
+        return self.data_dir / "cache"
+
+    @property
+    def schema_dir(self) -> Path:
+        """Get schema storage directory path."""
+        return self.data_dir / "schemas"
+
+    def ensure_directories(self) -> None:
+        """Create all required directories if they don't exist."""
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.schema_dir.mkdir(parents=True, exist_ok=True)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings singleton.
+
+    Returns:
+        Settings: The application settings instance.
+
+    Note:
+        This function is cached, so the settings are only loaded once.
+        To reload settings, clear the cache with get_settings.cache_clear().
+    """
+    return Settings()
+
+
+def reset_settings() -> None:
+    """Reset settings cache for testing purposes."""
+    get_settings.cache_clear()

truthound_dashboard/core/__init__.py

@@ -0,0 +1,264 @@
+"""Core business logic module.
+
+This module contains the core business logic for the dashboard,
+including services, adapters, and domain models.
+
+Exports:
+    - Adapter: TruthoundAdapter, get_adapter
+    - Services: SourceService, ValidationService, SchemaService, RuleService, ProfileService,
+                HistoryService, DriftService, ScheduleService
+    - Result types: CheckResult, LearnResult, ProfileResult, CompareResult
+    - Scheduler: ValidationScheduler, get_scheduler, start_scheduler, stop_scheduler
+    - Notifications: NotificationDispatcher, create_dispatcher, get_dispatcher
+    - Cache: CacheBackend, MemoryCache, FileCache, get_cache, get_cache_manager
+    - Maintenance: MaintenanceManager, get_maintenance_manager, cleanup_old_validations
+    - Sampling: DataSampler, SamplingStrategy, get_sampler (Large Dataset Handling)
+    - Exceptions: TruthoundDashboardError, SourceNotFoundError, ValidationError, etc.
+    - Encryption: encrypt_value, decrypt_value, encrypt_config, decrypt_config
+    - Logging: setup_logging, get_logger, get_audit_logger
+"""
+
+from .base import BaseService, CRUDService
+from .cache import (
+    CacheBackend,
+    CacheManager,
+    FileCache,
+    MemoryCache,
+    get_cache,
+    get_cache_manager,
+    reset_cache,
+)
+from .encryption import (
+    EncryptionError,
+    Encryptor,
+    decrypt_config,
+    decrypt_value,
+    encrypt_config,
+    encrypt_value,
+    get_encryptor,
+    is_sensitive_field,
+    mask_sensitive_value,
+)
+from .exceptions import (
+    AuthenticationFailedError,
+    AuthenticationRequiredError,
+    AuthorizationError,
+    DatabaseConnectionError,
+    DatabaseError,
+    DatabaseIntegrityError,
+    ErrorCode,
+    NotificationChannelNotFoundError,
+    NotificationError,
+    NotificationInvalidConfigError,
+    NotificationRuleNotFoundError,
+    NotificationSendError,
+    RateLimitExceededError,
+    RuleError,
+    RuleInvalidError,
+    RuleNotFoundError,
+    RuleParseError,
+    ScheduleConflictError,
+    ScheduleError,
+    ScheduleInvalidCronError,
+    ScheduleNotFoundError,
+    SchemaError,
+    SchemaInvalidError,
+    SchemaNotFoundError,
+    SchemaParseError,
+    SecurityError,
+    SourceAccessDeniedError,
+    SourceConnectionError,
+    SourceError,
+    SourceInvalidConfigError,
+    SourceNotFoundError,
+    TruthoundDashboardError,
+    ValidationError,
+    ValidationFailedError,
+    ValidationNotFoundError,
+    ValidationTimeoutError,
+    get_error_message,
+)
+from .logging import (
+    AuditLogger,
+    LogConfig,
+    LoggerAdapter,
+    get_audit_logger,
+    get_logger,
+    setup_logging,
+)
+from .maintenance import (
+    CleanupResult,
+    CleanupStrategy,
+    MaintenanceConfig,
+    MaintenanceManager,
+    MaintenanceReport,
+    cleanup_notification_logs,
+    cleanup_old_profiles,
+    cleanup_old_validations,
+    get_maintenance_manager,
+    reset_maintenance_manager,
+    vacuum_database,
+)
+from .notifications import (
+    NotificationDispatcher,
+    create_dispatcher,
+    get_dispatcher,
+)
+from .sampling import (
+    DataSampler,
+    HeadSamplingStrategy,
+    RandomSamplingStrategy,
+    SamplingConfig,
+    SamplingMethod,
+    SamplingResult,
+    SamplingStrategy,
+    StratifiedSamplingStrategy,
+    TailSamplingStrategy,
+    get_sampler,
+    reset_sampler,
+)
+from .scheduler import (
+    ValidationScheduler,
+    get_scheduler,
+    start_scheduler,
+    stop_scheduler,
+)
+from .services import (
+    DriftService,
+    HistoryService,
+    ProfileService,
+    RuleService,
+    ScheduleService,
+    SchemaService,
+    SourceService,
+    ValidationService,
+)
+from .truthound_adapter import (
+    CheckResult,
+    CompareResult,
+    LearnResult,
+    ProfileResult,
+    TruthoundAdapter,
+    get_adapter,
+    reset_adapter,
+)
+
+__all__ = [
+    # Base classes
+    "BaseService",
+    "CRUDService",
+    # Services
+    "SourceService",
+    "ValidationService",
+    "SchemaService",
+    "RuleService",
+    "ProfileService",
+    "HistoryService",
+    "DriftService",
+    "ScheduleService",
+    # Adapter
+    "TruthoundAdapter",
+    "get_adapter",
+    "reset_adapter",
+    # Result types
+    "CheckResult",
+    "LearnResult",
+    "ProfileResult",
+    "CompareResult",
+    # Scheduler
+    "ValidationScheduler",
+    "get_scheduler",
+    "start_scheduler",
+    "stop_scheduler",
+    # Notifications
+    "NotificationDispatcher",
+    "create_dispatcher",
+    "get_dispatcher",
+    # Cache (Phase 4)
+    "CacheBackend",
+    "MemoryCache",
+    "FileCache",
+    "CacheManager",
+    "get_cache",
+    "get_cache_manager",
+    "reset_cache",
+    # Maintenance (Phase 4)
+    "MaintenanceManager",
+    "MaintenanceConfig",
+    "MaintenanceReport",
+    "CleanupResult",
+    "CleanupStrategy",
+    "get_maintenance_manager",
+    "reset_maintenance_manager",
+    "cleanup_old_validations",
+    "cleanup_old_profiles",
+    "cleanup_notification_logs",
+    "vacuum_database",
+    # Exceptions (Phase 4)
+    "TruthoundDashboardError",
+    "ErrorCode",
+    "get_error_message",
+    "SourceError",
+    "SourceNotFoundError",
+    "SourceConnectionError",
+    "SourceInvalidConfigError",
+    "SourceAccessDeniedError",
+    "SchemaError",
+    "SchemaNotFoundError",
+    "SchemaInvalidError",
+    "SchemaParseError",
+    "RuleError",
+    "RuleNotFoundError",
+    "RuleInvalidError",
+    "RuleParseError",
+    "ValidationError",
+    "ValidationNotFoundError",
+    "ValidationFailedError",
+    "ValidationTimeoutError",
+    "ScheduleError",
+    "ScheduleNotFoundError",
+    "ScheduleInvalidCronError",
+    "ScheduleConflictError",
+    "NotificationError",
+    "NotificationChannelNotFoundError",
+    "NotificationRuleNotFoundError",
+    "NotificationSendError",
+    "NotificationInvalidConfigError",
+    "SecurityError",
+    "AuthenticationRequiredError",
+    "AuthenticationFailedError",
+    "AuthorizationError",
+    "RateLimitExceededError",
+    "DatabaseError",
+    "DatabaseConnectionError",
+    "DatabaseIntegrityError",
+    # Encryption (Phase 4)
+    "Encryptor",
+    "EncryptionError",
+    "get_encryptor",
+    "encrypt_value",
+    "decrypt_value",
+    "encrypt_config",
+    "decrypt_config",
+    "is_sensitive_field",
+    "mask_sensitive_value",
+    # Logging (Phase 4)
+    "LogConfig",
+    "LoggerAdapter",
+    "AuditLogger",
+    "setup_logging",
+    "get_logger",
+    "get_audit_logger",
+    # Sampling (Phase 4 - Large Dataset Handling)
+    "DataSampler",
+    "SamplingConfig",
+    "SamplingMethod",
+    "SamplingResult",
+    "SamplingStrategy",
+    "RandomSamplingStrategy",
+    "HeadSamplingStrategy",
+    "TailSamplingStrategy",
+    "StratifiedSamplingStrategy",
+    "get_sampler",
+    "reset_sampler",
+]

truthound_dashboard/core/base.py

@@ -0,0 +1,185 @@
+"""Base classes for core services.
+
+This module provides abstract base classes and protocols for
+implementing core business logic services with consistent patterns.
+
+The service pattern separates business logic from API handlers,
+enabling better testability and reusability.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from truthound_dashboard.db.repository import BaseRepository
+
+# Type variables
+ModelT = TypeVar("ModelT")
+CreateSchemaT = TypeVar("CreateSchemaT")
+UpdateSchemaT = TypeVar("UpdateSchemaT")
+ResponseSchemaT = TypeVar("ResponseSchemaT")
+
+
+class BaseService(ABC, Generic[ModelT]):
+    """Abstract base class for services.
+
+    Services encapsulate business logic and orchestrate
+    operations between repositories and external systems.
+
+    Type Parameters:
+        ModelT: The model type this service manages.
+    """
+
+    def __init__(self, session: AsyncSession) -> None:
+        """Initialize service with database session.
+
+        Args:
+            session: Async database session.
+        """
+        self.session = session
+
+    @abstractmethod
+    async def get_by_id(self, id: str) -> ModelT | None:
+        """Get entity by ID."""
+        ...
+
+    @abstractmethod
+    async def list(self, *, offset: int = 0, limit: int = 100) -> list[ModelT]:
+        """List entities with pagination."""
+        ...
+
+
+class CRUDService(BaseService[ModelT], Generic[ModelT, CreateSchemaT, UpdateSchemaT]):
+    """Base service with full CRUD operations.
+
+    Extends BaseService with create, update, and delete operations.
+
+    Type Parameters:
+        ModelT: The model type.
+        CreateSchemaT: Pydantic schema for creation.
+        UpdateSchemaT: Pydantic schema for updates.
+    """
+
+    repository_class: type[BaseRepository[ModelT]]
+
+    def __init__(self, session: AsyncSession) -> None:
+        super().__init__(session)
+        self.repository = self.repository_class(session)
+
+    async def get_by_id(self, id: str) -> ModelT | None:
+        """Get entity by ID.
+
+        Args:
+            id: Entity's unique identifier.
+
+        Returns:
+            Model instance or None if not found.
+        """
+        return await self.repository.get_by_id(id)
+
+    async def list(
+        self,
+        *,
+        offset: int = 0,
+        limit: int = 100,
+        **filters: Any,
+    ) -> list[ModelT]:
+        """List entities with pagination and filtering.
+
+        Args:
+            offset: Number of records to skip.
+            limit: Maximum records to return.
+            **filters: Additional filter criteria.
+
+        Returns:
+            List of model instances.
+        """
+        filter_conditions = self._build_filters(**filters)
+        result = await self.repository.list(
+            offset=offset,
+            limit=limit,
+            filters=filter_conditions,
+        )
+        return list(result)
+
+    async def create(self, data: CreateSchemaT) -> ModelT:
+        """Create new entity.
+
+        Args:
+            data: Pydantic schema with creation data.
+
+        Returns:
+            Created model instance.
+        """
+        create_data = self._prepare_create_data(data)
+        return await self.repository.create(**create_data)
+
+    async def update(self, id: str, data: UpdateSchemaT) -> ModelT | None:
+        """Update existing entity.
+
+        Args:
+            id: Entity's unique identifier.
+            data: Pydantic schema with update data.
+
+        Returns:
+            Updated model instance or None if not found.
+        """
+        update_data = self._prepare_update_data(data)
+        return await self.repository.update(id, **update_data)
+
+    async def delete(self, id: str) -> bool:
+        """Delete entity by ID.
+
+        Args:
+            id: Entity's unique identifier.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        return await self.repository.delete(id)
+
+    def _prepare_create_data(self, data: CreateSchemaT) -> dict[str, Any]:
+        """Prepare data for creation.
+
+        Override to customize creation data processing.
+
+        Args:
+            data: Pydantic schema with creation data.
+
+        Returns:
+            Dictionary of field values.
+        """
+        if hasattr(data, "model_dump"):
+            return data.model_dump(exclude_unset=True)  # type: ignore
+        return dict(data)  # type: ignore
+
+    def _prepare_update_data(self, data: UpdateSchemaT) -> dict[str, Any]:
+        """Prepare data for update.
+
+        Override to customize update data processing.
+
+        Args:
+            data: Pydantic schema with update data.
+
+        Returns:
+            Dictionary of field values (excluding None).
+        """
+        if hasattr(data, "model_dump"):
+            return data.model_dump(exclude_unset=True, exclude_none=True)  # type: ignore
+        return {k: v for k, v in dict(data).items() if v is not None}  # type: ignore
+
+    def _build_filters(self, **_filters: Any) -> list[Any]:
+        """Build SQLAlchemy filter conditions.
+
+        Override to customize filter building.
+
+        Args:
+            **filters: Filter criteria.
+
+        Returns:
+            List of SQLAlchemy filter conditions.
+        """
+        return []