How kcharvi/resonique works
Project Type and Purpose
• Resonique is a full-stack, AI-powered music discovery web application built with Streamlit (Python).
• It supports two major flows:
a. Multimodal Song Retrieval (text/image → Gemini AI → Pinecone → Spotify API)
b. Emotion-Based Audio Retrieval (local Emotify dataset → Pinecone → Supabase storage)
File Structure
• Top-level files:
• streamlit_app.py – Streamlit entrypoint (UI layer)
• requirements.txt, .streamlit/config.toml – dependency and config
• Directories:
• views/ – “controllers” implementing each user flow (landing_page, ingest_emotify, ingest_spotify, query_gemini, search_audio)
• utils/ – service connectors (connect.py handles Pinecone, Gemini, Spotify, Supabase)
• data/ – offline Emotify dataset and precomputed embeddings
• Dev/CI: .devcontainer/ for containerized dev environment
README Insights
• Tech stack: Streamlit, Google Gemini AI, Pinecone Vector DB, Supabase (storage & DB), Spotify API
• Two distinct pipelines (ingest vs. query) with embedding and vector-search at their core
• Credentials stored in .streamlit/secrets.toml
Main Components and Interactions
a. User Interface (Streamlit)
– Entrypoint: streamlit_app.py loads views
– Presents upload fields (image/text/emotion) and displays results (songs or audio clips)
b. Controller Layer (views/*.py)
– Landing page orchestration
– Ingestion scripts: ingest_emotify.py, ingest_spotify.py
– Query handlers: query_gemini.py (multimodal), search_audio.py (emotion)
c. Service Layer (utils/connect.py)
– Abstracts API calls and client instantiation for:
• Google Gemini (text/image embeddings)
• Pinecone (vector DB read/write)
• Spotify (track metadata)
• Supabase (audio file storage retrieval)
d. Data Stores & External Services
– Pinecone indexes (song embeddings, emotion embeddings)
– Supabase storage bucket (Emotify audio clips)
– Spotify API (playlist and track metadata)
Architectural Patterns & Design Principles
• Layered architecture: UI → Controllers → Services → External systems
• Separation of concerns: ingestion vs. query flows kept in separate view modules
• Dependency injection via utils/connect (single place for all external-service clients)
• Vector-search as core design principle (mpnet embeddings, cosine similarity)