QlooMoodFlix: Personalized movie moods by Qloo.

Bot
Logo

Inspiration

In a world of infinite content on platforms like Telegram, discovery is broken. We scroll through generic lists and channels, hoping to stumble upon something that fits our mood, but the experience is impersonal and inefficient. Our inspiration was to create a "movie sommelier"—an intelligent, empathetic companion that understands how you feel and recommends the perfect movie. We wanted to transform the cold, algorithmic nature of content discovery into a warm, personalized, and human-like conversation.

What it does

QlooMoodFlix is an intelligent Telegram bot that provides hyper-personalized movie recommendations based on a user's mood. A user can simply type a natural language message like, "I've had a stressful day and want to watch something heartwarming," and the bot delivers a curated list of relevant films. It bypasses generic genre filters by understanding the user's specific feeling, finding a perfect "seed" movie to match it, and then using Qloo's Taste AI™ to discover other movies with a similar "cultural DNA."

How we built it

QlooMoodFlix is built on a sophisticated, multi-step architecture designed to bridge the gap between human emotion and structured data.

Backend & Interface: We used FastAPI (Python) to create a robust backend, which communicates with the user through the Telegram Bot API. The application is designed for production deployment using Uvicorn and Nginx.

Intelligence Layer: We integrated the Google Gemini LLM to act as our "Seed Selector." Its primary role is to interpret the user's unstructured mood and select a single, highly relevant movie to act as a seed for Qloo.

Qloo Recommendation Core: The core of our project relies on a two-step process with Qloo's Taste AI™:

First, we use the /search endpoint to resolve the LLM's seed movie name into its official, unique Qloo Entity ID.

Second, we feed this ID into the /v2/insights endpoint, using it as a signal.interests.entities to get a list of culturally similar movies, powered by Qloo's deep taste data.

Integrated the /moviequizz custom Telegram command, which triggers the Qloo Insights API to fetch movie data. The results are then passed to an LLM to generate interactive quiz-style questions based on Qloo's insights

Challenges we ran into

Our biggest challenge was learning how to effectively query the Qloo Hackathon API to get meaningful results. Our initial, more direct approaches failed:

Using LLM-generated mood keywords (like "sad" or "melancholy") with filter.tags returned empty lists.

Our attempt to programmatically find Tag IDs using the /v2/tags/search endpoint resulted in a 404 Not Found error, indicating it was unavailable in the hackathon environment.

This forced us to completely rethink our architecture. Instead of trying to guess tags, we pivoted to a more robust, seed-based model, which required a more intelligent use of the LLM and a deeper understanding of the Qloo API's capabilities.

Accomplishments that we're proud of

We are incredibly proud of the final architecture. Instead of giving up when our initial approach was blocked, we successfully pivoted to a more sophisticated, real-world solution. Our proudest accomplishment is the intelligent use of the LLM not as a simple chatbot, but as a "navigator" that translates unstructured human feeling into a precise data point that Qloo's powerful engine can understand and act upon. We built a resilient, stable application that successfully solves the user's core problem.

What we learned

This project was a deep dive into the practical realities of API integration and creative problem-solving.

APIs Have Personalities: We learned that you must understand the "intent" of an API. The Qloo /insights API thrives on being given a known starting point (a seed entity) rather than ambiguous tags.

The Power of a Pivot: Our most significant learning was knowing when to abandon a failing approach and completely redesign the workflow. The final seed-based architecture is far superior to our initial idea.

LLMs as a Bridge: We learned that the true power of LLMs in many applications is their ability to act as a bridge between messy, human input and structured, powerful APIs like Qloo's.

What's next for QlooMoodFlix

This project has laid a powerful foundation. The next steps are to expand its capabilities to become a holistic wellness companion.

Cross-Domain Recommendations: Expand beyond movies to include books, music, and places, using the exact same robust architecture.

Actionable Results: Integrate with other APIs to provide deep links to watch a recommended movie on a streaming service or find a book at a local library.