Skip to main content

fetchium_core/social/
validate.rs

1//! Social post validation, fact-checking, and quality filtering.
2//!
3//! Every post from every platform passes through this pipeline:
4//!
5//! ```text
6//! Raw Posts
7//!   -> relevance_score()     -- word-overlap BM25 against query
8//!   -> authenticity_score()  -- bot/spam/quality heuristics
9//!   -> credibility_score()   -- platform weight x engagement legitimacy
10//!   -> filter_low_quality()  -- drop posts below threshold
11//!   -> cross_validate()      -- boost posts confirmed on 2+ platforms
12//!   -> ValidationReport      -- per-post flags + summary stats
13//! ```
14
15use crate::social::types::{EngagementMetrics, SocialPlatform, SocialPost};
16use std::collections::HashSet;
17
18// ─── Public Types ─────────────────────────────────────────────────
19
20/// Quality flags attached to a post after validation.
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub enum ValidationFlag {
23    /// More than 8 hashtags in a single post (spam signal)
24    ExcessiveHashtags,
25    /// Content is fewer than 8 words (low-value)
26    ShortContent,
27    /// Content is mostly uppercase (shouting / clickbait)
28    ExcessiveCaps,
29    /// Repeated filler phrases detected
30    SpamPatterns,
31    /// Account appears bot-like (random username, no bio context)
32    PossibleBot,
33    /// Low relevance to the search query
34    LowRelevance,
35    /// Deleted or anonymous author
36    DeletedAccount,
37    /// Engagement looks artificially inflated
38    SuspiciousEngagement,
39    /// Claim is extraordinary / unverified (high sentiment outlier)
40    ExtraordinaryClaim,
41}
42
43/// Per-post validation result.
44#[derive(Debug, Clone)]
45pub struct PostValidation {
46    pub relevance: f64,     // 0-1 word-overlap relevance to query
47    pub authenticity: f64,  // 0-1 content + account quality
48    pub credibility: f64,   // 0-1 platform weight × engagement legitimacy
49    pub quality_score: f64, // 0-1 composite (weighted average)
50    pub flags: Vec<ValidationFlag>,
51    pub passes: bool, // true if quality_score ≥ threshold
52}
53
54/// Summary stats from validating a batch of posts.
55#[derive(Debug, Clone, Default)]
56pub struct ValidationReport {
57    pub total: usize,
58    pub passed: usize,
59    pub filtered_bot: usize,
60    pub filtered_spam: usize,
61    pub filtered_irrelevant: usize,
62    pub avg_quality: f64,
63    pub avg_relevance: f64,
64    pub avg_credibility: f64,
65}
66
67// ─── Default threshold ────────────────────────────────────────────
68
69/// Minimum quality score for a post to be included in output.
70pub const MIN_QUALITY: f64 = 0.20;
71
72// ─── Main API ─────────────────────────────────────────────────────
73
74/// Validate a single post against a search query.
75pub fn validate_post(post: &SocialPost, query: &str) -> PostValidation {
76    let mut flags = Vec::new();
77
78    // ── Relevance ──────────────────────────────────────────────────
79    let relevance = compute_relevance(&post.content, query);
80    if relevance < 0.05 {
81        flags.push(ValidationFlag::LowRelevance);
82    }
83
84    // ── Authenticity ───────────────────────────────────────────────
85    let auth = compute_authenticity(post, &mut flags);
86
87    // ── Credibility ────────────────────────────────────────────────
88    let cred = compute_credibility(post, &mut flags);
89
90    // ── Composite quality score ────────────────────────────────────
91    // Weights: relevance 40%, authenticity 35%, credibility 25%
92    let quality = (relevance * 0.40 + auth * 0.35 + cred * 0.25).clamp(0.0, 1.0);
93
94    let passes = quality >= MIN_QUALITY;
95
96    PostValidation {
97        relevance,
98        authenticity: auth,
99        credibility: cred,
100        quality_score: quality,
101        flags,
102        passes,
103    }
104}
105
106/// Filter and rank a list of posts by quality score, keeping only passing posts.
107///
108/// Returns posts sorted by quality descending, up to `limit`.
109pub fn filter_and_rank(
110    posts: Vec<SocialPost>,
111    query: &str,
112    limit: usize,
113) -> (Vec<SocialPost>, ValidationReport) {
114    let total = posts.len();
115    let mut scored: Vec<(SocialPost, PostValidation)> = posts
116        .into_iter()
117        .map(|p| {
118            let v = validate_post(&p, query);
119            (p, v)
120        })
121        .collect();
122
123    let mut report = ValidationReport {
124        total,
125        ..Default::default()
126    };
127
128    for (_, v) in &scored {
129        if !v.passes {
130            if v.flags.contains(&ValidationFlag::PossibleBot) {
131                report.filtered_bot += 1;
132            } else if v.flags.contains(&ValidationFlag::SpamPatterns)
133                || v.flags.contains(&ValidationFlag::ExcessiveHashtags)
134            {
135                report.filtered_spam += 1;
136            } else if v.flags.contains(&ValidationFlag::LowRelevance) {
137                report.filtered_irrelevant += 1;
138            }
139        }
140    }
141
142    // Keep passing posts, sort by quality descending
143    scored.retain(|(_, v)| v.passes);
144    scored.sort_by(|(_, a), (_, b)| {
145        b.quality_score
146            .partial_cmp(&a.quality_score)
147            .unwrap_or(std::cmp::Ordering::Equal)
148    });
149
150    report.passed = scored.len().min(limit);
151    if !scored.is_empty() {
152        let n = scored.len() as f64;
153        report.avg_quality = scored.iter().map(|(_, v)| v.quality_score).sum::<f64>() / n;
154        report.avg_relevance = scored.iter().map(|(_, v)| v.relevance).sum::<f64>() / n;
155        report.avg_credibility = scored.iter().map(|(_, v)| v.credibility).sum::<f64>() / n;
156    }
157
158    let posts: Vec<SocialPost> = scored.into_iter().take(limit).map(|(p, _)| p).collect();
159    (posts, report)
160}
161
162/// Apply validation to a SocialPost and update its `authenticity` field in-place.
163pub fn enrich_post(post: &mut SocialPost, query: &str) {
164    let v = validate_post(post, query);
165    // Update the built-in authenticity field with our computed value
166    post.authenticity = v.authenticity;
167    // Adjust sentiment if extraordinary claim detected
168    if v.flags.contains(&ValidationFlag::ExtraordinaryClaim) {
169        // Dampen extreme sentiment toward neutral — signals need verification
170        post.sentiment *= 0.5;
171    }
172}
173
174// ─── Scoring Functions ────────────────────────────────────────────
175
176/// Compute word-overlap relevance score between post content and query.
177///
178/// Uses normalised Jaccard-like word set overlap with TF-IDF-style boost
179/// for rare query terms appearing in content.
180pub fn compute_relevance(content: &str, query: &str) -> f64 {
181    if content.is_empty() || query.is_empty() {
182        return 0.0;
183    }
184
185    let content_lower = content.to_lowercase();
186    let content_words: HashSet<&str> = content_lower
187        .split(|c: char| !c.is_alphanumeric())
188        .filter(|w| w.len() >= 3 && !is_stopword(w))
189        .collect();
190
191    let query_lower_owned = query.to_lowercase();
192    let query_words: Vec<&str> = query_lower_owned
193        .split(|c: char| !c.is_alphanumeric())
194        .filter(|w| w.len() >= 3 && !is_stopword(w))
195        .collect();
196
197    if query_words.is_empty() {
198        return 0.5; // no meaningful query words → neutral
199    }
200
201    let matched = query_words
202        .iter()
203        .filter(|qw| {
204            // Exact match or prefix match (e.g. "rust" matches "rustlang")
205            content_words
206                .iter()
207                .any(|cw| cw.contains(*qw) || qw.contains(cw))
208        })
209        .count();
210
211    let base = matched as f64 / query_words.len() as f64;
212
213    // Boost for exact multi-word phrase presence
214    let phrase_boost = if content_lower.contains(query_lower_owned.as_str()) {
215        0.2
216    } else {
217        0.0
218    };
219
220    (base + phrase_boost).min(1.0)
221}
222
223/// Compute authenticity score (0-1) with flag side-effects.
224fn compute_authenticity(post: &SocialPost, flags: &mut Vec<ValidationFlag>) -> f64 {
225    let mut score = 1.0f64;
226    let content = &post.content;
227    let words: Vec<&str> = content.split_whitespace().collect();
228
229    // Short content penalty
230    if words.len() < 8 {
231        flags.push(ValidationFlag::ShortContent);
232        score -= 0.25;
233    }
234
235    // Excessive hashtags penalty (>8 is spam territory)
236    let hashtag_count = words.iter().filter(|w| w.starts_with('#')).count();
237    if hashtag_count > 8 {
238        flags.push(ValidationFlag::ExcessiveHashtags);
239        score -= 0.30;
240    } else if hashtag_count > 5 {
241        score -= 0.10;
242    }
243
244    // Excessive caps penalty (>40% uppercase chars = shouting/spam)
245    let alpha_chars: Vec<char> = content.chars().filter(|c| c.is_alphabetic()).collect();
246    if !alpha_chars.is_empty() {
247        let caps_ratio = alpha_chars.iter().filter(|c| c.is_uppercase()).count() as f64
248            / alpha_chars.len() as f64;
249        if caps_ratio > 0.55 {
250            flags.push(ValidationFlag::ExcessiveCaps);
251            score -= 0.20;
252        }
253    }
254
255    // Spam patterns: repeated punctuation, URL-only content
256    let has_spam = content.contains("!!!")
257        || content.contains("$$$")
258        || content.contains("click here")
259        || content.contains("buy now")
260        || content.contains("limited offer")
261        || content.contains("bit.ly")
262        || content.contains("goo.gl");
263    if has_spam {
264        flags.push(ValidationFlag::SpamPatterns);
265        score -= 0.35;
266    }
267
268    // Deleted/anonymous account penalty
269    let author = &post.author;
270    if author == "[deleted]" || author == "[removed]" || author.is_empty() {
271        flags.push(ValidationFlag::DeletedAccount);
272        score -= 0.20;
273    }
274
275    // Bot-like username: random alphanum, no vowels, too short/long
276    if looks_like_bot_username(author) {
277        flags.push(ValidationFlag::PossibleBot);
278        score -= 0.30;
279    }
280
281    // Extraordinary claim detection: extreme sentiment (|s| > 0.85) on short content
282    if post.sentiment.abs() > 0.85 && words.len() < 20 {
283        flags.push(ValidationFlag::ExtraordinaryClaim);
284        score -= 0.10;
285    }
286
287    score.clamp(0.0, 1.0)
288}
289
290/// Compute credibility score (0-1) based on platform weight × engagement legitimacy.
291fn compute_credibility(post: &SocialPost, flags: &mut Vec<ValidationFlag>) -> f64 {
292    use crate::social::unified::trend::platform_weight;
293
294    let platform_cred = platform_weight(post.platform);
295
296    // Engagement legitimacy check
297    let eng_legit = compute_engagement_legitimacy(&post.engagement, post.platform);
298    if eng_legit < 0.3 {
299        flags.push(ValidationFlag::SuspiciousEngagement);
300    }
301
302    (platform_cred * 0.6 + eng_legit * 0.4).clamp(0.0, 1.0)
303}
304
305/// Check if engagement numbers look artificially inflated.
306///
307/// Red flags: 0 comments but 100k likes, 0 shares but massive likes, etc.
308fn compute_engagement_legitimacy(eng: &EngagementMetrics, platform: SocialPlatform) -> f64 {
309    // Zero engagement on all metrics → unknown (not fake, just new/unnoticed)
310    if eng.likes == 0 && eng.shares == 0 && eng.comments == 0 {
311        return 0.6; // neutral — can't tell
312    }
313
314    let likes = eng.likes as f64;
315    let shares = eng.shares as f64;
316    let comments = eng.comments as f64;
317
318    // Expected ratios (platform-specific)
319    let (expected_share_ratio, expected_comment_ratio) = match platform {
320        SocialPlatform::Twitter => (0.15, 0.08), // retweets common
321        SocialPlatform::Reddit => (0.02, 0.25),  // comments high relative to score
322        SocialPlatform::TikTok => (0.05, 0.03),  // shares moderate
323        SocialPlatform::HackerNews => (0.00, 0.40), // no shares, lots of comments
324        SocialPlatform::YouTube => (0.03, 0.02), // shares low, comments moderate
325        SocialPlatform::Facebook => (0.08, 0.05), // shares common
326    };
327
328    let mut score = 1.0f64;
329
330    // If shares wildly exceed likes (>3×) → suspicious
331    if likes > 10.0 && shares > likes * 3.0 {
332        score -= 0.30;
333    }
334
335    // If zero comments on high-engagement post → suspicious
336    if likes > 1000.0 && comments == 0.0 && platform != SocialPlatform::TikTok {
337        score -= 0.20;
338    }
339
340    // Expected ratio checks (gentle penalty for outliers)
341    if likes > 0.0 {
342        let actual_share_ratio = shares / likes;
343        if actual_share_ratio > expected_share_ratio * 10.0 {
344            score -= 0.15;
345        }
346        let actual_comment_ratio = comments / likes;
347        if actual_comment_ratio > expected_comment_ratio * 10.0 {
348            score -= 0.10;
349        }
350    }
351
352    score.clamp(0.3, 1.0)
353}
354
355// ─── Cross-Platform Validation ────────────────────────────────────
356
357/// Boost authenticity of posts whose content is confirmed on 2+ platforms.
358///
359/// Uses bigram-Jaccard similarity to detect "same story" across platforms.
360pub fn cross_validate_boost(posts: &mut [SocialPost]) {
361    use crate::social::types::bigrams;
362
363    let bigram_sets: Vec<_> = posts
364        .iter()
365        .map(|p| bigrams(&p.content.to_lowercase()))
366        .collect();
367
368    for i in 0..posts.len() {
369        let mut confirmed_on = 1usize;
370        for j in 0..posts.len() {
371            if i == j || posts[i].platform == posts[j].platform {
372                continue;
373            }
374            let sim = crate::social::types::jaccard(&bigram_sets[i], &bigram_sets[j]);
375            if sim > 0.35 {
376                confirmed_on += 1;
377            }
378        }
379        // Each cross-platform confirmation boosts authenticity by 5%
380        if confirmed_on > 1 {
381            let boost = 0.05 * (confirmed_on - 1) as f64;
382            posts[i].authenticity = (posts[i].authenticity + boost).min(1.0);
383        }
384    }
385}
386
387// ─── Markdown Report ──────────────────────────────────────────────
388
389/// Format a validation report as markdown summary.
390pub fn format_validation_report(report: &ValidationReport) -> String {
391    if report.total == 0 {
392        return String::new();
393    }
394    let pass_pct = report.passed as f64 / report.total as f64 * 100.0;
395    format!(
396        "**Validation:** {}/{} posts passed ({:.0}% quality rate) · avg quality {:.0}% · avg relevance {:.0}% · avg credibility {:.0}%\n\
397         Filtered: {} bot · {} spam · {} off-topic\n",
398        report.passed,
399        report.total,
400        pass_pct,
401        report.avg_quality * 100.0,
402        report.avg_relevance * 100.0,
403        report.avg_credibility * 100.0,
404        report.filtered_bot,
405        report.filtered_spam,
406        report.filtered_irrelevant,
407    )
408}
409
410// ─── Helpers ──────────────────────────────────────────────────────
411
412/// Check if a username looks bot-generated.
413///
414/// Heuristics: random alphanumeric (>3 consecutive digits), no vowels, generic patterns.
415fn looks_like_bot_username(username: &str) -> bool {
416    if username.is_empty() || username == "[deleted]" {
417        return false; // handled separately
418    }
419    let lower = username.to_lowercase();
420
421    // Contains 4+ consecutive digits → likely bot-generated
422    let digit_run = lower.chars().collect::<Vec<_>>();
423    for window in digit_run.windows(4) {
424        if window.iter().all(|c| c.is_ascii_digit()) {
425            return true;
426        }
427    }
428
429    // Very short username (1-2 chars) without context
430    if lower.len() <= 2 {
431        return true;
432    }
433
434    // No vowels at all in names >5 chars (like "brtxkrz")
435    if lower.len() > 5 {
436        let vowels = "aeiou";
437        let has_vowel = lower.chars().any(|c| vowels.contains(c));
438        if !has_vowel {
439            return true;
440        }
441    }
442
443    false
444}
445
446/// Common English stopwords to exclude from relevance computation.
447fn is_stopword(word: &str) -> bool {
448    matches!(
449        word,
450        "the"
451            | "and"
452            | "for"
453            | "are"
454            | "but"
455            | "not"
456            | "you"
457            | "all"
458            | "can"
459            | "her"
460            | "was"
461            | "one"
462            | "our"
463            | "out"
464            | "day"
465            | "get"
466            | "has"
467            | "him"
468            | "his"
469            | "how"
470            | "its"
471            | "may"
472            | "new"
473            | "now"
474            | "old"
475            | "see"
476            | "two"
477            | "way"
478            | "who"
479            | "boy"
480            | "did"
481            | "she"
482            | "use"
483            | "yes"
484            | "yet"
485            | "any"
486            | "far"
487            | "few"
488            | "got"
489            | "let"
490            | "off"
491            | "put"
492            | "say"
493            | "set"
494            | "try"
495            | "also"
496            | "back"
497            | "from"
498            | "have"
499            | "here"
500            | "just"
501            | "know"
502            | "like"
503            | "look"
504            | "make"
505            | "more"
506            | "much"
507            | "need"
508            | "only"
509            | "over"
510            | "same"
511            | "take"
512            | "than"
513            | "that"
514            | "them"
515            | "then"
516            | "they"
517            | "this"
518            | "time"
519            | "very"
520            | "well"
521            | "when"
522            | "will"
523            | "with"
524            | "been"
525            | "your"
526    )
527}
528
529#[cfg(test)]
530mod tests {
531    use super::*;
532    use crate::social::types::{EngagementMetrics, SocialPost};
533
534    fn make_post(platform: SocialPlatform, content: &str, author: &str) -> SocialPost {
535        let mut eng = EngagementMetrics {
536            likes: 500,
537            shares: 50,
538            comments: 30,
539            views: None,
540            score: 0.0,
541        };
542        eng.compute_score();
543        SocialPost {
544            platform,
545            id: "1".into(),
546            url: "https://example.com".into(),
547            author: author.into(),
548            content: content.into(),
549            published: "2025-01-01".into(),
550            engagement: eng,
551            media: Vec::new(),
552            hashtags: Vec::new(),
553            mentions: Vec::new(),
554            sentiment: 0.2,
555            authenticity: 0.7,
556        }
557    }
558
559    #[test]
560    fn relevance_exact_phrase_high() {
561        let r = compute_relevance(
562            "Rust programming language memory safety systems",
563            "rust programming",
564        );
565        assert!(r > 0.7, "exact phrase match should be high: {r}");
566    }
567
568    #[test]
569    fn relevance_unrelated_low() {
570        let r = compute_relevance("delicious chocolate cake recipe baking", "rust programming");
571        assert!(r < 0.2, "unrelated content should be low: {r}");
572    }
573
574    #[test]
575    fn validate_good_post_passes() {
576        let post = make_post(
577            SocialPlatform::Reddit,
578            "Rust's ownership model provides memory safety without garbage collection, making it ideal for systems programming and performance-critical applications.",
579            "rustacean",
580        );
581        let v = validate_post(&post, "rust programming");
582        assert!(v.passes, "good post should pass: score={}", v.quality_score);
583        assert!(v.quality_score > 0.5);
584    }
585
586    #[test]
587    fn validate_spam_post_flagged() {
588        let post = make_post(
589            SocialPlatform::Twitter,
590            "BUY NOW!!! LIMITED OFFER!!! bit.ly/abc123 #discount #sale #promo #deals #buy #now #cheap #free #win #money",
591            "spambot123456",
592        );
593        let v = validate_post(&post, "rust programming");
594        assert!(
595            v.flags.contains(&ValidationFlag::ExcessiveHashtags)
596                || v.flags.contains(&ValidationFlag::SpamPatterns)
597        );
598        assert!(
599            v.quality_score < 0.4,
600            "spam should have low quality: {}",
601            v.quality_score
602        );
603    }
604
605    #[test]
606    fn validate_deleted_author_penalised() {
607        let post = make_post(SocialPlatform::Reddit, "Some content here that is reasonably long enough to pass minimum word check easily in this test", "[deleted]");
608        let v = validate_post(&post, "rust");
609        assert!(v.flags.contains(&ValidationFlag::DeletedAccount));
610    }
611
612    #[test]
613    fn bot_username_detection() {
614        assert!(looks_like_bot_username("user12345678")); // 8 consecutive digits
615        assert!(looks_like_bot_username("brtxkrz")); // no vowels, >5 chars
616        assert!(!looks_like_bot_username("rustacean")); // normal
617        assert!(!looks_like_bot_username("alice42")); // normal with some digits
618    }
619
620    #[test]
621    fn filter_and_rank_removes_low_quality() {
622        let good = make_post(
623            SocialPlatform::HackerNews,
624            "Rust 2024 edition introduces new lifetime elision rules and improved async support with better ergonomics for developers building systems software and web backends.",
625            "pg",
626        );
627        let spam = make_post(
628            SocialPlatform::Twitter,
629            "BUY NOW!!! bit.ly #spam #ad",
630            "bot99999999",
631        );
632        let (filtered, report) = filter_and_rank(vec![good, spam], "rust programming", 10);
633        assert_eq!(report.total, 2);
634        assert!(filtered.len() <= 2);
635        // The spam post should be filtered out or ranked last
636        if filtered.len() == 2 {
637            assert!(
638                filtered[0].author != "bot99999999",
639                "spam should be ranked last"
640            );
641        }
642    }
643
644    #[test]
645    fn engagement_legit_zero_is_neutral() {
646        let eng = EngagementMetrics {
647            likes: 0,
648            shares: 0,
649            comments: 0,
650            views: None,
651            score: 0.0,
652        };
653        let legit = compute_engagement_legitimacy(&eng, SocialPlatform::Reddit);
654        assert!((legit - 0.6).abs() < 0.1);
655    }
656
657    #[test]
658    fn relevance_empty_content_zero() {
659        assert_eq!(compute_relevance("", "rust"), 0.0);
660        assert_eq!(compute_relevance("rust", ""), 0.0);
661    }
662
663    #[test]
664    fn short_content_flagged() {
665        let post = make_post(SocialPlatform::Twitter, "Nice lol", "user");
666        let v = validate_post(&post, "rust");
667        assert!(v.flags.contains(&ValidationFlag::ShortContent));
668    }
669
670    #[test]
671    fn cross_validate_boost_increases_authenticity() {
672        let mut posts = vec![
673            make_post(
674                SocialPlatform::Reddit,
675                "Rust memory safety ownership borrow checker guarantees thread safety",
676                "user1",
677            ),
678            make_post(
679                SocialPlatform::HackerNews,
680                "Rust memory safety ownership borrow checker guarantees thread safe",
681                "user2",
682            ),
683        ];
684        let before = posts[0].authenticity;
685        cross_validate_boost(&mut posts);
686        assert!(
687            posts[0].authenticity >= before,
688            "cross-platform confirmation should boost authenticity"
689        );
690    }
691}