# SmartPlayer - A Python Music Player with an AI DJ

This project is a desktop music player built with Python and Tkinter. It scans a local music directory, organizes the songs, and learns from the user's listening habits. The ultimate goal is to create a "Smart Mode" that uses a local LLM and embedding models to intelligently select music based on user history, mood, and context.

---

### Project Goal

The final application will:
1.  Scan and manage a local music library.
2.  Provide standard music player controls (play, pause, skip, volume, etc.).
3.  Offer playback modes like shuffle and repeat.
4.  Use web search and an LLM to enrich the song database with lyrics, genre, mood, and year.
5.  Track user listening history (plays, skips, finishes, likes).
6.  Implement a "Smart Mode" that uses an AI recommender to create context-aware playlists on the fly.

---

### File Structure Overview

*   `main_player.py`: The main application entry point, responsible for the UI and event loop.
*   `database.py`: Handles all SQLite database connections and schema management.
*   `music_scanner.py`: Logic for scanning the `./music` directory and populating the database.
*   `ai_enricher.py`: A script to fetch data and use AI to enrich the database. Run this manually after Phase 3.
*   `recommender.py`: Contains the AI logic for the "Smart Mode" recommendations.
*   `instructions/`: Directory containing the step-by-step tasks for the AI agent.
*   `music/`: Placeholder directory for music files.

---

### How to Run

1.  **Install Dependencies:**
    ```bash
    pip install -r requirements.txt
    ```

2.  **Run the Music Player:**
    ```bash
    python main_player.py
    ```

3.  **Run the AI Enricher (after Phase 3):**
    ```bash
    python ai_enricher.py
    ```

---

### Development Process

This project is built in phases. The instructions for the **current phase** are located in the `instructions/` directory.