Upload 3 files

README.md

@@ -1,12 +1,50 @@
----
-title: StreamSmartRecommender
-emoji: 🌖
-colorFrom: red
-colorTo: purple
-sdk: gradio
-sdk_version: 6.13.0
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# StreamSmart Recommender - Hugging Face Space
+
+Files included:
+- `app.py` - main Gradio app for Hugging Face Space
+- `requirements.txt` - Python dependencies
+- `n8n_streamsmart_workflow.json` - importable n8n workflow
+
+## 1) Hugging Face setup
+Create a new **Gradio Space** and replace the default files with:
+- `app.py`
+- `requirements.txt`
+
+Optional secret:
+- `N8N_WEBHOOK_URL` = your production n8n webhook URL
+
+## 2) CSV formats
+### Reviews CSV required columns
+- `title`
+- `review_text`
+
+Optional:
+- `genre`
+- `rating`
+- `user_segment`
+
+### Watch-time CSV required columns
+- `title`
+- `genre`
+- `avg_watch_time`
+- `completion_rate`
+- `drop_off_rate`
+- `rewatch_rate`
+- `click_through_rate`
+
+Rates should be decimals such as `0.82`, not percentages like `82%`.
+
+## 3) n8n setup
+In n8n:
+1. Import `n8n_streamsmart_workflow.json`
+2. Open the Webhook node and copy the **Production URL**
+3. In Hugging Face Space settings, add a secret named `N8N_WEBHOOK_URL`
+4. Rebuild the Space
+5. Run the analysis in the app, then click `Send Top Recommendations to n8n`
+
+## 4) What the app does
+- scores review sentiment with VADER
+- merges title-level sentiment with watch metrics
+- computes a weighted recommendation score
+- labels each title with a business action
+- sends the scored results to one n8n workflow

app.py

@@ -0,0 +1,380 @@
+import os
+import io
+import json
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+import gradio as gr
+import plotly.express as px
+import requests
+from vaderSentiment.vaderSentiment import SentimentIntensityAnalyzer
+
+APP_TITLE = "StreamSmart Recommender"
+APP_SUBTITLE = (
+    "Improve streaming recommendations by combining viewer review sentiment "
+    "with watch-time and engagement metrics."
+)
+
+analyzer = SentimentIntensityAnalyzer()
+
+REQUIRED_REVIEW_COLS = ["title", "review_text"]
+REQUIRED_WATCH_COLS = [
+    "title",
+    "genre",
+    "avg_watch_time",
+    "completion_rate",
+    "drop_off_rate",
+    "rewatch_rate",
+    "click_through_rate",
+]
+
+
+def clean_text(text: str) -> str:
+    if pd.isna(text):
+        return ""
+    text = str(text).strip().replace("\n", " ")
+    return " ".join(text.split())
+
+
+def compute_sentiment(text: str) -> float:
+    return analyzer.polarity_scores(clean_text(text))["compound"]
+
+
+def minmax(series: pd.Series) -> pd.Series:
+    series = pd.to_numeric(series, errors="coerce").fillna(0)
+    min_v = series.min()
+    max_v = series.max()
+    if max_v == min_v:
+        return pd.Series(np.full(len(series), 0.5), index=series.index)
+    return (series - min_v) / (max_v - min_v)
+
+
+def sentiment_label(score: float) -> str:
+    if score >= 0.2:
+        return "Positive"
+    if score <= -0.2:
+        return "Negative"
+    return "Neutral"
+
+
+def action_label(score: float) -> str:
+    if score >= 80:
+        return "Promote strongly"
+    if score >= 65:
+        return "Promote selectively"
+    if score >= 45:
+        return "Investigate mismatch"
+    return "Reduce priority"
+
+
+def business_explanation(row: pd.Series) -> str:
+    s = row["avg_sentiment"]
+    c = row["completion_rate"]
+    d = row["drop_off_rate"]
+    score = row["recommendation_score"]
+
+    if s >= 0.2 and c >= 0.7 and d <= 0.3:
+        return (
+            f"{row['title']} has strong viewer satisfaction and high completion, so it is a good candidate "
+            "for broader recommendation placement."
+        )
+    if s >= 0.2 and c < 0.7:
+        return (
+            f"{row['title']} gets positive reactions from viewers who engage with it, but completion is weaker. "
+            "This suggests the title may perform better with more targeted audience matching."
+        )
+    if s < 0.2 and c >= 0.7:
+        return (
+            f"{row['title']} keeps viewers watching, but sentiment is not especially strong. This may indicate "
+            "good initial appeal with weaker perceived quality or expectation mismatch."
+        )
+    if score < 45:
+        return (
+            f"{row['title']} shows weak satisfaction and engagement signals overall, so it should not be prioritized "
+            "in recommendation slots until content positioning improves."
+        )
+    return (
+        f"{row['title']} is a mixed case: some engagement indicators are promising, but the platform should review "
+        "audience fit, metadata, or recommendation placement before scaling promotion."
+    )
+
+
+def validate_columns(df: pd.DataFrame, required_cols: list, name: str) -> None:
+    missing = [c for c in required_cols if c not in df.columns]
+    if missing:
+        raise gr.Error(f"{name} is missing required columns: {missing}")
+
+
+def make_demo_data() -> Tuple[pd.DataFrame, pd.DataFrame]:
+    reviews = pd.DataFrame(
+        {
+            "title": [
+                "Midnight City", "Midnight City", "Ocean Echoes", "Ocean Echoes",
+                "Crimson Truth", "Crimson Truth", "Quiet Orbit", "Quiet Orbit",
+                "Laugh Track", "Laugh Track", "Golden Hour", "Golden Hour",
+            ],
+            "review_text": [
+                "Amazing pacing and really addictive storyline.",
+                "Loved the characters and watched it in one sitting.",
+                "Beautiful idea but too slow in the middle.",
+                "Strong visuals, but I almost stopped halfway.",
+                "Suspenseful and smart, one of the best thrillers.",
+                "Great acting and excellent ending.",
+                "Interesting concept but not very engaging.",
+                "Felt too long and the story did not pull me in.",
+                "Funny and light, easy to keep watching.",
+                "Very entertaining and rewatchable.",
+                "Good cast but the episodes drag a bit.",
+                "Not bad, but I expected more excitement.",
+            ],
+            "genre": [
+                "Sci-Fi", "Sci-Fi", "Drama", "Drama", "Thriller", "Thriller",
+                "Sci-Fi", "Sci-Fi", "Comedy", "Comedy", "Drama", "Drama",
+            ],
+        }
+    )
+
+    watch = pd.DataFrame(
+        {
+            "title": ["Midnight City", "Ocean Echoes", "Crimson Truth", "Quiet Orbit", "Laugh Track", "Golden Hour"],
+            "genre": ["Sci-Fi", "Drama", "Thriller", "Sci-Fi", "Comedy", "Drama"],
+            "avg_watch_time": [83, 58, 79, 41, 72, 54],
+            "completion_rate": [0.86, 0.61, 0.81, 0.39, 0.76, 0.57],
+            "drop_off_rate": [0.18, 0.33, 0.21, 0.48, 0.24, 0.37],
+            "rewatch_rate": [0.31, 0.15, 0.27, 0.08, 0.25, 0.11],
+            "click_through_rate": [0.42, 0.36, 0.39, 0.29, 0.41, 0.34],
+        }
+    )
+    return reviews, watch
+
+
+def run_analysis(reviews_file, watch_file, use_demo: bool):
+    if use_demo:
+        reviews_df, watch_df = make_demo_data()
+    else:
+        if reviews_file is None or watch_file is None:
+            raise gr.Error("Upload both CSV files or use the demo dataset.")
+        reviews_df = pd.read_csv(reviews_file.name)
+        watch_df = pd.read_csv(watch_file.name)
+
+    validate_columns(reviews_df, REQUIRED_REVIEW_COLS, "Reviews CSV")
+    validate_columns(watch_df, REQUIRED_WATCH_COLS, "Watch-time CSV")
+
+    reviews = reviews_df.copy()
+    watch = watch_df.copy()
+
+    reviews["review_text"] = reviews["review_text"].apply(clean_text)
+    reviews["sentiment_score"] = reviews["review_text"].apply(compute_sentiment)
+    reviews["sentiment_label"] = reviews["sentiment_score"].apply(sentiment_label)
+
+    agg_dict = {
+        "sentiment_score": ["mean", "count"],
+    }
+    if "genre" in reviews.columns:
+        review_agg = reviews.groupby("title", as_index=False).agg(
+            avg_sentiment=("sentiment_score", "mean"),
+            review_count=("sentiment_score", "count"),
+            dominant_genre=("genre", lambda s: s.mode().iat[0] if not s.mode().empty else s.iloc[0]),
+        )
+    else:
+        review_agg = reviews.groupby("title", as_index=False).agg(
+            avg_sentiment=("sentiment_score", "mean"),
+            review_count=("sentiment_score", "count"),
+        )
+        review_agg["dominant_genre"] = "Unknown"
+
+    merged = pd.merge(watch, review_agg, on="title", how="left")
+    merged["avg_sentiment"] = merged["avg_sentiment"].fillna(0)
+    merged["review_count"] = merged["review_count"].fillna(0).astype(int)
+    merged["genre"] = merged["genre"].fillna(merged["dominant_genre"]).fillna("Unknown")
+
+    merged["sentiment_norm"] = minmax(merged["avg_sentiment"])
+    merged["completion_norm"] = minmax(merged["completion_rate"])
+    merged["watch_norm"] = minmax(merged["avg_watch_time"])
+    merged["rewatch_norm"] = minmax(merged["rewatch_rate"])
+    merged["ctr_norm"] = minmax(merged["click_through_rate"])
+    merged["dropoff_norm"] = minmax(merged["drop_off_rate"])
+
+    raw_score = (
+        0.35 * merged["sentiment_norm"]
+        + 0.30 * merged["completion_norm"]
+        + 0.20 * merged["watch_norm"]
+        + 0.10 * merged["rewatch_norm"]
+        + 0.05 * merged["ctr_norm"]
+        - 0.15 * merged["dropoff_norm"]
+    )
+
+    merged["recommendation_score"] = (raw_score.clip(lower=0) * 100).round(2)
+    merged["action"] = merged["recommendation_score"].apply(action_label)
+    merged["explanation"] = merged.apply(business_explanation, axis=1)
+    merged = merged.sort_values("recommendation_score", ascending=False).reset_index(drop=True)
+
+    summary = (
+        f"Reviews analyzed: {len(reviews)} | Titles scored: {merged['title'].nunique()} | "
+        f"Average sentiment: {merged['avg_sentiment'].mean():.2f} | "
+        f"Average completion rate: {merged['completion_rate'].mean():.2f}"
+    )
+
+    top_table = merged[
+        [
+            "title", "genre", "avg_sentiment", "avg_watch_time", "completion_rate",
+            "drop_off_rate", "rewatch_rate", "click_through_rate", "review_count",
+            "recommendation_score", "action"
+        ]
+    ]
+
+    top_plot = px.bar(
+        merged.head(10),
+        x="title",
+        y="recommendation_score",
+        title="Top Titles by Recommendation Score",
+    )
+    scatter_plot = px.scatter(
+        merged,
+        x="avg_sentiment",
+        y="completion_rate",
+        size="avg_watch_time",
+        hover_name="title",
+        color="genre",
+        title="Sentiment vs Completion Rate",
+    )
+    genre_plot = px.bar(
+        merged.groupby("genre", as_index=False)["recommendation_score"].mean().sort_values("recommendation_score", ascending=False),
+        x="genre",
+        y="recommendation_score",
+        title="Average Recommendation Score by Genre",
+    )
+
+    processed_csv = io.StringIO()
+    top_table.to_csv(processed_csv, index=False)
+
+    payload = merged.to_json(orient="records")
+    return summary, top_table, top_plot, scatter_plot, genre_plot, payload, processed_csv.getvalue()
+
+
+def inspect_title(payload: str, selected_title: str):
+    if not payload:
+        raise gr.Error("Run the analysis first.")
+    records = json.loads(payload)
+    df = pd.DataFrame(records)
+    if selected_title not in df["title"].values:
+        raise gr.Error("Title not found.")
+    row = df[df["title"] == selected_title].iloc[0]
+    return (
+        f"Title: {row['title']}\n"
+        f"Genre: {row['genre']}\n"
+        f"Average sentiment: {row['avg_sentiment']:.2f}\n"
+        f"Average watch time: {row['avg_watch_time']:.2f}\n"
+        f"Completion rate: {row['completion_rate']:.2f}\n"
+        f"Drop-off rate: {row['drop_off_rate']:.2f}\n"
+        f"Recommendation score: {row['recommendation_score']:.2f}\n"
+        f"Suggested action: {row['action']}\n\n"
+        f"Explanation: {row['explanation']}"
+    )
+
+
+def update_title_choices(payload: str):
+    if not payload:
+        return gr.Dropdown(choices=[], value=None)
+    df = pd.DataFrame(json.loads(payload))
+    choices = sorted(df["title"].dropna().unique().tolist())
+    value = choices[0] if choices else None
+    return gr.Dropdown(choices=choices, value=value)
+
+
+def send_to_n8n(payload: str):
+    if not payload:
+        raise gr.Error("Run the analysis first.")
+
+    webhook_url = os.getenv("N8N_WEBHOOK_URL", "").strip()
+    if not webhook_url:
+        return (
+            "N8N_WEBHOOK_URL is not set yet. Add it as a Hugging Face Space secret, then try again."
+        )
+
+    data = json.loads(payload)
+    top5 = data[:5]
+    response = requests.post(webhook_url, json={"app": APP_TITLE, "top_recommendations": top5, "all_results": data}, timeout=60)
+    response.raise_for_status()
+
+    try:
+        result = response.json()
+        return f"n8n workflow ran successfully. Response: {json.dumps(result, indent=2)}"
+    except Exception:
+        return f"n8n workflow ran successfully. Raw response: {response.text}"
+
+
+with gr.Blocks(title=APP_TITLE) as demo:
+    gr.Markdown(f"# {APP_TITLE}\n\n{APP_SUBTITLE}")
+    gr.Markdown(
+        "This app combines qualitative viewer review sentiment with quantitative watch-time metrics "
+        "to score how strongly each title should be recommended on a streaming platform."
+    )
+
+    payload_state = gr.State("")
+    csv_state = gr.State("")
+
+    with gr.Tab("1. Upload & Run"):
+        use_demo = gr.Checkbox(label="Use built-in demo dataset", value=True)
+        reviews_file = gr.File(label="Upload reviews CSV", file_types=[".csv"])
+        watch_file = gr.File(label="Upload watch-time CSV", file_types=[".csv"])
+        run_btn = gr.Button("Run Analysis", variant="primary")
+        summary_box = gr.Textbox(label="Processing Summary", lines=2)
+
+    with gr.Tab("2. Dashboard"):
+        results_table = gr.Dataframe(label="Scored Titles")
+        chart_1 = gr.Plot(label="Top Recommendation Scores")
+        chart_2 = gr.Plot(label="Sentiment vs Completion")
+        chart_3 = gr.Plot(label="Genre Performance")
+
+    with gr.Tab("3. Title Drilldown"):
+        title_dropdown = gr.Dropdown(label="Select a title", choices=[])
+        detail_box = gr.Textbox(label="Title Recommendation Detail", lines=10)
+        inspect_btn = gr.Button("Explain Selected Title")
+
+    with gr.Tab("4. n8n Automation"):
+        gr.Markdown(
+            "This button sends your scored results to one n8n workflow through a webhook. "
+            "Set the `N8N_WEBHOOK_URL` secret in your Hugging Face Space first."
+        )
+        n8n_btn = gr.Button("Send Top Recommendations to n8n")
+        n8n_status = gr.Textbox(label="n8n Status", lines=5)
+
+    with gr.Tab("5. Download"):
+        download_file = gr.File(label="Download processed CSV")
+
+    def save_csv_text(csv_text: str):
+        path = "/tmp/processed_streamsmart_results.csv"
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(csv_text)
+        return path
+
+    run_btn.click(
+        fn=run_analysis,
+        inputs=[reviews_file, watch_file, use_demo],
+        outputs=[summary_box, results_table, chart_1, chart_2, chart_3, payload_state, csv_state],
+    ).then(
+        fn=update_title_choices,
+        inputs=[payload_state],
+        outputs=[title_dropdown],
+    ).then(
+        fn=save_csv_text,
+        inputs=[csv_state],
+        outputs=[download_file],
+    )
+
+    inspect_btn.click(
+        fn=inspect_title,
+        inputs=[payload_state, title_dropdown],
+        outputs=[detail_box],
+    )
+
+    n8n_btn.click(
+        fn=send_to_n8n,
+        inputs=[payload_state],
+        outputs=[n8n_status],
+    )
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,6 @@
+gradio>=4.44.0
+pandas>=2.2.2
+numpy>=1.26.4
+plotly>=5.24.1
+requests>=2.32.3
+vaderSentiment>=3.3.2