aprender-serve 0.64.0

//! GGUF Part 08: PARITY-011 (Integration QA-041 to QA-050) + PARITY-012-017 (GPU Optimization)
//!
//! Extracted from gguf_monolith.rs (PMAT-802)

// ========================================================================
// PARITY-011: Integration QA-041 to QA-050 - Make Bench Targets
// ========================================================================
//
// Reference: docs/specifications/performance-parity-ollama-llamacpp-gpu-inference-llms.md
// Section E: Integration (Points 41-50)
// PARITY-011: Integration QA-041 to QA-050 - Make Bench Targets
//
// Reference: docs/specifications/performance-parity-ollama-llamacpp-gpu-inference-llms.md
// Section E: Integration (Points 41-50)

/// Test PARITY-011a: QA-041 bench-inference-all completes without error
///
/// Verifies that the master bench target orchestrates all sub-targets correctly.
#[test]
fn test_parity011a_bench_inference_all() {
    /// Represents a benchmark target in the Makefile
    #[derive(Debug, Clone)]
    struct BenchTarget {
        name: String,
        depends_on: Vec<String>,
        graceful_skip: bool,
    }

    impl BenchTarget {
        fn new(name: &str, depends_on: Vec<&str>, graceful_skip: bool) -> Self {
            Self {
                name: name.to_string(),
                depends_on: depends_on.iter().map(|s| (*s).to_string()).collect(),
                graceful_skip,
            }
        }
    }

    /// Master benchmark orchestrator
    struct BenchInferenceAll {
        targets: Vec<BenchTarget>,
    }

    impl BenchInferenceAll {
        fn standard() -> Self {
            Self {
                targets: vec![
                    BenchTarget::new("bench-pytorch-inference", vec![], false),
                    BenchTarget::new("bench-cpu-inference", vec![], false),
                    BenchTarget::new("bench-wgpu", vec![], true), // Graceful skip
                    BenchTarget::new("bench-gguf-gpu-inference", vec![], true),
                    BenchTarget::new("bench-apr-gpu-inference", vec![], false),
                ],
            }
        }

        fn run_all(&self, available: &[bool]) -> BenchRunResult {
            let mut result = BenchRunResult::default();

            for (target, &avail) in self.targets.iter().zip(available.iter()) {
                if avail {
                    result.passed.push(target.name.clone());
                } else if target.graceful_skip {
                    result.skipped.push(target.name.clone());
                } else {
                    result.failed.push(target.name.clone());
                }
            }

            result
        }
    }

    #[derive(Debug, Default)]
    struct BenchRunResult {
        passed: Vec<String>,
        skipped: Vec<String>,
        failed: Vec<String>,
    }

    impl BenchRunResult {
        fn success(&self) -> bool {
            self.failed.is_empty()
        }

        fn total_executed(&self) -> usize {
            self.passed.len() + self.skipped.len()
        }
    }

    let orchestrator = BenchInferenceAll::standard();

    // Test: All targets available
    let result = orchestrator.run_all(&[true, true, true, true, true]);
    assert!(result.success(), "QA-041: All targets pass when available");
    assert_eq!(result.passed.len(), 5);

    // Test: GPU unavailable (graceful skip)
    let result = orchestrator.run_all(&[true, true, false, false, true]);
    assert!(result.success(), "QA-041: Graceful skip for GPU targets");
    assert_eq!(result.skipped.len(), 2);
    assert_eq!(result.passed.len(), 3);

    // Test: Required target fails
    let result = orchestrator.run_all(&[false, true, true, true, true]);
    assert!(!result.success(), "QA-041: Fail if required target fails");

    println!("\nPARITY-011a: bench-inference-all orchestration");
    println!("  Total targets: {}", orchestrator.targets.len());
    println!(
        "  Graceful skip targets: {}",
        orchestrator
            .targets
            .iter()
            .filter(|t| t.graceful_skip)
            .count()
    );
}

/// Test PARITY-011b: QA-042 bench-pytorch-inference produces comparison report
///
/// Verifies PyTorch vs APR MNIST comparison generates valid output.
#[test]
fn test_parity011b_pytorch_comparison() {
    /// Comparison result between two inference backends
    #[derive(Debug)]
    struct InferenceComparison {
        backend_a: String,
        backend_b: String,
        metric: String,
        value_a: f64,
        value_b: f64,
        unit: String,
    }

    impl InferenceComparison {
        fn speedup(&self) -> f64 {
            if self.value_b > 0.0 {
                self.value_a / self.value_b
            } else {
                f64::INFINITY
            }
        }

        fn winner(&self) -> &str {
            if self.value_a > self.value_b {
                &self.backend_a
            } else {
                &self.backend_b
            }
        }
    }

    /// Comparison report generator
    struct ComparisonReport {
        title: String,
        comparisons: Vec<InferenceComparison>,
    }

    impl ComparisonReport {
        fn new(title: &str) -> Self {
            Self {
                title: title.to_string(),
                comparisons: Vec::new(),
            }
        }

        fn add(&mut self, comparison: InferenceComparison) {
            self.comparisons.push(comparison);
        }

        fn to_markdown(&self) -> String {
            let mut md = format!("# {}\n\n", self.title);
            md.push_str("| Metric | APR | PyTorch | Speedup | Winner |\n");
            md.push_str("|--------|-----|---------|---------|--------|\n");
            for c in &self.comparisons {
                md.push_str(&format!(
                    "| {} | {:.2} {} | {:.2} {} | {:.2}x | {} |\n",
                    c.metric,
                    c.value_a,
                    c.unit,
                    c.value_b,
                    c.unit,
                    c.speedup(),
                    c.winner()
                ));
            }
            md
        }
    }

    // Create PyTorch vs APR comparison
    let mut report = ComparisonReport::new("PyTorch vs APR MNIST Inference");

    report.add(InferenceComparison {
        backend_a: "APR".to_string(),
        backend_b: "PyTorch".to_string(),
        metric: "Throughput".to_string(),
        value_a: 15000.0,
        value_b: 8000.0,
        unit: "samples/s".to_string(),
    });

    report.add(InferenceComparison {
        backend_a: "APR".to_string(),
        backend_b: "PyTorch".to_string(),
        metric: "Latency p50".to_string(),
        value_a: 0.067,
        value_b: 0.125,
        unit: "ms".to_string(),
    });

    report.add(InferenceComparison {
        backend_a: "APR".to_string(),
        backend_b: "PyTorch".to_string(),
        metric: "Cold Start".to_string(),
        value_a: 5.0,
        value_b: 850.0,
        unit: "ms".to_string(),
    });

    let markdown = report.to_markdown();
    assert!(
        markdown.contains("PyTorch vs APR"),
        "QA-042: Report has title"
    );
    assert!(
        markdown.contains("Throughput"),
        "QA-042: Report has throughput"
    );
    assert!(
        markdown.contains("Speedup"),
        "QA-042: Report has speedup column"
    );
    assert!(
        markdown.contains("Winner"),
        "QA-042: Report has winner column"
    );

    // Verify APR wins on cold start (170x faster)
    // For latency metrics, lower is better, so speedup = B/A (not A/B)
    let cold_start = &report.comparisons[2];
    let cold_start_speedup = cold_start.value_b / cold_start.value_a; // 850/5 = 170x
    assert!(
        cold_start_speedup > 100.0,
        "QA-042: APR cold start significantly faster"
    );

    println!("\nPARITY-011b: PyTorch vs APR comparison");
    println!("  Comparisons: {}", report.comparisons.len());
    println!("  Cold start speedup: {:.0}x", cold_start_speedup);
}

/// Test PARITY-011c: QA-043 bench-cpu-inference tests all CPU backends
///
/// Verifies CPU backend matrix testing across different implementations.
#[test]
fn test_parity011c_cpu_backend_matrix() {
    /// CPU backend configuration
    #[derive(Debug, Clone)]
    struct CpuBackend {
        name: String,
        simd_level: SimdLevel,
        available: bool,
    }

    #[derive(Debug, Clone, Copy)]
    enum SimdLevel {
        Scalar,
        Sse2,
        Avx2,
        Avx512,
        Neon,
    }

    impl SimdLevel {
        fn theoretical_speedup(&self) -> f64 {
            match self {
                SimdLevel::Scalar => 1.0,
                SimdLevel::Sse2 => 4.0,
                SimdLevel::Avx2 => 8.0,
                SimdLevel::Avx512 => 16.0,
                SimdLevel::Neon => 4.0,
            }
        }
    }

    /// CPU benchmark matrix
    struct CpuBenchMatrix {
        backends: Vec<CpuBackend>,
    }

    impl CpuBenchMatrix {
        fn detect_available() -> Self {
            // Simulate detection on x86_64
            Self {
                backends: vec![
                    CpuBackend {
                        name: "Scalar".to_string(),
                        simd_level: SimdLevel::Scalar,
                        available: true,
                    },
                    CpuBackend {
                        name: "SSE2".to_string(),
                        simd_level: SimdLevel::Sse2,
                        available: true,
                    },
                    CpuBackend {
                        name: "AVX2".to_string(),
                        simd_level: SimdLevel::Avx2,
                        available: true,
                    },
                    CpuBackend {
                        name: "AVX-512".to_string(),
                        simd_level: SimdLevel::Avx512,
                        available: false, // Not on all CPUs
                    },
                ],
            }
        }

        fn run_benchmarks(&self, base_throughput: f64) -> Vec<(String, f64)> {
            self.backends
                .iter()
                .filter(|b| b.available)
                .map(|b| {
                    let throughput = base_throughput * b.simd_level.theoretical_speedup();
                    (b.name.clone(), throughput)
                })
                .collect()
        }
    }

    let matrix = CpuBenchMatrix::detect_available();
    let results = matrix.run_benchmarks(100.0); // 100 tok/s baseline

    assert!(results.len() >= 3, "QA-043: At least 3 CPU backends tested");

    // Verify SIMD speedup hierarchy
    let scalar = results
        .iter()
        .find(|(n, _)| n == "Scalar")
        .map(|(_, v)| *v)
        .expect("test");
    let sse2 = results
        .iter()
        .find(|(n, _)| n == "SSE2")
        .map(|(_, v)| *v)
        .expect("test");
    let avx2 = results
        .iter()
        .find(|(n, _)| n == "AVX2")
        .map(|(_, v)| *v)
        .expect("test");

    assert!(sse2 > scalar, "QA-043: SSE2 faster than Scalar");
    assert!(avx2 > sse2, "QA-043: AVX2 faster than SSE2");
    assert!((avx2 / scalar - 8.0).abs() < 0.1, "QA-043: AVX2 ~8x Scalar");

    println!("\nPARITY-011c: CPU backend matrix");
    for (name, throughput) in &results {
        println!("  {}: {:.0} tok/s", name, throughput);
    }
}

include!("parity011d_wgpu_should.rs");
include!("parity011g_stage_trigger.rs");
include!("parity011j_docs_doc.rs");
include!("parity012c_fused.rs");