Smart Jobs

import { Aside } from ‘@astrojs/starlight/components’;

Smart Jobs use adaptive rating thresholds that adjust based on content popularity, allowing you to get mainstream blockbusters without sacrificing quality for lesser-known content.

The Problem

Traditional static rating filters have a fundamental issue:

Popular blockbusters with thousands of votes often have “average” ratings (6-7/10) even when they’re great movies. Think Marvel films, big-budget action movies, or mainstream hits - they appeal to everyone, including critics who vote them down.

Hidden gems with fewer votes need higher ratings to prove their quality. A movie with only 200 votes scoring 7.5 is likely genuinely good.

With static filters, you face a dilemma:

• Set min_rating: 7.0 → Miss great blockbusters rated 6.5-6.9
• Set min_rating: 6.0 → Get mediocre low-popularity content

The Solution

Smart Jobs automatically adjust rating requirements based on popularity percentile:

• High popularity (90th percentile) → Requires lower rating (6.2)
• Medium popularity (50th percentile) → Requires baseline rating (7.0)
• Low popularity (10th percentile) → Requires higher rating (7.8)

Think of it as "innocent until proven guilty" for popular content, and "prove yourself" for obscure content.

How It Works

The Formula

adjusted_threshold = base_min_rating - ((percentile - 0.5) × adjustment_factor)

Where:

• base_min_rating - Your baseline quality requirement (e.g., 7.0)
• percentile - Item’s popularity percentile (0.0 to 1.0)
• adjustment_factor - How aggressively to adjust (0.5 to 3.0)

Example Calculation

With base_min_rating: 7.0 and adjustment_factor: 2.0:

Popularity Percentile	Calculation	Required Rating
90th (very popular)	7.0 - ((0.9 - 0.5) × 2.0)	6.2
70th (popular)	7.0 - ((0.7 - 0.5) × 2.0)	6.6
50th (average)	7.0 - ((0.5 - 0.5) × 2.0)	7.0
30th (less popular)	7.0 - ((0.3 - 0.5) × 2.0)	7.4
10th (obscure)	7.0 - ((0.1 - 0.5) × 2.0)	7.8

Configuration

Basic Configuration

jobs:
  smart_popular_movies:
    enabled: true
    schedule: "0 */6 * * *"
    limit: 20
    base_min_rating: 7.0      # Baseline rating requirement
    adjustment_factor: 2.0     # How aggressive (default: 1.0)

Configuration Options

Option	Type	Default	Description
base_min_rating	float	7.0	Baseline rating for average popularity
adjustment_factor	float	1.0	Aggressiveness (0.5 = mild, 2.0 = aggressive, 3.0 = very aggressive)
limit	integer	10	Maximum items to add
schedule	string	-	Cron schedule

Additional Filters

You can combine adaptive ratings with other filters:

smart_popular_movies:
  enabled: true
  limit: 20
  base_min_rating: 7.0
  adjustment_factor: 2.0
  filters:
    min_votes: 1000            # Still require vote threshold
    exclude_genres: ["Documentary"]
    include_languages: ["en"]

Don't use `min_rating` filter with Smart Jobs - it's handled by the adaptive system.

Adjustment Factor Guide

The adjustment_factor controls how aggressively ratings are adjusted.

Conservative (0.5 - 1.0)

Subtle adjustments, closer to static filtering.

adjustment_factor: 0.5
# 90th percentile: 7.0 - ((0.9 - 0.5) × 0.5) = 6.8
# 10th percentile: 7.0 - ((0.1 - 0.5) × 0.5) = 7.2

Use when: You trust your baseline rating and want minor flexibility.

Moderate (1.0 - 1.5)

Balanced adjustments, good for most use cases.

adjustment_factor: 1.0
# 90th percentile: 7.0 - ((0.9 - 0.5) × 1.0) = 6.6
# 10th percentile: 7.0 - ((0.1 - 0.5) × 1.0) = 7.4

Use when: You want a balanced approach (recommended starting point).

Aggressive (2.0 - 2.5)

Significant adjustments, prioritizes mainstream content.

adjustment_factor: 2.0
# 90th percentile: 7.0 - ((0.9 - 0.5) × 2.0) = 6.2
# 10th percentile: 7.0 - ((0.1 - 0.5) × 2.0) = 7.8

Use when: You want to capture popular blockbusters with “average” ratings.

Very Aggressive (3.0+)

Maximum adjustments, heavily favors popularity.

adjustment_factor: 3.0
# 90th percentile: 7.0 - ((0.9 - 0.5) × 3.0) = 5.8
# 10th percentile: 7.0 - ((0.1 - 0.5) × 3.0) = 8.2

Use when: You primarily want mainstream content and trust popular opinion.

Available Smart Jobs

Currently, two smart jobs are available:

smart_popular_movies

Adaptive thresholds for popular movies.

smart_popular_movies:
  enabled: true
  schedule: "0 6 * * *"
  limit: 20
  base_min_rating: 7.0
  adjustment_factor: 2.0

smart_popular_shows

Adaptive thresholds for popular TV shows.

smart_popular_shows:
  enabled: true
  schedule: "0 12 * * *"
  limit: 15
  base_min_rating: 7.0
  adjustment_factor: 1.5

Real-World Examples

Example 1: Mainstream Movies

Goal: Get popular blockbusters without quality compromise.

smart_popular_movies:
  enabled: true
  limit: 25
  base_min_rating: 7.0
  adjustment_factor: 2.0
  filters:
    min_votes: 2000
    include_genres: ["Action", "Adventure", "Sci-Fi"]

Results:

• Dune: Part Two (8.7 rating, 95th percentile) ✓ Added (requires 6.1)
• Fast X (6.8 rating, 88th percentile) ✓ Added (requires 6.3)
• Unknown Indie (7.2 rating, 15th percentile) ✗ Filtered (requires 7.7)

Example 2: Balanced Discovery

Goal: Mix of popular and quality content.

smart_popular_movies:
  enabled: true
  limit: 20
  base_min_rating: 6.8
  adjustment_factor: 1.0
  filters:
    min_votes: 1000
    min_year: 2020

Results: Moderate adjustment curve, good mix of mainstream and quality.

Example 3: Quality First

Goal: High-quality content with some flexibility for popular items.

smart_popular_movies:
  enabled: true
  limit: 15
  base_min_rating: 7.5
  adjustment_factor: 0.8
  filters:
    min_votes: 1500

Results: Strict baseline with minor adjustments for popularity.

Comparing Regular vs. Smart Jobs

Regular Popular Job (Static Filter)

popular_movies:
  enabled: true
  limit: 20
  filters:
    min_rating: 7.0  # Fixed threshold

Result: Misses blockbusters rated 6.5-6.9, regardless of popularity.

Smart Popular Job (Adaptive Filter)

smart_popular_movies:
  enabled: true
  limit: 20
  base_min_rating: 7.0
  adjustment_factor: 2.0  # Adaptive threshold

Result: Gets blockbusters rated 6.2+ if popular, requires 7.8+ for obscure content.

Preview Smart Jobs

Always preview smart jobs to understand the adaptive behavior:

curl -X POST http://localhost:9090/v1/jobs/preview/smart-popular-movies

The response shows:

• Each item’s popularity percentile
• Calculated rating threshold for that item
• Whether it passed or failed

Best Practices

Start with Defaults

Begin with moderate settings and adjust based on results:

base_min_rating: 7.0
adjustment_factor: 1.0

Use min_votes

Always pair with min_votes to ensure rating reliability:

base_min_rating: 7.0
adjustment_factor: 2.0
filters:
  min_votes: 1000  # Critical for reliability

Preview Extensively

Smart jobs behave differently than static filters. Preview multiple times to understand the results.

Monitor Activity

Check what gets added and adjust base_min_rating or adjustment_factor as needed.

Combine with Other Filters

Smart rating is just one filter. Use genre, language, and keyword filters as normal:

smart_popular_movies:
  base_min_rating: 7.0
  adjustment_factor: 2.0
  filters:
    min_votes: 1000
    exclude_genres: ["Documentary", "Reality"]
    include_languages: ["en"]

Troubleshooting

Getting Too Much Low-Quality Content?

Increase base_min_rating:

base_min_rating: 7.5  # Up from 7.0

Or decrease adjustment_factor:

adjustment_factor: 1.0  # Down from 2.0

Missing Popular Blockbusters?

Increase adjustment_factor:

adjustment_factor: 2.5  # Up from 2.0

Or decrease base_min_rating:

base_min_rating: 6.5  # Down from 7.0

Too Many Obscure Items?

Increase min_votes:

filters:
  min_votes: 2000  # Up from 1000

Next Steps

• Learn about Regular Jobs
• Configure Advanced Filters
• Understand Integration Modes