MovieGPT

English | 中文

MovieGPT is a proof-of-concept chat assistant that lets you explore a local IMDb database using natural language. The backend converts your questions to SQL with Google Gemini and executes them on a MySQL instance. A React interface offers a streamlined chat experience with example prompts and message history.

MovieGPT/
├── backend/       # FastAPI server and Gemini integration
│  ├── fastapi_backend.py  # main FastAPI app
│  ├── get_info.py     # external API helpers
│  └── Schema.py      # database schema and integration
├── frontend/
│  └── moviegpt-react/   # React app
│    ├── src/components/ # React components
│    ├── src/services/  # API services
│    └── src/styles/   # CSS modules
├── db/          # SQL scripts used to load IMDb data
│  └── init.sql     # database initialisation script
├── docker-compose.yml  # spins up the MySQL service
└── start_dev.py     # convenience script for development

• Python 3.13+
• Node.js 16+ -Docker & Docker Compose
• Google Gemini API key

git clone <your-repo-url>
cd MovieGPT

docker-compose up -d

The first run imports IMDb data using db/init.sql

Create a .env file with the following:

# Google Gemini API
GOOGLE_API_KEY=your_gemini_api_key_here

# MySQL configuration
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=imdbuser
MYSQL_PASSWORD=imdbpass
MYSQL_DB=imdb

# OMDb API (optional)
OMDB_API_KEY=your_omdb_api_key_here

# Optional: custom system prompt
SYSTEM_PROMPT=You are an expert movie database assistant...

For the React frontend, set REACT_APP_API_BASE_URL in frontend/moviegpt-react/.env if the backend URL differs.

# Using pip
pip install -r requirements.txt

# Or using uv (recommended)
uv install

python start_dev.py

This automatically:

• Starts the FastAPI backend (http://localhost:8000)
• Starts the React frontend (http://localhost:3000)
• Opens your browser to the app

If you prefer full control:

Backend

cd backend
uvicorn fastapi_backend:app --host 0.0.0.0 --port 8000 --reload

Frontend

cd frontend/moviegpt-react
npm install
npm start

• InputArea – user input field
• MessageList – displays chat history
• LoadingMessage – shows progress while waiting for a reply
• ExampleQueries – handy example query buttons
• SimpleConfirmDialog – confirmation dialog
• Markdown support – responses render with react-markdown
• MovieInfoPanel – shows OMDb details when clicking a title
• ThemeToggleButton – light/dark switch

• Responsive design
• CSS modules
• Modern UI components
• Dark mode theme

# Start everything
python start_dev.py

# Or individually
# Backend with reload
uvicorn backend.fastapi_backend:app --reload

# Frontend
cd frontend/moviegpt-react && npm start

# Backend tests
python -m pytest backend/

# Frontend tests
cd frontend/moviegpt-react
npm test

# Build the frontend
cd frontend/moviegpt-react
npm run build

# Run the backend with uvicorn
uvicorn backend.fastapi_backend:app --host 0.0.0.0 --port 8000

The repo currently only contains Docker config for MySQL. Full containerisation is in progress.

# Start the MySQL service
docker-compose up -d

# Check service status
docker-compose ps

# Stop services
docker-compose down

• Backend Dockerfile
• Frontend Dockerfile
• Full docker-compose orchestration

User: "Show me the top rated 10 movies"
Assistant: runs SQL and returns the results...

User: "Which movies were released in 2020?"
Assistant: generates the corresponding query and displays the results...

User: "Tell me about The Shawshank Redemption"
Assistant: fetches and shows detailed info...

See TODO.md for the full plan.

• Full Docker containerisation
• User authentication system
• Query caching improvements
• Dark mode support

• Slack/Discord bot integration
• Multi-language localisation
• Mobile layout support
• Advanced search features

Contributions are welcome!

1. Fork the repo
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the GNU General Public License v3.0 – see the LICENSE file for details.

• Google Gemini – AI language model
• IMDb – movie database
• FastAPI – modern Python web framework
• React – UI library
• Docker – container platform