truthound-dashboard 1.0.0__py3-none-any.whl

truthound_dashboard/schemas/base.py

@@ -0,0 +1,96 @@
+"""Base Pydantic schemas and mixins.
+
+This module provides reusable base classes and mixins for Pydantic schemas,
+enabling consistent patterns across all API schemas.
+
+The schema classes follow a consistent naming convention:
+- *Base: Common fields shared by create/update/response
+- *Create: Fields for creation (POST)
+- *Update: Fields for updates (PUT/PATCH)
+- *Response: Fields returned in responses
+- *ListResponse: Paginated list response wrapper
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Type variable for generic response wrappers
+T = TypeVar("T")
+
+
+class BaseSchema(BaseModel):
+    """Base schema with common configuration.
+
+    All schemas should inherit from this base class to ensure
+    consistent behavior and serialization.
+    """
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True,
+        json_schema_extra={"example": {}},
+    )
+
+
+class TimestampMixin:
+    """Mixin for timestamp fields in responses."""
+
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+
+class IDMixin:
+    """Mixin for ID field in responses."""
+
+    id: str = Field(..., description="Unique identifier")
+
+
+class ResponseWrapper(BaseSchema, Generic[T]):
+    """Generic wrapper for single item responses.
+
+    Provides consistent structure for API responses.
+    """
+
+    success: bool = Field(default=True, description="Whether request succeeded")
+    data: T = Field(..., description="Response data")
+    message: str | None = Field(default=None, description="Optional message")
+
+
+class ListResponseWrapper(BaseSchema, Generic[T]):
+    """Generic wrapper for list responses with pagination.
+
+    Provides consistent structure for paginated API responses.
+    """
+
+    success: bool = Field(default=True, description="Whether request succeeded")
+    data: list[T] = Field(default_factory=list, description="List of items")
+    total: int = Field(default=0, description="Total count of items")
+    offset: int = Field(default=0, description="Offset for pagination")
+    limit: int = Field(default=100, description="Limit for pagination")
+
+    @property
+    def has_more(self) -> bool:
+        """Check if there are more items."""
+        return self.offset + len(self.data) < self.total
+
+
+class ErrorResponse(BaseSchema):
+    """Standard error response schema."""
+
+    success: bool = Field(default=False)
+    detail: str = Field(..., description="Error description")
+    code: str | None = Field(default=None, description="Error code")
+    errors: list[dict[str, Any]] | None = Field(
+        default=None, description="Validation errors"
+    )
+
+
+class MessageResponse(BaseSchema):
+    """Simple message response schema."""
+
+    success: bool = Field(default=True)
+    message: str = Field(..., description="Response message")

truthound_dashboard/schemas/drift.py

@@ -0,0 +1,118 @@
+"""Drift detection schemas.
+
+Schemas for drift comparison request/response.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from .base import IDMixin, TimestampMixin
+
+
+class DriftCompareRequest(BaseModel):
+    """Request body for drift comparison."""
+
+    baseline_source_id: str = Field(..., description="Baseline source ID")
+    current_source_id: str = Field(..., description="Current source ID to compare")
+    columns: list[str] | None = Field(
+        None, description="Columns to compare (None = all)"
+    )
+    method: Literal["auto", "ks", "psi", "chi2", "js"] = Field(
+        "auto", description="Drift detection method"
+    )
+    threshold: float | None = Field(None, ge=0, le=1, description="Custom threshold")
+    sample_size: int | None = Field(
+        None, ge=100, description="Sample size for large datasets"
+    )
+
+
+class ColumnDriftResult(BaseModel):
+    """Drift result for a single column."""
+
+    column: str = Field(..., description="Column name")
+    dtype: str = Field(..., description="Data type")
+    drifted: bool = Field(..., description="Whether drift was detected")
+    level: str = Field(..., description="Drift level (high, medium, low, none)")
+    method: str = Field(..., description="Detection method used")
+    statistic: float | None = Field(None, description="Test statistic value")
+    p_value: float | None = Field(None, description="P-value")
+    baseline_stats: dict[str, Any] = Field(
+        default_factory=dict, description="Baseline statistics"
+    )
+    current_stats: dict[str, Any] = Field(
+        default_factory=dict, description="Current statistics"
+    )
+
+
+class DriftResult(BaseModel):
+    """Full drift comparison result."""
+
+    baseline_source: str = Field(..., description="Baseline source path")
+    current_source: str = Field(..., description="Current source path")
+    baseline_rows: int = Field(..., description="Number of baseline rows")
+    current_rows: int = Field(..., description="Number of current rows")
+    has_drift: bool = Field(..., description="Whether any drift was detected")
+    has_high_drift: bool = Field(
+        ..., description="Whether high-severity drift was detected"
+    )
+    total_columns: int = Field(..., description="Total columns compared")
+    drifted_columns: list[str] = Field(
+        default_factory=list, description="Columns with drift"
+    )
+    columns: list[ColumnDriftResult] = Field(
+        default_factory=list, description="Per-column results"
+    )
+
+
+class DriftSourceSummary(BaseModel):
+    """Summary of a source in drift comparison."""
+
+    id: str = Field(..., description="Source ID")
+    name: str = Field(..., description="Source name")
+
+
+class DriftComparisonResponse(BaseModel, IDMixin, TimestampMixin):
+    """Response for drift comparison."""
+
+    baseline_source_id: str = Field(..., description="Baseline source ID")
+    current_source_id: str = Field(..., description="Current source ID")
+    has_drift: bool = Field(..., description="Whether drift was detected")
+    has_high_drift: bool = Field(
+        ..., description="Whether high-severity drift was detected"
+    )
+    total_columns: int | None = Field(None, description="Total columns compared")
+    drifted_columns: int | None = Field(
+        None, description="Number of columns with drift"
+    )
+    drift_percentage: float = Field(0, description="Percentage of columns with drift")
+    result: DriftResult | None = Field(None, description="Full drift result")
+    config: dict[str, Any] | None = Field(None, description="Comparison configuration")
+
+    # Optional source details
+    baseline: DriftSourceSummary | None = Field(
+        None, description="Baseline source info"
+    )
+    current: DriftSourceSummary | None = Field(None, description="Current source info")
+
+
+class DriftComparisonListItem(BaseModel, IDMixin, TimestampMixin):
+    """List item for drift comparisons."""
+
+    baseline_source_id: str
+    current_source_id: str
+    has_drift: bool
+    has_high_drift: bool
+    total_columns: int | None = None
+    drifted_columns: int | None = None
+    drift_percentage: float = 0
+
+
+class DriftComparisonListResponse(BaseModel):
+    """List response for drift comparisons."""
+
+    success: bool = True
+    data: list[DriftComparisonListItem] = Field(default_factory=list)
+    total: int = 0

truthound_dashboard/schemas/history.py

@@ -0,0 +1,74 @@
+"""History and analytics schemas.
+
+Schemas for validation history and trend analysis.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class TrendDataPoint(BaseModel):
+    """Single data point in trend analysis."""
+
+    date: str = Field(..., description="Date string (format depends on granularity)")
+    success_rate: float = Field(
+        ..., ge=0, le=100, description="Success rate percentage"
+    )
+    run_count: int = Field(..., ge=0, description="Number of validation runs")
+    passed_count: int = Field(..., ge=0, description="Number of passed validations")
+    failed_count: int = Field(..., ge=0, description="Number of failed validations")
+
+
+class FailureFrequencyItem(BaseModel):
+    """Failure frequency for an issue type."""
+
+    issue: str = Field(..., description="Issue identifier (column.issue_type)")
+    count: int = Field(..., ge=0, description="Total occurrence count")
+
+
+class RecentValidation(BaseModel):
+    """Summary of a recent validation run."""
+
+    id: str = Field(..., description="Validation ID")
+    status: str = Field(..., description="Validation status")
+    passed: bool | None = Field(None, description="Whether validation passed")
+    has_critical: bool | None = Field(None, description="Has critical issues")
+    has_high: bool | None = Field(None, description="Has high severity issues")
+    total_issues: int | None = Field(None, description="Total issue count")
+    created_at: str = Field(..., description="ISO timestamp")
+
+
+class HistorySummary(BaseModel):
+    """Summary statistics for the history period."""
+
+    total_runs: int = Field(..., ge=0, description="Total validation runs")
+    passed_runs: int = Field(..., ge=0, description="Number of passed runs")
+    failed_runs: int = Field(..., ge=0, description="Number of failed runs")
+    success_rate: float = Field(
+        ..., ge=0, le=100, description="Success rate percentage"
+    )
+
+
+class HistoryResponse(BaseModel):
+    """Validation history response with trends and analytics."""
+
+    summary: HistorySummary = Field(..., description="Summary statistics")
+    trend: list[TrendDataPoint] = Field(default_factory=list, description="Trend data")
+    failure_frequency: list[FailureFrequencyItem] = Field(
+        default_factory=list, description="Top failure types"
+    )
+    recent_validations: list[RecentValidation] = Field(
+        default_factory=list, description="Recent validation runs"
+    )
+
+
+class HistoryQueryParams(BaseModel):
+    """Query parameters for history endpoint."""
+
+    period: Literal["7d", "30d", "90d"] = Field("30d", description="Time period")
+    granularity: Literal["hourly", "daily", "weekly"] = Field(
+        "daily", description="Aggregation granularity"
+    )

truthound_dashboard/schemas/profile.py

@@ -0,0 +1,91 @@
+"""Profile-related Pydantic schemas.
+
+This module defines schemas for data profiling API operations.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from .base import BaseSchema
+
+
+class ColumnProfile(BaseSchema):
+    """Profile information for a single column."""
+
+    name: str = Field(..., description="Column name")
+    dtype: str = Field(..., description="Data type")
+    null_pct: str = Field(default="0%", description="Percentage of null values")
+    unique_pct: str = Field(default="0%", description="Percentage of unique values")
+    min: Any | None = Field(default=None, description="Minimum value")
+    max: Any | None = Field(default=None, description="Maximum value")
+    mean: float | None = Field(default=None, description="Mean value (numeric columns)")
+    std: float | None = Field(default=None, description="Standard deviation (numeric)")
+
+    # Additional statistics (optional)
+    distinct_count: int | None = Field(
+        default=None,
+        description="Count of distinct values",
+    )
+    most_common: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Most common values with counts",
+    )
+
+
+class ProfileResponse(BaseSchema):
+    """Data profiling response."""
+
+    source: str = Field(..., description="Source path/identifier")
+    row_count: int = Field(..., ge=0, description="Total number of rows")
+    column_count: int = Field(..., ge=0, description="Total number of columns")
+    size_bytes: int = Field(..., ge=0, description="Data size in bytes")
+    columns: list[ColumnProfile] = Field(
+        default_factory=list,
+        description="Profile for each column",
+    )
+
+    # Computed properties
+    @property
+    def size_human(self) -> str:
+        """Get human-readable size."""
+        size = self.size_bytes
+        for unit in ["B", "KB", "MB", "GB", "TB"]:
+            if size < 1024:
+                return f"{size:.1f} {unit}"
+            size /= 1024
+        return f"{size:.1f} PB"
+
+    @classmethod
+    def from_result(cls, result: Any) -> ProfileResponse:
+        """Create response from adapter result.
+
+        Args:
+            result: ProfileResult from adapter.
+
+        Returns:
+            ProfileResponse instance.
+        """
+        columns = [
+            ColumnProfile(
+                name=col["name"],
+                dtype=col["dtype"],
+                null_pct=col.get("null_pct", "0%"),
+                unique_pct=col.get("unique_pct", "0%"),
+                min=col.get("min"),
+                max=col.get("max"),
+                mean=col.get("mean"),
+                std=col.get("std"),
+            )
+            for col in result.columns
+        ]
+
+        return cls(
+            source=result.source,
+            row_count=result.row_count,
+            column_count=result.column_count,
+            size_bytes=result.size_bytes,
+            columns=columns,
+        )

truthound_dashboard/schemas/rule.py

@@ -0,0 +1,199 @@
+"""Rule-related Pydantic schemas.
+
+This module defines schemas for custom validation rules API operations.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+from pydantic import Field, field_validator
+
+from .base import BaseSchema, IDMixin, ListResponseWrapper, TimestampMixin
+
+
+class RuleBase(BaseSchema):
+    """Base rule schema with common fields."""
+
+    name: str = Field(
+        default="Default Rules",
+        min_length=1,
+        max_length=255,
+        description="Human-readable rule name",
+        examples=["Email Validation Rules", "User Data Constraints"],
+    )
+    description: str | None = Field(
+        default=None,
+        max_length=1000,
+        description="Optional description of the rules",
+    )
+    rules_yaml: str = Field(
+        ...,
+        min_length=1,
+        description="YAML content defining validation rules",
+        examples=[
+            """columns:
+  user_id:
+    not_null: true
+    unique: true
+  email:
+    pattern: "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$"
+"""
+        ],
+    )
+
+
+class RuleCreate(RuleBase):
+    """Schema for creating a new rule."""
+
+    @field_validator("rules_yaml")
+    @classmethod
+    def validate_yaml(cls, v: str) -> str:
+        """Validate YAML syntax."""
+        try:
+            yaml.safe_load(v)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML syntax: {e}")
+        return v
+
+
+class RuleUpdate(BaseSchema):
+    """Schema for updating an existing rule."""
+
+    name: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=255,
+        description="New rule name",
+    )
+    description: str | None = Field(
+        default=None,
+        max_length=1000,
+        description="New description",
+    )
+    rules_yaml: str | None = Field(
+        default=None,
+        min_length=1,
+        description="New YAML rules content",
+    )
+    is_active: bool | None = Field(
+        default=None,
+        description="Whether rule is active",
+    )
+    version: str | None = Field(
+        default=None,
+        max_length=50,
+        description="Version string for tracking changes",
+    )
+
+    @field_validator("rules_yaml")
+    @classmethod
+    def validate_yaml(cls, v: str | None) -> str | None:
+        """Validate YAML syntax if provided."""
+        if v is not None:
+            try:
+                yaml.safe_load(v)
+            except yaml.YAMLError as e:
+                raise ValueError(f"Invalid YAML syntax: {e}")
+        return v
+
+
+class ColumnRuleInfo(BaseSchema):
+    """Information about a single column's rules."""
+
+    name: str = Field(..., description="Column name")
+    constraints: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Constraints applied to this column",
+    )
+
+
+class RuleResponse(RuleBase, IDMixin, TimestampMixin):
+    """Schema for rule responses."""
+
+    source_id: str = Field(..., description="Source this rule belongs to")
+    is_active: bool = Field(default=True, description="Whether rule is active")
+    version: str | None = Field(default=None, description="Rule version")
+
+    # Computed from rules_json
+    rules_json: dict[str, Any] | None = Field(
+        default=None,
+        description="Parsed rules as JSON",
+    )
+    column_count: int = Field(
+        default=0,
+        description="Number of columns with rules",
+    )
+
+    @classmethod
+    def from_model(cls, rule: Any) -> RuleResponse:
+        """Create response from model with computed fields.
+
+        Args:
+            rule: Rule model instance.
+
+        Returns:
+            RuleResponse with computed fields.
+        """
+        return cls(
+            id=rule.id,
+            source_id=rule.source_id,
+            name=rule.name,
+            description=rule.description,
+            rules_yaml=rule.rules_yaml,
+            rules_json=rule.rules_json,
+            is_active=rule.is_active,
+            version=rule.version,
+            column_count=rule.column_count,
+            created_at=rule.created_at,
+            updated_at=rule.updated_at,
+        )
+
+
+class RuleListItem(BaseSchema, IDMixin, TimestampMixin):
+    """Rule list item (without full YAML content)."""
+
+    source_id: str
+    name: str
+    description: str | None = None
+    is_active: bool = True
+    version: str | None = None
+    column_count: int = 0
+
+    @classmethod
+    def from_model(cls, rule: Any) -> RuleListItem:
+        """Create list item from model.
+
+        Args:
+            rule: Rule model instance.
+
+        Returns:
+            RuleListItem instance.
+        """
+        return cls(
+            id=rule.id,
+            source_id=rule.source_id,
+            name=rule.name,
+            description=rule.description,
+            is_active=rule.is_active,
+            version=rule.version,
+            column_count=rule.column_count,
+            created_at=rule.created_at,
+            updated_at=rule.updated_at,
+        )
+
+
+class RuleListResponse(ListResponseWrapper[RuleListItem]):
+    """Paginated rule list response."""
+
+    pass
+
+
+class RuleSummary(BaseSchema):
+    """Minimal rule summary for embedded responses."""
+
+    id: str
+    name: str
+    is_active: bool = True
+    column_count: int = 0

truthound_dashboard/schemas/schedule.py

@@ -0,0 +1,88 @@
+"""Schedule management schemas.
+
+Schemas for validation schedule request/response.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .base import IDMixin, TimestampMixin
+
+
+class ScheduleBase(BaseModel):
+    """Base schedule fields."""
+
+    name: str = Field(..., min_length=1, max_length=255, description="Schedule name")
+    cron_expression: str = Field(
+        ...,
+        description="Cron expression (5 fields: min hour day month weekday)",
+        examples=["0 8 * * *", "*/30 * * * *", "0 0 * * 0"],
+    )
+    notify_on_failure: bool = Field(True, description="Send notification on failure")
+
+
+class ScheduleCreate(ScheduleBase):
+    """Request body for creating a schedule."""
+
+    source_id: str = Field(..., description="Source ID to schedule")
+    config: dict[str, Any] | None = Field(
+        None,
+        description="Additional configuration (validators, schema_path, etc.)",
+    )
+
+
+class ScheduleUpdate(BaseModel):
+    """Request body for updating a schedule."""
+
+    name: str | None = Field(None, min_length=1, max_length=255)
+    cron_expression: str | None = Field(None)
+    notify_on_failure: bool | None = Field(None)
+    config: dict[str, Any] | None = Field(None)
+
+
+class ScheduleResponse(BaseModel, IDMixin, TimestampMixin):
+    """Response for a schedule."""
+
+    name: str = Field(..., description="Schedule name")
+    source_id: str = Field(..., description="Source ID")
+    cron_expression: str = Field(..., description="Cron expression")
+    is_active: bool = Field(..., description="Whether schedule is active")
+    notify_on_failure: bool = Field(..., description="Notify on failure")
+    last_run_at: str | None = Field(None, description="Last run timestamp (ISO)")
+    next_run_at: str | None = Field(None, description="Next scheduled run (ISO)")
+    config: dict[str, Any] | None = Field(None, description="Configuration")
+
+    # Optional source info
+    source_name: str | None = Field(None, description="Source name")
+
+
+class ScheduleListItem(BaseModel, IDMixin, TimestampMixin):
+    """List item for schedules."""
+
+    name: str
+    source_id: str
+    cron_expression: str
+    is_active: bool
+    notify_on_failure: bool
+    last_run_at: str | None = None
+    next_run_at: str | None = None
+    source_name: str | None = None
+
+
+class ScheduleListResponse(BaseModel):
+    """List response for schedules."""
+
+    success: bool = True
+    data: list[ScheduleListItem] = Field(default_factory=list)
+    total: int = 0
+
+
+class ScheduleActionResponse(BaseModel):
+    """Response for schedule actions (pause, resume, run)."""
+
+    success: bool = True
+    message: str = Field(..., description="Action result message")
+    schedule: ScheduleResponse | None = Field(None, description="Updated schedule")