truthound-dashboard 1.3.1__py3-none-any.whl → 1.4.1__py3-none-any.whl

truthound_dashboard/schemas/profile_comparison.py

@@ -0,0 +1,242 @@
+"""Profile comparison Pydantic schemas.
+
+This module defines schemas for profile comparison,
+including time-series trends and version-to-version comparison.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import Field
+
+from .base import BaseSchema
+
+
+class TrendDirection(str, Enum):
+    """Direction of metric trend."""
+
+    UP = "up"
+    DOWN = "down"
+    STABLE = "stable"
+
+
+# =============================================================================
+# Profile Summary Schemas
+# =============================================================================
+
+
+class ProfileSummary(BaseSchema):
+    """Summary of a profile for listing."""
+
+    id: str = Field(..., description="Profile ID")
+    source_id: str = Field(..., description="Source ID")
+    row_count: int = Field(..., description="Number of rows")
+    column_count: int = Field(..., description="Number of columns")
+    size_bytes: int = Field(default=0, description="Data size in bytes")
+    created_at: datetime = Field(..., description="When profile was created")
+
+
+class ProfileListResponse(BaseSchema):
+    """List response for profiles."""
+
+    profiles: list[ProfileSummary] = Field(
+        default_factory=list, description="List of profiles"
+    )
+    total: int = Field(default=0, description="Total count")
+    source_id: str = Field(..., description="Source ID")
+
+
+# =============================================================================
+# Column Comparison Schemas
+# =============================================================================
+
+
+class StatisticalTestInfo(BaseSchema):
+    """Information about statistical significance test results."""
+
+    test_name: str = Field(..., description="Name of the statistical test used")
+    p_value: float = Field(..., description="P-value from the test")
+    is_significant: bool = Field(..., description="Whether result is significant at alpha=0.05")
+    effect_size: float | None = Field(default=None, description="Effect size (Cohen's d or r)")
+    interpretation: str = Field(default="", description="Human-readable interpretation")
+
+
+class ColumnComparison(BaseSchema):
+    """Comparison result for a single column metric."""
+
+    column: str = Field(..., description="Column name")
+    metric: str = Field(..., description="Metric name (e.g., null_pct, unique_pct)")
+    baseline_value: Any = Field(..., description="Value in baseline profile")
+    current_value: Any = Field(..., description="Value in current profile")
+    change: float | None = Field(
+        default=None, description="Absolute change in value"
+    )
+    change_pct: float | None = Field(
+        default=None, description="Percentage change"
+    )
+    is_significant: bool = Field(
+        default=False, description="Whether change is statistically significant"
+    )
+    trend: TrendDirection = Field(
+        default=TrendDirection.STABLE, description="Direction of change"
+    )
+    statistical_test: dict[str, Any] | None = Field(
+        default=None,
+        description="Statistical test results (test_name, p_value, effect_size, interpretation)"
+    )
+
+
+class ColumnComparisonSummary(BaseSchema):
+    """Summary of changes for a single column."""
+
+    column: str = Field(..., description="Column name")
+    metrics_changed: int = Field(default=0, description="Number of metrics changed")
+    significant_changes: int = Field(
+        default=0, description="Number of significant changes"
+    )
+    comparisons: list[ColumnComparison] = Field(
+        default_factory=list, description="Individual metric comparisons"
+    )
+
+
+# =============================================================================
+# Profile Comparison Schemas
+# =============================================================================
+
+
+class ProfileComparisonRequest(BaseSchema):
+    """Request to compare two profiles."""
+
+    baseline_profile_id: str = Field(..., description="Baseline profile ID")
+    current_profile_id: str = Field(..., description="Current profile ID")
+    significance_threshold: float = Field(
+        default=0.1,
+        ge=0.0,
+        le=1.0,
+        description="Threshold for significant change detection",
+    )
+
+
+class ProfileComparisonResponse(BaseSchema):
+    """Response containing profile comparison results."""
+
+    source_id: str = Field(..., description="Source ID")
+    source_name: str = Field(..., description="Source name")
+    baseline_profile_id: str = Field(..., description="Baseline profile ID")
+    current_profile_id: str = Field(..., description="Current profile ID")
+    baseline_timestamp: datetime = Field(..., description="Baseline profile timestamp")
+    current_timestamp: datetime = Field(..., description="Current profile timestamp")
+    row_count_change: int = Field(default=0, description="Change in row count")
+    row_count_change_pct: float = Field(
+        default=0.0, description="Percentage change in row count"
+    )
+    column_count_change: int = Field(default=0, description="Change in column count")
+    column_comparisons: list[ColumnComparison] = Field(
+        default_factory=list, description="Per-column metric comparisons"
+    )
+    significant_changes: int = Field(
+        default=0, description="Number of significant changes"
+    )
+    summary: dict[str, Any] = Field(
+        default_factory=dict, description="Summary statistics"
+    )
+    compared_at: datetime = Field(..., description="When comparison was performed")
+
+
+# =============================================================================
+# Profile Trend Schemas
+# =============================================================================
+
+
+class ProfileTrendPoint(BaseSchema):
+    """A single point in profile trend data."""
+
+    timestamp: datetime = Field(..., description="Profile timestamp")
+    profile_id: str = Field(..., description="Profile ID")
+    row_count: int = Field(..., description="Row count at this point")
+    column_count: int = Field(default=0, description="Column count")
+    avg_null_pct: float = Field(default=0.0, description="Average null percentage")
+    avg_unique_pct: float = Field(default=0.0, description="Average unique percentage")
+    size_bytes: int = Field(default=0, description="Data size in bytes")
+
+
+class ColumnTrend(BaseSchema):
+    """Trend data for a specific column metric."""
+
+    column: str = Field(..., description="Column name")
+    metric: str = Field(..., description="Metric name")
+    values: list[tuple[datetime, float]] = Field(
+        default_factory=list, description="Time-value pairs"
+    )
+    trend_direction: TrendDirection = Field(
+        default=TrendDirection.STABLE, description="Overall trend direction"
+    )
+    change_pct: float = Field(
+        default=0.0, description="Overall percentage change"
+    )
+    min_value: float | None = Field(default=None, description="Minimum value in period")
+    max_value: float | None = Field(default=None, description="Maximum value in period")
+    avg_value: float | None = Field(default=None, description="Average value in period")
+
+
+class ProfileTrendRequest(BaseSchema):
+    """Request for profile trend data."""
+
+    period: str = Field(
+        default="30d",
+        description="Time period (e.g., 7d, 30d, 90d)",
+    )
+    granularity: str = Field(
+        default="daily",
+        description="Data granularity (hourly, daily, weekly)",
+    )
+    columns: list[str] | None = Field(
+        default=None,
+        description="Specific columns to include in trends",
+    )
+    metrics: list[str] | None = Field(
+        default=None,
+        description="Specific metrics to include (null_pct, unique_pct, etc.)",
+    )
+
+
+class ProfileTrendResponse(BaseSchema):
+    """Response containing profile trend data."""
+
+    source_id: str = Field(..., description="Source ID")
+    source_name: str = Field(..., description="Source name")
+    period: str = Field(..., description="Time period analyzed")
+    granularity: str = Field(..., description="Data granularity")
+    data_points: list[ProfileTrendPoint] = Field(
+        default_factory=list, description="Overall trend points"
+    )
+    column_trends: list[ColumnTrend] = Field(
+        default_factory=list, description="Per-column trends"
+    )
+    total_profiles: int = Field(default=0, description="Total profiles in period")
+    row_count_trend: TrendDirection = Field(
+        default=TrendDirection.STABLE, description="Overall row count trend"
+    )
+    summary: dict[str, Any] = Field(
+        default_factory=dict, description="Summary statistics"
+    )
+
+
+# =============================================================================
+# Latest Comparison Shortcut
+# =============================================================================
+
+
+class LatestComparisonResponse(BaseSchema):
+    """Response for comparing latest profile with previous."""
+
+    source_id: str = Field(..., description="Source ID")
+    has_previous: bool = Field(
+        ..., description="Whether a previous profile exists"
+    )
+    comparison: ProfileComparisonResponse | None = Field(
+        default=None, description="Comparison result (if previous exists)"
+    )

truthound_dashboard/schemas/reports.py

@@ -0,0 +1,285 @@
+"""Report-related Pydantic schemas.
+
+This module defines schemas for report generation API operations.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import Field
+
+from .base import BaseSchema, IDMixin, ListResponseWrapper, TimestampMixin
+
+# Report format types
+ReportFormatType = Literal["html", "csv", "json", "markdown", "pdf", "junit", "excel", "custom"]
+
+# Report theme types
+ReportThemeType = Literal["light", "dark", "professional", "minimal", "high_contrast"]
+
+
+class ReportStatus(str, Enum):
+    """Status of report generation."""
+
+    PENDING = "pending"
+    GENERATING = "generating"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+class ReportGenerateRequest(BaseSchema):
+    """Request to generate a validation report.
+
+    All parameters are optional with sensible defaults.
+    """
+
+    format: ReportFormatType = Field(
+        default="html",
+        description="Output format for the report",
+    )
+    theme: ReportThemeType = Field(
+        default="professional",
+        description="Visual theme for the report (mainly for HTML)",
+    )
+    title: str | None = Field(
+        default=None,
+        description="Custom title for the report. Auto-generated if not provided.",
+    )
+    include_samples: bool = Field(
+        default=True,
+        description="Include sample problematic values in the report",
+    )
+    include_statistics: bool = Field(
+        default=True,
+        description="Include data statistics section",
+    )
+    custom_metadata: dict[str, Any] | None = Field(
+        default=None,
+        description="Additional metadata to include in the report",
+    )
+
+
+class ReportMetadataResponse(BaseSchema):
+    """Report metadata returned in API responses."""
+
+    title: str = Field(..., description="Report title")
+    generated_at: datetime = Field(..., description="Generation timestamp")
+    source_name: str | None = Field(default=None, description="Data source name")
+    source_id: str | None = Field(default=None, description="Data source ID")
+    validation_id: str | None = Field(default=None, description="Validation ID")
+    theme: str = Field(..., description="Visual theme used")
+    format: str = Field(..., description="Output format")
+
+
+class ReportResponse(BaseSchema):
+    """Response for report generation.
+
+    Contains metadata about the generated report and download info.
+    Note: The actual content is returned as a file download, not in this response.
+    """
+
+    filename: str = Field(..., description="Suggested filename for download")
+    content_type: str = Field(..., description="MIME content type")
+    size_bytes: int = Field(..., description="Size of report content in bytes")
+    generation_time_ms: int = Field(
+        ..., description="Time taken to generate in milliseconds"
+    )
+    metadata: ReportMetadataResponse = Field(..., description="Report metadata")
+
+
+class AvailableFormatsResponse(BaseSchema):
+    """Response listing available report formats."""
+
+    formats: list[str] = Field(
+        ...,
+        description="List of available format names",
+        examples=[["html", "csv", "json", "markdown"]],
+    )
+    themes: list[str] = Field(
+        ...,
+        description="List of available theme names",
+        examples=[["light", "dark", "professional", "minimal", "high_contrast"]],
+    )
+
+
+# =============================================================================
+# Report History Schemas
+# =============================================================================
+
+
+class GeneratedReportBase(BaseSchema):
+    """Base schema for generated report."""
+
+    name: str = Field(max_length=255, description="Report name")
+    description: str | None = Field(default=None, description="Report description")
+    format: ReportFormatType = Field(default="html", description="Output format")
+    theme: ReportThemeType | None = Field(default=None, description="Visual theme")
+    locale: str = Field(default="en", max_length=10, description="Language locale")
+    config: dict[str, Any] | None = Field(default=None, description="Generation config")
+    metadata: dict[str, Any] | None = Field(default=None, description="Additional metadata")
+
+
+class GeneratedReportCreate(GeneratedReportBase):
+    """Schema for creating a generated report record."""
+
+    validation_id: str | None = Field(default=None, description="Associated validation ID")
+    source_id: str | None = Field(default=None, description="Associated source ID")
+    reporter_id: str | None = Field(default=None, description="Custom reporter ID if used")
+    expires_in_days: int | None = Field(
+        default=30,
+        ge=1,
+        le=365,
+        description="Days until report expires (1-365)",
+    )
+
+
+class GeneratedReportUpdate(BaseSchema):
+    """Schema for updating a generated report record."""
+
+    name: str | None = Field(default=None, max_length=255)
+    description: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class GeneratedReportResponse(GeneratedReportBase, IDMixin, TimestampMixin):
+    """Response schema for generated report."""
+
+    validation_id: str | None = None
+    source_id: str | None = None
+    reporter_id: str | None = None
+    status: ReportStatus = ReportStatus.PENDING
+    file_path: str | None = None
+    file_size: int | None = None
+    content_hash: str | None = None
+    error_message: str | None = None
+    generation_time_ms: float | None = None
+    expires_at: datetime | None = None
+    downloaded_count: int = 0
+    last_downloaded_at: datetime | None = None
+
+    # Enriched fields (populated in API)
+    source_name: str | None = Field(default=None, description="Source name for display")
+    reporter_name: str | None = Field(default=None, description="Reporter name for display")
+    download_url: str | None = Field(default=None, description="URL to download the report")
+
+    @classmethod
+    def from_model(cls, model: Any) -> "GeneratedReportResponse":
+        """Create response from database model."""
+        return cls(
+            id=str(model.id),
+            name=model.name,
+            description=model.description,
+            format=model.format.value if hasattr(model.format, "value") else model.format,
+            theme=model.theme,
+            locale=model.locale,
+            config=model.config,
+            metadata=model.metadata,
+            validation_id=str(model.validation_id) if model.validation_id else None,
+            source_id=str(model.source_id) if model.source_id else None,
+            reporter_id=str(model.reporter_id) if model.reporter_id else None,
+            status=ReportStatus(model.status.value if hasattr(model.status, "value") else model.status),
+            file_path=model.file_path,
+            file_size=model.file_size,
+            content_hash=model.content_hash,
+            error_message=model.error_message,
+            generation_time_ms=model.generation_time_ms,
+            expires_at=model.expires_at,
+            downloaded_count=model.downloaded_count,
+            last_downloaded_at=model.last_downloaded_at,
+            created_at=model.created_at,
+            updated_at=model.updated_at,
+            source_name=model.source.name if model.source else None,
+            reporter_name=model.reporter.display_name if model.reporter else None,
+        )
+
+
+class GeneratedReportListResponse(ListResponseWrapper[GeneratedReportResponse]):
+    """Paginated list response for generated reports."""
+
+    pass
+
+
+class BulkReportGenerateRequest(BaseSchema):
+    """Request to generate reports for multiple validations."""
+
+    validation_ids: list[str] = Field(
+        ...,
+        min_length=1,
+        max_length=100,
+        description="List of validation IDs (1-100)",
+    )
+    format: ReportFormatType = Field(default="html", description="Output format")
+    theme: ReportThemeType = Field(default="professional", description="Visual theme")
+    locale: str = Field(default="en", max_length=10, description="Language locale")
+    reporter_id: str | None = Field(default=None, description="Custom reporter ID")
+    config: dict[str, Any] | None = Field(default=None, description="Reporter config")
+    save_to_history: bool = Field(
+        default=True,
+        description="Save reports to history",
+    )
+    expires_in_days: int | None = Field(
+        default=30,
+        ge=1,
+        le=365,
+        description="Days until reports expire",
+    )
+
+
+class BulkReportGenerateResponse(BaseSchema):
+    """Response for bulk report generation."""
+
+    total: int = Field(..., description="Total reports requested")
+    successful: int = Field(..., description="Successfully generated count")
+    failed: int = Field(..., description="Failed generation count")
+    reports: list[GeneratedReportResponse] = Field(
+        default_factory=list,
+        description="Generated report records",
+    )
+    errors: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Error details for failed reports",
+    )
+
+
+class ReportHistoryQuery(BaseSchema):
+    """Query parameters for report history."""
+
+    source_id: str | None = Field(default=None, description="Filter by source ID")
+    validation_id: str | None = Field(default=None, description="Filter by validation ID")
+    reporter_id: str | None = Field(default=None, description="Filter by reporter ID")
+    format: ReportFormatType | None = Field(default=None, description="Filter by format")
+    status: ReportStatus | None = Field(default=None, description="Filter by status")
+    include_expired: bool = Field(
+        default=False,
+        description="Include expired reports",
+    )
+    search: str | None = Field(default=None, description="Search by name")
+    sort_by: str = Field(default="created_at", description="Sort field")
+    sort_order: Literal["asc", "desc"] = Field(default="desc", description="Sort order")
+    page: int = Field(default=1, ge=1, description="Page number")
+    page_size: int = Field(default=20, ge=1, le=100, description="Items per page")
+
+
+class ReportStatistics(BaseSchema):
+    """Statistics for generated reports."""
+
+    total_reports: int = Field(..., description="Total reports generated")
+    total_size_bytes: int = Field(..., description="Total storage used")
+    reports_by_format: dict[str, int] = Field(
+        default_factory=dict,
+        description="Count by format",
+    )
+    reports_by_status: dict[str, int] = Field(
+        default_factory=dict,
+        description="Count by status",
+    )
+    total_downloads: int = Field(..., description="Total download count")
+    avg_generation_time_ms: float | None = Field(
+        default=None,
+        description="Average generation time",
+    )
+    expired_count: int = Field(default=0, description="Expired reports count")
+    reporters_used: int = Field(default=0, description="Unique reporters used")