AI Features

Dubby integrates AI capabilities for natural language search, automated metadata enrichment, and smart collection generation. These features require a license with AI inference credits.

Note

AI features require a license with AI inference credits. Free-tier users see an upgrade prompt when accessing AI features.

AI search

Type natural language queries into the search bar instead of building manual filters.

Examples:

• “dark mysteries from the 90s”
• “feel-good comedies with ensemble casts”
• “sci-fi movies about artificial intelligence”
• “critically acclaimed foreign films”

How it works

1. Your query is sent to the AI inference service
2. AI interprets the query into structured filters (genres, years, moods, themes, people, etc.)
3. Results are displayed with:
   • Interpretation — What the AI understood from your query
   • Confidence score — How confident the AI is in its interpretation (color-coded: green, yellow, orange)
   • Filter chips — Visual tags showing detected criteria (genres, years, moods, etc.)
4. Optionally save as collection — Convert the search results into a persistent smart collection with one click

Limitations

• Requires an active network connection to Dubby’s cloud service
• Each query consumes inference credits from your account balance
• Rate-limited to prevent excessive usage

AI enrichment

AI enrichment generates rich metadata for your media items beyond what TMDB provides.

Enrichment data

Field	Description	Example
Tags	Descriptive discovery tags beyond standard genres	”heist”, “ensemble cast”, “twist ending”
Mood	Emotional tone and atmosphere	”tense”, “suspenseful”, “uplifting”
Themes	Narrative and philosophical elements	”redemption”, “found family”, “revenge”
Content warnings	Specific content advisories	”graphic violence”, “substance abuse”
Synopses	AI-generated plot summaries (spoiler-free and with-spoilers)	Two variants with spoiler toggle

Enriching items

Single item: On any movie or show detail page, click the Enrich with AI button. The enrichment runs in a few seconds and the data appears on the page immediately.

Bulk enrichment: Admins can trigger enrichment for an entire library from Settings > AI or via the API. This enqueues a background workflow that processes items in batches.

Per-season enrichment: For TV shows, you can enrich all unenriched episodes in a season at once.

Viewing enrichment data

Enriched metadata appears on media detail pages as styled chips organized by category:

• Mood — Indigo chips
• Themes — Green chips
• Tags — Gray chips
• Content warnings — Red chips

Synopses are shown as text with a spoiler toggle. The toggle respects your spoiler mode preference:

• Never (default) — Always show the spoiler-free version
• Watched — Show spoilers only for items you’ve already watched
• Always — Always show the full synopsis

Using enrichment in collections

AI enrichment data powers additional auto-collection rules. When enrichment is enabled, you can create collections filtered by mood, theme, tags, or content warnings — for example, an auto collection of “tense thrillers with twist endings.”

Master catalog sync

Instead of generating enrichment data locally (which consumes inference credits), licensed instances can pull pre-enriched metadata from Dubby’s master catalog.

The catalog sync workflow:

1. Runs on the worker as a background job
2. Matches your library items to the master catalog by external IDs
3. Downloads enrichment data (tags, mood, themes, warnings, synopses) for matched items
4. Periodically re-syncs to pick up newly enriched content

This is more cost-effective for large libraries since the master catalog is a shared enrichment database maintained by Dubby.

Usage and credits

Viewing usage

Go to Settings > AI or the admin dashboard to see:

• Credit balance — Remaining inference credits
• Usage breakdown — Credits consumed by task type (search, enrichment, collections)
• Request log — Paginated history of AI requests with cost, latency, and status

Cost management

• AI search queries consume a small number of credits per request
• Enrichment consumes more credits (proportional to the amount of content analyzed)
• Master catalog sync does not consume inference credits
• Smart collection generation consumes credits for the rule interpretation step

Enabling AI features

AI features are controlled by two feature flags:

Flag	Default	Description
ai_enrichment	Disabled	Enable AI-generated tags, mood, themes, and warnings
ai_synopsis_replace_overview	Disabled	Replace TMDB overview with AI-generated synopsis

Toggle these from Settings > Feature Flags after ensuring your license includes AI inference credits.

API

# Check if AI is available
curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/v1/ai/available

# AI search
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "dark mysteries from the 90s", "libraryType": "movie"}' \
  http://localhost:3000/v1/ai/search

# Enrich a single item
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mediaType": "movie", "mediaId": "item-id"}' \
  http://localhost:3000/v1/enrichment/enrich

# Get enrichment data
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/v1/enrichment/movie/{mediaId}

# Get usage stats
curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/v1/ai/usage

See the REST API reference for the full endpoint list.