Update README.md

README.md

@@ -11,3 +11,184 @@ license: mit
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+
+# Therapeutic Music Generator 🎵 🧘‍♀️
+
+This Hugging Face Space hosts an interactive application that generates personalized therapeutic music based on your current emotional state and desired mood. By combining mood assessment with AI-powered music generation, it creates unique musical pieces designed to support emotional well-being and mood transformation.
+
+## Features
+
+- **Comprehensive Mood Assessment**: Complete a quick questionnaire about your current emotional state, including:
+  - Energy levels
+  - Stress levels
+  - Happiness levels
+  - Current emotions
+  - Desired mood state
+
+- **Customizable Music Preferences**: Optional settings to tailor the generated music to your taste:
+  - Genre preferences
+  - Preferred instruments
+  - Tempo preferences
+  - Musical mood preferences
+
+- **AI-Powered Music Generation**: Utilizes Facebook's MusicGen model to create unique, therapeutic music pieces based on your inputs
+
+## How It Works
+
+1. **Mood Assessment**: Users complete a simple questionnaire rating their current emotional state and desired mood
+2. **Music Preferences**: Optionally specify musical preferences to personalize the generated content
+3. **Prompt Generation**: The system uses GPT-4-mini through LangChain to create a specialized music generation prompt
+4. **Music Creation**: The prompt is processed by Facebook's MusicGen model to create a unique piece of music
+5. **Delivery**: Listen to your personalized therapeutic music directly in the browser
+
+## Code Structure and Flow
+
+### Core Components
+
+1. **Constants and Configurations**
+```python
+MOOD_QUESTIONS = [
+    "On a scale of 1-5, how would you rate your current energy level?",
+    # ... other questions
+]
+```
+- Defines the core assessment questions used in the interface
+- Maintains consistency in the mood evaluation process
+
+2. **LangChain Setup**
+```python
+llm = ChatOpenAI(model="gpt-4o-mini")
+music_prompt_template = """
+Based on the user's mood assessment:
+- Energy level: {energy}
+# ... template structure
+"""
+```
+- Initializes the language model for prompt generation
+- Defines the structured template for converting mood data into music generation prompts
+
+3. **Core Functions**
+
+#### `analyze_mood_and_generate_prompt(responses, preferences)`
+```python
+def analyze_mood_and_generate_prompt(responses, preferences):
+    """Convert questionnaire responses and preferences into a music generation prompt"""
+    try:
+        prompt_result = music_chain.invoke({
+            "energy": responses[0],
+            # ... parameter mapping
+        })
+        return prompt_result.content
+    except Exception as e:
+        return f"Error generating prompt: {str(e)}"
+```
+- Processes user inputs into a structured format
+- Invokes LangChain for prompt generation
+- Handles error cases gracefully
+
+#### `generate_music(prompt, duration=10)`
+```python
+def generate_music(prompt, duration=10):
+    """Generate music using the MusicGen API"""
+    API_URL = "https://api-inference.huggingface.co/models/facebook/musicgen-small"
+    # ... implementation
+```
+- Interfaces with the MusicGen API
+- Handles temporary file creation for audio storage
+- Manages API communication and error handling
+
+### Application Flow
+
+1. **Input Processing**
+   ```mermaid
+   graph LR
+   A[User Input] --> B[Mood Assessment]
+   B --> C[Musical Preferences]
+   C --> D[Prompt Generation]
+   D --> E[Music Generation]
+   E --> F[Audio Output]
+   ```
+
+2. **Data Flow**
+   - User inputs → Gradio interface
+   - Interface → LangChain prompt generation
+   - Prompt → MusicGen API
+   - API response → Audio file
+   - Audio file → User interface
+
+3. **Error Handling Flow**
+   - Input validation at the Gradio interface level
+   - Exception handling in prompt generation
+   - API error management in music generation
+   - User feedback through the interface
+
+### Gradio Interface Structure
+
+```python
+with gr.Blocks() as demo:
+    # Interface layout
+    with gr.Row():
+        with gr.Column():
+            # Input components
+        with gr.Column():
+            # Output components
+```
+- Organized in a two-column layout
+- Left column: User inputs and controls
+- Right column: Generated outputs and status
+
+## Usage
+
+1. Move the sliders to rate your current energy, stress, and happiness levels (1-5 scale)
+2. Type in your current emotions and desired mood state
+3. (Optional) Fill in your musical preferences
+4. Click "Generate Therapeutic Music"
+5. Wait for the system to generate your personalized music
+6. Listen to the generated audio and read the prompt that created it
+
+## Technical Requirements
+
+### Dependencies
+```python
+gradio
+requests
+langchain_openai
+langchain_core
+```
+
+### Environment Variables
+- `HF_API_KEY`: Your Hugging Face API key with access to the MusicGen model
+
+### API Specifications
+- MusicGen API endpoint: `https://api-inference.huggingface.co/models/facebook/musicgen-small`
+- Maximum request timeout: 300 seconds
+- Output format: WAV audio file
+
+## Limitations
+
+- Music generation may take a few minutes
+- Generated audio clips are limited in duration
+- The system works best with clear, specific emotional descriptions
+- API rate limits may apply
+- Temporary file storage considerations
+
+## Future Improvements
+
+- Extended music duration options
+- More detailed musical customization
+- Batch generation capabilities
+- History tracking of generated music
+- Mood improvement tracking
+- Integration with additional music generation models
+- Enhanced error handling and retry mechanisms
+- User session management
+- Feedback collection system
+ 
+## Credits
+
+- MusicGen by Facebook Research
+- GPT-4-mini for prompt generation
+- Hugging Face for model hosting
+- Gradio for the user interface
+