Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,5 @@
+venv/
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+# Set environment variables
+ENV PYTHONPATH="/app"
+ENV PYTHONUNBUFFERED=1
+
+# Create non-root user for Hugging Face Spaces
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR /app
+
+# Copy requirements first for better caching
+COPY --chown=user:user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+# Copy application code
+COPY --chown=user:user . .
+
+# Expose port (7860 for HF Spaces, can be overridden)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+  CMD curl -f http://localhost:7860/health || exit 1
+
+# Start the server
+# Use single worker to minimize memory usage
+CMD ["python", "-m", "gunicorn", "-b", "0.0.0.0:7860", "--workers", "1", "--threads", "2", "--timeout", "120", "server.api:app"]

LICENSE

@@ -0,0 +1,12 @@
+Warner Bros. Discovery Hackathon License (WBDHL)
+
+Copyright (c) 2025 - present Warner Bros. Discovery, Inc. or its subsidiaries and affiliates.
+
+This software and associated documentation files (the “Software”) are proprietary and confidential, 
+and Warner Bros. Discovery, Inc. or its subsidiaries and affiliates (“WBD”) reserves all rights to 
+the Software. Authorized participants in a hackathon hosted by WBD may use the Software solely for 
+internal research and development purposes within WBD. Any other use of the Software is strictly 
+prohibited. The Software may not be published, distributed, redistributed, sublicensed, rented, sold, 
+exported, or lent, unless WBD expressly provides separate authorization to do so. The Software may 
+not be copied, modified, or merged for any purpose other than internal research and development 
+purposes within WBD, unless WBD expressly provides separate authorization to do so.

README.md

@@ -1,12 +1,71 @@
 ---
-title: DynamicRail
-emoji: 🌍
+title: FF1000 Recommendation Service
+emoji: 🎬
 colorFrom: purple
-colorTo: red
+colorTo: blue
 sdk: docker
-pinned: false
-license: mit
-short_description: Prototype
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# FF1000 - ML Recommendation Service
+
+A pretrained recommendation service for content discovery, providing similarity-based and personalized recommendations.
+
+## API Endpoints
+
+### Health Check
+```
+GET /health
+```
+Returns `{"status": "ok"}` when the service is running.
+
+### Predict Endpoint
+```
+POST /predict/<model_name>
+Content-Type: application/json
+```
+
+**Available models:**
+- `similarity` - Find similar content based on embeddings
+- `rfy` - "Recommended for you" personalized recommendations  
+- `nfm` - "Not for me" content filtering
+
+**Request body:**
+```json
+{
+  "items": ["item_id_1", "item_id_2"]
+}
+```
+
+**Response:**
+```json
+{
+  "model": "similarity",
+  "predictions": [
+    {
+      "item_ids": ["..."],
+      "titles": ["..."],
+      "scores": [0.95, 0.87, ...],
+      "posters": ["https://...", ...],
+      "premiere_years": [2023, 2022, ...]
+    }
+  ]
+}
+```
+
+## Example Usage
+
+```bash
+curl -X POST https://YOUR-SPACE.hf.space/predict/similarity \
+  -H "Content-Type: application/json" \
+  -d '{"items": ["ab553cdc-e15d-4597-b65f-bec9201fd2dd"]}'
+```
+
+## Architecture
+
+The service loads pre-computed embeddings and serves three recommendation models:
+- **Similarity**: Cosine distance between content embeddings
+- **RFY**: Variance-explained recommendations for personalization
+- **NFM**: Negative preference modeling
+
+Built with Flask and scikit-learn.

app.py

@@ -0,0 +1,26 @@
+"""
+FF1000 Recommendation Service - Hugging Face Spaces Entry Point
+"""
+import os
+import sys
+import logging
+
+# Set up logging
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO"),
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    stream=sys.stdout,
+)
+log = logging.getLogger("ff1000-hf")
+
+# Import the Flask app from server.api
+from server.api import app
+
+# Hugging Face Spaces expects the app to be available as 'app'
+# The app will be run by the Spaces infrastructure
+
+if __name__ == "__main__":
+    # For local testing
+    port = int(os.environ.get("PORT", 7860))
+    app.run(host="0.0.0.0", port=port, debug=False)
+

machine_learning/datasets/embeddings_csv.py

@@ -0,0 +1,20 @@
+import json
+import pandas as pd
+import os
+
+
+class EmbeddingsDataLoader:
+    def __init__(
+        self,
+        filepath=None,
+    ):
+        if filepath is None:
+            # Use relative path from this file's location
+            current_dir = os.path.dirname(os.path.abspath(__file__))
+            filepath = os.path.join(current_dir, '..', 'prefetched', 'embeddings.csv.gz')
+        self.filepath = filepath
+
+    def load(self) -> pd.DataFrame:
+        df = pd.read_csv(self.filepath, compression='gzip')
+        df.embedding = df.embedding.apply(lambda vec: [float(v) for v in json.loads(vec)])
+        return df

machine_learning/datasets/embeddings_databricks.py

@@ -0,0 +1,50 @@
+import pandas as pd
+from pyspark.sql.session import SparkSession
+
+
+EMBEDDINGS_SQL = """
+SELECT DISTINCT
+  e.item_id,
+  s.seriesMainTitle AS title,
+  e.embedding
+FROM
+  {item_embeddings} e
+INNER JOIN
+  {s2s_content_entities} s
+  ON e.item_id = s.unpackedValue.series.id.id
+INNER JOIN
+  {series_offering_dim} off
+ON
+  s.unpackedValue.series.id.id = off.series_id
+  AND SIZE(ARRAY_INTERSECT(off.country_codes, ARRAY('US'))) > 0
+WHERE
+  date = (SELECT MAX(date) FROM bolt_recs_prod.gold.item_embeddings)
+  AND n_dimensions = 1536
+"""
+
+
+class EmbeddingsDataLoader:
+    def __init__(
+        self,
+        env: str = "prod",
+        spark_session: SparkSession = None,
+        item_embeddings: str = "bolt_recs_prod.gold.item_embeddings",
+        s2s_content_entities: str = "bolt_cep_prod.gold.s2s_content_entities",
+        series_offering_dim: str = "bolt_dai_ckg_prod.gold.series_offering_dim",
+    ):
+        if not spark_session:
+            spark_session = SparkSession.builder.appName(
+                "embeddings"
+            ).getOrCreate()
+
+        self._env = env
+        self._spark_session = spark_session
+        self._table_names = {
+            "item_embeddings": item_embeddings,
+            "s2s_content_entities": s2s_content_entities,
+            "series_offering_dim": series_offering_dim,
+        }
+
+    def load(self) -> pd.DataFrame:
+        query = EMBEDDINGS_SQL.format(**self._table_names)
+        return self._spark_session.sql(query).toPandas()

machine_learning/load_models.py

@@ -0,0 +1,35 @@
+import numpy as np
+
+from sklearn.pipeline import Pipeline
+
+from machine_learning.datasets.embeddings_csv import EmbeddingsDataLoader
+from machine_learning.models.rfy import BayesianRecommender
+from machine_learning.models.similarity import SimilarityRecommender
+from machine_learning.transformers.inverter import Inverter
+from machine_learning.transformers.item_encoder import ItemIdOneHotEncoder
+from machine_learning.transformers.scores_to_dict import ScoresToDict
+
+
+catalog = EmbeddingsDataLoader().load()
+embeddings = np.array(catalog.embedding.tolist())
+posters = catalog.poster if 'poster' in catalog.columns else None
+premiere_years = catalog.premiere_year if 'premiere_year' in catalog.columns else None
+
+recommended_for_you = Pipeline([
+    ('encoder', ItemIdOneHotEncoder(catalog.item_id)),
+    ('ranker', BayesianRecommender(embeddings)),
+    ('scores_to_dict', ScoresToDict(catalog.item_id, catalog.title, posters, premiere_years)),
+]).fit([])
+
+not_for_me = Pipeline([
+    ('encoder', ItemIdOneHotEncoder(catalog.item_id)),
+    ('inverter', Inverter()),
+    ('ranker', BayesianRecommender(embeddings)),
+    ('scores_to_dict', ScoresToDict(catalog.item_id, catalog.title, posters, premiere_years)),
+]).fit([])
+
+similarity = Pipeline([
+    ('encoder', ItemIdOneHotEncoder(catalog.item_id)),
+    ('ranker', SimilarityRecommender(embeddings)),
+    ('scores_to_dict', ScoresToDict(catalog.item_id, catalog.title, posters, premiere_years)),
+]).fit([])

machine_learning/models/rfy.py

@@ -0,0 +1,57 @@
+import numpy as np
+from sklearn.base import BaseEstimator
+
+
+class BayesianRecommender(BaseEstimator):
+    def __init__(self,
+                 item_embeddings: np.ndarray,
+                 lambda_reg: float = 1.0,
+                 sigma2: float = 1.0,
+                 z: float = -1.1645,  # -1.645=<10% LCB
+                 mask_value: float = -np.inf):
+
+        self.item_embeddings = np.asarray(item_embeddings, dtype=np.float64)
+        self.N_, self.d_ = self.item_embeddings.shape
+
+        self.lambda_reg = float(lambda_reg)
+        self.sigma2 = float(sigma2)
+        self.z = float(z)
+        self.mask_value = mask_value
+
+        self.X_items = self.item_embeddings
+        self.XT_items = self.item_embeddings.T
+
+    def fit(self, X=None, y=None):
+        return self
+
+    def _user_posterior_and_scores(self, y_vec: np.ndarray):
+        seen_mask = y_vec != 0
+        X_obs = self.X_items[seen_mask]
+        y_obs = y_vec[seen_mask].astype(np.float64)
+        A = self.lambda_reg * np.eye(self.d_, dtype=np.float64) + (X_obs.T @ X_obs) / self.sigma2
+        invA = np.linalg.inv(A)
+        mu = invA @ (X_obs.T @ y_obs) / self.sigma2
+
+        m = self.X_items @ mu
+        XinvA = self.X_items @ invA
+        s2 = np.einsum('ij,ij->i', XinvA, self.X_items)
+        s = np.sqrt(np.clip(s2, 0.0, None))
+
+        scores = m + self.z * s
+        scores[seen_mask] = self.mask_value
+
+        return scores
+
+    def transform(self, X):
+        X = np.asarray(X, dtype=np.float64)
+        if X.ndim == 1:
+            X = X[None, :]
+
+        B, N = X.shape
+        if N != self.N_:
+            raise ValueError(f"Input width {N} != number of items {self.N_}.")
+
+        out = np.empty((B, N), dtype=np.float64)
+        for b in range(B):
+            out[b] = self._user_posterior_and_scores(X[b])
+        return out

machine_learning/models/similarity.py

@@ -0,0 +1,24 @@
+import numpy as np
+from sklearn.base import BaseEstimator
+
+
+class SimilarityRecommender(BaseEstimator):
+    def __init__(self,
+                 item_embeddings: np.ndarray,
+                 mask_value: float = -np.inf):
+
+        E = np.asarray(item_embeddings, dtype=np.float64)
+        self.item_embeddings = E / np.linalg.norm(E, axis=1, keepdims=True)
+        self.N_, self.d_ = self.item_embeddings.shape
+        self.mask_value = mask_value
+
+    def fit(self, X=None, y=None):
+        return self
+
+    def transform(self, X):
+        X = np.asarray(X, dtype=np.float64)
+        U = X @ self.item_embeddings
+        U /= np.linalg.norm(U, axis=1, keepdims=True)
+        scores = U @ self.item_embeddings.T
+        scores[X != 0] = self.mask_value
+        return scores

machine_learning/prefetched/embeddings.csv.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:40897c6ec6916d39983608eb81ad85700db92ad6aec8bb7167cc79d100337f6d
+size 42019593

machine_learning/transformers/inverter.py

@@ -0,0 +1,9 @@
+from sklearn.base import BaseEstimator, TransformerMixin
+
+
+class Inverter(BaseEstimator, TransformerMixin):
+    def fit(self, X, y=None):
+        return self
+
+    def transform(self, scores_matrix):
+        return -scores_matrix

machine_learning/transformers/item_encoder.py

@@ -0,0 +1,21 @@
+import numpy as np
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.preprocessing import MultiLabelBinarizer
+
+
+class ItemIdOneHotEncoder(BaseEstimator, TransformerMixin):
+    def __init__(self, all_item_ids):
+        self.all_item_ids = list(all_item_ids)
+        self._mlb = MultiLabelBinarizer(classes=self.all_item_ids)
+
+    def fit(self, X, y=None):
+        self._mlb.fit([[]])
+        return self
+
+    def transform(self, X):
+        M = self._mlb.transform(X).astype(np.float64)
+        return M
+
+    @property
+    def vocab_(self):
+        return self.all_item_ids

machine_learning/transformers/scores_to_dict.py

@@ -0,0 +1,40 @@
+import numpy as np
+from sklearn.base import BaseEstimator, TransformerMixin
+
+
+class ScoresToDict(BaseEstimator, TransformerMixin):
+    def __init__(self, item_ids, titles, posters=None, premiere_years=None):
+        self.item_ids = list(item_ids)
+        self.titles = list(titles)
+        self.posters = list(posters) if posters is not None else [None] * len(item_ids)
+        self.premiere_years = list(premiere_years) if premiere_years is not None else [None] * len(item_ids)
+
+    def fit(self, X, y=None):
+        return self
+
+    def transform(self, scores_matrix):
+        scores_matrix = np.asarray(scores_matrix, dtype=np.float64)
+        B, N = scores_matrix.shape
+        out = []
+        for b in range(B):
+            out.append({
+                "item_ids": self.item_ids,
+                "scores": scores_matrix[b].tolist(),
+            })
+        return out
+
+    def predict(self, scores_matrix, limit=10):
+        scores_matrix = np.asarray(scores_matrix, dtype=np.float64)
+        B, N = scores_matrix.shape
+        out = []
+        for b in range(B):
+            scores = scores_matrix[b]
+            idx = np.argsort(-scores)[:limit]   # descending top-k
+            out.append({
+                "item_ids": [self.item_ids[i] for i in idx],
+                "titles": [self.titles[i] for i in idx],
+                "posters": [self.posters[i] for i in idx],
+                "premiere_years": [self.premiere_years[i] for i in idx],
+                "scores": scores[idx].tolist(),
+            })
+        return out

requirements.txt

@@ -0,0 +1,6 @@
+joblib==1.5.2
+numpy==2.0.2
+pandas==2.3.3
+scikit-learn==1.6.1
+Flask==3.0.3
+gunicorn==21.2.0

server/api.py

@@ -0,0 +1,73 @@
+import os
+import sys
+import logging
+
+from typing import Dict, Any
+from flask import Flask, request, jsonify
+from werkzeug.exceptions import HTTPException
+from machine_learning.load_models import (
+    not_for_me,
+    recommended_for_you,
+    similarity,
+)
+
+
+logging.basicConfig(
+    level=os.environ.get("LOG_LEVEL", "INFO"),
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    stream=sys.stdout,
+)
+log = logging.getLogger("ff1000-api")
+
+
+MODELS: Dict[str, Any] = {
+    "nfm": not_for_me,
+    "rfy": recommended_for_you,
+    "similarity": similarity,
+}
+
+
+def create_app() -> Flask:
+    app = Flask(__name__)
+
+    @app.errorhandler(Exception)
+    def handle_exception(e):
+        if isinstance(e, HTTPException):
+            return jsonify(error=e.name, message=e.description), e.code
+        log.exception("Unhandled exception")
+        return jsonify(error="InternalServerError", message=str(e)), 500
+
+    @app.get("/health")
+    def healthz():
+        return jsonify(status="ok")
+
+    @app.post("/predict/<model_name>")
+    def predict(model_name: str):
+        if model_name not in MODELS:
+            return jsonify(error="UnknownModel", message=f"valid models: {list(MODELS.keys())}"), 400
+
+        try:
+            payload = request.get_json(force=True, silent=False)
+        except Exception:
+            return jsonify(error="InvalidJSON", message="body must be valid JSON"), 400
+
+        if not isinstance(payload, dict) or "items" not in payload:
+            return jsonify(error="BadRequest", message="json must have key 'items'"), 400
+
+        inputs = payload["items"]
+        if not isinstance(inputs, list):
+            return jsonify(error="BadRequest", message="'items' must be a list"), 400
+
+        model = MODELS[model_name]
+        try:
+            preds = model.predict([inputs])
+        except Exception as e:
+            log.exception("Prediction failed")
+            return jsonify(error="PredictionError", message=str(e)), 500
+
+        return jsonify(model=model_name, predictions=preds)
+
+    return app
+
+
+app = create_app()