amit2003dh/song-savvy

Purpose and Runtime

SongSavvy is a local Python/Streamlit application that produces content-based Bollywood song recommendations. It runs as an interactive Streamlit process, launched with streamlit run app.py; it does not indicate a separate backend service, database, or external recommendation API.

Primary entry point: app.py

Dependency/runtime declarations: requirements.txt, pyproject.toml

User Interaction Layer

The Streamlit UI accepts a user’s selected or favorite song and presents ranked related tracks. This layer owns request-time interaction and rendering, while recommendation computation is delegated to the engine.

Grounding path:

• app.py

Dataset Boundary

The recommendation corpus is a repository-managed CSV dataset rather than a remote data source. The application depends on this file being present at runtime; changes to its schema, metadata quality, or acoustic-feature coverage directly affect recommendations.

Grounding path:

• data/bollywood_songs.csv

Preprocessing and Feature Construction

Data cleaning, normalization, and feature-preparation responsibilities are separated into utilities. The intended pipeline combines song metadata and acoustic/textual attributes into input suitable for vectorization, including artist, genre, lyrics, or similar fields when available in the dataset.

Grounding paths:

• utils.py

• data/bollywood_songs.csv

Recommendation Engine

The core domain component performs content-based retrieval: transform prepared song features into vector representations, compare a selected song to the corpus, and return top-N nearest songs. The documented model approach uses TF-IDF vectorization and cosine similarity, implemented with Pandas/NumPy/scikit-learn.

Grounding path:

• recommendation_engine.py

Primary Control and Data Flow

1. app.py loads or requests access to the CSV corpus.

2. Preprocessing utilities in utils.py clean/prepare fields for modeling.

3. recommendation_engine.py builds feature vectors and calculates similarity across songs.

4. The engine returns ranked candidate records to app.py.

5. Streamlit renders recommendations and any available similarity explanation.

The primary architectural boundary is between UI orchestration (app.py) and reusable recommendation logic (recommendation_engine.py); dataset handling/preparation is a second boundary via utils.py.

Infrastructure and Operational Constraints

The application requires Python 3.11+ and local installation of Streamlit, Pandas, NumPy, and scikit-learn. Development-container support exists for a reproducible environment, but the repository shows no deployment manifests, persistence layer, authentication, message queue, or external service integration.

Grounding paths:

• .devcontainer/devcontainer.json

• requirements.txt

• pyproject.toml