truthound-dashboard 1.4.4__py3-none-any.whl → 1.5.0__py3-none-any.whl

truthound_dashboard/schemas/mask.py

@@ -12,7 +12,7 @@ from typing import Literal
 
 from pydantic import Field
 
-from .base import BaseSchema, IDMixin, TimestampMixin
+from .base import BaseSchema, IDMixin
 
 
 class MaskingStrategy(str, Enum):
@@ -47,7 +47,9 @@ class MaskRequest(BaseSchema):
     Attributes:
         columns: Optional list of columns to mask. If None, auto-detects PII.
         strategy: Masking strategy to use. Defaults to "redact".
-        output_format: Output file format. Defaults to "csv".
+
+    Note: output_format parameter was removed as truthound's th.mask()
+    does not support this parameter. Output format is handled by the dashboard.
     """
 
     columns: list[str] | None = Field(
@@ -58,10 +60,6 @@ class MaskRequest(BaseSchema):
         default="redact",
         description="Masking strategy: 'redact' (asterisks), 'hash' (SHA256), 'fake' (realistic data)",
     )
-    output_format: Literal["csv", "parquet", "json"] = Field(
-        default="csv",
-        description="Output file format",
-    )
 
 
 class MaskSummary(BaseSchema):
@@ -86,7 +84,7 @@ class MaskSummary(BaseSchema):
     duration_ms: int | None = None
 
 
-class MaskResponse(BaseSchema, IDMixin, TimestampMixin):
+class MaskResponse(BaseSchema, IDMixin):
     """Response for a masking operation.
 
     Attributes:
@@ -103,6 +101,8 @@ class MaskResponse(BaseSchema, IDMixin, TimestampMixin):
         error_message: Error message if operation failed.
         started_at: When the operation started.
         completed_at: When the operation completed.
+        created_at: When the operation was created.
+        updated_at: When the operation was last updated.
     """
 
     source_id: str
@@ -117,6 +117,8 @@ class MaskResponse(BaseSchema, IDMixin, TimestampMixin):
     error_message: str | None = None
     started_at: datetime | None = None
     completed_at: datetime | None = None
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime | None = Field(default=None, description="Last update timestamp")
 
     @classmethod
     def from_db(cls, db_mask: object) -> MaskResponse:
@@ -185,7 +187,7 @@ class MaskListItem(BaseSchema, IDMixin):
         return cls(
             id=db_mask.id,
             source_id=db_mask.source_id,
-            source_name=source_name or getattr(db_mask.source, "name", None),
+            source_name=source_name if source_name is not None else None,
             status=db_mask.status,
             strategy=db_mask.strategy,
             columns_masked=len(db_mask.columns_masked) if db_mask.columns_masked else 0,

truthound_dashboard/schemas/model_monitoring.py

@@ -54,19 +54,32 @@ class MetricType(str, Enum):
 
 
 class AlertRuleType(str, Enum):
-    """Types of alert rules."""
+    """Types of alert rules.
+
+    Maps to truthound.ml.monitoring.alerting rules:
+    - ThresholdRule: Threshold-based alerting
+    - AnomalyRule: Anomaly-based alerting (statistical)
+    - TrendRule: Trend-based alerting
+    """
 
     THRESHOLD = "threshold"
-    STATISTICAL = "statistical"
+    STATISTICAL = "statistical"  # Maps to AnomalyRule
     TREND = "trend"
 
 
 class AlertHandlerType(str, Enum):
-    """Types of alert handlers."""
+    """Types of alert handlers.
+
+    Maps to truthound.ml.monitoring.alerting handlers:
+    - SlackAlertHandler
+    - PagerDutyAlertHandler
+    - WebhookAlertHandler
+    """
 
     SLACK = "slack"
     WEBHOOK = "webhook"
     EMAIL = "email"
+    PAGERDUTY = "pagerduty"
 
 
 # =============================================================================
@@ -75,14 +88,63 @@ class AlertHandlerType(str, Enum):
 
 
 class ModelConfigBase(BaseSchema):
-    """Configuration for model monitoring."""
+    """Configuration for model monitoring.
+
+    Maps to truthound.ml.monitoring.MonitorConfig parameters.
+    See: .truthound_docs/advanced/ml-anomaly.md#model-monitoring
+    """
+
+    # Core monitoring settings (from MonitorConfig)
+    batch_size: int = Field(
+        default=100,
+        description="Batch size for metric collection",
+        ge=1,
+        le=10000,
+    )
+    collect_interval_seconds: int = Field(
+        default=60,
+        description="Interval for collecting metrics (seconds)",
+        ge=1,
+        le=3600,
+    )
+    alert_evaluation_interval_seconds: int = Field(
+        default=30,
+        description="Interval for evaluating alert rules (seconds)",
+        ge=1,
+        le=3600,
+    )
+    retention_hours: int = Field(
+        default=24,
+        description="Hours to retain metrics data",
+        ge=1,
+        le=720,  # 30 days max
+    )
+
+    # Feature toggles
+    enable_drift_detection: bool = Field(
+        default=True,
+        description="Enable drift detection using th.compare()",
+    )
+    enable_quality_metrics: bool = Field(
+        default=True,
+        description="Enable quality metrics (accuracy, precision, recall, F1)",
+    )
+    enable_performance_metrics: bool = Field(
+        default=True,
+        description="Enable performance metrics (latency, throughput, error rate)",
+    )
 
-    enable_drift_detection: bool = Field(default=True, description="Enable drift detection")
-    enable_quality_metrics: bool = Field(default=True, description="Enable quality metrics")
-    enable_performance_metrics: bool = Field(default=True, description="Enable performance metrics")
-    sample_rate: float = Field(default=1.0, description="Sampling rate for metrics", ge=0.0, le=1.0)
-    drift_threshold: float = Field(default=0.1, description="Threshold for drift detection", ge=0.0, le=1.0)
-    drift_window_size: int = Field(default=1000, description="Window size for drift detection", ge=100)
+    # Drift detection settings
+    drift_threshold: float = Field(
+        default=0.1,
+        description="Threshold for drift detection alerts",
+        ge=0.0,
+        le=1.0,
+    )
+    drift_method: str = Field(
+        default="auto",
+        description="Drift detection method (auto, psi, ks, js, wasserstein, chi2, etc.)",
+    )
 
 
 class RegisteredModelBase(BaseSchema):
@@ -372,3 +434,20 @@ class MonitoringOverview(BaseModel):
     active_alerts: int = Field(default=0, description="Currently active alerts")
     models_with_drift: int = Field(default=0, description="Models with detected drift")
     avg_latency_ms: float | None = Field(None, description="Average latency across all models")
+
+
+class AlertHandlerTestResult(BaseModel):
+    """Result of testing an alert handler."""
+
+    success: bool = Field(..., description="Whether test was successful")
+    message: str = Field(..., description="Test result message")
+    handler_id: str = Field(..., description="Handler ID that was tested")
+    handler_type: str = Field(..., description="Type of the handler")
+
+
+class RuleEvaluationResult(BaseModel):
+    """Result of rule evaluation for a model."""
+
+    model_id: str = Field(..., description="Model ID that was evaluated")
+    alerts_created: int = Field(..., description="Number of alerts created")
+    alert_ids: list[str] = Field(default_factory=list, description="IDs of created alerts")

truthound_dashboard/schemas/notifications_advanced.py

@@ -1361,3 +1361,16 @@ class ExpressionValidateResponse(BaseModel):
         default_factory=list,
         description="Non-fatal warnings about the expression",
     )
+
+
+# =============================================================================
+# Cache Invalidation Response
+# =============================================================================
+
+
+class CacheInvalidateResponse(BaseSchema):
+    """Response for cache invalidation operations."""
+
+    message: str = Field(..., description="Descriptive message about the operation")
+    target: str = Field(..., description="Cache target that was invalidated")
+    timestamp: str = Field(..., description="ISO timestamp of the operation")

truthound_dashboard/schemas/observability.py

@@ -0,0 +1,453 @@
+"""Observability schemas for audit, metrics, and tracing.
+
+This module defines schemas for observability API operations
+using truthound's observability module.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import Field
+
+from .base import BaseSchema, ListResponseWrapper
+
+
+class AuditEventTypeEnum(str, Enum):
+    """Audit event types from truthound."""
+
+    CREATE = "create"
+    READ = "read"
+    UPDATE = "update"
+    DELETE = "delete"
+    QUERY = "query"
+    LIST = "list"
+    COUNT = "count"
+    INITIALIZE = "initialize"
+    CLOSE = "close"
+    FLUSH = "flush"
+    BATCH_CREATE = "batch_create"
+    BATCH_DELETE = "batch_delete"
+    REPLICATE = "replicate"
+    SYNC = "sync"
+    MIGRATE = "migrate"
+    ROLLBACK = "rollback"
+    ACCESS_DENIED = "access_denied"
+    ACCESS_GRANTED = "access_granted"
+    ERROR = "error"
+    VALIDATION_ERROR = "validation_error"
+
+
+class AuditStatusEnum(str, Enum):
+    """Audit status from truthound."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    PARTIAL = "partial"
+    DENIED = "denied"
+
+
+class MetricTypeEnum(str, Enum):
+    """Metric types from truthound."""
+
+    COUNTER = "counter"
+    GAUGE = "gauge"
+    HISTOGRAM = "histogram"
+    SUMMARY = "summary"
+
+
+class SpanKindEnum(str, Enum):
+    """Span kinds from truthound."""
+
+    INTERNAL = "internal"
+    SERVER = "server"
+    CLIENT = "client"
+    PRODUCER = "producer"
+    CONSUMER = "consumer"
+
+
+class SpanStatusEnum(str, Enum):
+    """Span status from truthound."""
+
+    UNSET = "unset"
+    OK = "ok"
+    ERROR = "error"
+
+
+# =============================================================================
+# Observability Configuration
+# =============================================================================
+
+
+class ObservabilityConfigRequest(BaseSchema):
+    """Request to update observability configuration."""
+
+    enable_audit: bool = Field(
+        default=True,
+        description="Enable audit logging",
+    )
+    enable_metrics: bool = Field(
+        default=True,
+        description="Enable metrics collection",
+    )
+    enable_tracing: bool = Field(
+        default=False,
+        description="Enable distributed tracing",
+    )
+    audit_log_path: str | None = Field(
+        default=None,
+        description="Path for audit log files",
+    )
+    audit_rotate_daily: bool = Field(
+        default=True,
+        description="Rotate audit logs daily",
+    )
+    audit_max_events: int = Field(
+        default=10000,
+        ge=1000,
+        le=1000000,
+        description="Maximum events to keep in memory",
+    )
+    redact_fields: list[str] = Field(
+        default_factory=lambda: ["password", "api_key", "token", "secret"],
+        description="Fields to redact in audit logs",
+    )
+    metrics_prefix: str = Field(
+        default="truthound_dashboard",
+        max_length=50,
+        description="Prefix for metric names",
+    )
+    tracing_service_name: str = Field(
+        default="truthound-dashboard",
+        max_length=100,
+        description="Service name for tracing",
+    )
+    tracing_endpoint: str | None = Field(
+        default=None,
+        description="OpenTelemetry endpoint (e.g., http://localhost:4317)",
+    )
+
+
+class ObservabilityConfigResponse(ObservabilityConfigRequest):
+    """Response with current observability configuration."""
+
+    pass
+
+
+# =============================================================================
+# Audit Events
+# =============================================================================
+
+
+class AuditEventResponse(BaseSchema):
+    """Audit event response."""
+
+    event_id: str = Field(..., description="Unique event ID")
+    event_type: AuditEventTypeEnum = Field(..., description="Event type")
+    timestamp: datetime = Field(..., description="Event timestamp")
+    status: AuditStatusEnum = Field(..., description="Event status")
+    store_type: str = Field(..., description="Store backend type")
+    store_id: str = Field(..., description="Store identifier")
+    item_id: str | None = Field(default=None, description="Related item ID")
+    user_id: str | None = Field(default=None, description="User who triggered event")
+    session_id: str | None = Field(default=None, description="Session ID")
+    duration_ms: float | None = Field(default=None, description="Operation duration")
+    metadata: dict[str, Any] | None = Field(
+        default=None, description="Additional metadata"
+    )
+    error_message: str | None = Field(default=None, description="Error message")
+    ip_address: str | None = Field(default=None, description="Client IP address")
+    user_agent: str | None = Field(default=None, description="Client user agent")
+
+
+class AuditEventListResponse(ListResponseWrapper):
+    """Response for audit event list."""
+
+    items: list[AuditEventResponse]
+
+
+class AuditQueryRequest(BaseSchema):
+    """Request to query audit events."""
+
+    event_type: AuditEventTypeEnum | None = Field(
+        default=None, description="Filter by event type"
+    )
+    status: AuditStatusEnum | None = Field(
+        default=None, description="Filter by status"
+    )
+    start_time: datetime | None = Field(
+        default=None, description="Filter events after this time"
+    )
+    end_time: datetime | None = Field(
+        default=None, description="Filter events before this time"
+    )
+    item_id: str | None = Field(
+        default=None, description="Filter by item ID"
+    )
+    user_id: str | None = Field(
+        default=None, description="Filter by user ID"
+    )
+    limit: int = Field(
+        default=100, ge=1, le=1000, description="Maximum events to return"
+    )
+    offset: int = Field(
+        default=0, ge=0, description="Offset for pagination"
+    )
+
+
+class AuditStatsResponse(BaseSchema):
+    """Audit statistics response."""
+
+    total_events: int = Field(default=0, ge=0, description="Total audit events")
+    events_today: int = Field(default=0, ge=0, description="Events today")
+    events_this_week: int = Field(default=0, ge=0, description="Events this week")
+    by_event_type: dict[str, int] = Field(
+        default_factory=dict, description="Events by type"
+    )
+    by_status: dict[str, int] = Field(
+        default_factory=dict, description="Events by status"
+    )
+    error_rate: float = Field(
+        default=0.0, ge=0, le=1, description="Error event rate"
+    )
+    avg_duration_ms: float | None = Field(
+        default=None, description="Average operation duration"
+    )
+
+
+# =============================================================================
+# Metrics
+# =============================================================================
+
+
+class MetricValue(BaseSchema):
+    """A single metric value."""
+
+    name: str = Field(..., description="Metric name")
+    value: float = Field(..., description="Metric value")
+    labels: dict[str, str] = Field(
+        default_factory=dict, description="Metric labels"
+    )
+    timestamp: datetime | None = Field(
+        default=None, description="Metric timestamp"
+    )
+    metric_type: MetricTypeEnum = Field(
+        default=MetricTypeEnum.GAUGE, description="Metric type"
+    )
+
+
+class HistogramBucket(BaseSchema):
+    """Histogram bucket."""
+
+    le: float = Field(..., description="Less than or equal boundary")
+    count: int = Field(..., ge=0, description="Count in bucket")
+
+
+class HistogramValue(BaseSchema):
+    """Histogram metric value."""
+
+    name: str = Field(..., description="Metric name")
+    count: int = Field(..., ge=0, description="Total count")
+    sum: float = Field(..., description="Sum of values")
+    buckets: list[HistogramBucket] = Field(
+        default_factory=list, description="Histogram buckets"
+    )
+    labels: dict[str, str] = Field(
+        default_factory=dict, description="Metric labels"
+    )
+
+
+class SummaryQuantile(BaseSchema):
+    """Summary quantile."""
+
+    quantile: float = Field(..., ge=0, le=1, description="Quantile (0-1)")
+    value: float = Field(..., description="Value at quantile")
+
+
+class SummaryValue(BaseSchema):
+    """Summary metric value."""
+
+    name: str = Field(..., description="Metric name")
+    count: int = Field(..., ge=0, description="Total count")
+    sum: float = Field(..., description="Sum of values")
+    quantiles: list[SummaryQuantile] = Field(
+        default_factory=list, description="Quantile values"
+    )
+    labels: dict[str, str] = Field(
+        default_factory=dict, description="Metric labels"
+    )
+
+
+class MetricsResponse(BaseSchema):
+    """Response with all metrics."""
+
+    counters: list[MetricValue] = Field(
+        default_factory=list, description="Counter metrics"
+    )
+    gauges: list[MetricValue] = Field(
+        default_factory=list, description="Gauge metrics"
+    )
+    histograms: list[HistogramValue] = Field(
+        default_factory=list, description="Histogram metrics"
+    )
+    summaries: list[SummaryValue] = Field(
+        default_factory=list, description="Summary metrics"
+    )
+    timestamp: datetime = Field(..., description="Metrics snapshot timestamp")
+
+
+class StoreMetricsResponse(BaseSchema):
+    """Store-specific metrics response."""
+
+    operations_total: int = Field(
+        default=0, ge=0, description="Total operations"
+    )
+    operations_by_type: dict[str, int] = Field(
+        default_factory=dict, description="Operations by type"
+    )
+    bytes_read_total: int = Field(
+        default=0, ge=0, description="Total bytes read"
+    )
+    bytes_written_total: int = Field(
+        default=0, ge=0, description="Total bytes written"
+    )
+    active_connections: int = Field(
+        default=0, ge=0, description="Active connections"
+    )
+    cache_hits: int = Field(
+        default=0, ge=0, description="Cache hits"
+    )
+    cache_misses: int = Field(
+        default=0, ge=0, description="Cache misses"
+    )
+    cache_hit_rate: float = Field(
+        default=0.0, ge=0, le=1, description="Cache hit rate"
+    )
+    errors_total: int = Field(
+        default=0, ge=0, description="Total errors"
+    )
+    errors_by_type: dict[str, int] = Field(
+        default_factory=dict, description="Errors by type"
+    )
+    avg_operation_duration_ms: float | None = Field(
+        default=None, description="Average operation duration"
+    )
+
+
+# =============================================================================
+# Tracing
+# =============================================================================
+
+
+class SpanContext(BaseSchema):
+    """Span context for distributed tracing."""
+
+    trace_id: str = Field(..., description="Trace ID")
+    span_id: str = Field(..., description="Span ID")
+    parent_span_id: str | None = Field(
+        default=None, description="Parent span ID"
+    )
+    trace_flags: int = Field(default=0, description="Trace flags")
+    trace_state: dict[str, str] = Field(
+        default_factory=dict, description="Trace state"
+    )
+
+
+class SpanEvent(BaseSchema):
+    """Event within a span."""
+
+    name: str = Field(..., description="Event name")
+    timestamp: datetime = Field(..., description="Event timestamp")
+    attributes: dict[str, Any] = Field(
+        default_factory=dict, description="Event attributes"
+    )
+
+
+class SpanResponse(BaseSchema):
+    """Span response for tracing."""
+
+    name: str = Field(..., description="Span name")
+    kind: SpanKindEnum = Field(..., description="Span kind")
+    context: SpanContext = Field(..., description="Span context")
+    start_time: datetime = Field(..., description="Span start time")
+    end_time: datetime | None = Field(default=None, description="Span end time")
+    duration_ms: float | None = Field(default=None, description="Duration in ms")
+    status: SpanStatusEnum = Field(
+        default=SpanStatusEnum.UNSET, description="Span status"
+    )
+    status_message: str | None = Field(
+        default=None, description="Status message if error"
+    )
+    attributes: dict[str, Any] = Field(
+        default_factory=dict, description="Span attributes"
+    )
+    events: list[SpanEvent] = Field(
+        default_factory=list, description="Span events"
+    )
+
+
+class SpanListResponse(ListResponseWrapper):
+    """Response for span list."""
+
+    items: list[SpanResponse]
+
+
+class TraceResponse(BaseSchema):
+    """Full trace with all spans."""
+
+    trace_id: str = Field(..., description="Trace ID")
+    spans: list[SpanResponse] = Field(
+        default_factory=list, description="All spans in trace"
+    )
+    duration_ms: float | None = Field(
+        default=None, description="Total trace duration"
+    )
+    service_count: int = Field(
+        default=0, ge=0, description="Number of services involved"
+    )
+    error_count: int = Field(
+        default=0, ge=0, description="Number of error spans"
+    )
+
+
+class TracingStatsResponse(BaseSchema):
+    """Tracing statistics response."""
+
+    enabled: bool = Field(..., description="Whether tracing is enabled")
+    total_traces: int = Field(default=0, ge=0, description="Total traces")
+    total_spans: int = Field(default=0, ge=0, description="Total spans")
+    avg_trace_duration_ms: float | None = Field(
+        default=None, description="Average trace duration"
+    )
+    traces_today: int = Field(default=0, ge=0, description="Traces today")
+    error_rate: float = Field(
+        default=0.0, ge=0, le=1, description="Error span rate"
+    )
+    by_service: dict[str, int] = Field(
+        default_factory=dict, description="Spans by service"
+    )
+
+
+# =============================================================================
+# Combined Statistics
+# =============================================================================
+
+
+class ObservabilityStatsResponse(BaseSchema):
+    """Combined observability statistics."""
+
+    audit: AuditStatsResponse = Field(
+        default_factory=AuditStatsResponse,
+        description="Audit statistics",
+    )
+    store_metrics: StoreMetricsResponse = Field(
+        default_factory=StoreMetricsResponse,
+        description="Store metrics",
+    )
+    tracing: TracingStatsResponse | None = Field(
+        default=None,
+        description="Tracing statistics (if enabled)",
+    )
+    last_updated: datetime = Field(..., description="Last update timestamp")