<?php

declare(strict_types=1);

namespace Infrastructure\AI;

// @responsibility: Berechnet gewichtete Scores aus Vector-Similarity, Recency und Authority

use DateTimeInterface;

/**
 * Calculates weighted scores for RAG search results.
 *
 * Combines vector similarity with recency and authority factors
 * to produce a more nuanced ranking of search results.
 */
final readonly class ScoringService
{
    /** Weight for vector similarity score (cosine) */
    private const WEIGHT_SIMILARITY = 0.7;

    /** Weight for document recency */
    private const WEIGHT_RECENCY = 0.1;

    /** Weight for source authority */
    private const WEIGHT_AUTHORITY = 0.2;

    /**
     * Calculate weighted score combining similarity, recency, and authority.
     *
     * @param float             $vectorScore    The cosine similarity score from vector search (0.0-1.0)
     * @param DateTimeInterface $documentDate   The document's processed/created date
     * @param float             $authorityScore The source authority score (0.0-1.0, default: 0.5)
     *
     * @return float The weighted score (0.0-1.0)
     */
    public function calculateScore(
        float $vectorScore,
        DateTimeInterface $documentDate,
        float $authorityScore = 0.5
    ): float {
        $recencyScore = $this->calculateRecency($documentDate);

        return (self::WEIGHT_SIMILARITY * $vectorScore)
             + (self::WEIGHT_RECENCY * $recencyScore)
             + (self::WEIGHT_AUTHORITY * $authorityScore);
    }

    /**
     * Calculate recency score based on document age.
     *
     * Returns 1.0 for today, linearly decreasing to 0.0 at 365 days old.
     *
     * @param DateTimeInterface $date The document date
     *
     * @return float Recency score (0.0-1.0)
     */
    private function calculateRecency(DateTimeInterface $date): float
    {
        $now = new \DateTime();
        $interval = $now->diff($date);
        $daysOld = $interval->days;

        // Documents older than 1 year get minimum recency score
        return max(0.0, 1.0 - ($daysOld / 365));
    }

    /**
     * Get the weight configuration for transparency.
     *
     * @return array{similarity: float, recency: float, authority: float}
     */
    public function getWeights(): array
    {
        return [
            'similarity' => self::WEIGHT_SIMILARITY,
            'recency' => self::WEIGHT_RECENCY,
            'authority' => self::WEIGHT_AUTHORITY,
        ];
    }
}