nat-engine 1__py3-none-any.whl

mannf/product/dashboard/models.py

@@ -0,0 +1,460 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Pydantic models for the NAT web dashboard data layer."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class DashboardSummary(BaseModel):
+    """Overall system statistics shown in the overview bar."""
+
+    total_scans: int = 0
+    endpoints_discovered: int = 0
+    anomalies_found: int = 0
+    avg_risk_score: float = 0.0
+    total_tests_run: int = 0
+    pass_rate: float = 0.0
+    active_anomalies: int = 0
+    last_scan_at: Optional[str] = None
+    health_score: float = 1.0
+
+
+class EndpointRiskCard(BaseModel):
+    """Per-endpoint card data for the risk heatmap."""
+
+    endpoint: str
+    risk_score: float
+    fault_rate: float
+    belief_signal: float
+    latency_signal: float
+    diversity_signal: float
+    trend: str
+    run_count: int
+    fault_count: int
+    anomaly_count: int = 0
+    last_test_result: Optional[str] = None
+
+
+class BeliefStateSnapshot(BaseModel):
+    """Agent belief state data formatted for visualization."""
+
+    agent_id: str
+    agent_role: str
+    beliefs: Dict[str, Any] = Field(default_factory=dict)
+    active: bool = True
+    current_task: Optional[str] = None
+    endpoints_assigned: List[str] = Field(default_factory=list)
+    confidence: float = 0.5
+    # Telemetry-enriched fields (populated by the real-time broadcast path)
+    confidence_per_service: Dict[str, float] = Field(default_factory=dict)
+    intentions: List[Dict[str, Any]] = Field(default_factory=list)
+    desires: Dict[str, float] = Field(default_factory=dict)
+    entropy: float = 0.0
+    timestamp: Optional[str] = None
+
+
+class AnomalyTimelineEntry(BaseModel):
+    """An anomaly event for the timeline display."""
+
+    endpoint: str
+    anomaly_type: str
+    severity: str
+    score: float
+    description: str
+    detected_at: str
+    scan_id: Optional[str] = None
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Functional Testing Results models
+# ---------------------------------------------------------------------------
+
+
+class VisualDiffEntry(BaseModel):
+    """A single visual regression comparison result."""
+
+    task_id: str
+    baseline_url: Optional[str] = None
+    current_url: Optional[str] = None
+    diff_url: Optional[str] = None
+    diff_percent: float = 0.0
+    passed: bool = True
+
+
+class A11yViolationSummary(BaseModel):
+    """Aggregated accessibility violation counts by severity."""
+
+    critical: int = 0
+    serious: int = 0
+    moderate: int = 0
+    minor: int = 0
+    total: int = 0
+    sample_violations: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+class PerfMetrics(BaseModel):
+    """Performance scorecard (Core Web Vitals + TTFB)."""
+
+    lcp_ms: Optional[float] = None   # Largest Contentful Paint
+    fid_ms: Optional[float] = None   # First Input Delay
+    cls: Optional[float] = None      # Cumulative Layout Shift
+    ttfb_ms: Optional[float] = None  # Time to First Byte
+
+
+class FunctionalTestItem(BaseModel):
+    """Per-task outcome row in the functional testing results."""
+
+    task_id: str
+    task_name: str
+    passed: bool
+    duration_ms: Optional[float] = None
+    error: Optional[str] = None
+    artifact_url: Optional[str] = None
+
+
+class FunctionalTestResult(BaseModel):
+    """Aggregated functional testing results for the dashboard."""
+
+    run_id: Optional[str] = None
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    total: int = 0
+    passed: int = 0
+    failed: int = 0
+    pass_rate: float = 0.0
+    items: List[FunctionalTestItem] = Field(default_factory=list)
+    visual_diffs: List[VisualDiffEntry] = Field(default_factory=list)
+    a11y: Optional[A11yViolationSummary] = None
+    perf: Optional[PerfMetrics] = None
+
+
+# ---------------------------------------------------------------------------
+# Usage & Billing models
+# ---------------------------------------------------------------------------
+
+
+class InvoiceEntry(BaseModel):
+    """A single invoice row for the billing tab."""
+
+    invoice_id: str
+    date: str
+    amount_cents: int
+    currency: str = "usd"
+    status: str  # "paid", "open", "void", etc.
+    pdf_url: Optional[str] = None
+
+
+class UsageSummary(BaseModel):
+    """Usage gauge data for the billing tab."""
+
+    plan_name: str = "Free"
+    plan_tier: str = "free"
+    functional_used: int = 0
+    functional_quota: int = 0
+    security_used: int = 0
+    security_quota: int = 0
+    functional_percent: float = 0.0
+    security_percent: float = 0.0
+    approaching_limit: bool = False
+    quota_reset_date: Optional[str] = None
+    stripe_portal_url: Optional[str] = None
+    invoices: List[InvoiceEntry] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Onboarding / Getting Started models
+# ---------------------------------------------------------------------------
+
+
+class OnboardingStep(BaseModel):
+    """A single step in the onboarding checklist."""
+
+    step: int
+    title: str
+    description: str
+    completed: bool = False
+    action_label: Optional[str] = None
+    action_url: Optional[str] = None
+    code_snippet: Optional[str] = None
+
+
+class OnboardingStatus(BaseModel):
+    """Onboarding checklist completion state."""
+
+    steps: List[OnboardingStep] = Field(default_factory=list)
+    completed_count: int = 0
+    total_count: int = 0
+    api_key_masked: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Scenario Suggestion / Discovery models (Phase 3)
+# ---------------------------------------------------------------------------
+
+
+class DiscoveryRequest(BaseModel):
+    """Request body for POST /api/v1/discover."""
+
+    url: str
+    max_pages: int = 50
+    max_depth: int = 5
+    include_negative: bool = True
+    include_boundary: bool = True
+    # Optional LLM configuration for AI-enhanced scenario generation
+    llm_provider: Optional[str] = None  # e.g. "openai" or "anthropic"
+    llm_api_key: Optional[str] = None
+    llm_model: Optional[str] = None
+
+
+class AutonomousRequest(BaseModel):
+    """Request body for POST /api/v1/autonomous/start."""
+
+    url: str
+    strategy: str = "all"  # "all", "high_risk", "new_changed", "belief_targeted"
+    max_iterations: int = 5
+    max_duration_s: float = 600.0
+    max_pages: int = 50
+    max_depth: int = 5
+    headless: bool = True
+    risk_threshold: float = 0.6
+    llm_provider: Optional[str] = None
+    llm_api_key: Optional[str] = None
+    llm_model: Optional[str] = None
+    # Deploy / commit attribution (Phase 6.3)
+    build_id: Optional[str] = None
+    commit_sha: Optional[str] = None
+    deploy_tag: Optional[str] = None
+
+
+class DiscoveryScenario(BaseModel):
+    """A single suggested functional test scenario."""
+
+    scenario_id: str
+    url: str
+    steps: List[Dict[str, Any]] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    selected: bool = True
+    confidence: float = 0.5
+    risk_score: float = 0.5
+
+
+class DiscoveryResult(BaseModel):
+    """In-memory record for a single discovery crawl + scenario generation run."""
+
+    discovery_id: str
+    status: str  # "running", "complete", "failed"
+    base_url: str
+    scenarios: List[DiscoveryScenario] = Field(default_factory=list)
+    stats: Dict[str, int] = Field(default_factory=dict)
+    created_at: str
+    error: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Bug Filing / Triage models (Phase 6.4)
+# ---------------------------------------------------------------------------
+
+
+class BugFilingConfig(BaseModel):
+    """Configuration for the auto-bug-filing pipeline.
+
+    Controls *which* failures get filed, *where* they go, and whether they
+    need manual approval before a ticket is created.
+    """
+
+    enabled: bool = False
+    """Master switch — no tickets are created when ``False``."""
+
+    target_system: str = "github"
+    """Ticket destination: ``"github"``, ``"jira"``, or ``"webhook"``."""
+
+    exporter_config: Dict[str, Any] = Field(default_factory=dict)
+    """System-specific config passed directly to the chosen exporter plugin."""
+
+    severity_threshold: str = "high"
+    """Minimum failure severity to file (``"critical"``, ``"high"``, ``"medium"``, ``"low"``)."""
+
+    auto_file: bool = True
+    """When ``True``, tickets are created automatically.
+    When ``False``, failures land in the pending-approval queue."""
+
+    deduplicate: bool = True
+    """When ``True``, the pipeline checks for an existing open ticket with the
+    same fingerprint before creating a new one."""
+
+
+class FiledBugEntry(BaseModel):
+    """A successfully auto-filed bug ticket."""
+
+    bug_id: str
+    """Internal UUID for this filing record."""
+
+    run_id: str
+    """Autonomous run that produced the failure."""
+
+    fingerprint: str
+    """Deterministic sha256 fingerprint of the failure."""
+
+    failure: Dict[str, Any] = Field(default_factory=dict)
+    """The original failure dict from ``AutonomousRunReport.unique_failures``."""
+
+    target_system: str
+    """Exporter used: ``"github"``, ``"jira"``, etc."""
+
+    external_id: Optional[str] = None
+    """Ticket ID in the external system (e.g. ``"NAT-42"`` or ``"99"``)."""
+
+    external_url: Optional[str] = None
+    """Direct link to the ticket in the external system."""
+
+    severity: str = "low"
+    filed_at: str = ""
+    was_duplicate: bool = False
+    """``True`` when this was a known duplicate — a comment was added instead of a new ticket."""
+
+
+class PendingBugEntry(BaseModel):
+    """A failure awaiting manual approval before a ticket is created."""
+
+    bug_id: str
+    """Internal UUID for this pending record."""
+
+    run_id: str
+    """Autonomous run that produced the failure."""
+
+    fingerprint: str
+    """Deterministic sha256 fingerprint of the failure."""
+
+    failure: Dict[str, Any] = Field(default_factory=dict)
+    """The original failure dict."""
+
+    severity: str = "low"
+    queued_at: str = ""
+    status: str = "pending"
+    """Lifecycle state: ``"pending"``, ``"approved"``, ``"dismissed"``."""
+
+
+# ---------------------------------------------------------------------------
+# ML/LLM Diagnostics models (Phase 6.5)
+# ---------------------------------------------------------------------------
+
+
+class BeliefTrend(BaseModel):
+    """Time-series entry for a single page's fault_likelihood over time."""
+
+    run_id: str
+    iteration: int
+    page_key: str
+    fault_likelihood: float
+    timestamp: str
+
+
+class FlakinessSummary(BaseModel):
+    """Flakiness statistics for a single page+scenario pair."""
+
+    page_key: str
+    scenario_id: str
+    is_flaky: bool
+    flake_rate: float
+    total_runs: int
+    pass_count: int
+    fail_count: int
+    alternations: int
+
+
+class FailureCluster(BaseModel):
+    """A cluster of failures sharing a similar error signature."""
+
+    cluster_id: str
+    label: str
+    representative_error: str
+    pages: List[str] = Field(default_factory=list)
+    size: int
+    failures: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+class RootCauseSuggestion(BaseModel):
+    """LLM-generated root cause suggestion for a failure."""
+
+    task_id: str = ""
+    url: str = ""
+    page: str = ""
+    likely_cause: str
+    suggested_fix: str
+    confidence: float
+    files_to_check: List[str] = Field(default_factory=list)
+
+
+class PredictiveRiskScore(BaseModel):
+    """Predicted failure probability for a page in the next run."""
+
+    page_key: str
+    predicted_failure_probability: float
+    belief_momentum: float
+    recent_failure_density: float
+    confidence: float
+
+
+# ---------------------------------------------------------------------------
+# Phase 7.4 — Confidence Calibration & Self-Validation models
+# ---------------------------------------------------------------------------
+
+
+class DismissedFinding(BaseModel):
+    """A finding dismissed by the user as a false positive."""
+
+    finding_id: str
+    """Unique identifier of the dismissed finding (from ``unique_failures`` or ``browser_security_findings``)."""
+
+    endpoint: str = ""
+    """Endpoint path/key the finding was associated with."""
+
+    dismissed_by: str = "user"
+    """Who dismissed the finding (user identifier or ``"user"`` if anonymous)."""
+
+    dismissed_at: str = ""
+    """ISO-8601 timestamp of the dismissal."""
+
+    run_id: str = ""
+    """Autonomous run that produced the finding."""
+
+    reason: str = ""
+    """Optional free-text reason supplied by the user."""
+
+
+class CalibrationBucket(BaseModel):
+    """A single bucket in the predicted-vs-actual reliability curve.
+
+    The bucket covers predictions in ``[bucket_low, bucket_high)``.
+    """
+
+    bucket_low: float
+    bucket_high: float
+    predicted_count: int
+    """Number of predictions falling in this bucket."""
+    actual_failure_rate: Optional[float] = None
+    """Observed fraction of failures among the predictions in this bucket.
+    ``None`` when no actual outcomes are available (sparse data)."""
+    mean_predicted: Optional[float] = None
+    """Mean predicted failure probability within this bucket."""
+
+
+class CalibrationReport(BaseModel):
+    """Predicted-vs-actual reliability curve for the calibration dashboard view."""
+
+    buckets: List[CalibrationBucket] = Field(default_factory=list)
+    total_predictions: int = 0
+    total_with_outcomes: int = 0
+    brier_score: Optional[float] = None
+    """Mean squared error between predicted probabilities and actual outcomes.
+    Lower is better (0 = perfect).  ``None`` when no actual outcomes are available."""
+    generated_at: str = ""
+