Initial commit

srcs/RobotNet10/Shared/RobotNet10.NavigationTune.Shared/Models/TuningAdvisorModels.cs

@@ -0,0 +1,156 @@
+namespace RobotNet10.NavigationTune.Shared.Models;
+
+/// <summary>
+/// Priority level for tuning suggestions.
+/// </summary>
+public enum SuggestionPriority
+{
+    Low = 0,
+    Medium = 1,
+    High = 2,
+    Critical = 3
+}
+
+/// <summary>
+/// Category of the diagnostic pattern detected from telemetry analysis.
+/// </summary>
+public enum DiagnosticCategory
+{
+    Oscillation,
+    LargeCTE,
+    CornerCutting,
+    GoalOvershoot,
+    SluggishResponse,
+    JerkyMotion,
+    VelocityEstimation,
+    GoalHeadingError,
+    PathEfficiency
+}
+
+/// <summary>
+/// A detected behavioral pattern from telemetry analysis.
+/// </summary>
+public class DiagnosticPattern
+{
+    public DiagnosticCategory Category { get; set; }
+
+    /// <summary>Human-readable description of what was detected.</summary>
+    public string Description { get; set; } = string.Empty;
+
+    /// <summary>Severity of the pattern (0.0 = negligible, 1.0 = critical).</summary>
+    public double Severity { get; set; }
+
+    /// <summary>Evidence values that led to the detection (e.g., oscillation frequency, CTE values).</summary>
+    public Dictionary<string, double> Evidence { get; set; } = new();
+
+    /// <summary>Which navigation phase this pattern was detected in (null = all phases combined).</summary>
+    public TelemetryPhase? DetectedInPhase { get; set; }
+}
+
+/// <summary>
+/// A single parameter adjustment suggestion.
+/// </summary>
+public class TuningSuggestion
+{
+    public Guid Id { get; set; } = Guid.NewGuid();
+
+    /// <summary>
+    /// Dot-path to the parameter, e.g., "PurePursuitConfig.LookaheadMin" or "StanleyConfig.K".
+    /// </summary>
+    public string ParameterPath { get; set; } = string.Empty;
+
+    /// <summary>Display name for the parameter.</summary>
+    public string ParameterDisplayName { get; set; } = string.Empty;
+
+    /// <summary>Current value of the parameter.</summary>
+    public double CurrentValue { get; set; }
+
+    /// <summary>Suggested new value.</summary>
+    public double SuggestedValue { get; set; }
+
+    /// <summary>Human-readable reason for the suggestion.</summary>
+    public string Reason { get; set; } = string.Empty;
+
+    /// <summary>Priority of this suggestion.</summary>
+    public SuggestionPriority Priority { get; set; }
+
+    /// <summary>Confidence in this suggestion (0.0 - 1.0).</summary>
+    public double Confidence { get; set; }
+
+    /// <summary>Which diagnostic pattern(s) triggered this suggestion.</summary>
+    public List<DiagnosticCategory> RelatedPatterns { get; set; } = new();
+
+    /// <summary>Expected impact description.</summary>
+    public string ExpectedImpact { get; set; } = string.Empty;
+
+    /// <summary>Which navigation phase this suggestion targets (null = general).</summary>
+    public TelemetryPhase? TargetPhase { get; set; }
+
+    /// <summary>Percentage change from current to suggested.</summary>
+    public double ChangePercent => CurrentValue != 0
+        ? ((SuggestedValue - CurrentValue) / Math.Abs(CurrentValue)) * 100.0
+        : 0;
+}
+
+/// <summary>
+/// Per-phase metrics computed from telemetry for phase-aware tuning analysis.
+/// </summary>
+public class PhaseMetrics
+{
+    public TelemetryPhase Phase { get; set; }
+    public int SampleCount { get; set; }
+    public double DurationMs { get; set; }
+
+    // Tracking
+    public double CrossTrackErrorRMS { get; set; }
+    public double CrossTrackErrorPeak { get; set; }
+    public double CrossTrackErrorMean { get; set; }
+    public double HeadingErrorRMS { get; set; }
+    public double HeadingErrorPeak { get; set; }
+
+    // Smoothness
+    public double AngularVelocityStdDev { get; set; }
+    public double VelocityStdDev { get; set; }
+    public double AccelerationStdDev { get; set; }
+
+    // Goal (FinalApproach/FinalRotation only)
+    public double GoalPositionError { get; set; }
+    public double GoalHeadingErrorDeg { get; set; }
+}
+
+/// <summary>
+/// Complete tuning analysis report for a test run.
+/// </summary>
+public class TuningReport
+{
+    public Guid Id { get; set; } = Guid.NewGuid();
+    public Guid TestRunId { get; set; }
+    public DateTime GeneratedAt { get; set; } = DateTime.UtcNow;
+
+    /// <summary>Which controller was active during the test.</summary>
+    public PathFollowingController ControllerType { get; set; }
+
+    /// <summary>Overall assessment of the test quality.</summary>
+    public string OverallAssessment { get; set; } = string.Empty;
+
+    /// <summary>Detected diagnostic patterns from telemetry analysis.</summary>
+    public List<DiagnosticPattern> DetectedPatterns { get; set; } = new();
+
+    /// <summary>Ordered list of suggestions (highest priority first).</summary>
+    public List<TuningSuggestion> Suggestions { get; set; } = new();
+
+    /// <summary>Number of telemetry samples analyzed.</summary>
+    public int TelemetrySamplesAnalyzed { get; set; }
+
+    /// <summary>Sample count per navigation phase.</summary>
+    public Dictionary<TelemetryPhase, int> PhaseSampleCounts { get; set; } = new();
+
+    /// <summary>Per-phase metrics computed from telemetry.</summary>
+    public Dictionary<TelemetryPhase, PhaseMetrics> PhaseMetricsMap { get; set; } = new();
+
+    /// <summary>Whether any critical issues were detected.</summary>
+    public bool HasCriticalIssues => Suggestions.Any(s => s.Priority == SuggestionPriority.Critical);
+
+    /// <summary>Count of high+ priority suggestions.</summary>
+    public int HighPriorityCount => Suggestions.Count(s => s.Priority >= SuggestionPriority.High);
+}