@ngocsangairvds/vsaf 3.2.16 → 4.0.1

package/tools/vds-scripts/memory_orchestrator/src/vds_memory_orchestrator/service/models/analytics_models.py

@@ -1,766 +0,0 @@
-"""
-VDS AI Memory Analytics Models
-
-Defines Pydantic models for comprehensive analytics, metrics,
-dashboards, and insights generation.
-"""
-
-import uuid
-from datetime import UTC, datetime
-from enum import StrEnum
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict, Field
-
-
-class MetricType(StrEnum):
-    """Types of analytics metrics."""
-
-    COUNT = "count"
-    AVERAGE = "average"
-    SUM = "sum"
-    PERCENTAGE = "percentage"
-    RATE = "rate"
-    DURATION = "duration"
-    SCORE = "score"
-    DISTRIBUTION = "distribution"
-
-
-class ChartType(StrEnum):
-    """Types of visualization charts."""
-
-    LINE = "line"
-    BAR = "bar"
-    PIE = "pie"
-    AREA = "area"
-    SCATTER = "scatter"
-    HEATMAP = "heatmap"
-    TREEMAP = "treemap"
-    GAUGE = "gauge"
-    KPI = "kpi"
-    TABLE = "table"
-
-
-class TimeGranularity(StrEnum):
-    """Time granularity for analytics."""
-
-    HOURLY = "hourly"
-    DAILY = "daily"
-    WEEKLY = "weekly"
-    MONTHLY = "monthly"
-    QUARTERLY = "quarterly"
-    YEARLY = "yearly"
-
-
-class TrendDirection(StrEnum):
-    """Trend direction indicators."""
-
-    UP = "up"
-    DOWN = "down"
-    STABLE = "stable"
-    FLUCTUATING = "fluctuating"
-
-
-class AnalyticsScope(StrEnum):
-    """Scope of analytics data."""
-
-    USER = "user"
-    TEAM = "team"
-    ORGANIZATION = "organization"
-    GLOBAL = "global"
-
-
-class MemoryMetric(BaseModel):
-    """Individual memory metric with context."""
-
-    name: str = Field(..., description="Metric name")
-    value: int | float | str = Field(..., description="Metric value")
-    metric_type: MetricType = Field(..., description="Type of metric")
-    unit: str | None = Field(None, description="Unit of measurement")
-    trend_direction: TrendDirection | None = Field(None, description="Trend direction")
-    trend_percentage: float | None = Field(None, description="Trend percentage change")
-    comparison_period: str | None = Field(None, description="Comparison period")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
-    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
-
-
-class UserActivityMetrics(BaseModel):
-    """User-specific activity metrics."""
-
-    user_id: uuid.UUID = Field(..., description="User ID")
-    total_memories: int = Field(..., description="Total memories created")
-    memories_created_today: int = Field(..., description="Memories created today")
-    memories_this_week: int = Field(..., description="Memories created this week")
-    memories_this_month: int = Field(..., description="Memories created this month")
-    avg_memories_per_day: float = Field(..., description="Average memories per day")
-    most_active_hour: int = Field(..., description="Most active hour (0-23)")
-    most_active_day: str = Field(..., description="Most active day of week")
-    total_searches: int = Field(..., description="Total searches performed")
-    avg_search_results: float = Field(..., description="Average search results")
-    search_success_rate: float = Field(..., description="Search success rate")
-    shared_memories: int = Field(..., description="Total memories shared")
-    collaboration_count: int = Field(..., description="Collaboration activities")
-    export_count: int = Field(..., description="Export operations")
-    import_count: int = Field(..., description="Import operations")
-    last_activity: datetime = Field(..., description="Last activity timestamp")
-    activity_streak: int = Field(..., description="Current activity streak in days")
-
-
-class MemoryContentAnalytics(BaseModel):
-    """Analytics about memory content."""
-
-    total_memories: int = Field(..., description="Total memories analyzed")
-    avg_content_length: float = Field(..., description="Average content length")
-    avg_title_length: float = Field(..., description="Average title length")
-    most_used_categories: list[dict[str, Any]] = Field(..., description="Most used categories")
-    category_distribution: dict[str, int] = Field(..., description="Category distribution")
-    importance_distribution: dict[str, int] = Field(..., description="Importance distribution")
-    tag_frequency: dict[str, int] = Field(..., description="Tag frequency analysis")
-    content_language_distribution: dict[str, int] = Field(
-        ..., description="Content language distribution"
-    )
-    sentiment_distribution: dict[str, int] = Field(..., description="Sentiment analysis")
-    content_themes: list[str] = Field(..., description="Identified content themes")
-    growth_metrics: dict[str, float] = Field(..., description="Content growth metrics")
-
-
-class SearchAnalytics(BaseModel):
-    """Search behavior analytics."""
-
-    total_searches: int = Field(..., description="Total searches performed")
-    unique_queries: int = Field(..., description="Unique search queries")
-    avg_results_per_search: float = Field(..., description="Average results per search")
-    search_success_rate: float = Field(..., description="Percentage of successful searches")
-    no_result_queries: int = Field(..., description="Queries with no results")
-    popular_search_terms: list[dict[str, Any]] = Field(..., description="Most popular search terms")
-    search_algorithm_usage: dict[str, int] = Field(..., description="Algorithm usage stats")
-    filter_usage: dict[str, int] = Field(..., description="Filter usage statistics")
-    avg_search_duration: float = Field(..., description="Average search duration")
-    search_trends: list[dict[str, Any]] = Field(..., description="Search trends over time")
-    query_patterns: list[str] = Field(..., description="Common query patterns")
-    seasonal_trends: dict[str, Any] = Field(..., description="Seasonal search patterns")
-
-
-class CollaborationAnalytics(BaseModel):
-    """Collaboration and sharing analytics."""
-
-    total_shares: int = Field(..., description="Total memories shared")
-    shared_with_users: int = Field(..., description="Unique users shared with")
-    shared_with_teams: int = Field(..., description="Unique teams shared with")
-    public_shares: int = Field(..., description="Public memory shares")
-    collaboration_sessions: int = Field(..., description="Collaboration sessions")
-    concurrent_collaborations: int = Field(..., description="Maximum concurrent collaborations")
-    avg_collaboration_duration: float = Field(..., description="Average collaboration duration")
-    most_collaborative_memories: list[dict[str, Any]] = Field(
-        ..., description="Most collaborated memories"
-    )
-    collaboration_success_rate: float = Field(..., description="Successful collaboration rate")
-    permission_changes: int = Field(..., description="Permission modification count")
-    external_collaborations: int = Field(..., description="External user collaborations")
-
-
-class PerformanceAnalytics(BaseModel):
-    """System performance analytics."""
-
-    avg_response_time: float = Field(..., description="Average response time")
-    p95_response_time: float = Field(..., description="95th percentile response time")
-    p99_response_time: float = Field(..., description="99th percentile response time")
-    error_rate: float = Field(..., description="Error rate percentage")
-    throughput: float = Field(..., description="Requests per second")
-    concurrent_users: int = Field(..., description="Current concurrent users")
-    cache_hit_rate: float = Field(..., description="Cache hit rate")
-    database_performance: dict[str, float] = Field(..., description="Database performance metrics")
-    api_performance: dict[str, float] = Field(..., description="API endpoint performance")
-    memory_usage: dict[str, Any] = Field(..., description="Memory usage statistics")
-    cpu_usage: dict[str, Any] = Field(..., description="CPU usage statistics")
-    storage_metrics: dict[str, Any] = Field(..., description="Storage usage and trends")
-
-
-class UsageTrend(BaseModel):
-    """Individual usage trend data point."""
-
-    timestamp: datetime = Field(..., description="Timestamp for the trend point")
-    value: int | float = Field(..., description="Trend value")
-    metric_name: str = Field(..., description="Name of the metric")
-    granularity: TimeGranularity = Field(..., description="Time granularity")
-    comparison_value: int | float | None = Field(
-        None, description="Previous period value for comparison"
-    )
-    change_percentage: float | None = Field(None, description="Percentage change")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional context")
-
-
-class TrendAnalysis(BaseModel):
-    """Comprehensive trend analysis."""
-
-    metric_name: str = Field(..., description="Metric being analyzed")
-    time_period: str = Field(..., description="Analysis time period")
-    granularity: TimeGranularity = Field(..., description="Data granularity")
-    trend_direction: TrendDirection = Field(..., description="Overall trend direction")
-    growth_rate: float = Field(..., description="Growth rate percentage")
-    seasonal_pattern: bool | None = Field(None, description="Seasonal pattern detected")
-    volatility_score: float = Field(..., description="Volatility score (0-1)")
-    forecast_next_period: int | float | None = Field(None, description="Forecasted next value")
-    confidence_interval: dict[str, float] | None = Field(
-        None, description="Confidence interval for forecast"
-    )
-    trend_points: list[UsageTrend] = Field(..., description="Individual trend data points")
-    insights: list[str] = Field(..., description="Generated insights from trend analysis")
-
-
-class PredictiveMetric(BaseModel):
-    """Predictive analytics output for a metric."""
-
-    metric_name: str = Field(..., description="Metric being predicted")
-    horizon_hours: int = Field(..., description="Forecast horizon in hours")
-    current_value: float = Field(..., description="Most recent observed value")
-    forecast_value: float = Field(..., description="Predicted next value")
-    confidence_interval: dict[str, float] = Field(
-        default_factory=dict, description="Forecast confidence interval"
-    )
-    trend_direction: TrendDirection = Field(..., description="Detected trend direction")
-    growth_rate: float = Field(..., description="Growth rate percentage")
-    risk_level: str = Field(..., description="Risk assessment (low/medium/high)")
-    insights: list[str] = Field(default_factory=list, description="Supporting predictive insights")
-
-
-class InsightCategory(StrEnum):
-    """Categories of insights."""
-
-    USAGE = "usage"
-    PERFORMANCE = "performance"
-    COLLABORATION = "collaboration"
-    CONTENT = "content"
-    EFFICIENCY = "efficiency"
-    GROWTH = "growth"
-    ANOMALY = "anomaly"
-    OPPORTUNITY = "opportunity"
-
-
-class InsightSeverity(StrEnum):
-    """Severity levels for insights."""
-
-    INFO = "info"
-    LOW = "low"
-    MEDIUM = "medium"
-    # Phase 196: WARNING is referenced 13 times in analytics_service.py
-    # (cache-hit-rate, error-rate, repush-stalled insights). It was missing from
-    # the enum, causing AttributeError at runtime. Aliased to "medium" semantics
-    # — distinct from a generic INFO/MEDIUM but tracked under a recognizable label.
-    WARNING = "warning"
-    HIGH = "high"
-    CRITICAL = "critical"
-
-
-class GeneratedInsight(BaseModel):
-    """AI-generated insight from analytics data."""
-
-    id: uuid.UUID = Field(default_factory=uuid.uuid4, description="Insight ID")
-    title: str = Field(..., description="Insight title")
-    description: str = Field(..., description="Detailed insight description")
-    category: InsightCategory = Field(..., description="Insight category")
-    severity: InsightSeverity = Field(..., description="Insight severity")
-    confidence_score: float = Field(..., ge=0.0, le=1.0, description="Confidence in insight")
-    supporting_metrics: list[str] = Field(..., description="Metrics supporting this insight")
-    recommendations: list[str] = Field(..., description="Actionable recommendations")
-    impact_assessment: str | None = Field(None, description="Potential impact assessment")
-    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    expires_at: datetime | None = Field(None, description="When insight expires")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional context")
-
-
-class ChartData(BaseModel):
-    """Data structure for chart visualization."""
-
-    chart_type: ChartType = Field(..., description="Type of chart")
-    title: str = Field(..., description="Chart title")
-    data_points: list[dict[str, Any]] = Field(..., description="Chart data points")
-    x_axis_label: str | None = Field(None, description="X-axis label")
-    y_axis_label: str | None = Field(None, description="Y-axis label")
-    series: list[dict[str, Any]] = Field(
-        default_factory=list, description="Data series for multi-series charts"
-    )
-    colors: list[str] = Field(default_factory=list, description="Color palette")
-    annotations: list[dict[str, Any]] = Field(default_factory=list, description="Chart annotations")
-    interactive_features: list[str] = Field(
-        default_factory=list, description="Interactive features"
-    )
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional chart metadata")
-
-
-class DashboardWidget(BaseModel):
-    """Individual dashboard widget."""
-
-    widget_id: str = Field(..., description="Widget identifier")
-    widget_type: str = Field(..., description="Widget type (chart, metric, table, etc.)")
-    title: str = Field(..., description="Widget title")
-    position: dict[str, int] = Field(..., description="Widget position (x, y, width, height)")
-    data: MemoryMetric | ChartData | dict[str, Any] | list[dict[str, Any]] = Field(
-        ..., description="Widget data"
-    )
-    refresh_interval: int | None = Field(None, description="Refresh interval in seconds")
-    interactive: bool = Field(True, description="Whether widget is interactive")
-    drill_down_available: bool = Field(False, description="Whether drill-down is available")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional widget metadata")
-
-
-class AnalyticsDashboard(BaseModel):
-    """Complete analytics dashboard."""
-
-    dashboard_id: uuid.UUID = Field(default_factory=uuid.uuid4, description="Dashboard ID")
-    title: str = Field(..., description="Dashboard title")
-    description: str | None = Field(None, description="Dashboard description")
-    scope: AnalyticsScope = Field(..., description="Dashboard scope")
-    user_id: uuid.UUID | None = Field(None, description="User ID for user-scoped dashboards")
-    widgets: list[DashboardWidget] = Field(..., description="Dashboard widgets")
-    layout: dict[str, Any] = Field(..., description="Dashboard layout configuration")
-    filters: dict[str, Any] = Field(default_factory=dict, description="Available filters")
-    time_range: dict[str, Any] = Field(..., description="Default time range")
-    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    last_refresh: datetime | None = Field(None, description="Last data refresh timestamp")
-    is_public: bool = Field(False, description="Whether dashboard is public")
-    metadata: dict[str, Any] = Field(
-        default_factory=dict, description="Additional dashboard metadata"
-    )
-
-
-class DashboardCreateRequest(BaseModel):
-    """Request payload for creating dashboards."""
-
-    title: str = Field(..., description="Dashboard title")
-    description: str | None = Field(None, description="Optional description")
-    scope: AnalyticsScope = Field(AnalyticsScope.USER, description="Dashboard scope")
-    widgets: list[dict[str, Any]] = Field(..., description="Widget definitions")
-    layout: dict[str, Any] | None = Field(None, description="Layout configuration")
-    filters: dict[str, Any] | None = Field(None, description="Filter configuration")
-    time_range: dict[str, Any] | None = Field(None, description="Time range presets")
-    is_public: bool = Field(False, description="Whether dashboard is publicly shareable")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
-
-
-class AnalyticsReport(BaseModel):
-    """Comprehensive analytics report."""
-
-    report_id: uuid.UUID = Field(default_factory=uuid.uuid4, description="Report ID")
-    title: str = Field(..., description="Report title")
-    description: str = Field(..., description="Report description")
-    time_period: dict[str, datetime] = Field(..., description="Report time period")
-    scope: AnalyticsScope = Field(..., description="Report scope")
-    user_id: uuid.UUID | None = Field(None, description="User ID for user-specific reports")
-
-    # Analytics sections
-    user_metrics: UserActivityMetrics | None = Field(None, description="User activity metrics")
-    content_analytics: MemoryContentAnalytics | None = Field(None, description="Content analytics")
-    search_analytics: SearchAnalytics | None = Field(None, description="Search analytics")
-    collaboration_analytics: CollaborationAnalytics | None = Field(
-        None, description="Collaboration analytics"
-    )
-    performance_analytics: PerformanceAnalytics | None = Field(
-        None, description="Performance analytics"
-    )
-
-    # Insights and trends
-    generated_insights: list[GeneratedInsight] = Field(
-        default_factory=list, description="AI-generated insights"
-    )
-    trend_analyses: list[TrendAnalysis] = Field(default_factory=list, description="Trend analyses")
-
-    # Visualizations
-    charts: list[ChartData] = Field(default_factory=list, description="Report charts")
-
-    # Metadata
-    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    generated_by: str = Field(..., description="Who generated the report")
-    report_format: str = Field("digital", description="Report format")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional report metadata")
-
-
-class ReportFormat(StrEnum):
-    """Supported analytics report formats."""
-
-    DIGITAL = "digital"
-    PDF = "pdf"
-    HTML = "html"
-    MARKDOWN = "markdown"
-    CSV = "csv"
-
-
-class ReportTemplate(BaseModel):
-    """Stored analytics report template."""
-
-    template_id: uuid.UUID = Field(default_factory=uuid.uuid4, description="Template ID")
-    name: str = Field(..., description="Template name")
-    description: str | None = Field(None, description="Template description")
-    owner_id: uuid.UUID | None = Field(None, description="Owning user id")
-    scope: AnalyticsScope = Field(AnalyticsScope.USER, description="Scope for generated reports")
-    metric_names: list[str] = Field(..., description="Metrics included in this template")
-    granularity: TimeGranularity = Field(TimeGranularity.DAILY, description="Default granularity")
-    default_time_range_days: int = Field(30, ge=1, le=365, description="Default time range in days")
-    filters: dict[str, Any] = Field(default_factory=dict, description="Default filters")
-    include_forecasts: bool = Field(False, description="Include forecasts by default")
-    include_insights: bool = Field(True, description="Include insights by default")
-    delivery_format: ReportFormat = Field(
-        ReportFormat.DIGITAL, description="Preferred delivery format"
-    )
-    metadata: dict[str, Any] = Field(
-        default_factory=dict, description="Additional template metadata"
-    )
-    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-
-
-class ReportTemplateCreateRequest(BaseModel):
-    """Request payload for creating report templates."""
-
-    name: str = Field(..., description="Template name")
-    description: str | None = Field(None, description="Template description")
-    scope: AnalyticsScope = Field(AnalyticsScope.USER, description="Scope for template")
-    metric_names: list[str] = Field(..., description="Metrics to include")
-    granularity: TimeGranularity = Field(TimeGranularity.DAILY, description="Granularity")
-    default_time_range_days: int = Field(30, ge=1, le=365, description="Default days range")
-    filters: dict[str, Any] = Field(default_factory=dict, description="Default filters")
-    include_forecasts: bool = Field(False, description="Include forecasts")
-    include_insights: bool = Field(True, description="Include insights")
-    delivery_format: ReportFormat = Field(ReportFormat.DIGITAL, description="Delivery format")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Extra metadata")
-
-
-class ReportTemplateGenerateRequest(BaseModel):
-    """Overrides when generating a report from a stored template."""
-
-    time_range_days: int | None = Field(
-        None, ge=1, le=365, description="Override time range in days"
-    )
-    user_id: uuid.UUID | None = Field(None, description="Override user id")
-    include_forecasts: bool | None = Field(None, description="Override forecasts flag")
-    include_insights: bool | None = Field(None, description="Override insights flag")
-    filters: dict[str, Any] | None = Field(None, description="Additional filters")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
-
-
-class BusinessKPI(BaseModel):
-    """Business intelligence KPI metric."""
-
-    name: str = Field(..., description="KPI name")
-    value: float = Field(..., description="KPI value")
-    unit: str | None = Field(None, description="Unit of measurement")
-    change_percentage: float | None = Field(None, description="Change vs prior period")
-    trend: TrendDirection = Field(..., description="Trend direction")
-    status: str = Field(..., description="Status label (good/warning/critical)")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional context")
-
-
-class BusinessIntelligenceReport(BaseModel):
-    """Business intelligence overview report."""
-
-    scope: AnalyticsScope = Field(..., description="Scope of analysis")
-    generated_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC), description="Generation timestamp"
-    )
-    kpis: list[BusinessKPI] = Field(..., description="Key KPIs")
-    insights: list[GeneratedInsight] = Field(..., description="Actionable insights")
-    summary: dict[str, Any] = Field(default_factory=dict, description="Additional summary stats")
-
-
-class ExportConfiguration(BaseModel):
-    """Configuration for analytics export."""
-
-    format: str = Field(..., description="Export format (pdf, excel, csv, json)")
-    include_charts: bool = Field(True, description="Include charts in export")
-    include_raw_data: bool = Field(False, description="Include raw data tables")
-    include_insights: bool = Field(True, description="Include insights section")
-    date_range: dict[str, datetime] = Field(..., description="Data date range")
-    filters: dict[str, Any] = Field(default_factory=dict, description="Export filters")
-    branding: dict[str, Any] = Field(default_factory=dict, description="Custom branding options")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional export config")
-
-
-class AnalyticsExport(BaseModel):
-    """Analytics export job status."""
-
-    export_id: uuid.UUID = Field(default_factory=uuid.uuid4, description="Export job ID")
-    status: str = Field(..., description="Export status")
-    file_url: str | None = Field(None, description="Download URL when ready")
-    file_size: int | None = Field(None, description="File size in bytes")
-    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
-    completed_at: datetime | None = Field(None, description="Completion timestamp")
-    expires_at: datetime | None = Field(None, description="File expiration timestamp")
-    configuration: ExportConfiguration = Field(..., description="Export configuration")
-    error_message: str | None = Field(None, description="Error message if failed")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional export metadata")
-
-
-class RealTimeMetrics(BaseModel):
-    """Real-time system metrics."""
-
-    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC), description="Timestamp")
-    active_users: int = Field(..., description="Currently active users")
-    concurrent_searches: int = Field(..., description="Concurrent search operations")
-    memory_creation_rate: float = Field(..., description="Memory creations per minute")
-    search_rate: float = Field(..., description="Searches per minute")
-    avg_response_time: float = Field(..., description="Current average response time")
-    error_rate: float = Field(..., description="Current error rate")
-    system_load: float = Field(..., description="Current system load")
-    database_connections: int = Field(..., description="Active database connections")
-    cache_performance: dict[str, float] = Field(..., description="Cache performance metrics")
-    queue_depth: int = Field(..., description="Background queue depth")
-    metadata: dict[str, Any] = Field(
-        default_factory=dict, description="Additional real-time metrics"
-    )
-
-
-class AlertSeverity(StrEnum):
-    """Alert severity levels."""
-
-    INFO = "info"
-    WARNING = "warning"
-    ERROR = "error"
-    CRITICAL = "critical"
-
-
-class AnalyticsAlert(BaseModel):
-    """Analytics-based alert."""
-
-    alert_id: uuid.UUID = Field(default_factory=uuid.uuid4, description="Alert ID")
-    title: str = Field(..., description="Alert title")
-    message: str = Field(..., description="Alert message")
-    severity: AlertSeverity = Field(..., description="Alert severity")
-    metric_name: str = Field(..., description="Metric that triggered alert")
-    threshold_value: int | float = Field(..., description="Threshold that was exceeded")
-    current_value: int | float = Field(..., description="Current metric value")
-    triggered_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC),
-        description="When alert was triggered",
-    )
-    acknowledged: bool = Field(False, description="Whether alert was acknowledged")
-    acknowledged_by: uuid.UUID | None = Field(None, description="User who acknowledged")
-    acknowledged_at: datetime | None = Field(None, description="Acknowledgment timestamp")
-    resolved: bool = Field(False, description="Whether alert is resolved")
-    resolved_at: datetime | None = Field(None, description="Resolution timestamp")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional alert context")
-
-
-class KPIDefinition(BaseModel):
-    """Key Performance Indicator definition."""
-
-    kpi_id: str = Field(..., description="KPI identifier")
-    name: str = Field(..., description="KPI name")
-    description: str = Field(..., description="KPI description")
-    formula: str = Field(..., description="Calculation formula")
-    unit: str | None = Field(None, description="Unit of measurement")
-    target_value: int | float | None = Field(None, description="Target value")
-    threshold_warning: int | float | None = Field(None, description="Warning threshold")
-    threshold_critical: int | float | None = Field(None, description="Critical threshold")
-    category: str = Field(..., description="KPI category")
-    is_active: bool = Field(True, description="Whether KPI is active")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional KPI metadata")
-
-
-class KPIValue(BaseModel):
-    """KPI value with context."""
-
-    kpi_id: str = Field(..., description="KPI identifier")
-    current_value: int | float = Field(..., description="Current KPI value")
-    previous_value: int | float | None = Field(None, description="Previous period value")
-    target_value: int | float | None = Field(None, description="Target value")
-    percentage_of_target: float | None = Field(None, description="Percentage of target achieved")
-    trend_direction: TrendDirection | None = Field(None, description="Trend direction")
-    status: str = Field(..., description="Current status (good, warning, critical)")
-    calculated_at: datetime = Field(
-        default_factory=lambda: datetime.now(UTC),
-        description="When value was calculated",
-    )
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional value context")
-
-
-class AnalyticsRequest(BaseModel):
-    """Request for analytics data."""
-
-    metric_names: list[str] = Field(..., description="Metrics to retrieve")
-    time_range: dict[str, datetime] = Field(..., description="Time range for data")
-    granularity: TimeGranularity = Field(TimeGranularity.DAILY, description="Data granularity")
-    scope: AnalyticsScope = Field(AnalyticsScope.USER, description="Analytics scope")
-    user_id: uuid.UUID | None = Field(None, description="User ID for user-scoped requests")
-    team_id: uuid.UUID | None = Field(None, description="Team ID for team-scoped requests")
-    filters: dict[str, Any] = Field(default_factory=dict, description="Additional filters")
-    include_forecasts: bool = Field(False, description="Include forecasted values")
-    include_insights: bool = Field(True, description="Include AI-generated insights")
-    max_data_points: int = Field(1000, ge=1, le=10000, description="Maximum data points to return")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional request context")
-
-
-# ============================================================================
-# SEARCH ANALYTICS API MODELS (Phase 1 Implementation)
-# ============================================================================
-
-
-class SearchAnalyticsMetric(BaseModel):
-    """Individual search analytics metric point."""
-
-    timestamp: datetime = Field(..., description="Metric timestamp")
-    org_id: str = Field(..., description="Organization ID")
-    search_mode: str = Field(..., description="Search mode (mem0, pgvector, bm25, mem0-error)")
-    total_searches: int = Field(..., description="Total searches in this time bucket")
-    avg_latency_ms: float = Field(..., description="Average latency in milliseconds")
-    p95_latency_ms: float = Field(..., description="95th percentile latency")
-    p99_latency_ms: float | None = Field(None, description="99th percentile latency")
-    cache_hits: int = Field(..., description="Number of cache hits")
-    cache_misses: int = Field(..., description="Number of cache misses")
-    cache_hit_rate: float = Field(..., description="Cache hit rate percentage")
-    avg_results: float = Field(..., description="Average results per search")
-    unique_users: int = Field(..., description="Number of unique users")
-    error_count: int = Field(default=0, description="Number of errors")
-
-
-class SearchAnalyticsBreakdown(BaseModel):
-    """Search analytics breakdown by search mode."""
-
-    search_mode: str = Field(..., description="Search mode")
-    total_searches: int = Field(..., description="Total searches")
-    percentage: float = Field(..., description="Percentage of total searches")
-    avg_latency_ms: float = Field(..., description="Average latency")
-    cache_hit_rate: float = Field(..., description="Cache hit rate")
-    error_rate: float = Field(..., description="Error rate percentage")
-
-
-class SearchAnalyticsResponse(BaseModel):
-    """Complete search analytics response for /api/v1/analytics/search-analytics."""
-
-    time_period: dict[str, datetime] = Field(..., description="Query time period")
-    granularity: str = Field(..., description="Data granularity (hourly, daily)")
-    total_searches: int = Field(..., description="Total searches in period")
-    unique_users: int = Field(..., description="Number of unique users")
-    overall_avg_latency_ms: float = Field(..., description="Overall average latency")
-    overall_p95_latency_ms: float = Field(..., description="Overall 95th percentile latency")
-    overall_cache_hit_rate: float = Field(..., description="Overall cache hit rate")
-    error_rate: float = Field(..., description="Error rate percentage")
-    metrics: list[SearchAnalyticsMetric] = Field(..., description="Time-series metrics")
-    breakdown_by_mode: list[SearchAnalyticsBreakdown] = Field(
-        ..., description="Breakdown by search mode"
-    )
-
-    model_config = ConfigDict(
-        json_schema_extra={
-            "example": {
-                "time_period": {
-                    "start": "2026-01-01T00:00:00Z",
-                    "end": "2026-01-02T00:00:00Z",
-                },
-                "granularity": "hourly",
-                "total_searches": 15234,
-                "unique_users": 342,
-                "overall_avg_latency_ms": 145.2,
-                "overall_p95_latency_ms": 320.5,
-                "overall_cache_hit_rate": 78.5,
-                "error_rate": 0.12,
-                "metrics": [
-                    {
-                        "timestamp": "2026-01-01T08:00:00Z",
-                        "org_id": "vds-internal",
-                        "search_mode": "mem0",
-                        "total_searches": 423,
-                        "avg_latency_ms": 120.5,
-                        "p95_latency_ms": 280.0,
-                        "cache_hit_rate": 82.3,
-                        "avg_results": 12.4,
-                        "unique_users": 45,
-                    }
-                ],
-                "breakdown_by_mode": [
-                    {
-                        "search_mode": "mem0",
-                        "total_searches": 12034,
-                        "percentage": 79.0,
-                        "avg_latency_ms": 135.2,
-                        "cache_hit_rate": 82.1,
-                        "error_rate": 0.05,
-                    }
-                ],
-            }
-        }
-    )
-
-
-class OverviewMetric(BaseModel):
-    """Single overview metric."""
-
-    name: str = Field(..., description="Metric name")
-    value: int | float = Field(..., description="Current value")
-    previous_value: int | float | None = Field(None, description="Previous period value")
-    change_percentage: float | None = Field(None, description="Change from previous period")
-    trend: TrendDirection = Field(..., description="Trend direction")
-    unit: str | None = Field(None, description="Unit of measurement")
-
-
-class OverviewResponse(BaseModel):
-    """Complete overview response for /api/v1/analytics/overview."""
-
-    time_period: dict[str, datetime] = Field(..., description="Query time period")
-    metrics: OverviewMetric = Field(..., description="Key performance metrics")
-    search_analytics: SearchAnalyticsResponse = Field(..., description="Search analytics")
-    system_health: dict[str, Any] = Field(..., description="System health indicators")
-    alerts: list[GeneratedInsight] = Field(default_factory=list, description="Active alerts")
-
-    model_config = ConfigDict(
-        json_schema_extra={
-            "example": {
-                "time_period": {
-                    "start": "2026-01-01T00:00:00Z",
-                    "end": "2026-01-02T00:00:00Z",
-                },
-                "metrics": {
-                    "name": "Total Searches",
-                    "value": 15234,
-                    "previous_value": 14521,
-                    "change_percentage": 4.9,
-                    "trend": "up",
-                    "unit": "searches",
-                },
-                "search_analytics": {},
-                "system_health": {
-                    "database_status": "healthy",
-                    "redis_status": "healthy",
-                    "mem0_status": "operational",
-                    "queue_depth": 12,
-                },
-                "alerts": [],
-            }
-        }
-    )
-
-
-class AnalyticsMetadata(BaseModel):
-    """Metadata for analytics responses."""
-
-    last_updated: datetime = Field(..., description="When data was last refreshed")
-    hours_since_update: float = Field(..., description="Hours since last update")
-    freshness_status: str = Field(..., description="Freshness status (fresh, stale, critical)")
-    cache_status: str = Field(..., description="Cache status (hit, miss, bypass)")
-    data_lag_seconds: float | None = Field(None, description="Data lag in seconds")
-    refresh_time_ms: int | None = Field(None, description="Last refresh time in milliseconds")
-    next_refresh_at: datetime | None = Field(None, description="Next scheduled refresh time")
-
-
-class AnalyticsResponseWithMetadata(BaseModel):
-    """Analytics response wrapper with metadata."""
-
-    data: SearchAnalyticsResponse | OverviewResponse = Field(..., description="Analytics data")
-    metadata: AnalyticsMetadata = Field(..., description="Response metadata")
-
-    model_config = ConfigDict(
-        json_schema_extra={
-            "example": {
-                "data": {},
-                "metadata": {
-                    "last_updated": "2026-01-05T08:30:00Z",
-                    "hours_since_update": 0.5,
-                    "freshness_status": "fresh",
-                    "cache_status": "hit",
-                    "data_lag_seconds": 120,
-                    "refresh_time_ms": 45,
-                    "next_refresh_at": "2026-01-05T09:30:00Z",
-                },
-            }
-        }
-    )