Improve recommendations endpoint

Author: dcadenas

src/http_server/handlers.rs

@@ -2,28 +2,52 @@ use super::router::ApiError;
 use super::AppState;
 use crate::relay_subscriber::GetEventsOf;
 use crate::repo::{Recommendation, RepoTrait};
-use axum::{extract::State, http::HeaderMap, response::Html, response::IntoResponse, Json};
+use axum::{
+    extract::{Query, State},
+    http::HeaderMap,
+    response::Html,
+    response::IntoResponse,
+    Json,
+};
 use nostr_sdk::PublicKey;
+use serde::Deserialize;
 use std::sync::Arc;
 
+#[derive(Debug, Deserialize)]
+pub struct RecommendationParams {
+    min_pagerank: Option<f64>,
+    limit: Option<usize>,
+}
+
 pub async fn cached_get_recommendations<T, U>(
     State(state): State<Arc<AppState<T, U>>>,
     axum::extract::Path(pubkey): axum::extract::Path<String>,
+    Query(params): Query<RecommendationParams>,
 ) -> Result<Json<Vec<Recommendation>>, ApiError>
 where
     T: RepoTrait,
     U: GetEventsOf,
 {
     let public_key = PublicKey::from_hex(&pubkey).map_err(ApiError::InvalidPublicKey)?;
-    if let Some(cached_recommendation_result) = state.recommendation_cache.get(&pubkey).await {
+
+    // Create cache key that includes parameters
+    let cache_key = format!(
+        "{}:{}:{}",
+        pubkey,
+        params.min_pagerank.unwrap_or(0.3),
+        params.limit.unwrap_or(50)
+    );
+
+    if let Some(cached_recommendation_result) = state.recommendation_cache.get(&cache_key).await {
         return Ok(Json(cached_recommendation_result));
     }
 
-    let recommendations = get_recommendations(&state.repo, public_key).await?;
+    let recommendations =
+        get_recommendations(&state.repo, public_key, params.min_pagerank, params.limit).await?;
 
     state
         .recommendation_cache
-        .insert(pubkey, recommendations.clone())
+        .insert(cache_key, recommendations.clone())
         .await;
 
     Ok(Json(recommendations))
@@ -32,11 +56,13 @@ where
 async fn get_recommendations<T>(
     repo: &Arc<T>,
     public_key: PublicKey,
+    min_pagerank: Option<f64>,
+    limit: Option<usize>,
 ) -> Result<Vec<Recommendation>, ApiError>
 where
     T: RepoTrait,
 {
-    repo.get_recommendations(&public_key)
+    repo.get_recommendations(&public_key, min_pagerank, limit)
         .await
         .map_err(ApiError::from)
 }

src/repo.rs

@@ -103,6 +103,8 @@ pub trait RepoTrait: Sync + Send + 'static {
     fn get_recommendations(
         &self,
         _pubkey: &PublicKey,
+        _min_pagerank: Option<f64>,
+        _limit: Option<usize>,
     ) -> impl std::future::Future<Output = Result<Vec<Recommendation>, RepoError>> + std::marker::Send
     {
         async { panic!("Not implemented") }
@@ -458,12 +460,29 @@ impl RepoTrait for Repo {
     async fn get_recommendations(
         &self,
         pubkey: &PublicKey,
+        min_pagerank: Option<f64>,
+        limit: Option<usize>,
     ) -> Result<Vec<Recommendation>, RepoError> {
+        // Validate and set defaults
+        let min_pagerank = min_pagerank.unwrap_or(0.3);
+        if min_pagerank < 0.0 {
+            return Err(RepoError::InvalidParameter(
+                "min_pagerank must be non-negative".into(),
+            ));
+        }
+
+        let limit = limit.unwrap_or(50);
+        if limit == 0 {
+            return Err(RepoError::InvalidParameter(
+                "limit must be greater than 0".into(),
+            ));
+        }
+
         let statement = r#"
             // Step 1: Get valid target nodes
             MATCH (source:User {pubkey: $pubkey_val})
             MATCH (target:User)
-            WHERE target.pagerank >= 0.3
+            WHERE target.pagerank >= $min_pagerank
             AND NOT EXISTS {
                 MATCH (source)-[:FOLLOWS]->(target)
             }
@@ -473,19 +492,28 @@ impl RepoTrait for Repo {
             CALL gds.nodeSimilarity.filtered.stream('filteredGraph', {
                 sourceNodeFilter: [id(source)],
                 targetNodeFilter: targetNodeIds,
-                topK: 10,
+                topK: $limit,
                 similarityCutoff: 0.1
             })
             YIELD node1, node2, similarity
             WITH gds.util.asNode(node2) AS targetUser, similarity
+
+            // Step 3: Count how many of source's follows also follow the target
+            OPTIONAL MATCH (source)-[:FOLLOWS]->(mutual:User)-[:FOLLOWS]->(targetUser)
+            WITH targetUser, similarity, count(DISTINCT mutual) AS mutualFollowCount
+
             RETURN targetUser.pubkey AS target_pubkey,
                    targetUser.friendly_id AS friendly_id,
                    similarity,
-                   targetUser.pagerank AS pagerank
+                   targetUser.pagerank AS pagerank,
+                   mutualFollowCount
             ORDER BY similarity DESC, pagerank DESC;
         "#;
 
-        let query = query(statement).param("pubkey_val", pubkey.to_hex());
+        let query = query(statement)
+            .param("pubkey_val", pubkey.to_hex())
+            .param("min_pagerank", min_pagerank)
+            .param("limit", limit as i64);
 
         let mut records = self
             .graph
@@ -507,13 +535,28 @@ impl RepoTrait for Repo {
             let pagerank: f64 = row.get::<f64>("pagerank").map_err(|e| {
                 RepoError::deserialization_with_context(e, "deserializing 'pagerank' field")
             })?;
+            let mutual_follow_count: i64 = row.get::<i64>("mutualFollowCount").unwrap_or(0);
+
+            // Determine recommendation reason
+            let reason_type = if similarity > 0.5 {
+                RecommendationReason::HighSimilarity
+            } else if similarity > 0.3 {
+                RecommendationReason::ModerateSimularity
+            } else if mutual_follow_count > 5 {
+                RecommendationReason::FollowedByMany
+            } else if pagerank > 1.0 {
+                RecommendationReason::PopularAccount
+            } else {
+                RecommendationReason::ModerateSimularity
+            };
 
             recommendations.push(Recommendation {
                 pubkey: PublicKey::from_hex(&pubkey)
                     .map_err(RepoError::GetRecommendationsPubkey)?,
                 friendly_id,
                 similarity,
                 pagerank,
+                reason_type,
             });
         }
 
@@ -710,6 +753,9 @@ pub enum RepoError {
 
     #[error("Failed to remove pubkey: {0}")]
     RemovePubkey(neo4rs::Error),
+
+    #[error("Invalid parameter: {0}")]
+    InvalidParameter(String),
 }
 
 impl RepoError {
@@ -724,10 +770,20 @@ impl RepoError {
     }
 }
 
+#[derive(Debug, Serialize, Clone)]
+#[serde(rename_all = "snake_case")]
+pub enum RecommendationReason {
+    HighSimilarity,     // Similarity score > 0.5
+    ModerateSimularity, // Similarity score 0.3-0.5
+    PopularAccount,     // High pagerank but lower similarity
+    FollowedByMany,     // Many of your follows also follow them
+}
+
 #[derive(Debug, Serialize, Clone)]
 pub struct Recommendation {
-    pubkey: PublicKey,
-    friendly_id: String,
-    similarity: f64,
-    pagerank: f64,
+    pub pubkey: PublicKey,
+    pub friendly_id: String,
+    pub similarity: f64,
+    pub pagerank: f64,
+    pub reason_type: RecommendationReason,
 }