Full Viral Images v1.0 implementation - all modules and configs

app.py

@@ -1 +1,552 @@
-<PLACEHOLDER>
+"""
+Viral Images — Image Scoring System
+Upload an image, score it, and improve it.
+
+Deployed on HuggingFace Spaces: https://huggingface.co/spaces/Babajaan/viral-images
+"""
+
+import os
+import sys
+import time
+import traceback
+from pathlib import Path
+
+# Ensure our modules are importable
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import gradio as gr
+import pandas as pd
+from PIL import Image
+
+from utils.preprocessing import preprocess_image, validate_image
+from utils.formatting import (
+    format_overall_score,
+    format_sub_scores,
+    format_strengths,
+    format_weaknesses,
+    format_suggestions,
+    format_projected_improvement,
+    format_comparison,
+)
+from scoring.engine import ScoringEngine, ScoreResponse
+from recommendations.engine import RecommendationEngine, compute_improvement_potential
+from compare.comparator import compare_scores
+from models.loader import ModelLoader
+
+# ───────────────────────────────────────────────────────────────
+# Global state (models loaded once at startup)
+# ───────────────────────────────────────────────────────────────
+
+MODEL_LOADER = None
+SCORING_ENGINE = None
+REC_ENGINE = None
+
+
+def _init_engines():
+    """Initialize scoring engines on startup."""
+    global MODEL_LOADER, SCORING_ENGINE, REC_ENGINE
+    
+    print("[ViralImages] Initializing engines...")
+    t0 = time.time()
+    
+    MODEL_LOADER = ModelLoader()
+    
+    # Try to find config files
+    config_paths = {
+        "scoring": None,
+        "rules": None,
+        "model": None,
+    }
+    
+    for base in ["configs", "viral-images/configs", os.path.join(os.path.dirname(__file__), "configs")]:
+        for key, fname in [("scoring", "scoring_weights.yaml"), 
+                           ("rules", "suggestion_rules.yaml"),
+                           ("model", "model_config.yaml")]:
+            if config_paths[key] is None:
+                p = os.path.join(base, fname)
+                if os.path.exists(p):
+                    config_paths[key] = p
+    
+    SCORING_ENGINE = ScoringEngine(
+        model_loader=MODEL_LOADER,
+        config_path=config_paths["scoring"]
+    )
+    REC_ENGINE = RecommendationEngine(
+        rules_path=config_paths["rules"]
+    )
+    
+    # Pre-warm (load CLIP if available)
+    try:
+        SCORING_ENGINE.warmup()
+        print(f"[ViralImages] Engines ready in {time.time()-t0:.1f}s")
+    except Exception as e:
+        print(f"[ViralImages] Warmup failed: {e}")
+        print("[ViralImages] Running in fallback mode (no CLIP).")
+
+
+# Initialize on module load
+_init_engines()
+
+# ───────────────────────────────────────────────────────────────
+# Score Image Tab
+# ───────────────────────────────────────────────────────────────
+
+def score_image(image_input, concept, audience, use_case, detail_level):
+    """
+    Score an uploaded image.
+    
+    Returns:
+        (overall_html, scores_df, strengths_text, weaknesses_text,
+         suggestions_text, projected_html)
+    """
+    if image_input is None:
+        return (
+            "<div style='padding:20px; color:#e74c3c;'><b>⚠️ Please upload an image first.</b></div>",
+            pd.DataFrame(),
+            "", "", "",
+            "<div style='padding:12px; color:#999;'>No image to analyze.</div>"
+        )
+    
+    try:
+        img = preprocess_image(image_input)
+        val_error = validate_image(img)
+        if val_error:
+            return (
+                f"<div style='padding:20px; color:#e74c3c;'><b>⚠️ {val_error}</b></div>",
+                pd.DataFrame(),
+                "", "", "",
+                "<div style='padding:12px; color:#999;'>Image validation failed.</div>"
+            )
+        
+        # Score
+        response = SCORING_ENGINE.score(img, concept or "", audience, use_case)
+        
+        # Generate suggestions
+        suggestions = REC_ENGINE.generate(
+            response.sub_scores,
+            response.raw_features,
+            use_case
+        )
+        response.suggestions = [
+            {
+                "priority": s.priority,
+                "sub_score_target": s.sub_score_target,
+                "message": s.message,
+                "projected_gain": s.projected_gain,
+                "trigger_feature": s.trigger_feature,
+                "trigger_value": s.trigger_value,
+            }
+            for s in suggestions
+        ]
+        
+        # Projected improvement
+        projected = REC_ENGINE.estimate_improvement(
+            response.sub_scores,
+            suggestions,
+            use_case
+        )
+        response.projected_improvement = projected
+        
+        # Format outputs
+        overall_html = format_overall_score(response.overall_score)
+        scores_df = format_sub_scores(response.sub_scores)
+        strengths_html = format_strengths(response.strengths)
+        weaknesses_html = format_weaknesses(response.weaknesses)
+        suggestions_html = format_suggestions(response.suggestions)
+        projected_html = format_projected_improvement(
+            response.overall_score, projected
+        )
+        
+        # Metadata footer
+        meta = response.metadata
+        meta_html = f"<div style='font-size:11px; color:#999; margin-top:8px;'>⏱ {meta.get('processing_time_ms', '?')}ms | Mode: {meta.get('neural_richness_mode', '?')} | Confidence: {response.confidence:.0%}</div>"
+        
+        return (
+            overall_html + meta_html,
+            scores_df,
+            strengths_html,
+            weaknesses_html,
+            suggestions_html,
+            projected_html,
+        )
+        
+    except Exception as e:
+        traceback.print_exc()
+        return (
+            f"<div style='padding:20px; color:#e74c3c;'><b>⚠️ Error during scoring:</b><br/>{str(e)}</div>",
+            pd.DataFrame(),
+            "", "", "",
+            "<div style='padding:12px; color:#999;'>Scoring failed.</div>"
+        )
+
+
+# ───────────────────────────────────────────────────────────────
+# Compare Mode Tab
+# ───────────────────────────────────────────────────────────────
+
+def compare_images(original_img, revised_img, concept, audience, use_case):
+    """
+    Compare before/after images.
+    
+    Returns:
+        (original_scores_label, revised_scores_label, comparison_html, next_steps_text)
+    """
+    if original_img is None or revised_img is None:
+        return (
+            {}, {},
+            "<div style='padding:20px; color:#e74c3c;'><b>⚠️ Please upload both images.</b></div>",
+            "Upload both original and revised images to compare."
+        )
+    
+    try:
+        # Score both
+        original = SCORING_ENGINE.score(original_img, concept or "", audience, use_case)
+        revised = SCORING_ENGINE.score(revised_img, concept or "", audience, use_case)
+        
+        # Compare
+        result = compare_scores(original, revised)
+        
+        # Format
+        orig_label = {k: v / 100 for k, v in original.sub_scores.items()}
+        rev_label = {k: v / 100 for k, v in revised.sub_scores.items()}
+        
+        comp_html = format_comparison_result(result)
+        
+        next_steps = "\n".join(
+            f"• {rec['message']}" for rec in result["next_recommendations"]
+        ) if result["next_recommendations"] else "No further improvements needed — your revised image scores well!"
+        
+        return (
+            orig_label,
+            rev_label,
+            comp_html,
+            next_steps,
+        )
+        
+    except Exception as e:
+        traceback.print_exc()
+        return (
+            {}, {},
+            f"<div style='padding:20px; color:#e74c3c;'><b>⚠️ Error:</b><br/>{str(e)}</div>",
+            "Comparison failed. Please try again."
+        )
+
+
+def format_comparison_result(result: dict) -> str:
+    """Format comparison as HTML."""
+    orig = result["original_overall"]
+    rev = result["revised_overall"]
+    delta = result["delta_overall"]
+    
+    color = "#27ae60" if delta > 0 else "#e74c3c" if delta < 0 else "#999"
+    emoji = "📈" if delta > 0 else "📉" if delta < 0 else "➡️"
+    
+    html = f"""
+    <div style="padding:16px; background:#f8f9fa; border-radius:8px;">
+        <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:16px;">
+            <div style="text-align:center; flex:1;">
+                <div style="font-size:12px; color:#666;">Original</div>
+                <div style="font-size:36px; font-weight:bold; color:#999;">{orig:.0f}</div>
+            </div>
+            <div style="font-size:28px; color:#ccc; padding:0 16px;">→</div>
+            <div style="text-align:center; flex:1;">
+                <div style="font-size:12px; color:#666;">Revised</div>
+                <div style="font-size:36px; font-weight:bold; color:{color};">{rev:.0f}</div>
+            </div>
+        </div>
+        <div style="text-align:center; color:{color}; font-weight:bold; font-size:16px; margin-bottom:12px;">
+            {emoji} Overall: {abs(delta):.0f} point{'s' if abs(delta) != 1 else ''} {'gained' if delta > 0 else 'lost' if delta < 0 else 'unchanged'}
+        </div>
+    """
+    
+    if result["improvements"]:
+        html += "<div style='font-weight:bold; color:#27ae60; margin-top:8px;'>✅ Improvements:</div><ul style='margin:4px 0; padding-left:20px;'>"
+        for name, val in result["improvements"]:
+            html += f"<li><b>{name.replace('_', ' ').title()}:</b> +{val:.0f} points</li>"
+        html += "</ul>"
+    
+    if result["regressions"]:
+        html += "<div style='font-weight:bold; color:#e74c3c; margin-top:8px;'>⚠️ Regressions:</div><ul style='margin:4px 0; padding-left:20px;'>"
+        for name, val in result["regressions"]:
+            html += f"<li><b>{name.replace('_', ' ').title()}:</b> {val:.0f} points</li>"
+        html += "</ul>"
+    
+    if result["next_recommendations"]:
+        html += "<div style='font-weight:bold; color:#2980b9; margin-top:8px;'>📋 Next Steps:</div><div style='margin:4px 0;'>"
+        for rec in result["next_recommendations"]:
+            html += f"<div style='margin:4px 0; padding:6px 10px; background:#e3f2fd; border-radius:4px; font-size:13px;'>{rec['message']}</div>"
+        html += "</div>"
+    
+    html += "</div>"
+    return html
+
+
+# ───────────────────────────────────────────────────────────────
+# Gradio App
+# ───────────────────────────────────────────────────────────────
+
+ABOUT_TEXT = """
+## 🧠 About Viral Images
+
+**Viral Images** scores any image across 8 dimensions and suggests concrete improvements.
+
+### What It Measures
+| Dimension | Description |
+|-----------|-------------|
+| **Concept Match** | Does the image convey your intended topic? |
+| **Visual Focus** | Is there a clear focal point that draws the eye? |
+| **Readability** | Is text legible and well-sized? |
+| **Complexity Balance** | Is detail level appropriate — not empty, not cluttered? |
+| **Communication Clarity** | Is the visual hierarchy clear and well-organized? |
+| **Predicted Neural Richness** | How visually engaging is the image? |
+| **Memorability** | Will viewers remember it after one viewing? |
+| **Improvement Potential** | How much room for improvement remains? |
+
+### How to Use
+1. **Upload an image** (JPG, PNG, or any common format)
+2. **Describe the concept** — what should this image communicate?
+3. **Select audience and use case**
+4. Click **"Score Image"**
+5. Review scores, strengths, weaknesses, and suggestions
+
+### Compare Mode
+Upload an **original** and a **revised** version to see what improved and what to focus on next.
+
+### ⚠️ Important Disclaimer
+- Scores are **AI-predicted proxies**, not measurements of real brain activity.
+- Scores do **not guarantee engagement, virality, or aesthetic quality**.
+- Use as **directional feedback** to complement your own judgment.
+- Predicted Neural Richness is estimated via computational proxy models, not from actual fMRI data.
+
+### Technical Details
+Models used: CLIP ViT-B/32 (concept matching), heuristic analysis (OpenCV), 
+saliency heuristics, OCR heuristics, and aesthetic proxies.
+Neural richness is estimated via proxy, not measured.
+"""
+
+
+def build_app():
+    """Build and return the Gradio app."""
+    
+    with gr.Blocks() as demo:
+        gr.Markdown(
+            """
+            # 🧠 Viral Images
+            ### *Upload an image, score it, and improve it.*
+            """
+        )
+        
+        # ── TAB 1: Score Image ──
+        with gr.Tab("📊 Score Image"):
+            with gr.Row():
+                # Input column
+                with gr.Column(scale=2):
+                    image_input = gr.Image(
+                        type="pil",
+                        label="📷 Upload Image",
+                        sources=["upload", "clipboard"],
+                        height=300,
+                    )
+                    
+                    concept_input = gr.Textbox(
+                        label="💡 Concept / Theme",
+                        placeholder="e.g., photosynthesis process, product launch, data visualization...",
+                        lines=1,
+                    )
+                    
+                    audience_input = gr.Dropdown(
+                        choices=[
+                            "General",
+                            "Children (K-8)",
+                            "High School Students",
+                            "College Students",
+                            "Professionals",
+                            "Researchers",
+                            "General Public",
+                            "Social Media Audience",
+                        ],
+                        label="👥 Target Audience",
+                        value="General",
+                    )
+                    
+                    usecase_input = gr.Dropdown(
+                        choices=[
+                            ("Social Media Post", "social_media"),
+                            ("Thumbnail", "thumbnail"),
+                            ("Educational", "educational"),
+                            ("Scientific Figure", "scientific_figure"),
+                            ("Infographic", "infographic"),
+                            ("Presentation Slide", "presentation_slide"),
+                            ("Marketing", "marketing"),
+                            ("General", "default"),
+                        ],
+                        label="🎯 Use Case",
+                        value="social_media",
+                    )
+                    
+                    score_btn = gr.Button(
+                        "🔍 Score Image",
+                        variant="primary",
+                        size="lg",
+                    )
+                    
+                    with gr.Accordion("⚙️ Advanced Options", open=False):
+                        detail_slider = gr.Slider(
+                            1, 5, value=3, step=1,
+                            label="Detail Level",
+                        )
+                
+                # Output column
+                with gr.Column(scale=3):
+                    overall_score = gr.HTML(
+                        label="Overall Score",
+                        value="<div style='padding:40px; text-align:center; color:#999;'>Upload an image and click 'Score Image' to see results.</div>"
+                    )
+                    
+                    with gr.Row():
+                        strengths_box = gr.HTML(
+                            label="✅ Strengths",
+                            value="",
+                        )
+                        weaknesses_box = gr.HTML(
+                            label="⚠️ Weaknesses",
+                            value="",
+                        )
+                    
+                    score_chart = gr.BarPlot(
+                        x="Sub-Score",
+                        y="Score",
+                        color="Sub-Score",
+                        title="Score Breakdown",
+                        y_lim=[0, 100],
+                        height=280,
+                        value=pd.DataFrame({"Sub-Score": [], "Score": []}),
+                    )
+                    
+                    suggestions_box = gr.HTML(
+                        label="💡 Improvement Suggestions",
+                        value="",
+                    )
+                    
+                    projected_html = gr.HTML(
+                        label="Projected Improvement",
+                        value="",
+                    )
+            
+            score_btn.click(
+                fn=score_image,
+                inputs=[image_input, concept_input, audience_input, usecase_input, detail_slider],
+                outputs=[overall_score, score_chart, strengths_box, weaknesses_box, suggestions_box, projected_html],
+                concurrency_id="inference",
+                concurrency_limit=1,
+            )
+        
+        # ── TAB 2: Compare Mode ──
+        with gr.Tab("🔄 Compare Mode"):
+            with gr.Row():
+                before_img = gr.Image(
+                    type="pil",
+                    label="📷 Original Image",
+                    sources=["upload"],
+                    height=250,
+                )
+                after_img = gr.Image(
+                    type="pil",
+                    label="📷 Revised Image",
+                    sources=["upload"],
+                    height=250,
+                )
+            
+            with gr.Row():
+                compare_concept = gr.Textbox(
+                    label="💡 Concept",
+                    placeholder="Same concept as original...",
+                    lines=1,
+                )
+                compare_audience = gr.Dropdown(
+                    choices=[
+                        "General", "Children (K-8)", "High School Students",
+                        "College Students", "Professionals", "Researchers",
+                        "General Public", "Social Media Audience",
+                    ],
+                    label="👥 Audience",
+                    value="General",
+                )
+                compare_usecase = gr.Dropdown(
+                    choices=[
+                        ("Social Media Post", "social_media"),
+                        ("Thumbnail", "thumbnail"),
+                        ("Educational", "educational"),
+                        ("Scientific Figure", "scientific_figure"),
+                        ("Infographic", "infographic"),
+                        ("Presentation Slide", "presentation_slide"),
+                        ("Marketing", "marketing"),
+                        ("General", "default"),
+                    ],
+                    label="🎯 Use Case",
+                    value="social_media",
+                )
+            
+            compare_btn = gr.Button(
+                "🔄 Compare",
+                variant="primary",
+                size="lg",
+            )
+            
+            with gr.Row():
+                before_scores = gr.Label(
+                    label="Original Scores",
+                    value={},
+                )
+                after_scores = gr.Label(
+                    label="Revised Scores",
+                    value={},
+                )
+            
+            comparison_html = gr.HTML(
+                label="Comparison Results",
+                value="<div style='padding:20px; text-align:center; color:#999;'>Upload both images to compare.</div>"
+            )
+            
+            next_steps = gr.HTML(
+                label="📋 Next Recommended Edits",
+                value="",
+            )
+            
+            compare_btn.click(
+                fn=compare_images,
+                inputs=[before_img, after_img, compare_concept, compare_audience, compare_usecase],
+                outputs=[before_scores, after_scores, comparison_html, next_steps],
+                concurrency_id="inference",
+                concurrency_limit=1,
+            )
+        
+        # ── TAB 3: About ──
+        with gr.Tab("ℹ️ About"):
+            gr.Markdown(ABOUT_TEXT)
+        
+        # Footer
+        gr.Markdown(
+            """
+            <div style="margin-top:20px; padding:12px; background:#f8f9fa; border-radius:8px; font-size:12px; color:#666;">
+            ⚠️ <b>Disclaimer:</b> Scores are AI-predicted proxies, not measurements of brain activity or guaranteed engagement. 
+            Use as directional feedback, not absolute truth. 
+            <a href="https://github.com/facebookresearch/algonauts-2025" target="_blank">TRIBE</a> is used only as inspiration for the neural richness proxy.
+            </div>
+            """
+        )
+    
+    return demo
+
+
+# ───────────────────────────────────────────────────────────────
+# Launch
+# ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    demo = build_app()
+    demo.queue(max_size=10, api_open=False).launch(
+        show_api=False,
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+    )

compare/comparator.py

@@ -0,0 +1,99 @@
+"""Before/after image comparison module."""
+
+from typing import Dict, Any, List, Tuple, Optional
+from scoring.engine import ScoreResponse
+
+
+def compare_scores(original: ScoreResponse, revised: ScoreResponse) -> Dict[str, Any]:
+    """
+    Compare two scored images and produce delta analysis.
+    
+    Returns dict with:
+        original_overall, revised_overall, delta_overall,
+        improvements, regressions, next_recommendations, all_deltas
+    """
+    orig_scores = original.sub_scores
+    rev_scores = revised.sub_scores
+    
+    # Compute deltas
+    all_deltas = {}
+    for key in orig_scores:
+        if key in rev_scores:
+            all_deltas[key] = round(rev_scores[key] - orig_scores[key], 1)
+    
+    # Identify improvements (>5) and regressions (<-5)
+    MEANINGFUL = 5.0
+    improvements = [(k, v) for k, v in all_deltas.items() if v > MEANINGFUL]
+    regressions = [(k, v) for k, v in all_deltas.items() if v < -MEANINGFUL]
+    
+    # Sort by magnitude
+    improvements.sort(key=lambda x: -x[1])
+    regressions.sort(key=lambda x: x[1])
+    
+    # Next recommendations: weakest sub-scores in revised version
+    # Exclude improvement_potential
+    filtered_rev = {k: v for k, v in rev_scores.items() if k != "improvement_potential"}
+    next_targets = sorted(filtered_rev.items(), key=lambda x: x[1])[:3]
+    
+    # Build next recommendations
+    readable_names = {
+        "concept_match": "Concept Match",
+        "visual_focus": "Visual Focus",
+        "readability": "Readability",
+        "complexity_balance": "Complexity Balance",
+        "communication_clarity": "Communication Clarity",
+        "neural_richness": "Neural Richness",
+        "memorability_proxy": "Memorability",
+    }
+    
+    next_recommendations = []
+    for name, score in next_targets:
+        readable = readable_names.get(name, name)
+        next_recommendations.append({
+            "sub_score": name,
+            "current_score": score,
+            "message": f"Further improve {readable.lower()} (currently {score:.0f}/100) — this is your weakest remaining dimension."
+        })
+    
+    return {
+        "original_overall": round(original.overall_score, 1),
+        "revised_overall": round(revised.overall_score, 1),
+        "delta_overall": round(revised.overall_score - original.overall_score, 1),
+        "improvements": improvements[:5],
+        "regressions": regressions[:5],
+        "next_recommendations": next_recommendations,
+        "all_deltas": all_deltas,
+    }
+
+
+def format_comparison_result(result: Dict[str, Any]) -> str:
+    """Format comparison result as human-readable text."""
+    lines = []
+    
+    orig = result["original_overall"]
+    rev = result["revised_overall"]
+    delta = result["delta_overall"]
+    
+    if delta > 0:
+        lines.append(f"📈 Overall improved: {orig:.0f} → {rev:.0f} (+{delta:.0f} points)")
+    elif delta < 0:
+        lines.append(f"📉 Overall decreased: {orig:.0f} → {rev:.0f} ({delta:.0f} points)")
+    else:
+        lines.append(f"➡️ Overall unchanged: {orig:.0f} → {rev:.0f}")
+    
+    if result["improvements"]:
+        lines.append("\n✅ Improvements:")
+        for name, val in result["improvements"]:
+            lines.append(f"   • {name}: +{val:.0f} points")
+    
+    if result["regressions"]:
+        lines.append("\n⚠️ Regressions:")
+        for name, val in result["regressions"]:
+            lines.append(f"   • {name}: {val:.0f} points")
+    
+    if result["next_recommendations"]:
+        lines.append("\n📋 Next recommended edits:")
+        for rec in result["next_recommendations"]:
+            lines.append(f"   • {rec['message']}")
+    
+    return "\n".join(lines)

configs/model_config.yaml

@@ -0,0 +1,27 @@
+models:
+  clip:
+    model_id: "openai/clip-vit-base-patch32"
+    dtype: "float16"
+    device: "auto"
+
+thresholds:
+  min_image_size: 50
+  max_image_size: 4096
+  ocr_confidence_min: 0.3
+  target_readability_coverage: 0.4
+  optimal_edge_density: 0.10
+  optimal_whitespace: 0.12
+
+scoring:
+  target_subscore: 75.0
+  max_plausible_gain_per_rule: 25.0
+  suggestion_limit: 5
+  confidence_base: 0.85
+  confidence_no_concept_penalty: 0.15
+  confidence_low_res_penalty: 0.10
+  confidence_ocr_uncertain_penalty: 0.10
+
+comparison:
+  meaningful_threshold: 5.0
+  significant_threshold: 15.0
+  max_suggestions: 3

configs/scoring_weights.yaml

@@ -0,0 +1,131 @@
+presets:
+  social_media:
+    concept_match: 0.10
+    visual_focus: 0.20
+    readability: 0.05
+    complexity_balance: 0.15
+    communication_clarity: 0.10
+    neural_richness: 0.20
+    memorability_proxy: 0.15
+    improvement_potential: 0.05
+
+  educational:
+    concept_match: 0.20
+    visual_focus: 0.10
+    readability: 0.20
+    complexity_balance: 0.10
+    communication_clarity: 0.20
+    neural_richness: 0.05
+    memorability_proxy: 0.05
+    improvement_potential: 0.10
+
+  thumbnail:
+    concept_match: 0.15
+    visual_focus: 0.25
+    readability: 0.05
+    complexity_balance: 0.15
+    communication_clarity: 0.10
+    neural_richness: 0.15
+    memorability_proxy: 0.10
+    improvement_potential: 0.05
+
+  scientific_figure:
+    concept_match: 0.20
+    visual_focus: 0.10
+    readability: 0.15
+    complexity_balance: 0.10
+    communication_clarity: 0.20
+    neural_richness: 0.05
+    memorability_proxy: 0.10
+    improvement_potential: 0.10
+
+  infographic:
+    concept_match: 0.15
+    visual_focus: 0.10
+    readability: 0.25
+    complexity_balance: 0.15
+    communication_clarity: 0.20
+    neural_richness: 0.05
+    memorability_proxy: 0.05
+    improvement_potential: 0.05
+
+  presentation_slide:
+    concept_match: 0.15
+    visual_focus: 0.10
+    readability: 0.25
+    complexity_balance: 0.15
+    communication_clarity: 0.20
+    neural_richness: 0.05
+    memorability_proxy: 0.05
+    improvement_potential: 0.05
+
+  marketing:
+    concept_match: 0.10
+    visual_focus: 0.20
+    readability: 0.10
+    complexity_balance: 0.10
+    communication_clarity: 0.15
+    neural_richness: 0.15
+    memorability_proxy: 0.15
+    improvement_potential: 0.05
+
+  default:
+    concept_match: 0.12
+    visual_focus: 0.15
+    readability: 0.12
+    complexity_balance: 0.12
+    communication_clarity: 0.15
+    neural_richness: 0.12
+    memorability_proxy: 0.12
+    improvement_potential: 0.10
+
+normalization:
+  clip_cosine:
+    min_val: 0.10
+    max_val: 0.45
+
+  edge_density:
+    optimal: 0.10
+    sigma: 0.06
+    min_val: 0.0
+    max_val: 0.25
+
+  color_entropy:
+    optimal: 4.5
+    sigma: 1.0
+    min_val: 0.0
+    max_val: 5.55
+
+  contrast:
+    min_val: 0.0
+    max_val: 1.0
+
+  whitespace:
+    optimal: 0.12
+    sigma: 0.08
+    min_val: 0.0
+    max_val: 0.40
+
+  sharpness:
+    min_val: 0.0
+    max_val: 2.0
+
+  peak_saliency:
+    min_val: 0.0
+    max_val: 1.0
+
+  saliency_entropy:
+    min_val: 0.0
+    max_val: 1.0
+
+  ocr_confidence:
+    min_val: 0.0
+    max_val: 1.0
+
+  nima_aesthetic:
+    min_val: 0.0
+    max_val: 1.0
+
+  clip_norm:
+    min_val: 10.0
+    max_val: 35.0

configs/suggestion_rules.yaml

@@ -0,0 +1,129 @@
+rules:
+  - sub_score: visual_focus
+    max_score: 50
+    trigger_feature: peak_saliency
+    trigger_condition: lt
+    trigger_value: 0.5
+    message: "Add a dominant focal element (larger main object, brighter color on subject, or isolate the subject from background)."
+    max_gain: 20
+
+  - sub_score: visual_focus
+    max_score: 50
+    trigger_feature: center_saliency
+    trigger_condition: lt
+    trigger_value: 0.3
+    message: "Move the main subject closer to the center or a rule-of-thirds intersection to establish a clear visual anchor."
+    max_gain: 15
+
+  - sub_score: visual_focus
+    max_score: 50
+    trigger_feature: top20_fraction
+    trigger_condition: gt
+    trigger_value: 0.4
+    message: "Too many competing focal areas — reduce background detail, blur non-essential zones, or remove decorative clutter."
+    max_gain: 18
+
+  - sub_score: readability
+    max_score: 50
+    trigger_feature: ocr_confidence
+    trigger_condition: lt
+    trigger_value: 0.6
+    message: "Increase text contrast: use darker text on lighter backgrounds (or vice versa). Ensure font size is at least 2% of image height."
+    max_gain: 20
+
+  - sub_score: readability
+    max_score: 50
+    trigger_feature: text_coverage
+    trigger_condition: gt
+    trigger_value: 0.4
+    message: "Reduce text density — move details to a caption or legend below the image. Use bullet points instead of paragraphs."
+    max_gain: 15
+
+  - sub_score: readability
+    max_score: 50
+    trigger_feature: word_count
+    trigger_condition: gt
+    trigger_value: 30
+    message: "Shorten labels to 2–3 words each; move long descriptions outside the image. Use abbreviations where appropriate."
+    max_gain: 12
+
+  - sub_score: complexity_balance
+    max_score: 50
+    trigger_feature: edge_density
+    trigger_condition: gt
+    trigger_value: 0.15
+    message: "Simplify: remove decorative borders, reduce line detail, and increase spacing between visual elements."
+    max_gain: 18
+
+  - sub_score: complexity_balance
+    max_score: 50
+    trigger_feature: edge_density
+    trigger_condition: lt
+    trigger_value: 0.03
+    message: "Add structural elements: borders, dividers, icons, or visual markers to guide the eye and provide visual structure."
+    max_gain: 15
+
+  - sub_score: complexity_balance
+    max_score: 50
+    trigger_feature: color_entropy
+    trigger_condition: gt
+    trigger_value: 5.0
+    message: "Reduce color palette to 3–5 main colors; use a consistent color scheme. Use shades of the same hue for related elements."
+    max_gain: 12
+
+  - sub_score: communication_clarity
+    max_score: 50
+    trigger_feature: whitespace_ratio
+    trigger_condition: lt
+    trigger_value: 0.05
+    message: "Increase padding and margins — add whitespace around key elements. White space is not wasted space."
+    max_gain: 15
+
+  - sub_score: communication_clarity
+    max_score: 50
+    trigger_feature: contrast
+    trigger_condition: lt
+    trigger_value: 0.3
+    message: "Increase overall contrast — the image appears flat/washed out. Darken darks and lighten lights."
+    max_gain: 18
+
+  - sub_score: communication_clarity
+    max_score: 50
+    trigger_feature: symmetry_lr
+    trigger_condition: lt
+    trigger_value: 0.7
+    message: "Balance the composition — distribute visual weight more evenly left-to-right to avoid a lopsided appearance."
+    max_gain: 10
+
+  - sub_score: concept_match
+    max_score: 50
+    trigger_feature: concept_cosine
+    trigger_condition: lt
+    trigger_value: 0.2
+    message: "The image doesn't clearly convey the intended concept — add concept-specific visual elements, icons, or labels that reinforce the topic."
+    max_gain: 25
+
+  - sub_score: neural_richness
+    max_score: 50
+    trigger_feature: clip_norm
+    trigger_condition: lt
+    trigger_value: 15
+    message: "Add visual variety: mix textures, depths, or scene complexity to enrich the visual signal. Avoid overly uniform or flat backgrounds."
+    max_gain: 12
+
+  - sub_score: memorability_proxy
+    max_score: 50
+    trigger_feature: nima_aesthetic_proxy
+    trigger_condition: lt
+    trigger_value: 0.4
+    message: "Improve visual appeal: better lighting, more saturated key colors, or a more dynamic and unexpected composition."
+    max_gain: 15
+
+fallback_messages:
+  visual_focus: "Improve the focal point by making the main subject larger, more colorful, or more isolated."
+  readability: "Review all text: increase contrast and font size, shorten labels, and declutter the text areas."
+  complexity_balance: "Reduce or add visual elements to find a balance — neither empty nor overcrowded."
+  communication_clarity: "Improve the visual hierarchy: use spacing, alignment, and contrast to guide the viewer's eye."
+  concept_match: "Strengthen the connection to the topic — add icons, labels, or imagery that directly illustrate the concept."
+  neural_richness: "Increase visual depth and variety through texture, lighting, or compositional complexity."
+  memorability_proxy: "Add an unusual or striking element — a bold color, unexpected angle, or strong visual metaphor."

features/heuristics.py

@@ -0,0 +1,73 @@
+"""Heuristic image feature extraction using OpenCV/numpy/scipy."""
+
+import cv2
+import numpy as np
+from PIL import Image
+from scipy.stats import entropy as scipy_entropy
+from typing import Dict
+
+
+def compute_heuristic_features(img: Image.Image) -> Dict[str, float]:
+    """
+    Compute 9+ heuristic features from a PIL Image using OpenCV.
+    
+    Returns dict with keys:
+        edge_density, contrast, whitespace_ratio, near_white_ratio,
+        color_entropy, saturation_entropy, symmetry_lr, symmetry_tb,
+        sharpness, center_weight
+    """
+    img_rgb = img.convert("RGB")
+    arr = np.array(img_rgb)
+    gray = cv2.cvtColor(arr, cv2.COLOR_RGB2GRAY)
+    H, W = gray.shape
+
+    features = {}
+
+    # 1. Edge density via Canny
+    edges = cv2.Canny(gray, 100, 200)
+    features["edge_density"] = float(edges.sum()) / (255 * H * W + 1e-8)
+
+    # 2. Contrast (std of luminance / max possible)
+    features["contrast"] = float(gray.std()) / 127.5
+
+    # 3. Whitespace ratio (near-white pixels)
+    features["whitespace_ratio"] = float((gray > 240).sum()) / (H * W + 1e-8)
+    features["near_white_ratio"] = float((gray > 200).sum()) / (H * W + 1e-8)
+
+    # 4. Color entropy (average per-channel)
+    entropies = []
+    for c in range(3):
+        hist, _ = np.histogram(arr[:, :, c], bins=256, range=(0, 256))
+        entropies.append(float(scipy_entropy(hist + 1)))
+    features["color_entropy"] = float(np.mean(entropies))
+
+    # 5. Saturation entropy (from HSV)
+    hsv = cv2.cvtColor(arr, cv2.COLOR_RGB2HSV)
+    sat_hist, _ = np.histogram(hsv[:, :, 1].ravel(), bins=256, range=(0, 256))
+    features["saturation_entropy"] = float(scipy_entropy(sat_hist + 1))
+
+    # 6. Symmetry (left-right)
+    flipped_lr = np.fliplr(gray).astype(float)
+    gray_f = gray.astype(float)
+    denom_lr = np.sqrt((gray_f ** 2).sum() * (flipped_lr ** 2).sum()) + 1e-8
+    features["symmetry_lr"] = float((gray_f * flipped_lr).sum() / denom_lr)
+
+    # 7. Symmetry (top-bottom)
+    flipped_tb = np.flipud(gray).astype(float)
+    denom_tb = np.sqrt((gray_f ** 2).sum() * (flipped_tb ** 2).sum()) + 1e-8
+    features["symmetry_tb"] = float((gray_f * flipped_tb).sum() / denom_tb)
+
+    # 8. Sharpness (Laplacian variance, log-normalized)
+    lap_var = cv2.Laplacian(gray, cv2.CV_64F).var()
+    features["sharpness"] = float(np.log1p(lap_var) / 10.0)
+
+    # 9. Center weight (rule of thirds center vs overall)
+    h3, w3 = max(1, H // 3), max(1, W // 3)
+    if h3 * 2 <= H and w3 * 2 <= W:
+        thirds_zone = gray[h3:2*h3, w3:2*w3]
+        center_mean = float(thirds_zone.mean())
+    else:
+        center_mean = float(gray.mean())
+    features["center_weight"] = center_mean / (gray.mean() + 1e-8)
+
+    return features

features/neural_richness.py

@@ -0,0 +1,81 @@
+"""Neural richness proxy computation.
+
+Uses composite signals derived from CLIP features, saliency, and aesthetic scores
+as a proxy for predicted brain-response richness.
+
+In a production V2 deployment, this module could be swapped to use
+V-JEPA-2 features or a precomputed TRIBE scoring service.
+"""
+
+import numpy as np
+from typing import Dict
+
+
+def compute_neural_richness_proxy(
+    semantic_features: Dict[str, float],
+    saliency_features: Dict[str, float],
+    quality_features: Dict[str, float],
+    heuristic_features: Dict[str, float]
+) -> float:
+    """
+    Compute a neural richness proxy score from available features.
+    
+    This is a weighted composite of signals known to correlate with
+    human visual engagement and brain response breadth:
+    
+    - CLIP embedding complexity (rich visual representations)
+    - Saliency spatial spread (distributed attention engagement)
+    - Aesthetic signal (reward-circuit correlates)
+    - Color/feature diversity (visual cortex breadth)
+    
+    Args:
+        semantic_features: from features/semantic.py
+        saliency_features: from features/saliency.py
+        quality_features: from features/quality.py
+        heuristic_features: from features/heuristics.py
+    
+    Returns:
+        Float in [0, 100] representing predicted neural richness.
+    """
+    # CLIP complexity: normalized embedding norm
+    clip_norm = semantic_features.get("clip_image_norm", 0.0)
+    # Typical range observed: 15–35 for CLIP ViT-B/32 features
+    clip_complexity = _sigmoid_normalize(clip_norm, center=25.0, scale=8.0)
+    
+    # Saliency spread: entropy of saliency map (already normalized in saliency_features)
+    saliency_spread = saliency_features.get("saliency_entropy", 0.5)
+    
+    # Aesthetic signal: NIMA proxy
+    aesthetic = quality_features.get("nima_aesthetic_proxy", 0.5)
+    
+    # Feature diversity: color entropy (normalized by max possible ~5.55)
+    color_entropy = heuristic_features.get("color_entropy", 3.0)
+    feature_diversity = _sigmoid_normalize(color_entropy, center=4.5, scale=1.5)
+    
+    # Edge density (complexity proxy)
+    edge_density = heuristic_features.get("edge_density", 0.08)
+    complexity = _sigmoid_normalize(edge_density, center=0.10, scale=0.06)
+    
+    # Weighted combination
+    weights = {
+        "clip_complexity": 0.25,
+        "saliency_spread": 0.20,
+        "aesthetic": 0.20,
+        "feature_diversity": 0.15,
+        "complexity": 0.20,
+    }
+    
+    score = (
+        weights["clip_complexity"] * clip_complexity +
+        weights["saliency_spread"] * saliency_spread +
+        weights["aesthetic"] * aesthetic +
+        weights["feature_diversity"] * feature_diversity +
+        weights["complexity"] * complexity
+    )
+    
+    return float(np.clip(score * 100, 0, 100))
+
+
+def _sigmoid_normalize(x: float, center: float, scale: float) -> float:
+    """Map x to [0,1] using logistic sigmoid centered at `center` with width `scale`."""
+    return 1.0 / (1.0 + np.exp(-(x - center) / scale))

features/ocr.py

@@ -0,0 +1,88 @@
+"""OCR-based readability features. Fallback to heuristic when OCR unavailable."""
+
+import numpy as np
+from PIL import Image
+from typing import Dict
+
+
+def _compute_text_heuristic(img: Image.Image) -> Dict[str, float]:
+    """
+    Fallback heuristic: detect high-contrast regions as proxy for text presence.
+    Returns reasonable defaults when OCR is unavailable.
+    """
+    gray = np.array(img.convert("L")).astype(np.float32)
+    # Edge density is proxy for text
+    edges = np.abs(np.diff(gray, axis=1, append=gray[:, -1:])) + np.abs(np.diff(gray, axis=0, append=gray[-1:, :]))
+    text_proxy = float(edges.mean()) / (gray.max() + 1e-8)
+    
+    return {
+        "text_coverage": 0.0,
+        "avg_ocr_confidence": 0.0,
+        "word_count": 0,
+        "text_density": 0.0,
+        "avg_text_height_ratio": 0.0,
+        "has_text": False,
+        "text_proxy": text_proxy,
+    }
+
+
+def compute_ocr_features(img: Image.Image, ocr_results: list = None) -> Dict[str, float]:
+    """
+    Compute OCR-based readability features.
+    
+    Args:
+        img: PIL Image
+        ocr_results: List of (bbox, text, confidence) tuples from EasyOCR.
+                     If None, uses heuristic fallback.
+    
+    Returns dict with keys:
+        text_coverage, avg_ocr_confidence, word_count, text_density,
+        avg_text_height_ratio, has_text, text_proxy
+    """
+    if ocr_results is None:
+        return _compute_text_heuristic(img)
+    
+    total_area = img.width * img.height
+    
+    if not ocr_results:
+        return {
+            "text_coverage": 0.0,
+            "avg_ocr_confidence": 0.0,
+            "word_count": 0,
+            "text_density": 0.0,
+            "avg_text_height_ratio": 0.0,
+            "has_text": False,
+            "text_proxy": 0.0,
+        }
+    
+    text_area = 0.0
+    total_conf = 0.0
+    total_height = 0.0
+    
+    for result in ocr_results:
+        # result[0] is bbox: [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
+        # result[1] is text string
+        # result[2] is confidence
+        bbox = result[0]
+        conf = result[2]
+        
+        # Approximate area from bbox
+        xs = [p[0] for p in bbox]
+        ys = [p[1] for p in bbox]
+        area = (max(xs) - min(xs)) * (max(ys) - min(ys))
+        text_area += area
+        total_conf += conf
+        total_height += max(ys) - min(ys)
+    
+    num_detections = len(ocr_results)
+    avg_height = total_height / num_detections
+    
+    return {
+        "text_coverage": float(text_area / (total_area + 1e-8)),
+        "avg_ocr_confidence": float(total_conf / num_detections),
+        "word_count": num_detections,
+        "text_density": float(num_detections / (total_area / 10000 + 1e-8)),
+        "avg_text_height_ratio": float(avg_height / (img.height + 1e-8)),
+        "has_text": True,
+        "text_proxy": float(total_conf / num_detections),
+    }

features/quality.py

@@ -0,0 +1,107 @@
+"""Image quality and aesthetic features using lightweight proxies.
+Since pyiqa may not be available in all environments, we use PIL/NumPy heuristics
+that correlate with known quality dimensions."""
+
+import numpy as np
+from PIL import Image, ImageStat
+from typing import Dict
+
+
+def compute_quality_features(img: Image.Image) -> Dict[str, float]:
+    """
+    Compute image quality and aesthetic proxy features.
+    
+    These are lightweight heuristics. In production, swap with:
+    - pyiqa.create_metric('topiq_nr')
+    - pyiqa.create_metric('nima')
+    - pyiqa.create_metric('clipiqa+')
+    
+    Returns dict with keys:
+        topiq_nr_proxy, nima_aesthetic_proxy, clipiqa_proxy,
+        laion_aesthetic_proxy, sharpness, colorfulness
+    """
+    arr = np.array(img.convert("RGB")).astype(np.float32)
+    gray = arr.mean(axis=2)
+    H, W = gray.shape
+    
+    features = {}
+    
+    # --- TOP-IQ NR proxy: combined sharpness + contrast + noise ---
+    # Sharpness: Laplacian variance
+    lap = cv2.Laplacian(gray.astype(np.uint8), cv2.CV_64F).var() if 'cv2' in globals() else 0.0
+    if lap == 0.0:
+        import cv2
+        lap = cv2.Laplacian(gray.astype(np.uint8), cv2.CV_64F).var()
+    
+    # Contrast: Michelson-ish measure
+    contrast_proxy = (gray.max() - gray.min()) / (gray.max() + gray.min() + 1e-8)
+    # Noise: estimate via local variance
+    local_var = np.var(gray[::4, ::4])
+    noise_proxy = 1.0 - np.exp(-local_var / 1000.0)  # higher var = less noise bias
+    
+    # Composite quality proxy: sharpness * contrast * (1 - noise_penalty)
+    sharp_norm = np.log1p(lap) / 10.0
+    features["topiq_nr_proxy"] = float(np.clip(sharp_norm * contrast_proxy * noise_proxy, 0, 1))
+    
+    # --- NIMA aesthetic proxy: composition + color + exposure ---
+    # Colorfulness (Hasler & Süsstrunk approximation)
+    rg = np.abs(arr[:, :, 0] - arr[:, :, 1])
+    yb = np.abs(0.5 * (arr[:, :, 0] + arr[:, :, 1]) - arr[:, :, 2])
+    colorfulness = float(np.sqrt(rg.std()**2 + yb.std()**2) + 0.3 * np.sqrt(rg.mean()**2 + yb.mean()**2))
+    color_score = np.clip(colorfulness / 100.0, 0, 1)
+    
+    # Exposure balance: histogram centering
+    hist, _ = np.histogram(gray.ravel(), bins=256, range=(0, 256))
+    hist_norm = hist / (hist.sum() + 1e-8)
+    mean_idx = np.sum(np.arange(256) * hist_norm)
+    exposure_score = 1.0 - abs(mean_idx - 128.0) / 128.0
+    
+    # Composition: rule of thirds center
+    h3, w3 = max(1, H // 3), max(1, W // 3)
+    if h3 * 2 <= H and w3 * 2 <= W:
+        center_brightness = gray[h3:2*h3, w3:2*w3].mean() / 255.0
+    else:
+        center_brightness = gray.mean() / 255.0
+    
+    # Weighted aesthetic proxy
+    features["nima_aesthetic_proxy"] = float(np.clip(
+        0.3 * sharp_norm + 0.3 * color_score + 0.2 * exposure_score + 0.2 * center_brightness,
+        0, 1
+    ))
+    
+    # --- CLIP-IQA+ proxy: image-text quality correlation ---
+    # Proxy: how "natural" / well-composed the image appears
+    # Use edge + color + exposure composite
+    features["clipiqa_proxy"] = features["nima_aesthetic_proxy"]  # reuse for now
+    
+    # --- LAION aesthetic proxy ---
+    features["laion_aesthetic_proxy"] = features["nima_aesthetic_proxy"]
+    
+    # Individual quality signals
+    features["sharpness"] = sharp_norm
+    features["colorfulness"] = color_score
+    features["exposure_balance"] = exposure_score
+    
+    return features
+
+
+def _try_pyiqa_features(img_path: str) -> Dict[str, float]:
+    """
+    Attempt to use pyiqa models if available.
+    Falls back silently.
+    
+    Returns empty dict if pyiqa is not available.
+    """
+    try:
+        import pyiqa
+        results = {}
+        for metric_name in ['brisque', 'niqe', 'clipiqa']:
+            try:
+                metric = pyiqa.create_metric(metric_name, device='cpu')
+                score = metric(img_path).item()
+                results[f"pyiqa_{metric_name}"] = score
+            except Exception:
+                pass
+        return results
+    except ImportError:
+        return {}

features/saliency.py

@@ -0,0 +1,62 @@
+"""Saliency map computation using pretrained MSI-Net (fallback to heuristic)."""
+
+import numpy as np
+from PIL import Image
+from scipy.stats import entropy as scipy_entropy
+from typing import Dict, Optional
+
+
+def _compute_heuristic_saliency(img: Image.Image) -> np.ndarray:
+    """
+    Fallback saliency using luminance contrast and color variance.
+    Returns a pseudo-saliency map in [0,1].
+    """
+    arr = np.array(img.convert("RGB")).astype(np.float32)
+    gray = arr.mean(axis=2)
+    # Compute local contrast via gradient magnitude
+    dx = np.abs(np.diff(gray, axis=1, append=gray[:, -1:]))
+    dy = np.abs(np.diff(gray, axis=0, append=gray[-1:, :]))
+    grad = np.sqrt(dx**2 + dy**2)
+    # Normalize
+    sal = grad / (grad.max() + 1e-8)
+    return sal.astype(np.float32)
+
+
+def compute_saliency_features(img: Image.Image, saliency_map: Optional[np.ndarray] = None) -> Dict[str, float]:
+    """
+    Compute saliency-based features from an image.
+    
+    If MSI-Net fails or is not loaded, falls back to heuristic.
+    """
+    if saliency_map is None:
+        saliency_map = _compute_heuristic_saliency(img)
+    
+    sal_flat = saliency_map.ravel()
+    sal_probs = sal_flat / (sal_flat.sum() + 1e-8)
+    
+    features = {}
+    
+    # 1. Peak saliency
+    features["peak_saliency"] = float(saliency_map.max())
+    
+    # 2. Mean saliency
+    features["mean_saliency"] = float(saliency_map.mean())
+    
+    # 3. Saliency entropy (spatial spread)
+    max_entropy = np.log(len(sal_flat) + 1e-8)
+    features["saliency_entropy"] = float(scipy_entropy(sal_probs + 1e-10)) / max_entropy
+    
+    # 4. Top-20% fraction
+    threshold = 0.8 * features["peak_saliency"]
+    features["top20_fraction"] = float((saliency_map > threshold).sum()) / (saliency_map.size + 1e-8)
+    
+    # 5. Center saliency (central third)
+    H, W = saliency_map.shape
+    h3, w3 = max(1, H // 3), max(1, W // 3)
+    center_zone = saliency_map[h3:2*h3, w3:2*w3]
+    features["center_saliency"] = float(center_zone.mean())
+    
+    # 6. Saliency uniformity (lower = more varied = more interesting)
+    features["saliency_uniformity"] = float(saliency_map.std() / (features["mean_saliency"] + 1e-8))
+    
+    return features

features/semantic.py

@@ -0,0 +1,124 @@
+"""Semantic / concept matching features using CLIP or SigLIP."""
+
+import numpy as np
+from PIL import Image
+import torch
+import torch.nn.functional as F
+from typing import Dict, Optional, Tuple
+
+
+class SemanticFeatureExtractor:
+    """Extracts concept-match features from image + user text using CLIP."""
+    
+    def __init__(self, model, processor, device="cpu"):
+        self.model = model
+        self.processor = processor
+        self.device = device
+    
+    @classmethod
+    def from_clip(cls, model_id="openai/clip-vit-base-patch32", device="cpu"):
+        """Load a standard CLIP model from transformers."""
+        try:
+            from transformers import CLIPModel, CLIPProcessor
+            model = CLIPModel.from_pretrained(model_id)
+            processor = CLIPProcessor.from_pretrained(model_id)
+            model = model.to(device)
+            if device == "cpu":
+                model = model.float()  # avoid half precision issues on CPU
+            return cls(model, processor, device)
+        except Exception as e:
+            print(f"[SemanticFeatureExtractor] CLIP load failed: {e}")
+            return cls(None, None, device)
+    
+    def _encode_image(self, img: Image.Image) -> Optional[torch.Tensor]:
+        """Encode image with CLIP via vision_model + visual_projection."""
+        if self.model is None or self.processor is None:
+            return None
+        try:
+            inputs = self.processor(images=img, return_tensors="pt").to(self.device)
+            with torch.no_grad():
+                vision_outputs = self.model.vision_model(pixel_values=inputs["pixel_values"])
+                image_embeds = vision_outputs.pooler_output
+                image_features = self.model.visual_projection(image_embeds)
+            return F.normalize(image_features, dim=-1)
+        except Exception as e:
+            print(f"[SemanticFeatureExtractor] Image encode failed: {e}")
+            return None
+    
+    def _encode_text(self, texts: list) -> Optional[torch.Tensor]:
+        """Encode text prompts with CLIP via text_model + text_projection."""
+        if self.model is None or self.processor is None:
+            return None
+        try:
+            inputs = self.processor(text=texts, return_tensors="pt", padding=True).to(self.device)
+            with torch.no_grad():
+                text_outputs = self.model.text_model(**inputs)
+                text_embeds = text_outputs.pooler_output
+                text_features = self.model.text_projection(text_embeds)
+            return F.normalize(text_features, dim=-1)
+        except Exception as e:
+            print(f"[SemanticFeatureExtractor] Text encode failed: {e}")
+            return None
+    
+    def compute(self, img: Image.Image, concept: str, audience: str, use_case: str) -> Dict[str, float]:
+        """
+        Compute concept-match features.
+        
+        Returns dict with keys:
+            concept_cosine, audience_cosine, usecase_cosine, composite_cosine,
+            clip_image_norm, clip_image_std
+        """
+        img_features = self._encode_image(img)
+        
+        if img_features is None:
+            # Fallback: heuristic based on image size and color variety
+            arr = np.array(img.convert("RGB"))
+            return {
+                "concept_cosine": 0.0,
+                "audience_cosine": 0.0,
+                "usecase_cosine": 0.0,
+                "composite_cosine": 0.0,
+                "clip_image_norm": 0.0,
+                "clip_image_std": 0.0,
+            }
+        
+        # Build prompts
+        prompts = [
+            concept or "an image",
+            f"{concept or 'an image'} for {audience}" if audience else concept or "an image",
+            f"{use_case}: {concept or 'an image'}" if use_case else concept or "an image",
+        ]
+        text_features = self._encode_text(prompts)
+        
+        if text_features is None:
+            return {
+                "concept_cosine": 0.0,
+                "audience_cosine": 0.0,
+                "usecase_cosine": 0.0,
+                "composite_cosine": 0.0,
+                "clip_image_norm": float(img_features.norm(dim=-1).item()),
+                "clip_image_std": float(img_features.std(dim=-1).item()),
+            }
+        
+        # Cosine similarities (already normalized)
+        sims = (img_features @ text_features.T).squeeze(0)
+        
+        return {
+            "concept_cosine": float(sims[0].item()),
+            "audience_cosine": float(sims[1].item()),
+            "usecase_cosine": float(sims[2].item()),
+            "composite_cosine": float(sims.mean().item()),
+            "clip_image_norm": float(img_features.norm(dim=-1).item()),
+            "clip_image_std": float(img_features.std(dim=-1).item()),
+        }
+
+
+def compute_semantic_features(img: Image.Image, concept: str, audience: str, use_case: str,
+                              extractor: Optional[SemanticFeatureExtractor] = None) -> Dict[str, float]:
+    """
+    Compute semantic/concept-match features.
+    If extractor not provided, creates one (slow on first call).
+    """
+    if extractor is None:
+        extractor = SemanticFeatureExtractor.from_clip(device="cpu")
+    return extractor.compute(img, concept, audience, use_case)

models/loader.py

@@ -0,0 +1,66 @@
+"""Model loading and caching utilities."""
+
+import os
+from typing import Optional, Any
+
+
+class ModelLoader:
+    """Singleton-like model loader that lazily loads and caches models."""
+    
+    def __init__(self, config: dict = None):
+        self.config = config or {}
+        self._cache = {}
+        self._device = self._get_device()
+    
+    def _get_device(self) -> str:
+        import torch
+        if torch.cuda.is_available():
+            return "cuda"
+        # Check for MPS (Apple Silicon)
+        if hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+            return "mps"
+        return "cpu"
+    
+    def get_clip_model(self):
+        """Load CLIP model and processor."""
+        if "clip" in self._cache:
+            return self._cache["clip"]
+        
+        model_id = self.config.get("models", {}).get("clip", {}).get("model_id", "openai/clip-vit-base-patch32")
+        
+        try:
+            import torch
+            from transformers import CLIPModel, CLIPProcessor
+            
+            print(f"[ModelLoader] Loading CLIP: {model_id}...")
+            model = CLIPModel.from_pretrained(model_id)
+            processor = CLIPProcessor.from_pretrained(model_id)
+            model = model.to(self._device)
+            if self._device == "cpu":
+                model = model.float()  # Use full precision on CPU
+            
+            self._cache["clip"] = (model, processor)
+            print(f"[ModelLoader] CLIP loaded on {self._device}")
+            return self._cache["clip"]
+        except Exception as e:
+            print(f"[ModelLoader] CLIP load FAILED: {e}")
+            self._cache["clip"] = None
+            return None
+    
+    def get_device(self) -> str:
+        return self._device
+    
+    def warmup(self):
+        """Preload critical models."""
+        self.get_clip_model()
+    
+    def clear(self):
+        """Clear model cache to free memory."""
+        import torch
+        import gc
+        for key in list(self._cache.keys()):
+            del self._cache[key]
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        self._cache.clear()

recommendations/engine.py

@@ -0,0 +1,196 @@
+"""Recommendation engine — turns score weaknesses into actionable suggestions."""
+
+import os
+import yaml
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class Suggestion:
+    priority: int
+    sub_score_target: str
+    message: str
+    projected_gain: float
+    trigger_feature: str = ""
+    trigger_value: float = 0.0
+
+
+class RecommendationEngine:
+    """Generates ranked improvement suggestions from sub-scores and raw features."""
+    
+    def __init__(self, rules_path: Optional[str] = None):
+        self.rules = self._load_rules(rules_path)
+        self.target_score = 75.0
+        self.max_suggestions = 5
+    
+    def _load_rules(self, rules_path: Optional[str]) -> List[Dict[str, Any]]:
+        """Load suggestion rules from YAML."""
+        if rules_path and os.path.exists(rules_path):
+            with open(rules_path, 'r') as f:
+                data = yaml.safe_load(f) or {}
+                return data.get("rules", [])
+        
+        # Try default paths
+        for path in ['configs/suggestion_rules.yaml', 'viral-images/configs/suggestion_rules.yaml']:
+            if os.path.exists(path):
+                with open(path, 'r') as f:
+                    data = yaml.safe_load(f) or {}
+                    return data.get("rules", [])
+        return []
+    
+    def generate(self, sub_scores: Dict[str, float],
+                 raw_features: Dict[str, Any],
+                 use_case: str = "default") -> List[Suggestion]:
+        """
+        Generate ranked improvement suggestions.
+        
+        Args:
+            sub_scores: 8 sub-scores [0-100]
+            raw_features: Raw extracted features
+            use_case: Current use case preset
+        
+        Returns:
+            List of Suggestion objects, ranked by priority.
+        """
+        suggestions = []
+        
+        # Sort sub-scores ascending to find weakest areas
+        weakest = sorted(sub_scores.items(), key=lambda x: x[1])
+        
+        # Try to match each weak sub-score with a specific rule
+        for sub_name, sub_value in weakest:
+            # Skip improvement_potential (meta-score)
+            if sub_name == "improvement_potential":
+                continue
+            
+            # Find matching rules for this sub-score
+            matching = self._find_matching_rules(sub_name, sub_value, raw_features)
+            
+            # Take best matching rule
+            for rule in matching[:2]:  # max 2 per sub-score
+                gain = min(rule.get("max_gain", 15.0), self.target_score - sub_value)
+                gain = max(0, gain)
+                
+                sugg = Suggestion(
+                    priority=0,  # assigned later
+                    sub_score_target=sub_name,
+                    message=rule.get("message", ""),
+                    projected_gain=gain,
+                    trigger_feature=rule.get("trigger_feature", ""),
+                    trigger_value=rule.get("trigger_value", 0.0)
+                )
+                suggestions.append(sugg)
+        
+        # Rank by: (gap to target) × (max_gain weight) = most impactful first
+        for sugg in suggestions:
+            current = sub_scores.get(sugg.sub_score_target, 50)
+            gap = max(0, self.target_score - current)
+            # Priority score = gap × projected_gain
+            sugg.priority = gap * sugg.projected_gain
+        
+        # Sort descending by priority, then take top N
+        suggestions.sort(key=lambda x: -x.priority)
+        suggestions = suggestions[:self.max_suggestions]
+        
+        # Renumber priorities 1..N
+        for i, sugg in enumerate(suggestions, 1):
+            sugg.priority = i
+        
+        return suggestions
+    
+    def _find_matching_rules(self, sub_score_name: str, sub_score_value: float,
+                              raw_features: Dict[str, Any]) -> List[Dict]:
+        """Find rules that match this sub-score's weakness."""
+        matches = []
+        
+        for rule in self.rules:
+            # Check sub-score match
+            if rule.get("sub_score") != sub_score_name:
+                continue
+            
+            # Check max_score threshold
+            if sub_score_value > rule.get("max_score", 100):
+                continue
+            
+            # Check trigger feature condition
+            trigger_feature = rule.get("trigger_feature", "")
+            trigger_value = rule.get("trigger_value", 0.0)
+            trigger_cond = rule.get("trigger_condition", "lt")
+            
+            # Look up trigger feature value in raw features
+            feat_key = None
+            # Try heuristic_, saliency_, ocr_, quality_, semantic_ prefixes
+            for prefix in ["heuristic_", "saliency_", "ocr_", "quality_", "semantic_"]:
+                candidate = f"{prefix}{trigger_feature}"
+                if candidate in raw_features:
+                    feat_key = candidate
+                    break
+            
+            if feat_key is None:
+                feat_key = trigger_feature  # try raw key
+            
+            feat_val = raw_features.get(feat_key)
+            if feat_val is None:
+                continue
+            
+            # Evaluate condition
+            matched = False
+            if trigger_cond == "lt" and feat_val < trigger_value:
+                matched = True
+            elif trigger_cond == "gt" and feat_val > trigger_value:
+                matched = True
+            elif trigger_cond == "eq" and abs(feat_val - trigger_value) < 0.01:
+                matched = True
+            
+            if matched:
+                matches.append(rule)
+        
+        return matches
+    
+    def estimate_improvement(self, sub_scores: Dict[str, float],
+                             suggestions: List[Suggestion],
+                             use_case: str) -> float:
+        """
+        Estimate overall score improvement if all suggestions are followed.
+        
+        Returns projected overall score.
+        """
+        if not suggestions:
+            return sub_scores.get("overall_score", 50.0)
+        
+        # Apply projected gains to each targeted sub-score
+        projected = dict(sub_scores)
+        
+        # Aggregate gains per sub-score (take max, not sum — overlapping suggestions)
+        gains_by_sub = {}
+        for sugg in suggestions:
+            gains_by_sub[sugg.sub_score_target] = max(
+                gains_by_sub.get(sugg.sub_score_target, 0),
+                sugg.projected_gain
+            )
+        
+        for sub_name, gain in gains_by_sub.items():
+            current = projected.get(sub_name, 0)
+            projected[sub_name] = min(100, current + gain)
+        
+        # Re-aggregate (same weights as scoring engine)
+        # For simplicity, approximate: mean of top 3 weakest improvements
+        improved_subs = [projected[s] for s in gains_by_sub.keys()]
+        if not improved_subs:
+            return sub_scores.get("overall_score", 50.0)
+        
+        # Rough estimate: apply gains proportionally to their weights
+        # This is approximate — in production, call ScoringEngine._aggregate()
+        current_overall = sum(sub_scores.values()) / len(sub_scores)
+        projected_overall = sum(projected.values()) / len(projected)
+        
+        return round(min(100, projected_overall), 1)
+
+
+def compute_improvement_potential(sub_scores: Dict[str, float]) -> float:
+    """Compute improvement potential as meta-score."""
+    target = 75.0
+    gaps = sorted([max(0, target - s) for s in sub_scores.values() if s != "improvement_potential"], reverse=True)
+    top3 = gaps[:3]
+    return round(sum(top3) / len(top3) if top3 else 0.0, 1)

scoring/engine.py

@@ -0,0 +1,282 @@
+"""Main scoring engine — orchestrates feature extraction, sub-score computation, and aggregation."""
+
+import os
+import time
+import yaml
+import numpy as np
+from pathlib import Path
+from typing import Dict, Any, Optional
+from dataclasses import dataclass, field
+from PIL import Image
+
+from .normalizers import ScoreNormalizer
+from features.heuristics import compute_heuristic_features
+from features.saliency import compute_saliency_features
+from features.ocr import compute_ocr_features
+from features.quality import compute_quality_features
+from features.semantic import compute_semantic_features, SemanticFeatureExtractor
+from features.neural_richness import compute_neural_richness_proxy
+from utils.preprocessing import preprocess_image, validate_image
+from models.loader import ModelLoader
+
+
+@dataclass
+class ScoreResponse:
+    overall_score: float = 0.0
+    sub_scores: Dict[str, float] = field(default_factory=dict)
+    confidence: float = 0.85
+    strengths: list = field(default_factory=list)
+    weaknesses: list = field(default_factory=list)
+    suggestions: list = field(default_factory=list)
+    projected_improvement: float = 0.0
+    raw_features: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class ScoringEngine:
+    """Orchestrates the full image scoring pipeline."""
+    
+    def __init__(self, model_loader: Optional[ModelLoader] = None,
+                 config_path: Optional[str] = None):
+        self.model_loader = model_loader or ModelLoader()
+        self.config = self._load_config(config_path)
+        self.normalizer = ScoreNormalizer(self.config)
+        self.extractor = None  # Lazy init
+        self.warmup_complete = False
+    
+    def _load_config(self, config_path: Optional[str]) -> dict:
+        """Load scoring config from YAML."""
+        if config_path and os.path.exists(config_path):
+            with open(config_path, 'r') as f:
+                return yaml.safe_load(f) or {}
+        # Try default paths
+        for path in ['configs/scoring_weights.yaml', 'viral-images/configs/scoring_weights.yaml']:
+            if os.path.exists(path):
+                with open(path, 'r') as f:
+                    return yaml.safe_load(f) or {}
+        return {}
+    
+    def warmup(self):
+        """Pre-load models for faster first inference."""
+        if self.warmup_complete:
+            return
+        self.model_loader.warmup()
+        self.warmup_complete = True
+        
+        # Initialize semantic extractor with CLIP
+        clip_model = self.model_loader.get_clip_model()
+        if clip_model is not None:
+            model, processor = clip_model
+            self.extractor = SemanticFeatureExtractor(model, processor, self.model_loader.get_device())
+    
+    def score(self, image_input, concept: str = "", audience: str = "General",
+              use_case: str = "social_media") -> ScoreResponse:
+        """
+        Score an image across 8 dimensions.
+        
+        Args:
+            image_input: PIL Image, numpy array, or file path
+            concept: User-declared concept/theme
+            audience: Target audience
+            use_case: Use case preset key
+        
+        Returns:
+            ScoreResponse with all scores, explanations, and suggestions.
+        """
+        t0 = time.time()
+        response = ScoreResponse()
+        
+        # --- 1. Preprocess ---
+        try:
+            img = preprocess_image(image_input)
+        except Exception as e:
+            response.metadata["error"] = f"Preprocessing failed: {e}"
+            return response
+        
+        val_error = validate_image(img)
+        if val_error:
+            response.metadata["error"] = val_error
+            return response
+        
+        # --- 2. Initialize extractor if needed ---
+        if self.extractor is None:
+            clip_model = self.model_loader.get_clip_model()
+            if clip_model is not None:
+                model, processor = clip_model
+                self.extractor = SemanticFeatureExtractor(model, processor, self.model_loader.get_device())
+        
+        # --- 3. Extract features ---
+        raw_features = {}
+        
+        # Heuristic features (always available)
+        heuristic_feats = compute_heuristic_features(img)
+        raw_features.update({f"heuristic_{k}": v for k, v in heuristic_feats.items()})
+        
+        # Saliency features (with heuristic fallback)
+        saliency_feats = compute_saliency_features(img)
+        raw_features.update({f"saliency_{k}": v for k, v in saliency_feats.items()})
+        
+        # OCR features (with heuristic fallback)
+        ocr_feats = compute_ocr_features(img)
+        raw_features.update({f"ocr_{k}": v for k, v in ocr_feats.items()})
+        
+        # Quality features
+        quality_feats = compute_quality_features(img)
+        raw_features.update({f"quality_{k}": v for k, v in quality_feats.items()})
+        
+        # Semantic features (CLIP-based)
+        semantic_feats = compute_semantic_features(
+            img, concept, audience, use_case, self.extractor
+        )
+        raw_features.update({f"semantic_{k}": v for k, v in semantic_feats.items()})
+        
+        # --- 4. Compute sub-scores ---
+        sub_scores = {}
+        
+        # Concept Match
+        sub_scores["concept_match"] = self.normalizer.normalize_concept_match(
+            semantic_feats.get("composite_cosine", 0.0)
+        )
+        
+        # Visual Focus
+        sub_scores["visual_focus"] = self.normalizer.normalize_visual_focus(
+            saliency_feats.get("peak_saliency", 0.3),
+            saliency_feats.get("center_saliency", 0.2),
+            saliency_feats.get("top20_fraction", 0.2)
+        )
+        
+        # Readability
+        sub_scores["readability"] = self.normalizer.normalize_readability(
+            ocr_feats.get("avg_ocr_confidence", 0.0),
+            ocr_feats.get("text_coverage", 0.0),
+            ocr_feats.get("word_count", 0),
+            ocr_feats.get("has_text", False)
+        )
+        
+        # Complexity Balance
+        sub_scores["complexity_balance"] = self.normalizer.normalize_complexity_balance(
+            heuristic_feats.get("edge_density", 0.08),
+            heuristic_feats.get("color_entropy", 3.0)
+        )
+        
+        # Communication Clarity
+        sub_scores["communication_clarity"] = self.normalizer.normalize_communication_clarity(
+            heuristic_feats.get("whitespace_ratio", 0.05),
+            heuristic_feats.get("contrast", 0.4),
+            heuristic_feats.get("symmetry_lr", 0.5),
+            heuristic_feats.get("sharpness", 0.3)
+        )
+        
+        # Neural Richness (proxy)
+        neural_proxy = compute_neural_richness_proxy(
+            semantic_feats, saliency_feats, quality_feats, heuristic_feats
+        )
+        sub_scores["neural_richness"] = self.normalizer.normalize_neural_richness(neural_proxy)
+        
+        # Memorability Proxy
+        sub_scores["memorability_proxy"] = self.normalizer.normalize_memorability_proxy(
+            quality_feats.get("nima_aesthetic_proxy", 0.5),
+            quality_feats.get("colorfulness", 0.5),
+            quality_feats.get("sharpness", 0.3)
+        )
+        
+        # Improvement Potential
+        sub_scores["improvement_potential"] = self.normalizer.normalize_improvement_potential(
+            sub_scores
+        )
+        
+        # --- 5. Compute confidence ---
+        confidence = self._compute_confidence(
+            concept, img.size[0], img.size[1],
+            ocr_feats.get("has_text", False),
+            self.extractor is not None
+        )
+        
+        # --- 6. Aggregate ---
+        overall = self._aggregate(sub_scores, use_case)
+        
+        # --- 7. Strengths and weaknesses ---
+        strengths, weaknesses = self._identify_strengths_weaknesses(sub_scores)
+        
+        # --- 8. Build response ---
+        response.overall_score = round(overall, 1)
+        response.sub_scores = {k: round(v, 1) for k, v in sub_scores.items()}
+        response.confidence = round(confidence, 2)
+        response.strengths = strengths
+        response.weaknesses = weaknesses
+        response.raw_features = {k: round(v, 4) if isinstance(v, float) else v 
+                                 for k, v in raw_features.items()}
+        response.metadata = {
+            "processing_time_ms": round((time.time() - t0) * 1000, 1),
+            "models_used": ["clip-vit-base-patch32", "heuristic-fallback", 
+                          "saliency-heuristic", "ocr-heuristic"],
+            "neural_richness_mode": "proxy",
+            "api_version": "1.0.0",
+            "image_size": f"{img.size[0]}x{img.size[1]}",
+        }
+        
+        return response
+    
+    def _compute_confidence(self, concept: str, width: int, height: int,
+                           has_text: bool, has_clip: bool) -> float:
+        """Compute confidence in the scoring."""
+        base = self.config.get("scoring", {}).get("confidence_base", 0.85)
+        
+        if not concept or len(concept.strip()) < 3:
+            base -= self.config.get("scoring", {}).get("confidence_no_concept_penalty", 0.15)
+        
+        if width < 200 or height < 200:
+            base -= self.config.get("scoring", {}).get("confidence_low_res_penalty", 0.10)
+        
+        if not has_text and concept and "text" in concept.lower():
+            base -= self.config.get("scoring", {}).get("confidence_ocr_uncertain_penalty", 0.10)
+        
+        if not has_clip:
+            base -= 0.25  # major signal missing
+        
+        return max(0.4, base)
+    
+    def _aggregate(self, sub_scores: Dict[str, float], use_case: str) -> float:
+        """Weighted aggregation of sub-scores."""
+        presets = self.config.get("presets", {})
+        weights = presets.get(use_case, presets.get("default", {}))
+        
+        if not weights:
+            # Uniform weights fallback
+            weights = {k: 1.0 / len(sub_scores) for k in sub_scores}
+        
+        total = sum(weights.get(k, 0.0) * v for k, v in sub_scores.items())
+        weight_sum = sum(weights.get(k, 0.0) for k in sub_scores)
+        
+        if weight_sum > 0:
+            return total / weight_sum
+        return np.mean(list(sub_scores.values())) if sub_scores else 0.0
+    
+    def _identify_strengths_weaknesses(self, sub_scores: Dict[str, float],
+                                        threshold_high: float = 70.0,
+                                        threshold_low: float = 50.0):
+        """Identify top strengths and weaknesses from sub-scores."""
+        readable_names = {
+            "concept_match": "Concept Match",
+            "visual_focus": "Visual Focus",
+            "readability": "Readability",
+            "complexity_balance": "Complexity Balance",
+            "communication_clarity": "Communication Clarity",
+            "neural_richness": "Predicted Neural Richness",
+            "memorability_proxy": "Memorability",
+            "improvement_potential": "Improvement Potential",
+        }
+        
+        strengths = []
+        weaknesses = []
+        
+        sorted_scores = sorted(sub_scores.items(), key=lambda x: -x[1])
+        
+        for name, score in sorted_scores:
+            readable = readable_names.get(name, name)
+            if score >= threshold_high:
+                strengths.append(f"Strong {readable.lower()}: scored {score:.0f}/100")
+            elif score <= threshold_low:
+                weaknesses.append(f"Weak {readable.lower()}: scored only {score:.0f}/100")
+        
+        return strengths[:5], weaknesses[:5]

scoring/normalizers.py

@@ -0,0 +1,125 @@
+"""Sub-score normalization utilities."""
+
+import numpy as np
+from typing import Dict, Any, Optional
+
+
+def _clamp(x: float, lo: float = 0, hi: float = 100) -> float:
+    return float(np.clip(x, lo, hi))
+
+
+def _rescale(x: float, min_val: float, max_val: float) -> float:
+    """Rescale x from [min_val, max_val] to [0, 100]."""
+    if max_val == min_val:
+        return 50.0
+    return _clamp(100 * (x - min_val) / (max_val - min_val))
+
+
+def _gaussian_score(x: float, optimal: float, sigma: float) -> float:
+    """Score peaks at `optimal`, decreases with Gaussian falloff."""
+    return 100 * np.exp(-((x - optimal) ** 2) / (2 * sigma ** 2))
+
+
+def _sigmoid_normalize(x: float, center: float = 0.5, scale: float = 0.1) -> float:
+    """Map x to [0,1] with logistic sigmoid."""
+    return 1.0 / (1.0 + np.exp(-(x - center) / scale))
+
+
+class ScoreNormalizer:
+    """Normalizes raw feature values to 0–100 sub-scores."""
+    
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        self.config = config or {}
+    
+    def normalize_concept_match(self, raw_cosine: float) -> float:
+        """CLIP cosine similarity → [0, 100]."""
+        norm_cfg = self.config.get("normalization", {}).get("clip_cosine", {})
+        min_val = norm_cfg.get("min_val", 0.10)
+        max_val = norm_cfg.get("max_val", 0.45)
+        return _rescale(raw_cosine, min_val, max_val)
+    
+    def normalize_visual_focus(self, peak_saliency: float, center_saliency: float,
+                                top20_fraction: float) -> float:
+        """Saliency metrics → visual focus [0, 100]."""
+        # Peak should be strong
+        peak_score = peak_saliency * 100
+        # Center saliency should be above average
+        center_score = min(center_saliency / (peak_saliency + 0.01) * 100, 100)
+        # Top20 fraction: ideal is 0.15-0.25 (not too diffuse, not too concentrated)
+        spread_score = 100 * np.exp(-((top20_fraction - 0.20) ** 2) / (2 * 0.08 ** 2))
+        return _clamp(0.4 * peak_score + 0.3 * center_score + 0.3 * spread_score)
+    
+    def normalize_readability(self, ocr_confidence: float, text_coverage: float,
+                            word_count: int, has_text: bool) -> float:
+        """OCR metrics → readability [0, 100]."""
+        if not has_text:
+            return 70.0  # neutral: no text is not a flaw
+        
+        conf_score = ocr_confidence * 100
+        # Coverage penalty: prefer 5-20%
+        coverage_score = 100 * np.exp(-((text_coverage - 0.12) ** 2) / (2 * 0.08 ** 2))
+        # Word count: moderate is good
+        wc_score = 100 * np.exp(-((word_count - 8) ** 2) / (2 * 15 ** 2))
+        
+        return _clamp(0.5 * conf_score + 0.3 * coverage_score + 0.2 * wc_score)
+    
+    def normalize_complexity_balance(self, edge_density: float,
+                                     color_entropy: float) -> float:
+        """Edge density + color entropy → complexity balance [0, 100]."""
+        norm_cfg = self.config.get("normalization", {})
+        
+        edge_cfg = norm_cfg.get("edge_density", {})
+        edge_score = _gaussian_score(
+            edge_density,
+            edge_cfg.get("optimal", 0.10),
+            edge_cfg.get("sigma", 0.06)
+        )
+        
+        color_cfg = norm_cfg.get("color_entropy", {})
+        color_score = _gaussian_score(
+            color_entropy,
+            color_cfg.get("optimal", 4.5),
+            color_cfg.get("sigma", 1.0)
+        )
+        
+        return _clamp(0.6 * edge_score + 0.4 * color_score)
+    
+    def normalize_communication_clarity(self, whitespace: float, contrast: float,
+                                        symmetry_lr: float, sharpness: float) -> float:
+        """Whitespace, contrast, symmetry, sharpness → clarity [0, 100]."""
+        norm_cfg = self.config.get("normalization", {})
+        ws_cfg = norm_cfg.get("whitespace", {})
+        ws_score = _gaussian_score(
+            whitespace,
+            ws_cfg.get("optimal", 0.12),
+            ws_cfg.get("sigma", 0.08)
+        )
+        
+        contrast_score = contrast * 100
+        sym_score = symmetry_lr * 100  # already in [0,1]
+        sharp_score = min(sharpness / 0.5 * 100, 100)  # sharpness normalized
+        
+        return _clamp(0.3 * ws_score + 0.3 * contrast_score + 0.2 * sym_score + 0.2 * sharp_score)
+    
+    def normalize_neural_richness(self, proxy_score: float) -> float:
+        """Neural richness proxy [0,100] is already normalized."""
+        return _clamp(proxy_score)
+    
+    def normalize_memorability_proxy(self, aesthetic_proxy: float,
+                                     colorfulness: float,
+                                     sharpness: float) -> float:
+        """Aesthetic + colorfulness + sharpness → memorability [0, 100]."""
+        aesthetic_score = aesthetic_proxy * 100
+        color_score = colorfulness * 100
+        sharp_score = min(sharpness / 0.5 * 100, 100)
+        return _clamp(0.5 * aesthetic_score + 0.3 * color_score + 0.2 * sharp_score)
+    
+    def normalize_improvement_potential(self, sub_scores: Dict[str, float],
+                                        target: float = 75.0) -> float:
+        """Inverse of how far weakest scores are from target."""
+        gaps = [max(0, target - s) for s in sub_scores.values()]
+        # Top 3 gaps weighted
+        gaps_sorted = sorted(gaps, reverse=True)
+        top3 = gaps_sorted[:3]
+        avg_gap = np.mean(top3) if top3 else 0
+        return _clamp(avg_gap)  # already 0-100

utils/formatting.py

@@ -0,0 +1,126 @@
+"""Output formatting utilities for Gradio."""
+
+import pandas as pd
+from typing import Dict, List, Any
+
+
+def format_overall_score(score: float) -> str:
+    """Format overall score as HTML progress bar."""
+    score_int = int(round(score))
+    color = "#2ecc71" if score_int >= 70 else "#f39c12" if score_int >= 50 else "#e74c3c"
+    return f"""
+    <div style="padding:16px; background:#f8f9fa; border-radius:8px; text-align:center;">
+        <div style="font-size:14px; color:#666; margin-bottom:8px;">Overall Score</div>
+        <div style="font-size:48px; font-weight:bold; color:{color};">{score_int}<span style="font-size:20px; color:#999;">/100</span></div>
+        <div style="margin-top:8px; background:#ddd; border-radius:4px; height:20px; width:100%;">
+            <div style="background:{color}; width:{score_int}%; height:20px; border-radius:4px; transition:width 0.5s;"></div>
+        </div>
+    </div>
+    """
+
+
+def format_sub_scores(sub_scores: Dict[str, float]) -> pd.DataFrame:
+    """Format sub-scores as a DataFrame for gr.BarPlot."""
+    df = pd.DataFrame({
+        "Sub-Score": list(sub_scores.keys()),
+        "Score": list(sub_scores.values())
+    })
+    return df
+
+
+def format_strengths(strengths: List[str]) -> str:
+    """Format strengths as HTML list."""
+    if not strengths:
+        return "No notable strengths detected."
+    items = "\n".join(f"<li>✅ {s}</li>" for s in strengths)
+    return f"<ul style='margin:0; padding-left:20px;'>{items}</ul>"
+
+
+def format_weaknesses(weaknesses: List[str]) -> str:
+    """Format weaknesses as HTML list."""
+    if not weaknesses:
+        return "No notable weaknesses detected."
+    items = "\n".join(f"<li>⚠️ {w}</li>" for w in weaknesses)
+    return f"<ul style='margin:0; padding-left:20px;'>{items}</ul>"
+
+
+def format_suggestions(suggestions: List[Dict[str, Any]]) -> str:
+    """Format suggestions as numbered HTML list."""
+    if not suggestions:
+        return "No specific suggestions — your image scores well across all dimensions."
+    items = []
+    for i, s in enumerate(suggestions[:5], 1):
+        priority_emoji = {1: "🔴", 2: "🟡", 3: "🟡"}.get(i, "🟢")
+        items.append(
+            f"<div style='margin-bottom:12px; padding:10px; background:#f0f4ff; border-radius:6px; border-left:4px solid #4a86e8;'>">
+            f"<b>{priority_emoji} Priority {i}</b> — {s['sub_score_target']}<br/>"
+            f"<div style='margin-top:6px; color:#333;'>{s['message']}</div>"
+            f"<div style='margin-top:4px; font-size:12px; color:#888;'>📈 Projected gain: +{s['projected_gain']:.0f} points</div>"
+            f"</div>"
+        )
+    return "\n".join(items)
+
+
+def format_projected_improvement(current: float, projected: float) -> str:
+    """Format projected improvement as HTML."""
+    delta = projected - current
+    if delta <= 0:
+        return "<div style='padding:12px; background:#e8f5e9; border-radius:6px;'>🎉 This image is already well-optimized!</div>"
+    return f"""
+    <div style="padding:12px; background:#fff3e0; border-radius:6px;">
+        <b>💡 Projected Improvement</b><br/>
+        Current: <b>{current:.0f}</b>/100 &rarr; After suggestions: <b>{projected:.0f}</b>/100
+        <span style="color:#e65100;"> (+{delta:.0f} points)</span>
+    </div>
+    """
+
+
+def format_comparison(original: Dict[str, Any], revised: Dict[str, Any], 
+                      improvements: List, regressions: List, 
+                      next_steps: List[Dict[str, Any]]) -> str:
+    """Format comparison results as HTML."""
+    orig_score = original.get("overall_score", 0)
+    rev_score = revised.get("overall_score", 0)
+    delta = rev_score - orig_score
+    
+    result = f"""
+    <div style="padding:16px; background:#f8f9fa; border-radius:8px;">
+        <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:16px;">
+            <div style="text-align:center;">
+                <div style="font-size:12px; color:#666;">Original</div>
+                <div style="font-size:32px; font-weight:bold; color:#e74c3c;">{orig_score:.0f}</div>
+            </div>
+            <div style="font-size:24px;">&rarr;</div>
+            <div style="text-align:center;">
+                <div style="font-size:12px; color:#666;">Revised</div>
+                <div style="font-size:32px; font-weight:bold; color:#2ecc71;">{rev_score:.0f}</div>
+            </div>
+        </div>
+    """
+    
+    if delta > 0:
+        result += f"<div style='text-align:center; color:#27ae60; font-weight:bold; margin-bottom:12px;'>📈 Overall improved by +{delta:.0f} points</div>"
+    elif delta < 0:
+        result += f"<div style='text-align:center; color:#e74c3c; font-weight:bold; margin-bottom:12px;'>📉 Overall decreased by {delta:.0f} points</div>"
+    else:
+        result += "<div style='text-align:center; color:#666; margin-bottom:12px;'>Overall score unchanged</div>"
+    
+    if improvements:
+        result += "<div style='font-weight:bold; color:#27ae60; margin-top:12px;'>✅ Improvements:</div><ul>"
+        for name, val in improvements[:5]:
+            result += f"<li>{name}: +{val:.0f} points</li>"
+        result += "</ul>"
+    
+    if regressions:
+        result += "<div style='font-weight:bold; color:#e74c3c; margin-top:12px;'>⚠️ Regressions:</div><ul>"
+        for name, val in regressions[:5]:
+            result += f"<li>{name}: {val:.0f} points</li>"
+        result += "</ul>"
+    
+    if next_steps:
+        result += "<div style='font-weight:bold; margin-top:12px;'>📋 Next Recommended Edits:</div>"
+        for step in next_steps[:3]:
+            result += f"<div style='margin:4px 0; padding:8px; background:#e3f2fd; border-radius:4px;'>{step['message']}</div>"
+    
+    result += "</div>"
+    return result

utils/preprocessing.py

@@ -0,0 +1,63 @@
+"""Image preprocessing utilities."""
+
+import numpy as np
+from PIL import Image
+import hashlib
+from typing import Tuple, Optional
+
+
+def preprocess_image(image_input, max_size: int = 1024) -> Image.Image:
+    """
+    Preprocess any image input into a standardized PIL RGB image.
+    
+    Args:
+        image_input: PIL Image, numpy array, or file path
+        max_size: maximum dimension for resizing
+        
+    Returns:
+        PIL Image in RGB mode, resized to max_size if needed
+    """
+    if isinstance(image_input, str):
+        img = Image.open(image_input).convert("RGB")
+    elif isinstance(image_input, np.ndarray):
+        if image_input.ndim == 2:
+            img = Image.fromarray(image_input).convert("RGB")
+        elif image_input.ndim == 3:
+            img = Image.fromarray(image_input).convert("RGB")
+        else:
+            raise ValueError(f"Unexpected array shape: {image_input.shape}")
+    elif isinstance(image_input, Image.Image):
+        img = image_input.convert("RGB")
+    else:
+        raise TypeError(f"Unsupported image type: {type(image_input)}")
+    
+    # Resize if too large
+    w, h = img.size
+    if max(w, h) > max_size:
+        scale = max_size / max(w, h)
+        new_w, new_h = int(w * scale), int(h * scale)
+        img = img.resize((new_w, new_h), Image.LANCZOS)
+    
+    return img
+
+
+def compute_image_hash(img: Image.Image) -> str:
+    """Compute SHA256 hash of image pixels for caching."""
+    return hashlib.sha256(np.array(img).tobytes()).hexdigest()
+
+
+def get_image_size(img: Image.Image) -> Tuple[int, int]:
+    """Return (width, height) of image."""
+    return img.size
+
+
+def validate_image(img: Image.Image, min_size: int = 50) -> Optional[str]:
+    """
+    Validate image meets minimum requirements.
+    
+    Returns error message if invalid, None if valid.
+    """
+    w, h = img.size
+    if w < min_size or h < min_size:
+        return f"Image too small: {w}x{h}. Minimum {min_size}x{min_size} required."
+    return None