Intitial commit

DEPLOYMENT.md

@@ -0,0 +1,189 @@
+# Deployment Guide
+
+## Deploying to Hugging Face Spaces (FREE)
+
+Hugging Face Spaces is the recommended free hosting platform for this Gradio app. Users will provide their own Anthropic API keys through the UI.
+
+### Prerequisites
+
+- A [Hugging Face](https://huggingface.co/) account (free)
+- A GitHub account (to connect your repository)
+
+### Step 1: Prepare Your GitHub Repository
+
+1. Push this code to a GitHub repository:
+   ```bash
+   git push origin main
+   ```
+
+2. Make sure your repository includes:
+   - `app.py`
+   - `utils.py`
+   - `requirements.txt`
+   - `README.md`
+   - `.gitignore` (to exclude logs and cache)
+
+### Step 2: Create a Hugging Face Space
+
+1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
+
+2. Click **"Create new Space"**
+
+3. Fill in the details:
+   - **Space name**: `sheet-music-metaphor-analyzer` (or your preferred name)
+   - **License**: Choose your preferred license (MIT recommended)
+   - **Select the Space SDK**: Choose **Gradio**
+   - **Space hardware**: Choose **CPU basic** (free)
+   - **Visibility**: Public (so others can use it)
+
+4. Click **"Create Space"**
+
+### Step 3: Connect to GitHub
+
+You have two options:
+
+#### Option A: Direct Git Push (Recommended)
+
+1. After creating the Space, you'll see a Git URL like:
+   ```
+   https://huggingface.co/spaces/YOUR-USERNAME/sheet-music-metaphor-analyzer
+   ```
+
+2. Clone the empty Space repository:
+   ```bash
+   git clone https://huggingface.co/spaces/YOUR-USERNAME/sheet-music-metaphor-analyzer
+   cd sheet-music-metaphor-analyzer
+   ```
+
+3. Copy your files into this directory:
+   ```bash
+   cp /path/to/your/app.py .
+   cp /path/to/your/utils.py .
+   cp /path/to/your/requirements.txt .
+   cp /path/to/your/README.md .
+   cp /path/to/your/.gitignore .
+   ```
+
+4. Commit and push:
+   ```bash
+   git add .
+   git commit -m "Initial deployment"
+   git push
+   ```
+
+#### Option B: GitHub Sync
+
+1. In your Space settings, click on **"Files and versions"** tab
+
+2. Click **"Add file"** > **"Upload files"**
+
+3. Upload all required files:
+   - `app.py`
+   - `utils.py`
+   - `requirements.txt`
+   - `README.md`
+
+4. Commit the changes
+
+### Step 4: Verify Deployment
+
+1. Wait 1-2 minutes for the Space to build and start
+
+2. Your app will be available at:
+   ```
+   https://huggingface.co/spaces/YOUR-USERNAME/sheet-music-metaphor-analyzer
+   ```
+
+3. Test the app:
+   - Upload a sheet music image
+   - Enter your Anthropic API key
+   - Click "Analyze Music"
+   - Verify the results appear correctly
+
+### Step 5: Share Your Space
+
+Your Space is now live! Share the URL with others:
+```
+https://huggingface.co/spaces/YOUR-USERNAME/sheet-music-metaphor-analyzer
+```
+
+Users will need their own Anthropic API keys to use the app.
+
+## Alternative Deployment Options
+
+### Railway (Limited Free Tier)
+
+1. Sign up at [Railway](https://railway.app/)
+2. Create a new project from GitHub
+3. Add a start command: `python app.py`
+4. Deploy
+
+### Render (Limited Free Tier)
+
+1. Sign up at [Render](https://render.com/)
+2. Create a new Web Service
+3. Connect your GitHub repository
+4. Set build command: `pip install -r requirements.txt`
+5. Set start command: `python app.py`
+6. Deploy
+
+## Troubleshooting
+
+### Space Won't Start
+
+- Check the logs in the Space's "Logs" tab
+- Verify `requirements.txt` has correct package versions
+- Ensure `app.py` has `if __name__ == "__main__": main()`
+
+### Import Errors
+
+- Make sure all files are in the root directory of the Space
+- Verify `utils.py` is uploaded
+- Check that `requirements.txt` includes all dependencies
+
+### API Key Issues
+
+- The app now requires users to input their own API key
+- API keys are not stored or logged
+- Users need to get keys from [Anthropic Console](https://console.anthropic.com/)
+
+## Security Notes
+
+- Never commit API keys to the repository
+- Users provide their own keys through the UI
+- Keys are passed only in-memory and not persisted
+- Logs directory is gitignored to prevent accidental data exposure
+
+## Updating Your Deployment
+
+To update your deployed Space:
+
+1. Make changes to your local files
+2. Commit changes:
+   ```bash
+   git add .
+   git commit -m "Update: description of changes"
+   ```
+3. Push to Hugging Face Space:
+   ```bash
+   git push
+   ```
+
+The Space will automatically rebuild and redeploy.
+
+## Cost Considerations
+
+- **Hugging Face Spaces**: Completely free for CPU-based Gradio apps
+- **API Usage**: Users pay for their own Anthropic API usage
+- **Rate Limits**: Consider Anthropic's rate limits for API usage
+
+## Getting an Anthropic API Key
+
+Users will need to:
+1. Go to [Anthropic Console](https://console.anthropic.com/)
+2. Sign up or log in
+3. Navigate to API Keys section
+4. Create a new API key
+5. Copy and paste into the app
+
+API keys start with `sk-ant-api-` and should be kept secure.

app.py

@@ -0,0 +1,370 @@
+"""
+Sheet Music Metaphor Analyzer - Main Gradio Application
+"""
+
+import base64
+import io
+import os
+from typing import Optional, Tuple
+
+import anthropic
+import gradio as gr
+from PIL import Image
+
+from utils import (
+    parse_and_validate_json,
+    save_analysis_log,
+    setup_logging,
+)
+
+# Initialize logger
+logger = setup_logging()
+
+# Claude API prompt
+ANALYSIS_PROMPT = """You are an experienced music conductor and teacher analyzing sheet music to provide performance guidance.
+
+Follow this step-by-step process:
+
+STEP 1: CONDUCTOR ANALYSIS
+As an experienced conductor, examine the musical notation carefully and describe:
+- mood: The emotional tone and feeling the notation suggests
+- gesture: The physical conducting gesture or body movement this would inspire
+- motion: The type of movement quality (e.g., flowing, crisp, sustained, bouncing)
+
+STEP 2: NOTATION INSIGHTS
+Identify 2-4 specific aspects of the notation that caught your attention and influenced your interpretation. These might be dynamics, articulation, tempo markings, phrase shapes, rhythmic patterns, or harmonic progressions. Write these as clear observations that help explain how you arrived at your interpretation.
+
+STEP 3: INSTRUCTIONAL METAPHORS
+Based on your analysis, create exactly 3 simple, direct instructional metaphors for the performer. Each should:
+- Start with a phrase like "Play this like...", "Think of...", "Imagine...", or similar
+- Use simple, everyday imagery that's easy to grasp
+- Be direct and practical, not flowery or ornate
+- Avoid technical music terminology
+- Focus on feeling and physicality
+- Keep it grounded - prefer "walking through tall grass" over "dancing through celestial meadows"
+
+STEP 4: FINAL METAPHOR
+Synthesize everything above into one concise, simple instructional metaphor. Keep it direct and practical - a clear image the performer can immediately use. Avoid overly poetic or elaborate language.
+
+Return ONLY valid JSON matching this exact schema:
+
+{
+  "mood": "string",
+  "gesture": "string",
+  "motion": "string",
+  "notation_details": ["observation 1", "observation 2", "..."],
+  "instructional_metaphors": ["metaphor 1", "metaphor 2", "metaphor 3"],
+  "final_metaphor": "one simple, direct metaphor"
+}
+
+Remember: Return ONLY the JSON object, no additional text or explanation."""
+
+
+def resize_image(image: Image.Image, max_width: int = 1400) -> Image.Image:
+    """
+    Resize image to max width while maintaining aspect ratio.
+
+    Args:
+        image: PIL Image to resize
+        max_width: Maximum width in pixels
+
+    Returns:
+        Resized PIL Image
+    """
+    if image.width <= max_width:
+        return image
+
+    ratio = max_width / image.width
+    new_height = int(image.height * ratio)
+    return image.resize((max_width, new_height), Image.Resampling.LANCZOS)
+
+
+def image_to_base64(image: Image.Image) -> str:
+    """
+    Convert PIL Image to base64 string.
+
+    Args:
+        image: PIL Image to convert
+
+    Returns:
+        Base64 encoded string
+    """
+    buffered = io.BytesIO()
+    image.save(buffered, format="PNG")
+    return base64.b64encode(buffered.getvalue()).decode("utf-8")
+
+
+def analyze_sheet_music(
+    image: Optional[Image.Image],
+    api_key: Optional[str] = None
+) -> Tuple[str, str, str]:
+    """
+    Analyze sheet music image using Claude Vision API.
+
+    Args:
+        image: PIL Image of sheet music
+        api_key: Optional API key (uses env var if not provided)
+
+    Returns:
+        Tuple of (final_metaphor_html, json_output, error_message)
+    """
+    if image is None:
+        return "", "", "Please upload an image first."
+
+    # Get API key
+    if not api_key:
+        api_key = os.getenv("ANTHROPIC_API_KEY")
+
+    if not api_key:
+        error_msg = "ANTHROPIC_API_KEY not found in environment variables."
+        logger.error(error_msg)
+        return "", "", error_msg
+
+    try:
+        # Resize image
+        logger.info(f"Processing image of size {image.size}")
+        resized_image = resize_image(image)
+        logger.info(f"Resized to {resized_image.size}")
+
+        # Convert to base64
+        image_b64 = image_to_base64(resized_image)
+
+        # Initialize Anthropic client
+        client = anthropic.Anthropic(api_key=api_key)
+
+        # First attempt
+        logger.info("Sending request to Claude Vision API...")
+        response = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1024,
+            temperature=0.2,
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "image",
+                            "source": {
+                                "type": "base64",
+                                "media_type": "image/png",
+                                "data": image_b64,
+                            },
+                        },
+                        {
+                            "type": "text",
+                            "text": ANALYSIS_PROMPT
+                        }
+                    ],
+                }
+            ],
+        )
+
+        raw_response = response.content[0].text
+        logger.info(f"Received response: {raw_response[:200]}...")
+
+        # Parse and validate
+        parsed_data, error = parse_and_validate_json(raw_response, logger)
+
+        # If parsing failed, retry with stricter instruction
+        if parsed_data is None and error:
+            logger.warning(f"First attempt failed: {error}. Retrying with stricter prompt...")
+
+            retry_response = client.messages.create(
+                model="claude-sonnet-4-20250514",
+                max_tokens=1024,
+                temperature=0.1,
+                messages=[
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "image",
+                                "source": {
+                                    "type": "base64",
+                                    "media_type": "image/png",
+                                    "data": image_b64,
+                                },
+                            },
+                            {
+                                "type": "text",
+                                "text": ANALYSIS_PROMPT
+                            }
+                        ],
+                    },
+                    {
+                        "role": "assistant",
+                        "content": raw_response
+                    },
+                    {
+                        "role": "user",
+                        "content": "Return valid JSON only, no prose. Use the exact schema structure provided."
+                    }
+                ],
+            )
+
+            raw_response = retry_response.content[0].text
+            parsed_data, error = parse_and_validate_json(raw_response, logger)
+
+        # Save log
+        save_analysis_log(
+            image_path="uploaded_image",
+            raw_response=raw_response,
+            parsed_data=parsed_data,
+            error=error
+        )
+
+        # Handle results
+        if parsed_data is None:
+            return "", raw_response, f"Failed to parse response: {error}"
+
+        # Format outputs
+        final_metaphor_html = f"""
+        <div style="padding: 30px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                    border-radius: 15px; text-align: center; box-shadow: 0 10px 30px rgba(0,0,0,0.3);">
+            <h2 style="color: white; margin-bottom: 20px; font-size: 24px; font-weight: 300;">
+                Performance Guidance
+            </h2>
+            <p style="color: white; font-size: 32px; font-weight: 500; line-height: 1.5;
+                      font-style: italic; margin: 0;">
+                {parsed_data['final_metaphor']}
+            </p>
+        </div>
+
+        <div style="margin-top: 25px; padding: 20px; background: #f8f9fa;
+                    border-radius: 10px; border-left: 4px solid #667eea;">
+            <h3 style="margin-top: 0; color: #333; font-size: 18px;">Conductor Analysis</h3>
+            <p style="margin: 10px 0;"><strong>Mood:</strong> {parsed_data['mood']}</p>
+            <p style="margin: 10px 0;"><strong>Gesture:</strong> {parsed_data['gesture']}</p>
+            <p style="margin: 10px 0;"><strong>Motion:</strong> {parsed_data['motion']}</p>
+        </div>
+
+        <div style="margin-top: 20px; padding: 20px; background: #e7f3ff;
+                    border-radius: 10px; border-left: 4px solid #2196f3;">
+            <h3 style="margin-top: 0; color: #333; font-size: 18px;">What the Conductor Noticed</h3>
+            <ul style="margin: 10px 0; padding-left: 20px; line-height: 1.8;">
+                {"".join(f'<li>{detail}</li>' for detail in parsed_data['notation_details'])}
+            </ul>
+        </div>
+
+        <div style="margin-top: 20px; padding: 20px; background: #fff3cd;
+                    border-radius: 10px; border-left: 4px solid #ffc107;">
+            <h3 style="margin-top: 0; color: #333; font-size: 18px;">Instructional Metaphors</h3>
+            <ul style="margin: 10px 0; padding-left: 20px; line-height: 1.8;">
+                {"".join(f'<li>{m}</li>' for m in parsed_data['instructional_metaphors'])}
+            </ul>
+        </div>
+        """
+
+        import json
+        json_output = json.dumps(parsed_data, indent=2, ensure_ascii=False)
+
+        logger.info("Analysis completed successfully")
+        return final_metaphor_html, json_output, ""
+
+    except anthropic.APIError as e:
+        error_msg = f"API Error: {str(e)}"
+        logger.error(error_msg)
+        return "", "", error_msg
+    except Exception as e:
+        error_msg = f"Unexpected error: {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        return "", "", error_msg
+
+
+def create_ui() -> gr.Blocks:
+    """
+    Create and configure the Gradio UI.
+
+    Returns:
+        Configured Gradio Blocks interface
+    """
+    with gr.Blocks(
+        title="Sheet Music Metaphor Analyzer",
+        theme=gr.themes.Soft()
+    ) as demo:
+        gr.Markdown(
+            """
+            # Sheet Music Metaphor Analyzer
+
+            Upload a photo of sheet music and get poetic, sensory performance guidance from an AI conductor.
+
+            **Note:** You need your own [Anthropic API key](https://console.anthropic.com/) to use this app.
+            """
+        )
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                image_input = gr.Image(
+                    type="pil",
+                    label="Upload Sheet Music Photo",
+                    height=400
+                )
+
+                api_key_input = gr.Textbox(
+                    label="Anthropic API Key (required)",
+                    type="password",
+                    placeholder="sk-ant-api-..."
+                )
+
+                analyze_btn = gr.Button(
+                    "Analyze Music",
+                    variant="primary",
+                    size="lg"
+                )
+
+            with gr.Column(scale=1):
+                result_html = gr.HTML(label="Result")
+
+                error_output = gr.Textbox(
+                    label="Errors",
+                    visible=True,
+                    interactive=False,
+                    lines=2
+                )
+
+                with gr.Accordion("Debug: Full JSON Response", open=False):
+                    json_output = gr.Code(
+                        label="Raw JSON",
+                        language="json",
+                        lines=15
+                    )
+
+        # Event handlers
+        analyze_btn.click(
+            fn=analyze_sheet_music,
+            inputs=[image_input, api_key_input],
+            outputs=[result_html, json_output, error_output]
+        )
+
+        gr.Markdown(
+            """
+            ---
+            **Tips:**
+            - Upload clear photos of printed sheet music
+            - Works best with short musical phrases
+            - The app will provide sensory metaphors to guide your performance
+            """
+        )
+
+    return demo
+
+
+def main():
+    """
+    Launch the Gradio application.
+    """
+    logger.info("Starting Sheet Music Metaphor Analyzer...")
+
+    # Check for API key
+    if not os.getenv("ANTHROPIC_API_KEY"):
+        logger.warning(
+            "ANTHROPIC_API_KEY not found in environment. "
+            "Users will need to provide it in the UI."
+        )
+
+    demo = create_ui()
+    demo.launch(share=True)
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,3 @@
+anthropic>=0.39.0
+gradio>=4.0.0
+Pillow>=10.0.0

utils.py

@@ -0,0 +1,214 @@
+"""
+Utility functions for JSON validation, repair, and logging.
+"""
+
+import json
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# Expected JSON schema
+SCHEMA = {
+    "mood": str,
+    "gesture": str,
+    "motion": str,
+    "notation_details": list,
+    "instructional_metaphors": list,
+    "final_metaphor": str
+}
+
+
+def setup_logging(log_dir: str = "./logs") -> logging.Logger:
+    """
+    Set up logging to both file and console.
+
+    Args:
+        log_dir: Directory to store log files
+
+    Returns:
+        Configured logger instance
+    """
+    Path(log_dir).mkdir(exist_ok=True)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    log_file = Path(log_dir) / f"metaphor_analyzer_{timestamp}.log"
+
+    logger = logging.getLogger("metaphor_analyzer")
+    logger.setLevel(logging.INFO)
+
+    # Clear any existing handlers
+    logger.handlers.clear()
+
+    # File handler
+    file_handler = logging.FileHandler(log_file)
+    file_handler.setLevel(logging.INFO)
+    file_formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    file_handler.setFormatter(file_formatter)
+
+    # Console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+    console_formatter = logging.Formatter("%(levelname)s - %(message)s")
+    console_handler.setFormatter(console_formatter)
+
+    logger.addHandler(file_handler)
+    logger.addHandler(console_handler)
+
+    return logger
+
+
+def extract_json_from_text(text: str) -> Optional[str]:
+    """
+    Extract JSON from text that might contain markdown code blocks or prose.
+
+    Args:
+        text: Raw text that might contain JSON
+
+    Returns:
+        Extracted JSON string or None if no JSON found
+    """
+    # Try to find JSON in markdown code blocks
+    if "```json" in text:
+        start = text.find("```json") + 7
+        end = text.find("```", start)
+        if end > start:
+            return text[start:end].strip()
+
+    if "```" in text:
+        start = text.find("```") + 3
+        end = text.find("```", start)
+        if end > start:
+            potential_json = text[start:end].strip()
+            if potential_json.startswith("{"):
+                return potential_json
+
+    # Try to find raw JSON by looking for curly braces
+    start = text.find("{")
+    end = text.rfind("}")
+    if start >= 0 and end > start:
+        return text[start:end + 1].strip()
+
+    return None
+
+
+def validate_schema(data: Dict[str, Any]) -> tuple[bool, Optional[str]]:
+    """
+    Validate JSON data against the expected schema.
+
+    Args:
+        data: Parsed JSON data to validate
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    for key, expected_type in SCHEMA.items():
+        if key not in data:
+            return False, f"Missing required field: {key}"
+
+        if not isinstance(data[key], expected_type):
+            return False, f"Field '{key}' has wrong type. Expected {expected_type.__name__}, got {type(data[key]).__name__}"
+
+    # Additional validation for notation_details
+    if not data["notation_details"]:
+        return False, "Field 'notation_details' cannot be empty"
+
+    if not all(isinstance(d, str) for d in data["notation_details"]):
+        return False, "All items in 'notation_details' must be strings"
+
+    # Additional validation for instructional_metaphors
+    if not data["instructional_metaphors"]:
+        return False, "Field 'instructional_metaphors' cannot be empty"
+
+    if len(data["instructional_metaphors"]) != 3:
+        return False, f"Field 'instructional_metaphors' must contain exactly 3 items, got {len(data['instructional_metaphors'])}"
+
+    if not all(isinstance(m, str) for m in data["instructional_metaphors"]):
+        return False, "All items in 'instructional_metaphors' must be strings"
+
+    return True, None
+
+
+def parse_and_validate_json(
+    response_text: str,
+    logger: Optional[logging.Logger] = None
+) -> tuple[Optional[Dict[str, Any]], Optional[str]]:
+    """
+    Parse and validate JSON response from Claude.
+
+    Args:
+        response_text: Raw response text from API
+        logger: Optional logger instance
+
+    Returns:
+        Tuple of (parsed_data, error_message)
+    """
+    if logger:
+        logger.info(f"Raw response: {response_text[:500]}...")
+
+    # Try to extract JSON
+    json_str = extract_json_from_text(response_text)
+
+    if not json_str:
+        # Maybe it's already pure JSON
+        json_str = response_text.strip()
+
+    # Try to parse
+    try:
+        data = json.loads(json_str)
+    except json.JSONDecodeError as e:
+        error = f"JSON parsing failed: {str(e)}"
+        if logger:
+            logger.error(error)
+        return None, error
+
+    # Validate schema
+    is_valid, error_msg = validate_schema(data)
+
+    if not is_valid:
+        if logger:
+            logger.error(f"Schema validation failed: {error_msg}")
+        return None, f"Schema validation failed: {error_msg}"
+
+    if logger:
+        logger.info(f"Successfully parsed and validated JSON: {json.dumps(data, indent=2)}")
+
+    return data, None
+
+
+def save_analysis_log(
+    image_path: str,
+    raw_response: str,
+    parsed_data: Optional[Dict[str, Any]],
+    error: Optional[str],
+    log_dir: str = "./logs"
+) -> None:
+    """
+    Save detailed analysis log to file.
+
+    Args:
+        image_path: Path to analyzed image
+        raw_response: Raw API response
+        parsed_data: Parsed JSON data (if successful)
+        error: Error message (if failed)
+        log_dir: Directory to store logs
+    """
+    Path(log_dir).mkdir(exist_ok=True)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    log_file = Path(log_dir) / f"analysis_{timestamp}.json"
+
+    log_entry = {
+        "timestamp": datetime.now().isoformat(),
+        "image_path": image_path,
+        "raw_response": raw_response,
+        "parsed_data": parsed_data,
+        "error": error,
+        "success": parsed_data is not None
+    }
+
+    with open(log_file, "w", encoding="utf-8") as f:
+        json.dump(log_entry, f, indent=2, ensure_ascii=False)