Designing a Feature: Similar & Theme Programs in Moirai

For decades, streaming services and other purveyors of media have been chasing the Holy Grail of a perfect recommendation engine. At the surface level, the idea is straightforward: given what a viewer likes, recommend additional related content with a high chance of being watched and enjoyed. It’s a famously difficult problem, one Netflix was willing to offer a million dollar prize for in 2006.

Take Alien, The Thing, and Event Horizon. They share enough that a channel built around them makes sense, but checking the Science Fiction and Horror genre boxes doesn't quite capture the overarching theme. The isolation, the hostile environments, and the dawning realization that things are going very badly are harder to quantify in a database query. Such an approach easily misses a good fit in an adjacent genre while admitting a pile of movies that happen to share a taxonomy.

Alien, The Thing, and Event Horizon beside thematic fits Pandorum and Life, and lighter-toned mismatches Men in Black and Spaceballs.

I wanted that functionality in Moirai, my IPTV scheduler project. Its Programs define what a channel schedule can draw from: a hand-picked collection of media, a query, or a sequence combining other Programs. The gist of the new idea was to give it a few examples and have it build a cohesive set of related material.

That became Similar Items. Theme grew from the same premise, with a written description supplying the starting point instead (e.g., “space exploration and first contact” or “quiet mysteries in small towns.”)

Could I Ship a Language Model?

The first direction I looked at was to bundle and use a local language model. I’ve never built such a system, but at this point I have enough experience with them that it seemed like a promising fit: give it the library, describe the kind of programming wanted, and ask it to select titles.

Actually evaluating whether a bundled local language model could work raised a lot of questions, both in performance and behaviors. How much memory does the model and runtime actually use? How long does selection take on the kind of CPU running Moirai? What happens as the library grows beyond what fits in a prompt? Does dividing the catalog into batches change which titles win?

Moirai is self-hosted and the computer running it already has consistent work: it may be scanning media files, constructing schedules, or transcoding video to a viewer. A new feature shouldn't add significant overhead to a media server that’s already likely near its limits with playback, especially if it negatively impacts playback performance.

Then there's the output. A model might suggest a movie that isn't in the library, misunderstand which version of a title it was given, or somehow consider plausible a poor match. The application has to validate every selected identifier against the eligible catalog. Constraining the output format helps with parsing, but whether the selection is any good still needed assessing.

A small model like Qwen3-0.6B could plausibly work on a lot of hardware and was small enough to bundle, but the LLM I was using suggested trying an embedding model first instead.

Qwen generates suggested titles from a catalog and instructions; BGE converts descriptions into cached vectors for ranking in Moirai.

Describing a Neighborhood

The core operation of the feature is comparing descriptions. I already had titles, plots, genres, and other metadata; I wanted to find items whose descriptions occupied a similar point in dimensional space, like houses in a neighborhood.

An embedding model turns text into a vector, a fixed-length list of numbers that acts something like an address in a space organized by meaning. The individual numbers aren't labels like “contains aliens” or “the world ends”; the representation works as a whole, placing descriptions with related meanings near each other even when they use different words. Comparing those locations gives us a way to find similarities that a handful of genre labels would miss.

Descriptions pass through an embedding model into numerical vectors; related descriptions occupy nearby houses, while a romance lives farther away.

The embedding model recommended by the LLM was BGE-small-en-v1.5, an English embedding model that produces 384-dimensional vectors, accepting a maximum of 512 input tokens. Each vector takes 1,536 bytes as 384 single-precision numbers, translating to a storage requirement of about 15 MB per 10,000 items.

Moirai uses the model to prepare the representation once during its indexing phase, reusing the result for any number of selections. This also supplied a straightforward path to Theme Programs: a user-provided description can be embedded and compared with the same media vectors already stored. Similar Items starts with examples while Theme starts with words, but both can share the algorithms that rank candidates and maintain a selection.

There are limits to what that buys, though. Similarity to a description of space exploration doesn't establish that every movie includes a voyage into space, and a plot with sparse details gives the model less to work with. We can assemble related programming from available descriptions, but more detailed factual verification needs more than proximity between vectors.

To that end, I did later build for Moirai a separate AI Program feature using large models for selections. That has its own workflow and configuration, calling out to the appropriate APIs to query and retrieve results. Similar Items and Theme remain local embedding features.

Improving Result Variety

Taking the nearest twenty items would have been a workable first pass, but it would also tend towards a very repetitive channel. If the closest candidates were all fairly similar, the result can feel like twenty variations of the same pick (e.g., not all of the results of a space sci-fi prompt should be Star Trek movies).

Moirai's Cohesion / Variety slider at 10, above sample matches including The Black Hole, The Thing from Another World, Prometheus, and Aliens.

The Cohesion / Variety control balances closeness to the examples or theme with variety among the selected items. Moirai uses an approach called maximal marginal relevance: as the set grows, a candidate's relevance to the original request is weighed against its resemblance to items already chosen. Once a few very similar titles have been selected, there's more room for something that fits the premise from a different angle.

The same Moirai slider at 85, with Aliens vs Predator: Requiem moved earlier and The Fog and Passengers appearing in the visible sample.

For Similar Items, relevance considers both the examples collectively and the closest individual example. A candidate can fit one part of the source collection especially well without having to resemble everything in it.

The ordinary eligibility rules come first: the source library, media kinds, availability, and configured metadata filters determine which candidates can be considered. Moirai then limits selection to a related pool within those candidates. Turning the slider toward Varied shouldn't send it wandering into an unrelated part of the library just because it looks different.

That relatedness boundary is relative to the available candidates, so it still can't promise a good match in a library with nothing suitable. The interface reports when the related pool can't fill the requested quantity, and sample matches give the administrator a chance to judge the result. Filling a quota at the expense of the channel's premise would defeat the purpose of the feature.

A Selection Becomes a Commitment

Moirai prepares schedules ahead of playback, so a selection that changes every time the scheduler looks at it would be a poor foundation for a television guide. Once something has a place on the schedule, finding a slightly better match shouldn't replace it. Moirai saves each generated set's membership and order, keeping both stable across restarts and as new embeddings become available (e.g., when new media is added). Editing the source collection, quantity, or preferences affects the next set only, and the current one is allowed to finish first. Like other Program types, each schedule maintains its own progress, so using a Program in two places doesn't make them consume a single shared queue.

Previews are explicitly excluded from those requirements, though. Opening an editor or trying a different preference works with disposable state, so it doesn't consume an item or replace a committed set. It’s meant to show an approximation of the real schedule rather than the exact lineup.

The feature’s processing overhead also had to fit alongside the scanning, scheduling, and playback work already running on the server. A background child process runs the model on the CPU with a single inference thread, processes limited batches, and then releases the model after a minute idle or under resource pressure. Cached vectors are automatically invalidated and regenerated when the descriptive inputs used to produce them or the model identity change.

Additionally, the model comes with the application. The build packages a pinned version of it, and at runtime, Moirai loads that bundle locally. Someone installing Moirai gets everything the feature needs without a surprise first-run download.

The Details That Changed the Feature

Getting useful results also meant paying closer attention to what was given to the model. An episode needs some context from its show, but the show's description can be long enough to crowd out the episode's own story within the input token limit. If that happens, carefully storing episode-level metadata hasn't helped: the model barely sees it.

The fix was to segment and budget the input using the model's tokenizer, reserving room for identifying information, the item's overview, descriptive metadata, and context from its show. Improving what reaches the existing model was a better design choice than switching to a larger one.

Rotation exposed another problem. Avoiding only the previous set can create a short loop, alternating between two sets while other eligible titles never get a turn. The selection now considers the last ten completed sets, preferring unseen candidates and then less recently used ones. It remains deterministic, but it has enough memory to avoid that particular rut when the eligible pool allows it.

Then came a simple but broad need: no superhero movies. There are some categories of media that have had enough items produced that virtually any theme has a few, yet rarely are they the matches that you want included on multiple channels. Putting that sentence into a similarity prompt isn't a reliable way to enforce it because the “no” can't receive sufficient priority in the preferencing. The resulting vector can still be close to superhero descriptions even though the sentence asks to avoid them.

The feature gained explicit exclusion support instead: enter “superhero movies,” internally compare candidates with that concept, and preemptively remove close matches before ranking. A strictness control adjusts how broadly the exclusion reaches.

Moirai's genre and release-year filters, followed by the superhero movies exclusion at strictness 65 and separate remaining and excluded movie samples.

Given the nature of language models, even that comparison is still approximate, so the editor shows excluded matches alongside the remaining sample. The administrator can see when the filter has swept up something worth keeping and judge whether it needs further tuning. Individual, explicit removals handle the other direction: a title that keeps qualifying but has no place on the channel can be excluded persistently, without needing the model to agree.

More Like These

The appeal of the original idea was being able to express programming through examples or a few words. Making that work meant deciding how far a selection could wander, how it would rotate, and when it needed to stay put. Those decisions ended up shaping the feature as much as the choice of model.

A small but local LLM remains an intriguing future option for tasks that need interpretation or explanation, and I’ll likely evaluate one again if the need arises. For these Programs, the smaller embedding model and ordinary selection logic were enough to build out the feature I wanted now.

Between that and the subsequently added AI API support, Moirai is in a pretty good state for any future feature ideas.

The populated Similar Items editor for Isolation and Dread, showing its source, quantity, preferences, variety and exclusion controls, real sample matches, and excluded superhero movies.