[embed]TMDbGPT App Demo

Building a Movie Data Explorer Agent with TMDb, ChatGPT, and Custom Search

In this article I share how I developed TMDbW, a tool that combines The Movie Database (TMDb) API, GPT-powered Retrieval-Augmented Generation (RAG), MongoDB, Whoosh, and a custom UI to enable dynamic exploration of movie data space. The system allows users to ask complex, natural language queries about movies and receive precise, well-formatted responses — all in real time.

The core idea behind this project was to meet the needs of a client in movie editorial publishing by creating an AI-powered assistant capable of:

• Understanding natural language movie-related questions, so that users can express complex information needs without having to learn query syntax or API structures.
• Transforming those questions into structured queries and API calls, saving significant time and effort otherwise spent crafting precise filters, parameters, or database queries — especially beneficial for non-technical users.
• Efficiently searching both live TMDb data and pre-cached or indexed data, ensuring rapid, relevant results by balancing up-to-date API calls with optimized local searches.
• Presenting clear, readable answers enriched by GPT’s language capabilities, so that users receive well-organized, context-aware responses without needing to manually parse raw JSON data or documentation.

Beyond simply querying data, the system provides an interactive browser of the information already available through the TMDb API. Users can explore this data through an intuitive interface, with added layers of information retrieval and advanced search functionalities:

• The tool enables structured searches using indexed fields (via MongoDB) and free-text searches (via Whoosh) over the cached dataset.
• It enhances traditional API data by executing SERP queries (Search Engine Results Pages) and dynamically integrates those external results into the search flow, offering broader context and richer answers.
• The tool also introduces an innovative user experience, where users (and agents) can operate across multiple independent, versioned text buffers. This enables GPT to better organize, compare, and manipulate the information retrieved, supporting more coherent, traceable, and context-aware responses. Users can inspect, refine, or branch different stages of query results without losing prior work, encouraging exploration and iterative refinement.

In short, I was required to build a system where anyone could type something like “Which sci-fi films after 2015 about space travel have ratings above 7?” and instantly receive an intelligent, well-organized response — without manual filtering, without digging through API docs, and with the benefit of integrated external insights.

System Architecture

The architecture integrates several components, each playing a specific role:

TMDb API + Caching

At the foundation, the tool interfaces with TMDb’s public API to retrieve movie, actor, and genre data. To reduce API load and mitigate rate limits, I implemented:

• A caching layer that stores recent API responses.
• Pre-caching for popular or frequently requested data.

MongoDB & Whoosh Indexing

Data retrieved through the API (or pre-cached) is indexed in two ways:

• MongoDB for structured searches — enabling fast filtering by year, rating, genre, director, and more.
• Whoosh for full-text search — allowing queries on titles, overviews, and other text fields.

This hybrid indexing approach means users can issue both structured and fuzzy text queries.

RAG Layer with ChatGPT + PydanticAI

The Retrieval-Augmented Generation layer leverages ChatGPT through PydanticAI, supporting:

• Multi-agent architecture for decomposing complex queries into sub-tasks handled by cooperating agents.
• Multi-buffer support so agents can reason with multiple data inputs simultaneously.
• Markdown rendering to produce clean, readable outputs including tables, lists, and highlights.

GPT is guided to generate responses strictly based on the data retrieved or indexed, avoiding unsupported hallucinations.

UI & Frontend

The frontend, built with Bootstrap, provides a clean browser-based interface where users can:

• Type natural language queries.
• Review structured, markdown-enhanced results.
• Refine or adjust queries interactively based on suggestions.

The backend is built with Flask, orchestrating the retrieval, search, and GPT generation processes.

Overall App Architecture

Key Features

Natural Language + Hybrid Search Users can ask rich, complex questions — combining natural language, filters, and free text. Example: “Find comedies released between 2010 and 2020 with ratings over 6 that feature time travel.”

Multi-agent GPT reasoning Queries are broken into sub-queries managed by cooperating agents that plan and execute structured searches, free text searches, and result synthesis.

Caching + Pre-caching Results from recent API calls and popular queries are cached to improve speed and reduce external API hits, top contents are precached to improve data indexing.

Markdown-rich results Responses are formatted cleanly for display, with GPT generating readable lists, tables, and sections.

Interactive browser interface Users explore and refine queries easily via a simple, intuitive web UI.

Example Queries

Here’s what interacting with the system looks like:

Query: List sci-fi movies released after 2015 about space travel with ratings above.

Here are some notable science fiction films that match your criteria:

• Arrival (2016): A linguist helps humanity communicate with extraterrestrials.
• Dune (2021): Epic tale of politics, survival, and destiny on a desert planet.
• The Wandering Earth (2019): A bold mission to save Earth by moving it across the galaxy.

Advanced GPT RAG Features: Buffer Control, Versioning, and Multi-format Output

One of the most distinctive aspects of this project is the advanced functionality built into the GPT-powered Retrieval-Augmented Generation (RAG) system. Beyond simply feeding data to a large language model and getting a response, this architecture provides fine-grained control and traceability over the interaction between data, reasoning, and output generation.

Here’s a closer look at these advanced features:

Token Context Control

The system offers full control over the token context window provided to GPT. This means:

• The exact context messages is measurable and visible during queries.
• Users can decide how much of the buffer (retrieved data, search results, query history) is passed in, allowing precise balance between completeness and token efficiency.
• History messages can be deleted or modified.
• Optional dynamic trimming strategies ensure large results sets do not overwhelm the LLM’s context limits.

This flexibility allows the RAG engine to handle both compact facts and rich multi-source responses without performance degradation or loss of grounding.

Buffer Versioning

Each query interaction maintains a versioned buffer:

• Every generated response, intermediate result, or manual edit is captured as a distinct version.
• Users can compare versions side-by-side, viewing diffs of changes made by agents or human users.
• Any version can be reverted or branched for further refinement, enabling exploratory workflows where users or agents can backtrack without loss of work.

This feature effectively brings version control semantics (familiar from code development) into the realm of AI-generated conversational data.

Benefits of This Design

Transparency & traceability — Every step in query handling and response generation is inspectable. Reproducibility — Users can return to prior states, audit agent decisions, or share specific output versions. Format flexibility — Outputs are ready for various consumption contexts (browser UI, API, or machine integration). Experimentation-friendly — The architecture encourages iterative refinement, sandboxing, and exploratory querying.

What’s Next

I’m planning several enhancements:

• Extend multi-agent logic to support conversational query refinement across sessions.
• Add visualizations such as timelines, genre distribution charts, and rating histograms.

Thank you!

If you’ve made it this far, you’ve probably enjoyed my article. Why don’t you leave me feedback, like a comment or applause? If you’re new to Medium, you probably won’t know that a click on the applause button is only worth 1/50 of the top grade.