agentleFS
asgard-ai-platformasgard-ai-platform/skills/algo-rec-mf/SKILL.md

algo-rec-mf

Skill238 starsChanged 6 months agoMITView on GitHub

Implement matrix factorization to decompose user-item interaction matrices into latent factor representations. Use this skill when the user needs scalable collaborative filtering, latent feature discovery, or dimensionality reduction for recommendation — even if they say 'SVD recommendations', 'latent factors', or 'factorize the rating matrix'.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When interaction data is extremely sparse (< 0.1% fill) — insufficient for learning

    line 23
  2. Distinctive:

    When you need real-time updates (retraining is expensive)

    line 24
  3. Distinctive:

    SGD alternative: Update u_i, v_j incrementally for each observed rating using gradient descent.

    line 47
  4. Distinctive:

    Expected: After ALS with k=1 (one latent factor, λ=0.01, 50 iterations), approximate factorization:

    line 74
  5. Distinctive:

    Verify: R_hat ≈ R on observed entries (within 0.2 RMSE).

    line 82
  6. Distinctive:

    Bias terms: Add user bias bᵢ and item bias bⱼ: r̂ᵢⱼ = μ + bᵢ + bⱼ + uᵢ·vⱼ.

    line 97

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Matrix Factorization

Overview

Matrix factorization decomposes the user-item interaction matrix R (m×n) into two low-rank matrices: U (m×k) and V (n×k), where k << min(m,n). Predicted rating: r̂ᵢⱼ = uᵢ · vⱼ. Trains in O(k × nnz × iterations) where nnz = non-zero entries.

When to Use

Trigger conditions:

  • Scaling CF beyond pairwise similarity (millions of users/items)
  • Discovering latent factors that explain user-item interactions
  • Predicting ratings for unobserved user-item pairs

When NOT to use:

  • When interaction data is extremely sparse (< 0.1% fill) — insufficient for learning
  • When you need real-time updates (retraining is expensive)

Algorithm

IRON LAW: Rank k Controls Bias-Variance Trade-Off
- Too LOW k: underfits, misses nuanced preferences (high bias)
- Too HIGH k: overfits to noise, poor generalization (high variance)
- Typical k: 20-200. Select via cross-validation on held-out ratings.
- Always add regularization (λ) to prevent overfitting.

Phase 1: Input Validation

Load sparse interaction matrix. Split into train/validation/test. Check minimum density. Gate: Train matrix has sufficient entries per user and item.

Phase 2: Core Algorithm

ALS (Alternating Least Squares):

  1. Initialize U, V randomly (or with SVD warm-start)
  2. Fix V, solve for U: minimize ||R - UV^T||² + λ(||U||² + ||V||²)
  3. Fix U, solve for V using same objective
  4. Alternate until convergence (RMSE change < ε)

SGD alternative: Update u_i, v_j incrementally for each observed rating using gradient descent.

Phase 3: Verification

Compute RMSE on held-out validation set. Compare against baseline (global mean, user mean). Gate: Validation RMSE significantly below baseline.

Phase 4: Output

Return top-N predictions per user with predicted scores.

Output Format

{
  "recommendations": [{"user_id": "u1", "items": [{"item_id": "i5", "predicted_rating": 4.3}]}],
  "metadata": {"rank_k": 50, "regularization": 0.01, "iterations": 20, "train_rmse": 0.82, "val_rmse": 0.91}
}

Examples

Sample I/O

Input: 3×3 rating matrix R (0 = unobserved), k=1

R = [[5, 3, 0],
     [4, 0, 2],
     [0, 1, 1]]

Expected: After ALS with k=1 (one latent factor, λ=0.01, 50 iterations), approximate factorization:

U ≈ [[2.24], [1.84], [0.53]]
V ≈ [[2.23], [1.06], [0.98]]
R_hat ≈ [[4.99, 2.37, 2.20],
         [4.10, 1.95, 1.80],
         [1.18, 0.56, 0.52]]

Verify: R_hat ≈ R on observed entries (within 0.2 RMSE). U[0] >> U[2] correctly captures user 0's higher ratings.

Edge Cases

InputExpectedWhy
User with 1 ratingPoor predictions for that userInsufficient data to learn user factors
Highly popular itemPredicted near averageDominant first latent factor captures popularity
All ratings = 5Trivial factorizationNo variance to learn from

Gotchas

  • Implicit data needs different loss: For clicks/views (no explicit ratings), use weighted matrix factorization (Hu et al. 2008) with confidence weighting, not RMSE.
  • Cold start remains: New users/items have no entries in R. MF can't factorize what doesn't exist. Use side features or hybrid approaches.
  • Negative sampling: For implicit feedback, you must sample negative examples (unobserved ≠ disliked). Random negative sampling works but biased sampling is better.
  • Initialization matters: Random initialization can converge to poor local optima. SVD-based warm-start often helps.
  • Bias terms: Add user bias bᵢ and item bias bⱼ: r̂ᵢⱼ = μ + bᵢ + bⱼ + uᵢ·vⱼ. This captures systematic rating tendencies.

References

  • For ALS vs SGD comparison, see references/optimization-comparison.md
  • For implicit feedback matrix factorization, see references/implicit-mf.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.