🎨 Clio - Your RAG-Powered AI Art Historian

Meet Clio. She turns your smartphone into an intelligent museum guide.

Instead of reading tiny plaques on the wall, simply point your camera at an artwork. Clio will identify it, pull up real historical data from the MET Museum, and let you chat with the artwork—via text or voice.

It's like walking through a museum with a personal historian in your pocket.

---

🎬 Demo Video

👉 Watch Clio in Action on YouTube

---

⚡ Quick Start

1. Get the Code

git clone https://github.com/sqqstellar/cs50final.git
cd cs50final

2. Set Up the Environment

You'll need Python 3.10+. A virtual environment is recommended:

Windows:

python -m venv venv
.\venv\Scripts\Activate.ps1

Mac/Linux:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Add Your Brain (API Key)

Clio uses Google Gemini to think. Get a free key at Google AI Studio.

1. Create a file named .env in the project folder
2. Paste your key inside:

GEMINI_API_KEY=AIzaSy...your_key_here...

5. Run It!

python app.py

Open your browser to http://127.0.0.1:5000

---

📱 How to Use

1. Scan: Point your camera at an artwork. (Check the image_library/ folder to see which art pieces Clio currently recognizes!)

2. Confirm: Clio will match the image and pull metadata (Artist, Date, History) from the MET API.

3. Chat: Ask questions like "Why is this significant?" or "How was this made?"

4. Voice Mode: Tap the 🎧 headphone icon to speak to Clio hands-free.

---

🧪 Testing Clio

Want to try Clio without visiting a museum? Here's how:

1. Set Up Your API Key

Create a .env file in the project root with your Gemini API key:

GEMINI_API_KEY=your_api_key_here

Get a free key at Google AI Studio.

2. Test with the Existing Library

Since Clio uses your camera, you can test it by:

1. Open the image_library/ folder on your computer
2. Download or send one of the artwork images to your phone
3. Display the image on your phone screen
4. Use another device (or the same phone) to scan it through Clio's camera

3. Verify Artwork Recognition

To confirm Clio identified the artwork correctly:

• Check random_artworks.json — it contains detailed metadata for each artwork in the library (artist, creation date, medium, culture, dimensions, etc.)
• Compare the information Clio displays with the data in this file
• The artwork ID in the filename (e.g., artwork_436535.jpg) corresponds to the MET Museum's object ID

4. Add Your Own Artworks

Want to expand the library?

1. Visit the MET Collection
2. Find an artwork and note its Object ID from the URL
3. Download the image and save it as artwork_[ID].jpg in image_library/
4. Run python get_random_artworks.py to update the metadata

⚠️ Troubleshooting

Issue	Solution
Camera not working	Browsers block camera on http:// unless it's localhost. Use http://127.0.0.1:5000 or enable HTTPS.
Artwork not recognized	Clio only knows artworks in image_library/. Add more by downloading from MET Collection and naming as artwork_[ID].jpg.
Voice not playing	Check browser audio permissions. Interact with the page first (click/tap).
API errors	Verify your .env file exists and contains a valid GEMINI_API_KEY.

---

Questions? Feel free to reach out!