Skip to main content

fetchium_core/intelligence/
acs.rs

1//! Adversarial Content Shield (ACS) — PRD §8.17, §35.
2//!
3//! 4-layer detection system:
4//! 1. AI content detection (burstiness, vocabulary diversity, sentence variance)
5//! 2. Bot farm signals (domain age, publishing velocity)
6//! 3. Source manipulation detection (cross-site duplication)
7//! 4. Trust score aggregation
8//!
9//! Starts in **shadow mode** (flag but don't filter) for the first 30 days.
10
11use chrono::{DateTime, Utc};
12
13// ─── Mode and results ────────────────────────────────────────────────────────
14
15/// Operating mode for ACS.
16#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
17#[serde(rename_all = "snake_case")]
18pub enum AcsMode {
19    /// Flag but don't filter — used for the first 30 days to collect accuracy data.
20    Shadow,
21    /// Flag and filter — active enforcement mode.
22    Active,
23    /// ACS disabled entirely.
24    Disabled,
25}
26
27/// A specific flag raised by ACS.
28#[derive(Debug, Clone, PartialEq, serde::Serialize)]
29#[serde(rename_all = "snake_case")]
30pub enum AcsFlag {
31    LikelyAiGenerated,
32    LikelyBotFarm,
33    LikelyManipulated,
34    LowVocabularyDiversity,
35    UniformSentenceLengths,
36}
37
38/// Action recommended by ACS after analysis.
39#[derive(Debug, Clone, serde::Serialize)]
40#[serde(rename_all = "snake_case")]
41pub enum AcsAction {
42    /// Trust > 0.8 — include normally.
43    Include,
44    /// 0.5 < trust ≤ 0.8 — include with a warning shown to the user.
45    IncludeWithWarning { warning: String },
46    /// trust ≤ 0.5 — exclude from results.
47    Exclude { reason: String },
48    /// trust < 0.2 — flag as potentially adversarial.
49    FlagAdversarial { reason: String },
50}
51
52/// Full ACS analysis result for a single piece of content.
53#[derive(Debug, Clone, serde::Serialize)]
54pub struct AcsResult {
55    /// Aggregate trust score 0.0-1.0.
56    pub trust_score: f64,
57    pub ai_generated_probability: f64,
58    pub bot_farm_probability: f64,
59    pub manipulation_probability: f64,
60    pub flags: Vec<AcsFlag>,
61    pub action: AcsAction,
62    /// True if running in shadow mode (action is always Include in this case).
63    pub is_shadow: bool,
64}
65
66// ─── AI Content Detector ─────────────────────────────────────────────────────
67
68struct AiContentDetector;
69
70impl AiContentDetector {
71    /// Returns AI-generation probability 0.0-1.0.
72    /// AI text: low burstiness + low vocabulary diversity + uniform sentence length.
73    fn detect(&self, content: &str) -> f64 {
74        let burst = self.burstiness_score(content);
75        let vocab = self.vocabulary_diversity(content);
76        let variance = self.sentence_length_variance(content);
77
78        // Low burstiness/diversity/variance → high AI probability
79        let ai = (1.0 - burst) * 0.4 + (1.0 - vocab) * 0.3 + (1.0 - variance) * 0.3;
80        ai.clamp(0.0, 1.0)
81    }
82
83    /// Coefficient of variation of sentence lengths.
84    /// High CV = bursty = human; Low CV = uniform = AI.
85    fn burstiness_score(&self, content: &str) -> f64 {
86        let lengths: Vec<f64> = content
87            .split(['.', '!', '?'])
88            .filter(|s| s.split_whitespace().count() >= 3)
89            .map(|s| s.split_whitespace().count() as f64)
90            .collect();
91        if lengths.len() < 3 {
92            return 0.5;
93        }
94        let mean = lengths.iter().sum::<f64>() / lengths.len() as f64;
95        if mean < 1e-9 {
96            return 0.5;
97        }
98        let variance =
99            lengths.iter().map(|l| (l - mean).powi(2)).sum::<f64>() / lengths.len() as f64;
100        let cv = variance.sqrt() / mean;
101        (cv / 0.5).clamp(0.0, 1.0)
102    }
103
104    /// Type-Token Ratio: unique words / total words.
105    fn vocabulary_diversity(&self, content: &str) -> f64 {
106        let words: Vec<&str> = content.split_whitespace().collect();
107        if words.is_empty() {
108            return 0.5;
109        }
110        let unique: std::collections::HashSet<_> = words.iter().map(|w| w.to_lowercase()).collect();
111        (unique.len() as f64 / words.len() as f64).clamp(0.0, 1.0)
112    }
113
114    /// Std deviation of sentence lengths, normalised by mean.
115    fn sentence_length_variance(&self, content: &str) -> f64 {
116        let lengths: Vec<f64> = content
117            .split(['.', '!', '?'])
118            .filter(|s| s.len() > 5)
119            .map(|s| s.split_whitespace().count() as f64)
120            .collect();
121        if lengths.len() < 3 {
122            return 0.5;
123        }
124        let mean = lengths.iter().sum::<f64>() / lengths.len() as f64;
125        let std_dev =
126            (lengths.iter().map(|l| (l - mean).powi(2)).sum::<f64>() / lengths.len() as f64).sqrt();
127        (std_dev / mean.max(1.0)).clamp(0.0, 1.0)
128    }
129}
130
131// ─── Bot Farm Detector ───────────────────────────────────────────────────────
132
133struct BotFarmDetector;
134
135impl BotFarmDetector {
136    /// Returns bot-farm probability 0.0-1.0 based on simple URL/domain heuristics.
137    fn analyze(&self, domain: &str, content_len: usize) -> f64 {
138        let mut score = 0.0_f64;
139
140        // Very short content (< 100 words) from unknown domains → suspicious
141        if content_len < 500 {
142            score += 0.2;
143        }
144
145        // Known content-farm / clickbait TLD patterns
146        let lower = domain.to_lowercase();
147        let suspicious_patterns = [
148            ".click",
149            ".info",
150            ".biz",
151            ".xyz",
152            "bestof",
153            "top10",
154            "viral",
155            "clickbait",
156        ];
157        for pat in suspicious_patterns {
158            if lower.contains(pat) {
159                score += 0.15;
160                break;
161            }
162        }
163
164        score.clamp(0.0, 1.0)
165    }
166}
167
168// ─── Manipulation Detector ───────────────────────────────────────────────────
169
170struct ManipulationDetector;
171
172impl ManipulationDetector {
173    /// Returns manipulation probability 0.0-1.0 based on content heuristics.
174    fn check(&self, content: &str) -> f64 {
175        let lower = content.to_lowercase();
176        let mut score = 0.0_f64;
177
178        // Excessive hedging / uncertainty language common in disinformation
179        let hedge_words = [
180            "they say",
181            "some people claim",
182            "allegedly",
183            "reportedly",
184            "sources say",
185            "rumored",
186            "unverified",
187        ];
188        let hedge_count = hedge_words.iter().filter(|w| lower.contains(*w)).count();
189        score += (hedge_count as f64 * 0.1).min(0.4);
190
191        // Extremely clickbait title signals (ALL CAPS words)
192        let all_caps_words: usize = content
193            .split_whitespace()
194            .filter(|w| w.len() > 3 && w.chars().all(|c| c.is_uppercase()))
195            .count();
196        score += (all_caps_words as f64 * 0.05).min(0.3);
197
198        score.clamp(0.0, 1.0)
199    }
200}
201
202// ─── ACS Main Engine ─────────────────────────────────────────────────────────
203
204/// Adversarial Content Shield.
205pub struct AdversarialContentShield {
206    ai_detector: AiContentDetector,
207    bot_detector: BotFarmDetector,
208    manipulation_detector: ManipulationDetector,
209    mode: AcsMode,
210    first_enabled_at: DateTime<Utc>,
211}
212
213impl AdversarialContentShield {
214    /// Create a new ACS in shadow mode starting now.
215    pub fn new() -> Self {
216        Self {
217            ai_detector: AiContentDetector,
218            bot_detector: BotFarmDetector,
219            manipulation_detector: ManipulationDetector,
220            mode: AcsMode::Shadow,
221            first_enabled_at: Utc::now(),
222        }
223    }
224
225    /// Create with an explicit mode and start time.
226    pub fn with_mode(mode: AcsMode, first_enabled_at: DateTime<Utc>) -> Self {
227        Self {
228            ai_detector: AiContentDetector,
229            bot_detector: BotFarmDetector,
230            manipulation_detector: ManipulationDetector,
231            mode,
232            first_enabled_at,
233        }
234    }
235
236    /// Compute the effective operating mode.
237    ///
238    /// Auto-transitions shadow → active after 30 days.
239    pub fn effective_mode(&self) -> AcsMode {
240        if self.mode == AcsMode::Shadow {
241            let days_active = (Utc::now() - self.first_enabled_at).num_days();
242            if days_active >= 30 {
243                return AcsMode::Active;
244            }
245        }
246        self.mode.clone()
247    }
248
249    /// Analyse a piece of content from `domain`.
250    pub fn analyze(&self, content: &str, domain: &str) -> AcsResult {
251        let ai_prob = self.ai_detector.detect(content);
252        let bot_prob = self.bot_detector.analyze(domain, content.len());
253        let manip_prob = self.manipulation_detector.check(content);
254
255        let trust_score = 1.0_f64 - ai_prob.max(bot_prob).max(manip_prob);
256        let trust_score = trust_score.clamp(0.0, 1.0);
257
258        let mut flags = Vec::new();
259        if ai_prob > 0.7 {
260            flags.push(AcsFlag::LikelyAiGenerated);
261        }
262        if bot_prob > 0.7 {
263            flags.push(AcsFlag::LikelyBotFarm);
264        }
265        if manip_prob > 0.7 {
266            flags.push(AcsFlag::LikelyManipulated);
267        }
268
269        let eff_mode = self.effective_mode();
270        let is_shadow = eff_mode == AcsMode::Shadow;
271
272        let action = match eff_mode {
273            AcsMode::Shadow | AcsMode::Disabled => AcsAction::Include,
274            AcsMode::Active => {
275                if trust_score > 0.8 {
276                    AcsAction::Include
277                } else if trust_score > 0.5 {
278                    AcsAction::IncludeWithWarning {
279                        warning: format!(
280                            "Low trust ({:.0}%): possible AI-generated or manipulated content",
281                            trust_score * 100.0
282                        ),
283                    }
284                } else if trust_score > 0.2 {
285                    AcsAction::Exclude {
286                        reason: format!(
287                            "Trust score {:.0}% — likely low-quality or manipulated content",
288                            trust_score * 100.0
289                        ),
290                    }
291                } else {
292                    AcsAction::FlagAdversarial {
293                        reason: format!(
294                            "Trust score {:.0}% — likely adversarial content (domain: {domain})",
295                            trust_score * 100.0
296                        ),
297                    }
298                }
299            }
300        };
301
302        AcsResult {
303            trust_score,
304            ai_generated_probability: ai_prob,
305            bot_farm_probability: bot_prob,
306            manipulation_probability: manip_prob,
307            flags,
308            action,
309            is_shadow,
310        }
311    }
312}
313
314impl Default for AdversarialContentShield {
315    fn default() -> Self {
316        Self::new()
317    }
318}
319
320#[cfg(test)]
321mod tests {
322    use super::*;
323
324    const NATURAL_TEXT: &str = "Rust is a systems programming language focused on safety, speed, \
325        and concurrency. It accomplishes these goals without a garbage collector, making it \
326        useful for a number of use cases other languages aren't good at: embedding in other \
327        languages, programs with specific space and time requirements, and writing low-level \
328        code, like device drivers and operating systems.";
329
330    const REPETITIVE_AI_TEXT: &str = "The the the the the. A a a a a a. The solution is great. \
331        The answer is good. The result is fine. The output is nice. The outcome is excellent. \
332        The conclusion is perfect. The end result is wonderful. The final answer is satisfactory.";
333
334    #[test]
335    fn natural_text_has_lower_ai_probability() {
336        let acs = AdversarialContentShield::new();
337        let natural = acs.analyze(NATURAL_TEXT, "rust-lang.org");
338        let repetitive = acs.analyze(REPETITIVE_AI_TEXT, "spammy.xyz");
339        assert!(
340            repetitive.ai_generated_probability >= natural.ai_generated_probability,
341            "natural_ai={:.2}, repetitive_ai={:.2}",
342            natural.ai_generated_probability,
343            repetitive.ai_generated_probability,
344        );
345    }
346
347    #[test]
348    fn shadow_mode_always_includes() {
349        let acs = AdversarialContentShield::with_mode(
350            AcsMode::Shadow,
351            Utc::now(), // just started
352        );
353        let result = acs.analyze(REPETITIVE_AI_TEXT, "spammy.xyz");
354        assert!(matches!(result.action, AcsAction::Include));
355        assert!(result.is_shadow);
356    }
357
358    #[test]
359    fn active_mode_excludes_low_trust() {
360        let acs = AdversarialContentShield::with_mode(
361            AcsMode::Active,
362            Utc::now() - chrono::Duration::days(31), // 31 days ago
363        );
364        // Force a highly manipulated-looking piece
365        let manip = "THEY SAY allegedly reportedly SOME PEOPLE CLAIM unverified sources say \
366                     RUMORED to be true allegedly allegedly allegedly allegedly allegedly";
367        let result = acs.analyze(manip, "clickbait.click");
368        // Trust score will be low; action should not be Include
369        assert!(
370            !matches!(result.action, AcsAction::Include),
371            "expected non-Include for low-trust content"
372        );
373    }
374
375    #[test]
376    fn auto_transition_to_active_after_30_days() {
377        let acs = AdversarialContentShield::with_mode(
378            AcsMode::Shadow,
379            Utc::now() - chrono::Duration::days(31),
380        );
381        assert_eq!(acs.effective_mode(), AcsMode::Active);
382    }
383}