oximedia-recommend 0.1.8

Content recommendation engine for media libraries
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

//! Recommendation reasoning.

use crate::RecommendationReason;
use serde::{Deserialize, Serialize};

/// Explanation builder for recommendations
pub struct ExplanationBuilder {
    /// Template for explanations
    templates: ExplanationTemplates,
}

/// Explanation templates
#[derive(Debug, Clone)]
pub struct ExplanationTemplates {
    /// Similar to liked template
    pub similar_to_liked: String,
    /// Collaborative filtering template
    pub collaborative: String,
    /// Trending template
    pub trending: String,
    /// Matches profile template
    pub matches_profile: String,
    /// Fresh content template
    pub fresh_content: String,
    /// Popular template
    pub popular: String,
    /// Continue watching template
    pub continue_watching: String,
}

impl Default for ExplanationTemplates {
    fn default() -> Self {
        Self {
            similar_to_liked: String::from("Similar to content you enjoyed"),
            collaborative: String::from("Users with similar tastes also liked this"),
            trending: String::from("Trending in your area"),
            matches_profile: String::from("Matches your interests in {}"),
            fresh_content: String::from("New content from {} days ago"),
            popular: String::from("Popular with {} views"),
            continue_watching: String::from("Continue watching ({}% complete)"),
        }
    }
}

impl ExplanationBuilder {
    /// Create a new explanation builder
    #[must_use]
    pub fn new() -> Self {
        Self {
            templates: ExplanationTemplates::default(),
        }
    }

    /// Build explanation from reason
    #[must_use]
    pub fn build_explanation(&self, reason: &RecommendationReason) -> String {
        match reason {
            RecommendationReason::SimilarToLiked { similarity, .. } => {
                format!(
                    "{} ({:.0}% match)",
                    self.templates.similar_to_liked,
                    similarity * 100.0
                )
            }
            RecommendationReason::CollaborativeFiltering { confidence } => {
                format!(
                    "{} ({:.0}% confidence)",
                    self.templates.collaborative,
                    confidence * 100.0
                )
            }
            RecommendationReason::Trending { trending_score } => {
                format!("{} (score: {:.1})", self.templates.trending, trending_score)
            }
            RecommendationReason::MatchesProfile { categories } => {
                let cats = categories.join(", ");
                self.templates.matches_profile.replace("{}", &cats)
            }
            RecommendationReason::FreshContent { published_days_ago } => self
                .templates
                .fresh_content
                .replace("{}", &published_days_ago.to_string()),
            RecommendationReason::Popular { view_count } => self
                .templates
                .popular
                .replace("{}", &view_count.to_string()),
            RecommendationReason::ContinueWatching { progress } => self
                .templates
                .continue_watching
                .replace("{}", &format!("{:.0}", progress * 100.0)),
        }
    }

    /// Combine multiple reasons into a single explanation
    #[must_use]
    pub fn combine_reasons(&self, reasons: &[RecommendationReason]) -> String {
        if reasons.is_empty() {
            return String::from("Recommended for you");
        }

        if reasons.len() == 1 {
            return self.build_explanation(&reasons[0]);
        }

        let explanations: Vec<String> = reasons.iter().map(|r| self.build_explanation(r)).collect();

        explanations.join("; ")
    }
}

impl Default for ExplanationBuilder {
    fn default() -> Self {
        Self::new()
    }
}

/// Explanation metadata
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExplanationMetadata {
    /// Primary reason
    pub primary_reason: String,
    /// Secondary reasons
    pub secondary_reasons: Vec<String>,
    /// Confidence score
    pub confidence: f32,
}

impl Default for ExplanationMetadata {
    fn default() -> Self {
        Self {
            primary_reason: String::from("Recommended for you"),
            secondary_reasons: Vec::new(),
            confidence: 0.5,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use uuid::Uuid;

    #[test]
    fn test_explanation_builder() {
        let builder = ExplanationBuilder::new();
        let reason = RecommendationReason::SimilarToLiked {
            content_id: Uuid::new_v4(),
            similarity: 0.85,
        };

        let explanation = builder.build_explanation(&reason);
        assert!(explanation.contains("Similar to"));
    }

    #[test]
    fn test_combine_reasons() {
        let builder = ExplanationBuilder::new();
        let reasons = vec![
            RecommendationReason::Trending {
                trending_score: 0.9,
            },
            RecommendationReason::Popular { view_count: 1000 },
        ];

        let explanation = builder.combine_reasons(&reasons);
        assert!(explanation.contains("Trending"));
        assert!(explanation.contains("Popular"));
    }
}