<?php

declare(strict_types=1);

namespace App\Framework\MachineLearning\ModelManagement;

use App\Framework\Core\ValueObjects\Version;
use App\Framework\Core\ValueObjects\Duration;

/**
 * Performance Storage Interface
 *
 * Storage abstraction for ML model performance tracking data.
 */
interface PerformanceStorage
{
    /**
     * Store a prediction record
     *
     * @param array{
     *     model_name: string,
     *     version: string,
     *     prediction: mixed,
     *     actual: mixed,
     *     confidence: float,
     *     features: array,
     *     timestamp: \DateTimeImmutable,
     *     is_correct: ?bool
     * } $predictionRecord
     */
    public function storePrediction(array $predictionRecord): void;

    /**
     * Get predictions within time window
     *
     * @return array<array{
     *     model_name: string,
     *     version: string,
     *     prediction: mixed,
     *     actual: mixed,
     *     confidence: float,
     *     features: array,
     *     timestamp: \DateTimeImmutable,
     *     is_correct: ?bool
     * }>
     */
    public function getPredictions(
        string $modelName,
        Version $version,
        Duration $timeWindow
    ): array;

    /**
     * Get historical average confidence for baseline
     */
    public function getHistoricalAverageConfidence(
        string $modelName,
        Version $version
    ): ?float;

    /**
     * Store confidence baseline for drift detection
     */
    public function storeConfidenceBaseline(
        string $modelName,
        Version $version,
        float $avgConfidence,
        float $stdDevConfidence
    ): void;

    /**
     * Clear old prediction records (cleanup)
     */
    public function clearOldPredictions(Duration $olderThan): int;

    /**
     * Get recent predictions (limit-based)
     *
     * @return array<array{
     *     model_name: string,
     *     version: string,
     *     prediction: mixed,
     *     actual: mixed,
     *     confidence: float,
     *     features: array,
     *     timestamp: \DateTimeImmutable,
     *     is_correct: ?bool
     * }>
     */
    public function getRecentPredictions(
        string $modelName,
        Version $version,
        int $limit
    ): array;

    /**
     * Calculate accuracy from recent predictions
     */
    public function calculateAccuracy(
        string $modelName,
        Version $version,
        int $limit
    ): float;

    /**
     * Get confidence baseline
     *
     * @return array{avg_confidence: float, std_dev_confidence: float}|null
     */
    public function getConfidenceBaseline(
        string $modelName,
        Version $version
    ): ?array;
}