{"id":29913707,"url":"https://github.com/connergroth/timbre","last_synced_at":"2025-08-02T02:13:47.922Z","repository":{"id":273429778,"uuid":"919696878","full_name":"connergroth/Timbre","owner":"connergroth","description":"A hybrid music recommendation engine that combines collaborative filtering and content-based models to generate personalized playlists using Spotify, Last.fm, and AOTY data.","archived":false,"fork":false,"pushed_at":"2025-07-28T23:01:38.000Z","size":67011,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-29T00:27:47.262Z","etag":null,"topics":["docker","fastapi","lastfm-api","machine-learning","music","postgresql","python","pytorch","redis","spotify-api","sqlalchemy"],"latest_commit_sha":null,"homepage":"https://tensoe.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/connergroth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-20T20:54:30.000Z","updated_at":"2025-07-28T23:01:43.000Z","dependencies_parsed_at":"2025-02-24T23:23:02.949Z","dependency_job_id":"8f91a1f2-0123-4d7b-b598-9deea211cd99","html_url":"https://github.com/connergroth/Timbre","commit_stats":null,"previous_names":["connergroth/sonic-lens","connergroth/sonance","connergroth/tensoe","connergroth/timbre"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/connergroth/Timbre","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connergroth%2FTimbre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connergroth%2FTimbre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connergroth%2FTimbre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connergroth%2FTimbre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/connergroth","download_url":"https://codeload.github.com/connergroth/Timbre/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connergroth%2FTimbre/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268326739,"owners_count":24232496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","lastfm-api","machine-learning","music","postgresql","python","pytorch","redis","spotify-api","sqlalchemy"],"created_at":"2025-08-02T02:13:29.043Z","updated_at":"2025-08-02T02:13:47.902Z","avatar_url":"https://github.com/connergroth.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/ff6a407e-cefa-4855-8a90-22ae328b8e95\" alt=\"Timbre\" width=\"350px\" /\u003e\n  \u003ch1\u003eTimbre - AI Powered Music Discovery\u003c/h1\u003e\n\u003c/div\u003e\n\n\u003e **Timbre** — a machine learning-powered music recommendation engine that uses AI agents to create personalized music experiences.\n\nTimbre is an intelligent music recommendation platform that combines data from **Spotify**, **Last.fm**, and **Album of the Year (AOTY)** to provide personalized music suggestions through conversational AI agents. The platform features a hybrid recommendation system and modern web interface built with React and Next.js.\n\n---\n\n## Features\n\n- **🤖 AI-Powered Music Agent**  \n  Conversational AI agent that understands music preferences and provides intelligent recommendations through natural language interactions.\n\n- **🎧 Personalized Recommendations**  \n  Hybrid recommendation system combining collaborative filtering and content-based approaches using listening behavior and audio features.\n\n- **🔗 Multi-Platform Integration**  \n  Seamlessly connects with **Spotify**, **Last.fm**, and **Album of the Year** to gather comprehensive music data and preferences.\n\n- **📱 Modern Web Interface**  \n  Clean, responsive UI built with React/Next.js featuring chat interface, playlist management, and real-time music discovery.\n\n- **🎵 Smart Playlist Creation**  \n  AI-generated playlists with Spotify integration for seamless music discovery and playlist management.\n\n- **⚡ High-Performance Backend**  \n  FastAPI-powered backend with multi-tier caching (Redis + in-memory), rate limiting, and async processing.\n\n- **📊 Rich Music Metadata**  \n  Enhanced with AOTY ratings, reviews, tags, and similar album data through custom web scraping pipeline.\n\n---\n\n## Architecture Overview\n\n### Backend (FastAPI)\n- **Multi-tier caching**: Redis primary + in-memory fallback\n- **Rate limiting**: 30 requests/minute via SlowAPI  \n- **Database**: PostgreSQL with SQLAlchemy ORM and Alembic migrations\n- **Web scraping**: Playwright browser automation for AOTY data\n- **AI Agent**: NLP processor with tool registry for music recommendations\n\n### Frontend \n- **Main site**: Vite + React + shadcn/ui components\n- **Auth app**: Next.js application for OAuth flows\n- **State management**: React Context + Supabase auth\n\n### Key Components\n- `/backend/agent/`: AI agent core, tools, and NLP processing\n- `/backend/routes/`: API endpoints (agent, albums, playlists, users)\n- `/backend/services/`: Business logic (Spotify, Last.fm, ML, AOTY)\n- `/backend/ingestion/`: Data pipeline for music metadata\n- `/frontend/app/`: Next.js authentication and chat interface\n\n---\n\n## Tech Stack\n\n### 💻 Backend Technologies\n\n- **FastAPI** – Async Python web framework with automatic OpenAPI docs\n- **PostgreSQL + SQLAlchemy** – Relational database with async ORM\n- **Redis** – High-performance caching layer\n- **Playwright** – Browser automation for AOTY web scraping\n- **Pydantic** – Data validation and serialization\n\n### 📊 Data Sources \u0026 APIs\n\n- **Spotify Web API** – User listening data, playlists, and audio features\n- **Last.fm API** – Scrobbling data and music discovery\n- **AOTY Custom Scraper** – Album ratings, reviews, and metadata\n- **Supabase** – Authentication and user management\n\n### 🤖 AI \u0026 Machine Learning\n\n- **AI Agent Architecture** – Tool-based agent for music recommendations\n- **NLP Processing** – Natural language understanding for music queries\n- **Hybrid Recommender** – Collaborative + content-based filtering\n- **External ML Models** – Integration with [Timbral](https://github.com/connergroth/timbral) recommendation engine\n\n---\n\n## Getting Started\n\n### Prerequisites\n- Python 3.8+\n- Node.js 18+\n- PostgreSQL\n- Redis (optional, falls back to in-memory cache)\n\n### Backend Setup\n```bash\ncd backend\npip install -r requirements.txt\nuvicorn main:app --reload\n```\n\n### Frontend Setup\n```bash\n# Main site\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n\n# Auth app  \ncd frontend/app \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\n### Environment Variables\nConfigure `.env` files in both `backend/` and `frontend/app/` directories with your API keys for Spotify, Last.fm, and Supabase.\n\n---\n\n## Current Status\n\n✅ **Completed:**\n- AI agent architecture with conversational interface\n- Multi-platform data integration (Spotify, Last.fm, AOTY)\n- Modern React/Next.js frontend with chat interface\n- FastAPI backend with caching and rate limiting\n\n🚧 **In Progress:**\n- ML model integration and recommendation refinement\n- Enhanced playlist management features\n- Performance optimizations and deployment preparation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnergroth%2Ftimbre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconnergroth%2Ftimbre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnergroth%2Ftimbre/lists"}