Skip to main content

Gemini AI (gemini-service.js & content-manager-gemini.js)

Gemini is used as an editorial layer on top of the deterministic pipeline. The project depends on @google/generative-ai and centralizes the client in gemini-service.js, while content-manager-gemini.js wraps it with content-category logic.

What Gemini does​

  1. Track validation — given a discovered track's raw metadata (often a messy YouTube title), Gemini decides whether the track plausibly belongs to the requested category and is "radio-safe" (proper artist/title, not a low-quality upload or lyric-mashup).
  2. Metadata cleansing — when the regex-based sanitizer is insufficient, Gemini proposes a clean {artist, title} pair, correctly separating e.g. "Amr Diab & Tamer Hosny – new track (Official Audio)".
  3. Category assignment — the model can suggest moving a track into a more fitting category (e.g. an underground track found via egyptian_trends discovery that fits arab_techno better).
  4. Label screening — works alongside the LABEL regex filter used across the pipeline so official/featured/remix markers do not pollute registry entries.

Request pattern​

The pipeline batches metadata through Gemini in prompt form with strict JSON instructions so responses can be parsed and merged back into the registry. All calls go through the shared gemini-service.js client (single API key, shared generation config, retry/timeout handling).

Trade-offs & toggles​

  • Gemini calls are slow and cost money, so the pipeline only invokes it for ambiguous cases (metadata the regex sanitizer flags as uncertain).
  • The pipeline exposes flags to disable AI entirely (--no-ai style paths in the content scripts) for dry runs and offline use.

Relationship to the RL scheduler​

The AI content layer feeds the registry, and the registry feeds the scheduler. Gemini decides what gets in; the scheduler's Thompson-sampling arms decide what plays and how often.