gorse-05-config-migration

Gorse 0.5.x Config Migration from 0.4

Problem

Gorse 0.5 introduced breaking config changes from 0.4. Old config sections are silently ignored (no error, no warning), making it appear that features like collaborative filtering, trending, and item neighbors are configured when they're actually disabled.

The most critical issue: [recommend.collaborative] defaults to type = "none" in 0.5, meaning collaborative filtering is silently disabled unless you explicitly set type = "mf".

Context / Trigger Conditions

• Gorse 0.5.x is deployed but recommendations seem random or low quality
• Collaborative filtering doesn't seem to work despite config having [recommend.collaborative]
• Config has old 0.4 sections: [recommend.popular], [recommend.neighbors], [recommend.online], [recommend.offline]
• Upgrading from Gorse 0.4 to 0.5
• Gorse master starts successfully but old config features don't take effect

Solution

Removed 0.4 Sections (silently ignored in 0.5)

Removed 0.4 Keys (do not exist in 0.5)

• enable_item_neighbor_index
• enable_user_neighbor_index
• item_neighbor_type
• neighbor_type
• explore_recommend
• popular_window

Critical Fix: Enable Collaborative Filtering

# 0.4 style (BROKEN in 0.5 — CF silently disabled):
[recommend.collaborative]
fit_period = "60m"
fit_epoch = 100

# 0.5 style (WORKING — must add type = "mf"):
[recommend.collaborative]
type = "mf"
fit_period = "60m"
fit_epoch = 100

Complete 0.5 Config Template

[recommend]
cache_size = 100
cache_expire = "72h"
context_size = 100

[recommend.data_source]
positive_feedback_types = ["reaction", "comment", "repost"]
read_feedback_types = ["view"]
positive_feedback_ttl = 0
item_ttl = 0

# Collaborative filtering — MUST set type = "mf" to enable
[recommend.collaborative]
type = "mf"
fit_period = "60m"
fit_epoch = 100
optimize_period = "360m"
optimize_trials = 10

[recommend.collaborative.early_stopping]
patience = 10

# Trending/popular — TOML array syntax [[...]] for multiple leaderboards
[[recommend.non-personalized]]
name = "trending_weekly"
score = "count(feedback, .FeedbackType == 'reaction') + count(feedback, .FeedbackType == 'comment') * 2"
filter = "(now() - item.Timestamp).Hours() < 168"

# Content-based item similarity (requires items to have Labels)
[[recommend.item-to-item]]
name = "similar_content"
type = "tags"         # matches on item Labels

# Collaborative item similarity
[[recommend.item-to-item]]
name = "also_liked"
type = "users"        # users who liked X also liked Y

# User similarity
[[recommend.user-to-user]]
name = "similar_users"
type = "items"        # users who share liked items

# FM ranker blends all candidate sources
[recommend.ranker]
type = "fm"           # or "llm" for LLM-based reranking
recommenders = ["latest", "collaborative", "non-personalized/trending_weekly", "item-to-item/similar_content", "item-to-item/also_liked", "user-to-user/similar_users"]
fit_period = "60m"
fit_epoch = 100

[recommend.ranker.early_stopping]
patience = 10

[recommend.fallback]
recommenders = ["latest"]

[recommend.replacement]
enable_replacement = true
positive_replacement_decay = 0.8
read_replacement_decay = 0.6