{"id":20027982,"url":"https://github.com/vojay-dev/gemini-movie-detectives-api","last_synced_at":"2025-05-05T03:31:56.784Z","repository":{"id":233180989,"uuid":"781630643","full_name":"vojay-dev/gemini-movie-detectives-api","owner":"vojay-dev","description":"Use Gemini Pro LLM via VertexAI to create an engaging quiz game incorporating TMDB API data","archived":false,"fork":false,"pushed_at":"2025-03-16T12:20:01.000Z","size":10360,"stargazers_count":29,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-08T16:04:28.774Z","etag":null,"topics":["ai","artificial-intelligence","data-engineering","fastapi","game-development","gemini-api","gemini-pro","google","google-cloud-platform","httpx","llm","python","rag","tmdb-api","vertexai"],"latest_commit_sha":null,"homepage":"https://movie-detectives.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vojay-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-03T18:41:56.000Z","updated_at":"2025-03-19T06:45:31.000Z","dependencies_parsed_at":"2024-04-29T19:53:23.501Z","dependency_job_id":"226bce32-5d32-4df6-a8f1-44e62f75fc9a","html_url":"https://github.com/vojay-dev/gemini-movie-detectives-api","commit_stats":null,"previous_names":["vojay-dev/gemini-movie-detectives-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vojay-dev%2Fgemini-movie-detectives-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vojay-dev%2Fgemini-movie-detectives-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vojay-dev%2Fgemini-movie-detectives-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vojay-dev%2Fgemini-movie-detectives-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vojay-dev","download_url":"https://codeload.github.com/vojay-dev/gemini-movie-detectives-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252434884,"owners_count":21747308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","data-engineering","fastapi","game-development","gemini-api","gemini-pro","google","google-cloud-platform","httpx","llm","python","rag","tmdb-api","vertexai"],"created_at":"2024-11-13T09:12:45.611Z","updated_at":"2025-05-05T03:31:55.335Z","avatar_url":"https://github.com/vojay-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gemini Movie Detectives API\n\n![logo](doc/logo.png)\n\nGemini Movie Detectives harnesses Google's AI to revolutionize educational gaming, transforming movie trivia\ninto a proof-of-concept gateway for AI-driven, adaptive learning across all subjects, challenging your inner\nmovie nerd while showcasing how AI can reshape education in schools and universities.\n\n**Try it yourself**: [movie-detectives.com](https://movie-detectives.com/)\n\n## Backend\n\nThe backend infrastructure is built with FastAPI and Python, employing the Retrieval-Augmented Generation (RAG)\nmethodology to enrich queries with real-time metadata. Utilizing Jinja templating, the backend modularize\nprompt generation into base, personality, and data enhancement templates, enabling the generation of accurate\nand engaging quiz questions in different game modes. Each game mode uses a different combination of data source\nshowcasing the broad range of possibilities how to employ advanced Gemini applications.\n\nIn addition to Gemini, the application leverages Google's state-of-the-art Text-to-Speech AI to synthesize quiz\nquestions, dramatically enhancing the immersive atmosphere of a professional trivia game show. Moreover, the\nSequel Salad game mode demonstrates the power of AI integration by utilizing Gemini to generate creative prompts.\nThese prompts are then seamlessly fed into Google's cutting-edge Imagen text-to-image diffusion model, producing\nfake movie posters. This sophisticated interplay of various AI models showcases the limitless potential for\ncreating captivating and dynamic game experiences, pushing the boundaries of what's possible in interactive\nentertainment.\n\nThe application's infrastructure is further strengthened by the integration of Google Firebase. This integration\nenables secure user authentication, facilitating personalized interactions within the app. Firestore is used to\nstore and manage essential user data, powering the dynamic rendering of user profiles with game statistics.\nAdditionally, it handles crucial metadata, including movie franchise information and game mode usage metrics\ntogether with configurable limits, allowing for precise control over daily operational costs.\n\n## Frontend\n\nThe frontend is powered by Vue 3 and Vite, supported by daisyUI and Tailwind CSS for efficient frontend\ndevelopment. Together, these tools provide users with a sleek and modern interface for seamless interaction\nwith the backend.\n\n## Summary\n\nIn Movie Detectives, quiz answers are interpreted by the Language Model (LLM) once again, allowing for dynamic\nscoring and personalized responses. This showcases the potential of integrating LLM with RAG in game design and\ndevelopment, paving the way for truly individualized gaming experiences. Furthermore, it demonstrates the\npotential for creating engaging quiz trivia or educational games by involving LLM. Adding and changing personalities\nis as easy as adding more Jinja template modules. With very little effort, this can change the full game experience,\nreducing the effort for developers. Try it yourself and change the AI personality in the quiz configuration.\n\nMovie Detectives tackles the challenge of maintaining student interest, improving knowledge retention, and making\nlearning enjoyable. It's not just a movie quiz; it’s a glimpse into AI-enhanced education, pushing boundaries\nfor accessible, engaging, and effective learning experiences.\n\n![mockup](doc/mockup.png)\n\n---\n\n## Examples\n\n![demo bttf trivia](doc/demo-bttf-trivia.png)\n*Game mode: Back to the Future Trivia*\n\n![demo profile](doc/demo-profile.png)\n*User profile*\n\n![demo sequel salad](doc/demo-sequel-salad.png)\n*Game mode: Sequel Salad*\n\n---\n\n**Frontend**: [gemini-movie-detectives-ui](https://github.com/vojay-dev/gemini-movie-detectives-ui)\n\n## Tech stack and project overview\n\n- Python 3.12 + [FastAPI](https://fastapi.tiangolo.com/) API development\n- [httpx](https://www.python-httpx.org/) for TMDB client implementation\n- [Jinja](https://jinja.palletsprojects.com/) templating for modular prompt generation including personalities\n- [Pydantic](https://docs.pydantic.dev/latest/) for data modeling and validation\n- [Poetry](https://python-poetry.org/) for dependency management\n- [Docker](https://www.docker.com/) for deployment\n- [Firestore](https://firebase.google.com/docs/firestore) for storing user data, quiz usage and limit management as well as managing the list of franchises for the Sequel Salad game mode\n- [Firebase](https://firebase.google.com/) for user authentication\n- [TMDB API](https://www.themoviedb.org/) for movie metadata\n- [Wikipedia](https://pypi.org/project/wikipedia/) for fetching data from Wikipedia to add more context to the generation process, especially for movie fun facts and Back to the Future trivia\n- [Gemini](https://cloud.google.com/vertex-ai/docs/generative-ai/model-reference/gemini) via [VertexAI](https://cloud.google.com/vertex-ai) for generating quiz questions and evaluating answers\n- [Imagen](https://imagen.research.google/) via [VertexAI](https://cloud.google.com/vertex-ai) for generating fake movie posters\n- [Ruff](https://docs.astral.sh/ruff/) as linter and code formatter together with [pre-commit](https://pre-commit.com/) hooks\n- [Github Actions](https://github.com/features/actions) to automatically run tests and linter on every push\n\n![system overview](doc/architecture.png)\n*Movie Detectives - System Overview*\n\n## Makefile\n\nThe project includes a `Makefile` with common tasks like setting up the virtual environment with Poetry, running the\nservice locally and within Docker, running test, linter and more. Simply run:\n```sh\nmake help\n```\nto get an overview of all available tasks.\n\n![make help](doc/make-help.png)\n*make help*\n\n## Project setup\n\n**(Optional) Configure poetry to use in-project virtualenvs**:\n```sh\npoetry config virtualenvs.in-project true\n```\n\n**Install dependencies**:\n```sh\npoetry install\n```\n\n**Run**:\n\n*Please check the Configuration section to ensure all requirements are met.*\n```sh\npoetry run fastapi dev gemini_movie_detectives_api/main.py\ncurl -s localhost:8000/movies | jq .\n```\n\n## Configuration\n\n**Prerequisite**\n\n- TMDB API key ([can be generated for free](https://developer.themoviedb.org/docs/getting-started))\n- GCP project with TTS and VertexAI API enabled and access to Gemini (`gemini-1.5-pro-001` or `gemini-1.5-flash-001`) and Imagen (`imagegeneration@006`)\n- Firebase project with authentication and Firestore enabled\n- JSON credentials file for GCP Service Account with VertexAI permissions\n- JSON credentials file for Firebase Service Account with write permissions\n\nThe API is configured via environment variables. If a `.env` file is present in the project root, it will be loaded\nautomatically. The following variables must be set:\n\n- `TMDB_API_KEY`: The API key for The Movie Database (TMDB).\n- `GCP_PROJECT_ID`: The ID of the Google Cloud Platform (GCP) project used for VertexAI and Gemini.\n- `GCP_LOCATION`: The location used for prediction processes.\n- `GCP_SERVICE_ACCOUNT_FILE`: The path to the service account file used for authentication with GCP.\n- `FIREBASE_SERVICE_ACCOUNT_FILE`: The path to the service account file used for authentication with Firebase.\n\nThere are more config variables with defaults, which can be used to adjust the default API behavior.\n\nThe necessary documents within Firestore are created automatically when the API is started for the first time. The\nlimits and franchises can be adjusted in the Firestore console.\n\n![firestore](doc/firestore.png)\n\n**Gemini model**\n\nThe default model used for Gemini is `gemini-1.5-pro-001`. To use a different model, simply adjust the `GCP_GEMINI_MODEL`\nin the `.env` file. For this use-case, also the Flash model delivers good results and might be a cost-efficient\nalternative.\n```\nGCP_GEMINI_MODEL=gemini-1.5-flash-001\n```\n\n### Logging\n\nThe API uses the Python logging module and optionally supports Cloud Logging to allow for log analysis and monitoring\nvia Google Cloud. To enable Cloud Logging, set the `GCP_CLOUD_LOGGING_ENABLED` environment variable to `true`. Ensure\nthat the provided Service Account, which belongs to the JSON credentials file set as `GCP_SERVICE_ACCOUNT_FILE`, has\nthe necessary permissions (e.g. role: _Logs Writer_) to write logs to Cloud Logging.\n\n![Google Cloud Logging](doc/cloud-logging.png)\n*Google Cloud Logging*\n\n## Docker\n\nAll Docker commands are also encapsulated in the `Makefile` for convenience.\n\n### Build\n\n```sh\ndocker build -t gemini-movie-detectives-api .\n```\n\n### Run\n\n```sh\ndocker run -d --rm --name gemini-movie-detectives-api -p 9091:9091 gemini-movie-detectives-api\ncurl -s localhost:9091/movies | jq .\ndocker stop gemini-movie-detectives-api\n```\n\n### Save image for deployment\n\n```sh\ndocker save gemini-movie-detectives-api:latest | gzip \u003e gemini-movie-detectives-api_latest.tar.gz\n```\n\n## Gemini interaction\n\nGemini interaction is encapsulated in the `GeminiClient` class. To ensure a high quality of prompt responses and to\navoid unnecessary parsing issues. The `GeminiClient` class uses the Gemini JSON format mode.\n\nSee: [https://ai.google.dev/gemini-api/docs/api-overview#json](https://ai.google.dev/gemini-api/docs/api-overview#json)\n\nThis ensures Gemini replies with valid JSON, whereas the schema is attached to the individual prompt, for example:\n```\nReply using this JSON schema:\n\n{\"question\": str, \"hint1\": str, \"hint2\": str}\n\n- question: your generated question\n- hint1: The first hint to help the participants\n- hint2: The second hint to get the title more easily\n```\n\nThis approach is then combined with Pydantic models to ensure the correctness of datatypes and the overall structure:\n```py\n    @staticmethod\n    def _parse_gemini_answer(gemini_reply: str) -\u003e TitleDetectivesGeminiAnswer:\n        try:\n            return TitleDetectivesGeminiAnswer.model_validate(from_json(gemini_reply))\n        except Exception as e:\n            msg = f'Gemini replied with an unexpected format. Gemini reply: {gemini_reply}, error: {e}'\n            logger.warning(msg)\n            raise ValueError(msg)\n```\n\nThis is a great example how to programmatically interact with Gemini, ensure the quality of the responses and use a LLM\nto cover core business logic.\n\n## API example usage\n\n### Get a list of movies\n\n```sh\ncurl -s localhost:8000/movies | jq .\n```\n\n### Get a random movie\n\n```sh\ncurl -s localhost:8000/movies/random | jq .\n```\n\n```json\n{\n  \"adult\": false,\n  \"backdrop_path\": \"/oe7mWkvYhK4PLRNAVSvonzyUXNy.jpg\",\n  \"belongs_to_collection\": null,\n  \"budget\": 85000000,\n  \"genres\": [\n    {\n      \"id\": 28,\n      \"name\": \"Action\"\n    },\n    {\n      \"id\": 53,\n      \"name\": \"Thriller\"\n    }\n  ],\n  \"homepage\": \"https://www.amazon.com/gp/video/detail/B0CH5YQPZQ\",\n  \"id\": 359410,\n  \"imdb_id\": \"tt3359350\",\n  \"original_language\": \"en\",\n  \"original_title\": \"Road House\",\n  \"overview\": \"Ex-UFC fighter Dalton takes a job as a bouncer at a Florida Keys roadhouse, only to discover that this paradise is not all it seems.\",\n  \"popularity\": 1880.547,\n  \"poster_path\": \"/bXi6IQiQDHD00JFio5ZSZOeRSBh.jpg\",\n  \"production_companies\": [\n    {\n      \"id\": 21,\n      \"logo_path\": \"/usUnaYV6hQnlVAXP6r4HwrlLFPG.png\",\n      \"name\": \"Metro-Goldwyn-Mayer\",\n      \"origin_country\": \"US\"\n    },\n    {\n      \"id\": 1885,\n      \"logo_path\": \"/xlvoOZr4s1PygosrwZyolIFe5xs.png\",\n      \"name\": \"Silver Pictures\",\n      \"origin_country\": \"US\"\n    }\n  ],\n  \"production_countries\": [\n    {\n      \"iso_3166_1\": \"US\",\n      \"name\": \"United States of America\"\n    }\n  ],\n  \"release_date\": \"2024-03-08\",\n  \"revenue\": 0,\n  \"runtime\": 121,\n  \"spoken_languages\": [\n    {\n      \"english_name\": \"English\",\n      \"iso_639_1\": \"en\",\n      \"name\": \"English\"\n    }\n  ],\n  \"status\": \"Released\",\n  \"tagline\": \"Take it outside.\",\n  \"title\": \"Road House\",\n  \"video\": false,\n  \"vote_average\": 7.14,\n  \"vote_count\": 1182,\n  \"poster_url\": \"https://image.tmdb.org/t/p/original/bXi6IQiQDHD00JFio5ZSZOeRSBh.jpg\"\n}\n```\n\n### Start a Title Detectives quiz\n\n```sh\ncurl -s -X POST localhost:8000/quiz/title-detectives \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"quiz_type\": \"title-detectives\"}' | jq .\n```\n\n```json\n{\n  \"quiz_id\": \"70ce5970-65bc-40b4-8b72-31a618254c63\",\n  \"quiz_type\": \"title-detectives\",\n  \"quiz_data\": {\n    \"question\": {\n      \"question\": \"Yo, movie buffs! This one's gonna be lit! Think of a horror flick where some reckless teenagers think they've hit the jackpot by breaking into a blind man's crib. Little did they know, this dude's got some serious secrets hidden inside. What am I talking 'bout?\",\n      \"hint1\": \"This movie proves that sometimes, it's best to leave well enough alone.  Especially when it comes to messing with people's homes.\",\n      \"hint2\": \"D_n'_t B_e_t_e\"\n    },\n    \"movie\": {...},\n    \"speech\": \"/audio/fc481314-6074-4654-94d5-6e967f20a313.mp3\"\n  }\n}\n```\n\nWith the `speech` URL, you can get the result of the Google Text-to-Speech synthesis of the quiz question.\n\n```sh\nwget localhost:8000/audio/fc481314-6074-4654-94d5-6e967f20a313.mp3\n```\n\nGenerated audio and image files are automatically deleted after 24 hours.\n\n### Send answer and finish a quiz\n\n```sh\ncurl -s -X POST localhost:8000/quiz/70ce5970-65bc-40b4-8b72-31a618254c63/answer \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"quiz_id\": \"70ce5970-65bc-40b4-8b72-31a618254c63\", \"answer\": \"Don't Breathe\"}' | jq .\n```\n\n## Rate limit\n\nIn order to control costs and prevent abuse, the API offers a way to limit the number of quiz sessions per game mode\nand per day.\n\nThe limits are managed in Firestore and can be adjusted in the Firestore console.\n\n## Cleanup\n\nThe generated audio and image files by Google Text-to-Speech and Imagen are automatically deleted after 24 hours. The\ncleanup logic is handled in the `TempDirCleaner` class, which is scheduled via the `apscheduler` module.\n\n## Personalities\n\nDue to the modularity of the prompt generation, it is possible to easily switch personalities of the quiz master. The\npersonalities are defined in Jinja templates in the `gemini_movie_detectives_api/templates/personality/` directory.\n\n### Example: Dad Jokes Dad personality\n\n![dad jokes](doc/sequel-salad-dad-jokes.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvojay-dev%2Fgemini-movie-detectives-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvojay-dev%2Fgemini-movie-detectives-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvojay-dev%2Fgemini-movie-detectives-api/lists"}