diff --git a/.gitignore b/.gitignore index 8f47f85..ca615cd 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,6 @@ *.db-shm *.db-wal .env + +.idea/** +.claude/worktrees/** \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml index d3b9ca3..355f5a3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,7 @@ members = [ [workspace.package] edition = "2021" version = "0.1.0" -license = "MIT" +license = "AGPL-3" [workspace.dependencies] tokio = { version = "1", features = ["full"] } diff --git a/crates/core/src/affinity.rs b/crates/core/src/affinity.rs index f49bd18..1ac906b 100644 --- a/crates/core/src/affinity.rs +++ b/crates/core/src/affinity.rs @@ -117,10 +117,10 @@ mod tests { // --- apply_feedback: new = clamp(current + LEARNING_RATE(0.15) * surprise, -1, 1) --- + /// Positive surprise (engaged more than predicted) should move the + /// score up, never down or unchanged. #[test] fn under_predicted_relevance_boosts_topic() { - // Positive surprise (engaged more than predicted) should move the - // score up, never down or unchanged. let mut aff = TopicAffinities::default(); let topics = vec!["rust".to_string()]; // Model predicted 0.2 relevance, user fully read it: surprise = 0.8. @@ -128,10 +128,10 @@ mod tests { assert!(aff.score("rust") > 0.0); } + /// Negative surprise (engaged less than predicted) should move the + /// score down, the mirror image of the boost case above. #[test] fn over_predicted_relevance_lowers_topic() { - // Negative surprise (engaged less than predicted) should move the - // score down, the mirror image of the boost case above. let mut aff = TopicAffinities::default(); let topics = vec!["crypto".to_string()]; // Model predicted 0.9, user dismissed unread: engagement 0, surprise = -0.9. @@ -139,11 +139,11 @@ mod tests { assert!(aff.score("crypto") < 0.0); } + /// Scores are documented to live in [-1.0, 1.0]. Repeated max-surprise + /// feedback would overshoot 1.0 without the clamp, so this guards the + /// invariant directly rather than trusting a single update. #[test] fn apply_feedback_clamps_at_positive_one() { - // Scores are documented to live in [-1.0, 1.0]. Repeated max-surprise - // feedback would overshoot 1.0 without the clamp, so this guards the - // invariant directly rather than trusting a single update. let mut aff = TopicAffinities::default(); let topics = vec!["rust".to_string()]; for _ in 0..20 { @@ -152,9 +152,9 @@ mod tests { assert_eq!(aff.score("rust"), 1.0); } + /// Verifies a decay from a large negative value doesn't overshoot and go beyond -1.0 #[test] fn apply_feedback_clamps_at_negative_one() { - // Same invariant as above, checked on the negative side. let mut aff = TopicAffinities::default(); let topics = vec!["crypto".to_string()]; for _ in 0..20 { @@ -163,11 +163,11 @@ mod tests { assert_eq!(aff.score("crypto"), -1.0); } + /// apply_feedback loops over every topic on the article and applies + /// the same surprise to each independently; it must not skip topics + /// or bleed the update into topics the article wasn't tagged with. #[test] fn apply_feedback_updates_every_topic_on_the_article() { - // apply_feedback loops over every topic on the article and applies - // the same surprise to each independently; it must not skip topics - // or bleed the update into topics the article wasn't tagged with. let mut aff = TopicAffinities::default(); let topics = vec!["rust".to_string(), "async".to_string()]; aff.apply_feedback(&topics, 0.4); @@ -177,10 +177,10 @@ mod tests { assert_eq!(aff.score("crypto"), 0.0); } + /// surprise = 0.0 means engagement exactly matched the prediction, so + /// the score shouldn't move at all (current + 0.15 * 0.0 == current). #[test] fn apply_feedback_zero_surprise_is_a_noop() { - // surprise = 0.0 means engagement exactly matched the prediction, so - // the score shouldn't move at all (current + 0.15 * 0.0 == current). let mut aff = TopicAffinities::default(); let topics = vec!["rust".to_string()]; aff.apply_feedback(&topics, 0.5); @@ -191,10 +191,10 @@ mod tests { // --- decay: v -= sign(v) * DAILY_DECAY(0.02), settling at 0 instead of overshooting --- + /// Core decay behavior: a positive score should shrink toward zero + /// after one nightly pass, without crossing it. #[test] fn decay_pulls_toward_zero() { - // Core decay behavior: a positive score should shrink toward zero - // after one nightly pass, without crossing it. let mut aff = TopicAffinities::default(); aff.apply_feedback(&["rust".to_string()], 1.0); let before = aff.score("rust"); @@ -203,11 +203,11 @@ mod tests { assert!(aff.score("rust") > 0.0); } + /// Pins the exact arithmetic (not just the direction) so a future + /// change to the decay formula is caught immediately. + /// surprise 1.0 -> 0.15, then one decay pass subtracts DAILY_DECAY (0.02). #[test] fn decay_gives_expected_value() { - // Pins the exact arithmetic (not just the direction) so a future - // change to the decay formula is caught immediately. - // surprise 1.0 -> 0.15, then one decay pass subtracts DAILY_DECAY (0.02). let mut aff = TopicAffinities::default(); aff.apply_feedback(&["java".to_string()], 1.0); aff.decay(); @@ -215,33 +215,33 @@ mod tests { assert_eq!(aff.score("java"), 0.13); } + /// Regression test for a real bug: subtracting a fixed 0.02 from a + /// smaller score (e.g. 0.015) used to flip its sign to -0.005 instead + /// of landing on 0.0, which would make the score oscillate around + /// zero on every subsequent decay pass rather than settling. #[test] fn decay_settles_at_zero_instead_of_overshooting() { - // Regression test for a real bug: subtracting a fixed 0.02 from a - // smaller score (e.g. 0.015) used to flip its sign to -0.005 instead - // of landing on 0.0, which would make the score oscillate around - // zero on every subsequent decay pass rather than settling. let mut aff = TopicAffinities::default(); aff.apply_feedback(&["rust".to_string()], 0.1); // score = 0.015 aff.decay(); assert_eq!(aff.score("rust"), 0.0); } + /// Same fix as above, verified on the negative side, and also checks + /// that the post-decay prune (dropping |v| <= 1e-4) actually removes + /// the entry rather than leaving a stray 0.0 in the map. #[test] fn decay_prunes_negative_scores_that_settle_at_zero() { - // Same fix as above, verified on the negative side, and also checks - // that the post-decay prune (dropping |v| <= 1e-4) actually removes - // the entry rather than leaving a stray 0.0 in the map. let mut aff = TopicAffinities::default(); aff.apply_feedback(&["crypto".to_string()], -0.1); // score = -0.015 aff.decay(); assert_eq!(aff.score("crypto"), 0.0); } + /// decay_pulls_toward_zero's mirror image: negative scores should + /// shrink in magnitude too, not just positive ones. #[test] fn decay_is_symmetric_for_negative_scores() { - // decay_pulls_toward_zero's mirror image: negative scores should - // shrink in magnitude too, not just positive ones. let mut aff = TopicAffinities::default(); aff.apply_feedback(&["crypto".to_string()], -1.0); let before = aff.score("crypto"); @@ -252,27 +252,27 @@ mod tests { // --- score / get_mean_affinity --- + /// A topic with no feedback yet must read as neutral (0.0), not + /// panic or return some other sentinel. #[test] fn score_defaults_to_zero_for_unknown_topic() { - // A topic with no feedback yet must read as neutral (0.0), not - // panic or return some other sentinel. let aff = TopicAffinities::default(); assert_eq!(aff.score("never-seen"), 0.0); } + /// Documented behavior for untagged articles: defer entirely to the + /// embedding/LLM stages by returning a neutral 0.0 rather than + /// dividing by zero. #[test] fn get_mean_affinity_given_empty_topics_returns_zero() { - // Documented behavior for untagged articles: defer entirely to the - // embedding/LLM stages by returning a neutral 0.0 rather than - // dividing by zero. let aff = TopicAffinities::default(); assert_eq!(aff.get_mean_affinity(&[]), 0.0); } + /// Confirms it's a plain arithmetic mean: an equally strong positive + /// and negative topic on the same article should cancel out to 0.0. #[test] fn get_mean_affinity_averages_across_topics() { - // Confirms it's a plain arithmetic mean: an equally strong positive - // and negative topic on the same article should cancel out to 0.0. let mut aff = TopicAffinities::default(); aff.apply_feedback(&["rust".to_string()], 1.0); // 0.15 aff.apply_feedback(&["crypto".to_string()], -1.0); // -0.15 @@ -280,11 +280,11 @@ mod tests { assert_eq!(aff.get_mean_affinity(&topics), 0.0); } + /// A topic mix of "known" and "never seen" shouldn't shrink the + /// denominator or get skipped — the unscored topic counts as 0.0 in + /// the average, per score()'s default. #[test] fn get_mean_affinity_treats_unscored_topics_as_zero() { - // A topic mix of "known" and "never seen" shouldn't shrink the - // denominator or get skipped — the unscored topic counts as 0.0 in - // the average, per score()'s default. let mut aff = TopicAffinities::default(); aff.apply_feedback(&["rust".to_string()], 1.0); // 0.15 let topics = vec!["rust".to_string(), "never-seen".to_string()]; @@ -293,10 +293,10 @@ mod tests { // --- top_n --- + /// top_n is used to surface a user's strongest interests, so it must + /// sort highest-first (not insertion order) and respect the limit. #[test] fn top_n_sorts_descending_and_truncates() { - // top_n is used to surface a user's strongest interests, so it must - // sort highest-first (not insertion order) and respect the limit. let mut aff = TopicAffinities::default(); aff.apply_feedback(&["low".to_string()], 0.2); aff.apply_feedback(&["high".to_string()], 1.0); @@ -310,72 +310,72 @@ mod tests { // --- engagement_score --- + /// No signal at all (not opened, not dismissed) is neutral, not + /// penalized. #[test] fn engagement_score_never_opened_is_zero() { - // No signal at all (not opened, not dismissed) is neutral, not - // penalized. assert_eq!(engagement_score(false, None, None, false, false), 0.0); } + /// Dismissing without opening is an explicit negative signal, but + /// engagement_score itself is floored at 0.0 (the doc comment notes + /// the negative direction is expressed later via `surprise`, not + /// here) — this pins that the dismissed+!opened branch returns 0.0, + /// not a negative number. #[test] fn engagement_score_dismissed_without_opening_is_zero() { - // Dismissing without opening is an explicit negative signal, but - // engagement_score itself is floored at 0.0 (the doc comment notes - // the negative direction is expressed later via `surprise`, not - // here) — this pins that the dismissed+!opened branch returns 0.0, - // not a negative number. assert_eq!(engagement_score(false, None, None, false, true), 0.0); } + /// Reading half the estimated time should score as half-engaged. #[test] fn engagement_score_opened_uses_dwell_over_estimate_ratio() { - // Reading half the estimated time should score as half-engaged. assert_eq!( engagement_score(true, Some(30), Some(60), false, false), 0.5 ); } + /// Dwelling far longer than the estimate (e.g. left the tab open) + /// must not push the score above the documented [0.0, 1.0] range. #[test] fn engagement_score_opened_caps_ratio_at_one() { - // Dwelling far longer than the estimate (e.g. left the tab open) - // must not push the score above the documented [0.0, 1.0] range. assert_eq!( engagement_score(true, Some(600), Some(60), false, false), 1.0 ); } + /// When we simply don't have dwell/estimate data yet, the code + /// credits partial engagement (0.5) rather than assuming 0 (unfairly + /// penalizing) or 1 (unfairly rewarding). #[test] fn engagement_score_opened_without_dwell_or_estimate_defaults_to_half() { - // When we simply don't have dwell/estimate data yet, the code - // credits partial engagement (0.5) rather than assuming 0 (unfairly - // penalizing) or 1 (unfairly rewarding). assert_eq!(engagement_score(true, None, None, false, false), 0.5); } + /// est == 0 would divide by zero, so the `est > 0` guard routes this + /// case to the same "unknown read time" default (0.5) instead of + /// panicking or producing NaN/infinity. #[test] fn engagement_score_opened_with_zero_estimate_defaults_to_half() { - // est == 0 would divide by zero, so the `est > 0` guard routes this - // case to the same "unknown read time" default (0.5) instead of - // panicking or producing NaN/infinity. assert_eq!(engagement_score(true, Some(10), Some(0), false, false), 0.5); } + /// Starring is an explicit "yes" beyond dwell time: it should add + /// 0.3 on top of the dwell-ratio score. #[test] fn engagement_score_starred_adds_bonus() { - // Starring is an explicit "yes" beyond dwell time: it should add - // 0.3 on top of the dwell-ratio score. assert_eq!( engagement_score(true, Some(30), Some(60), true, false), 0.8 ); } + /// The +0.3 star bonus must also respect the 1.0 ceiling, even when + /// the dwell ratio alone is already at the max. #[test] fn engagement_score_starred_bonus_caps_at_one() { - // The +0.3 star bonus must also respect the 1.0 ceiling, even when - // the dwell ratio alone is already at the max. assert_eq!( engagement_score(true, Some(60), Some(60), true, false), 1.0 diff --git a/crates/core/src/scoring.rs b/crates/core/src/scoring.rs index fba8353..fe64420 100644 --- a/crates/core/src/scoring.rs +++ b/crates/core/src/scoring.rs @@ -22,7 +22,7 @@ const W_EMBEDDING: f32 = 0.25; const W_AFFINITY: f32 = 0.15; pub fn score_article(inputs: RelevanceInputs) -> f32 { - let affinity = inputs.affinities.score_topics(inputs.topics) as f32; // [-1, 1] + let affinity = inputs.affinities.get_mean_affinity(inputs.topics) as f32; // [-1, 1] let affinity_component = (affinity + 1.0) / 2.0; // renormalize to [0, 1] match inputs.llm_score { diff --git a/crates/web/src/app.rs b/crates/web/src/app.rs index 50017b2..d6784e0 100644 --- a/crates/web/src/app.rs +++ b/crates/web/src/app.rs @@ -19,7 +19,7 @@ pub fn App() -> Element { let articles = use_server_future(list_ranked_articles)?; rsx! { - style { {include_str!("../assets/app.css")} } + Stylesheet { href: asset!("/assets/app.css") } main { h1 { "feedsignal" } match articles.read().as_ref() {