README.md

metadata

title: BeatDebate
emoji: 🚀
colorFrom: yellow
colorTo: gray
sdk: gradio
sdk_version: 5.32.1
app_file: app.py
pinned: false
license: mit
python_version: 3.11.4
short_description: Multi-Agent System for Music Recommendation

🎵 BeatDebate

Multi-Agent Music Recommendation System for AgentX Competition

🌟 Try BeatDebate Live on HuggingFace Spaces | 🏆 AgentX Competition | 📂 GitHub Repository

BeatDebate is a sophisticated music recommendation system that uses 4 specialized AI agents to discover under-the-radar tracks through intelligent debate and strategic planning. Built for the AgentX competition, it demonstrates advanced agentic planning behavior in a real-world application.

🎯 Key Features

• Strategic Planning: PlannerAgent analyzes queries and orchestrates a multi-step recommendation strategy using Gemini.
• Multi-Agent System: Four specialized agents (Planner, GenreMood, Discovery, Judge) collaborate within a LangGraph workflow.
• Intent-Aware Recommendations: The system adapts its scoring and diversity logic based on the user's detected intent (e.g., artist similarity, pure discovery, contextual needs).
• Underground Discovery: DiscoveryAgent focuses on indie, lesser-known tracks, and serendipitous finds.
• Explainable AI: JudgeAgent provides transparent reasoning for each recommendation, linking back to the planning strategy.
• Conversational Interface: A Gradio-based UI allows for natural language interaction and displays rich track information.
• Contextual Conversations: SmartContextManager and ContextAwareIntentAnalyzer enable multi-turn dialogues.
• Agent Reasoning Display: See the complete multi-agent planning and decision-making process in real-time.

🚀 Live Demo

🌟 Try It Now: BeatDebate on HuggingFace Spaces

Experience the power of multi-agent AI planning for music discovery! The live demo includes:

• Agent Reasoning Viewer: Watch how the 4 agents collaborate and make decisions
• Example Queries: Try different types of music discovery intents
• Real-time Planning: See strategic planning in action for the AgentX competition

🏗️ Architecture

The core workflow follows this sequence, orchestrated by LangGraph:

User Query → PlannerAgent (Strategy & Intent Analysis) → [GenreMoodAgent || DiscoveryAgent] (Candidate Generation) → JudgeAgent (Ranking & Explanation) → Formatted Response

Agent Roles:

• 🧠 PlannerAgent:
  • Analyzes user queries using its QueryUnderstandingEngine (powered by Gemini and pattern matching).
  • Extracts entities, detects intent (including hybrid intents and context overrides).
  • Generates a comprehensive planning_strategy dict detailing task analysis, advocate agent coordination parameters, and the evaluation_framework for the Judge.
• 🎸 GenreMoodAgent:
  • Executes the planner's strategy for genre and mood-based discovery.
  • Uses UnifiedCandidateGenerator and ComprehensiveQualityScorer (from src/agents/components/) to fetch and score tracks.
  • Employs MoodLogic and TagGenerator for nuanced style matching.
• 🔍 DiscoveryAgent:
  • Focuses on similarity, novelty, and underground tracks as per the planner's strategy.
  • Also uses UnifiedCandidateGenerator and ComprehensiveQualityScorer.
  • Internal components like SimilarityExplorer and UndergroundDetector aid in finding unique recommendations.
• ⚖️ JudgeAgent:
  • Evaluates candidates from both advocate agents against the planner's evaluation_framework.
  • Applies intent-aware RankingLogic to score and select the final tracks.
  • Uses ConversationalExplainer (potentially with LLM) to generate explanations.

🚀 Quick Start

Prerequisites

• Python 3.11+
• API keys for Gemini, Last.fm, and Spotify (see .env.example)

Installation

1. Clone and setup environment

   git clone https://github.com/SulmanK/BeatDebate.git
   cd BeatDebate
   

2. Install uv dependency manager

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Setup project and install dependencies

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv sync --dev
   

4. Configure environment variables

   cp env.example .env
   # Edit .env with your API keys:
   # GEMINI_API_KEY=your_gemini_api_key
   # LASTFM_API_KEY=your_lastfm_api_key
   # SPOTIFY_CLIENT_ID=your_spotify_client_id
   # SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
   # Optional: LASTFM_SHARED_SECRET
   

5. Run the application

   uv run python -m src.main
   

   The Gradio interface will typically be available at http://localhost:7860 and the FastAPI backend at http://localhost:8000.

🧪 Development

Data Validation

(Scripts to test API responses and data quality)

uv run python scripts/validate_lastfm.py
# uv run python scripts/validate_spotify.py # (If you create this)

Testing

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src --cov-report=html

# Run a specific test file
uv run pytest tests/agents/test_planner_agent.py

Code Quality

# Format code
uv run black src/ tests/
uv run isort src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type check
uv run mypy src/

Project Structure

The project is organized into distinct layers and components:

beatDebate/
├── Design/                  # Design documents and refactoring notes
├── scripts/                 # Utility and validation scripts (e.g., validate_lastfm.py)
├── src/                     # Main source code
│   ├── agents/              # Core AI agent implementations
│   │   ├── base_agent.py    # Abstract base class for all agents
│   │   ├── components/      # Shared utilities for agents
│   │   │   ├── __init__.py
│   │   │   ├── candidate_processor.py
│   │   │   ├── entity_extraction_utils.py
│   │   │   ├── llm_utils.py
│   │   │   ├── query_analysis_utils.py
│   │   │   ├── unified_candidate_generator.py
│   │   │   ├── scoring/
│   │   │   └── generation_strategies/
│   │   ├── discovery/       # DiscoveryAgent and its specific components
│   │   │   ├── agent.py
│   │   │   ├── discovery_config.py
│   │   │   ├── discovery_diversity.py
│   │   │   ├── discovery_filter.py
│   │   │   ├── discovery_scorer.py
│   │   │   ├── similarity_explorer.py
│   │   │   └── underground_detector.py
│   │   ├── genre_mood/      # GenreMoodAgent and its specific components
│   │   │   ├── agent.py
│   │   │   ├── mood_logic.py
│   │   │   ├── tag_generator.py
│   │   │   └── components/
│   │   ├── judge/           # JudgeAgent and its specific components
│   │   │   ├── agent.py
│   │   │   ├── explainer.py
│   │   │   ├── ranking_logic.py
│   │   │   └── components/
│   │   └── planner/         # PlannerAgent and its specific components
│   │       ├── agent.py
│   │       ├── context_analyzer.py
│   │       ├── entity_processor.py
│   │       ├── entity_recognizer.py
│   │       ├── query_analyzer.py
│   │       ├── query_understanding_engine.py
│   │       └── strategy_planner.py
│   ├── api/                 # FastAPI backend and external API clients
│   │   ├── backend.py
│   │   ├── base_client.py
│   │   ├── client_factory.py
│   │   ├── lastfm_client.py
│   │   ├── logging_middleware.py
│   │   ├── rate_limiter.py
│   │   └── spotify_client.py
│   ├── models/              # Pydantic data models and schemas
│   │   ├── agent_models.py
│   │   ├── metadata_models.py
│   │   └── recommendation_models.py
│   ├── services/            # Business logic and service orchestration
│   │   ├── api_service.py
│   │   ├── cache_manager.py
│   │   ├── intent_orchestration_service.py
│   │   ├── llm_fallback_service.py
│   │   ├── metadata_service.py
│   │   ├── recommendation_service.py
│   │   ├── session_manager_service.py
│   │   └── components/      # Modular service components
│   ├── ui/                  # Gradio user interface components
│   │   ├── chat_interface.py
│   │   ├── planning_display.py
│   │   └── response_formatter.py
│   ├── utils/               # Shared utility functions (e.g., logging)
│   │   └── logging_config.py
│   └── main.py              # Application entry point
├── tests/                   # Unit and integration tests
├── .env.example
├── README.md
...

## 🎵 Usage Examples

### Basic Music Discovery

You: "I need focus music for coding"

🧠 PlannerAgent: "Analyzing coding music requirements, setting intent to 'contextual' with activity 'coding'..." 🎸 GenreMoodAgent: "Fetching instrumental, ambient, post-rock based on plan..." 🔍 DiscoveryAgent: "Searching for lesser-known artists suitable for study/focus..." ⚖️ JudgeAgent: "Evaluating candidates. Prioritizing 'concentration_friendliness_score' and quality. Selecting optimal tracks..."

🎵 Results: 3 tracks like "Ambient Focus" by Concentration Master, with explanations referencing coding and focus.

### Artist Similarity with Contextual Refinement

You: "Music like Mk.gee" 🤖 BeatDebate: (Recommends some Mk.gee-like tracks) You: "More Mk.gee tracks, but make them more electronic"

🧠 PlannerAgent: "Context override detected: 'artist_style_refinement' for Mk.gee with 'electronic' style. Updating coordination strategy." 🎸 GenreMoodAgent: "Focusing on Mk.gee's discography, filtering for electronic elements and related tags..." 🔍 DiscoveryAgent: "Looking for Mk.gee tracks or very close collaborators with strong electronic tags..." ⚖️ JudgeAgent: "Prioritizing Mk.gee tracks matching 'electronic'. Evaluating based on similarity to Mk.gee's core style AND electronic fit..."

🎵 Results: Mk.gee tracks that lean electronic, or similar artists known for that specific fusion.

## 🚀 Deployment

### HuggingFace Spaces (Live Demo)

**🌟 [Access the live demo here](https://huggingface.co/spaces/SulmanK/BeatDebate)**

BeatDebate is deployed as a public HuggingFace Space, showcasing advanced agentic planning behavior for the AgentX competition. The deployment features:

- **Public Access**: Try the system without any setup or API keys
- **Agent Reasoning Display**: See how the 4 agents collaborate through strategic planning
- **Competition Integration**: Direct links to AgentX competition and project documentation
- **Real-time Interaction**: Experience multi-agent music discovery in your browser

## 📋 HuggingFace Spaces Deployment Checklist

Ready to deploy BeatDebate to HuggingFace Spaces? Follow this step-by-step guide:

### Step 1: Create HuggingFace Space
1. **Go to [HuggingFace Spaces](https://huggingface.co/new-space)**
2. **Configure Space Settings**:
   - **Space Name**: `beatdebate` (or your preferred name)
   - **License**: `mit`
   - **SDK**: `gradio`
   - **Python Version**: `3.11`
   - **Visibility**: `public`
3. **Set Space Title**: 

BeatDebate: A Multi-Agent System with Strategic Planning for Explainable Music Recommendation

4. **Add Description**:

Multi-agent AI system showcasing strategic planning for music discovery. Features 4 specialized agents collaborating through LangGraph workflow. Built for AgentX competition demonstrating advanced agentic behavior.

### Step 2: Upload Core Files
Upload these files to your HuggingFace Space:

**Required Files**:
- ✅ `app.py` - HuggingFace Spaces entry point
- ✅ `requirements.txt` - Generated dependencies
- ✅ `README.md` - Updated with Spaces info
- ✅ `pyproject.toml` - Project configuration

**Required Directories**:
- ✅ `src/` - Complete source code directory
- ✅ `Design/` - Design documents (optional but helpful)
- ✅ `.env.example` - Environment template

**Optional Files** (recommended):
- ✅ `logging.conf` - Logging configuration
- ✅ `.gitignore` - Git ignore patterns

### Step 3: Configure API Key Secrets
In your Space settings, add these secrets:

**Required Secrets**:
- 🔑 `GEMINI_API_KEY` - Your Google Gemini API key
- 🔑 `LASTFM_API_KEY` - Your Last.fm API key
- 🔑 `SPOTIFY_CLIENT_ID` - Your Spotify Client ID
- 🔑 `SPOTIFY_CLIENT_SECRET` - Your Spotify Client Secret

**Optional Secrets**:
- 🔑 `LASTFM_SHARED_SECRET` - Last.fm shared secret (for advanced features)

**How to Add Secrets**:
1. Go to your Space settings
2. Click "Repository secrets"
3. Add each secret with the exact name listed above
4. Paste your API key values (never commit these to code!)

### Step 4: Update Space URL in README
Replace `YOUR_USERNAME/beatdebate` with your actual HuggingFace Space URL:
```bash
# Find and replace in README.md:
YOUR_USERNAME/beatdebate → your-hf-username/your-space-name

Step 5: Verify Deployment

Once uploaded, your Space should automatically build and deploy:

Check These Items:

• ✅ Space builds without errors (check logs)
• ✅ All 4 agents initialize properly
• ✅ API connections work (Gemini, Last.fm, Spotify)
• ✅ Chat interface loads correctly
• ✅ Agent reasoning display shows planning process
• ✅ Example queries work as expected

Step 6: Competition Integration

Ensure your Space showcases AgentX competition requirements:

Agentic Planning Features:

• ✅ Strategic Planning: PlannerAgent creates comprehensive strategies
• ✅ Multi-Agent Coordination: 4 agents collaborate based on plans
• ✅ Reasoning Transparency: Complete reasoning logs visible
• ✅ Real-World Application: Functional music discovery system

Competition Links:

• ✅ AgentX Competition link in header
• ✅ GitHub Repository link in header
• ✅ Agent reasoning viewer showcases planning behavior

🎯 Quick API Key Setup Guide

Get Gemini API Key (Free):

1. Go to Google AI Studio
2. Click "Get API Key" → "Create API Key"
3. Copy the key and add as GEMINI_API_KEY secret

Get Last.fm API Key (Free):

1. Go to Last.fm API
2. Create an account and get your API key
3. Add as LASTFM_API_KEY secret

Get Spotify API Keys (Free):

1. Go to Spotify Developer Dashboard
2. Create a new app
3. Copy Client ID and Client Secret
4. Add as SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET secrets

🚨 Troubleshooting Common Issues

Build Fails:

• Check requirements.txt for dependency conflicts
• Verify Python 3.11 is selected
• Check logs for specific error messages

Import Errors:

• Ensure all source files are uploaded
• Check that src/ directory structure is maintained
• Verify app.py imports work correctly

API Connection Fails:

• Double-check all API key secrets are set correctly
• Verify secret names match exactly (case-sensitive)
• Test API keys work outside of Spaces

Agents Don't Initialize:

• Check Gemini API key is valid and has quota
• Verify environment variables are accessible
• Review startup logs for specific agent errors

Local Development

For local development and testing:

# Start the backend and frontend (FastAPI runs on port 8000, Gradio on 7860 by default)
uv run python -m src.main

Alternatively, for hot-reloading of the FastAPI backend during development:

# Terminal 1: Start FastAPI backend
uv run uvicorn src.api.backend:app --host 127.0.0.1 --port 8000 --reload

# Terminal 2: Start Gradio UI (pointing to the backend)
# (Ensure your chat_interface.py is configured to use http://127.0.0.1:8000 if run separately)
# Or simply run the main `uv run python -m src.main` which handles both.

🏆 AgentX Competition

BeatDebate demonstrates sophisticated agentic planning behavior for the AgentX competition:

• Strategic Planning: PlannerAgent creates comprehensive, LLM-driven recommendation strategies.
• Agent Coordination: Structured communication via MusicRecommenderState and targeted strategies.
• Reasoning Transparency: reasoning_log in MusicRecommenderState and explanations from JudgeAgent.
• Technical Innovation: Novel application of multi-agent planning to music recommendation, including intent-aware logic and context management.
• Live Demonstration: Public HuggingFace Space showcasing real-time agent collaboration.

Competition Features

• Agent Reasoning Viewer: Watch the planning process unfold in real-time
• Multi-Agent Coordination: See how agents collaborate based on strategic plans
• Explainable AI: Transparent decision-making with full reasoning logs
• Real-World Application: Functional music discovery with immediate practical value

📊 Technical Details

Core Technologies

• Backend: FastAPI, Python 3.11
• Agent Orchestration: LangGraph
• LLM: Google Gemini (via langchain-google-genai)
• Data Models: Pydantic
• Frontend: Gradio
• Dependency Management: uv
• Logging: structlog

Rate Limiting Strategy

• Implemented via UnifiedRateLimiter (src/api/rate_limiter.py) and configured per service (Gemini, Last.fm, Spotify) in APIClientFactory.
• Gemini: Default 15 calls/minute (configurable, e.g., 8-12 for safety).
• Last.fm: Default 3 calls/second.
• Spotify: Default 50 calls/hour.

Caching & Performance

• CacheManager (src/services/cache_manager.py): Uses diskcache for file-based caching of API responses and track metadata with configurable TTLs.
• Async Processing: FastAPI and aiohttp (in BaseAPIClient) ensure non-blocking I/O for external API calls. LangGraph orchestrates agents asynchronously.
• Request optimization and careful LLM use aim to keep costs low and performance acceptable.

Data Sources

• Last.fm API: Primary source for track/artist metadata, tags, and similarity information. Accessed via LastFmClient.
• Spotify Web API: Secondary source for audio previews and potentially audio features (though full audio feature integration for scoring is a future enhancement). Accessed via SpotifyClient.
• Text Embeddings (Future Enhancement): Design allows for future integration of sentence transformers for semantic search (e.g., with ChromaDB), but current MVP focuses on API-driven metadata and LLM reasoning.

🤝 Contributing

1. Fork the repository.
2. Create feature branch: git checkout -b feature/your-new-feature
3. Install dependencies: uv sync --dev
4. Make your changes.
5. Follow code standards: Run uv run black ., uv run isort ., uv run ruff check .
6. Add tests: Ensure new functionality is covered by tests.
7. Run tests: uv run pytest
8. Update docs: If applicable, update README and relevant design documents.
9. Create Pull Request: Submit for review.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Primary Design Document: Design/Plans/beatdebate-design-doc.md
• AgentX Course: LLM Agents Learning @ Stanford
• HuggingFace Space: BeatDebate Live Demo