Deploy from GitHub main

.gitattributes

@@ -1,35 +1,4 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
 *.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text

.github/workflows/deploy-to-hf-spaces.yml

@@ -0,0 +1,52 @@
+name: Deploy to HF Spaces (on main)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: deploy-hf-space
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install deps
+        run: |
+          python -m pip install -U pip
+          pip install -U "huggingface_hub[cli]"
+
+      - name: Validate app file exists
+        run: |
+          test -f src/ui/compi_phase3_final_dashboard.py || (echo "App file missing" && exit 1)
+
+      - name: Push folder to Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_SPACE_ID: ${{ secrets.HF_SPACE_ID }}
+        run: |
+          python - << 'PY'
+          from huggingface_hub import HfApi
+          import os
+          api = HfApi()
+          repo_id = os.environ["HF_SPACE_ID"]  # e.g. "username/compi-final-dashboard"
+          api.upload_folder(
+              token=os.environ["HF_TOKEN"],
+              repo_id=repo_id,
+              repo_type="space",
+              folder_path=".",
+              path_in_repo="",
+              commit_message="Deploy from GitHub main"
+          )
+          print("Uploaded to Space:", repo_id)
+          PY

.gitignore

@@ -0,0 +1,103 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+compi-env/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Data files (large datasets)
+data/raw/
+data/processed/
+*.csv
+*.json
+*.parquet
+*.h5
+*.hdf5
+
+# Model files (large pretrained models)
+models/pretrained/
+*.pth
+*.pt
+*.ckpt
+*.safetensors
+
+# Generated outputs
+outputs/images/
+outputs/audio/
+outputs/videos/
+*.wav
+*.mp3
+*.mp4
+*.avi
+*.png
+*.jpg
+*.jpeg
+*.gif
+
+# Logs
+logs/
+*.log
+
+# Cache
+.cache/
+*.cache
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+temp/
+tmp/
+
+# Weights & Biases
+wandb/
+
+# Hugging Face cache
+.cache/huggingface/

DEPLOYMENT_CHECKLIST.md

@@ -0,0 +1,147 @@
+# 🚀 CompI Phase 4 Deployment Checklist
+
+## Prerequisites
+- [ ] GitHub account with your CompI repository
+- [ ] Hugging Face account ([sign up here](https://huggingface.co/join))
+- [ ] OpenWeatherMap API key (optional, for real-time weather data)
+
+## Phase 4.A: Repository Preparation ✅
+- [x] `packages.txt` created with system dependencies
+- [x] `.gitattributes` created for Git LFS support
+- [x] `requirements.txt` verified and ready
+- [x] GitHub Actions workflow created
+
+## Phase 4.B: Hugging Face Space Setup
+
+### Step 1: Create Space
+1. [ ] Go to [Hugging Face Spaces](https://huggingface.co/spaces)
+2. [ ] Click "Create new Space"
+3. [ ] Fill in details:
+   - **Owner**: Your username
+   - **Space name**: `compi-final-dashboard` (or your choice)
+   - **License**: Apache 2.0 (recommended)
+   - **SDK**: Streamlit
+   - **Hardware**: CPU basic (free)
+   - **Visibility**: Public
+
+### Step 2: Configure Space
+4. [ ] In your new Space, click "Files" → "README.md" → Edit
+5. [ ] Replace content with this header:
+
+```markdown
+---
+title: CompI — Final Dashboard
+emoji: 🎨
+sdk: streamlit
+app_file: src/ui/compi_phase3_final_dashboard.py
+pinned: false
+---
+
+# CompI - Multimodal AI Art Generation Platform
+
+The ultimate creative platform combining text, audio, data, emotion, and real-time inputs for AI art generation.
+
+## Features
+
+🧩 **Multimodal Inputs** - Text, Audio, Data, Emotion, Real-time feeds
+🖼️ **Advanced References** - Multi-image upload with role assignment  
+⚙️ **Model Management** - SD 1.5/SDXL switching, LoRA integration
+🖼️ **Professional Gallery** - Filtering, rating, annotation system
+💾 **Preset Management** - Save/load complete configurations
+📦 **Export System** - Complete bundles with metadata
+
+## Usage
+
+1. Configure your inputs in the "Inputs" tab
+2. Upload reference images in "Advanced References" 
+3. Choose your model and performance settings
+4. Generate with intelligent fusion of all inputs
+5. Review results in the gallery and export bundles
+
+Built with Streamlit, PyTorch, and Diffusers.
+```
+
+6. [ ] Commit the README changes
+
+### Step 3: Add Secrets (Optional)
+7. [ ] Go to Space Settings → Repository secrets
+8. [ ] Add secret: `OPENWEATHER_KEY` = `your_api_key_here`
+
+## Phase 4.C: GitHub Actions Setup
+
+### Step 1: Get Hugging Face Token
+9. [ ] Go to [HF Settings → Access Tokens](https://huggingface.co/settings/tokens)
+10. [ ] Click "New token"
+11. [ ] Name: `CompI Deployment`
+12. [ ] Type: **Write**
+13. [ ] Click "Generate"
+14. [ ] **Copy the token** (you won't see it again!)
+
+### Step 2: Add GitHub Secrets
+15. [ ] Go to your GitHub repo → Settings → Secrets and variables → Actions
+16. [ ] Click "New repository secret"
+17. [ ] Add secret 1:
+    - **Name**: `HF_TOKEN`
+    - **Secret**: Paste your HF token from step 14
+18. [ ] Add secret 2:
+    - **Name**: `HF_SPACE_ID`
+    - **Secret**: `your-username/your-space-name` (e.g., `AXRZCE/compi-final-dashboard`)
+
+## Phase 4.D: Test Deployment
+
+### Step 1: Trigger First Deploy
+19. [ ] In your GitHub repo, make a small change (e.g., edit README.md)
+20. [ ] Commit to `main` branch:
+```bash
+git add .
+git commit -m "Initial deployment setup"
+git push origin main
+```
+
+### Step 2: Monitor Deployment
+21. [ ] Go to GitHub repo → Actions tab
+22. [ ] Watch the "Deploy to HF Spaces (on main)" workflow
+23. [ ] Verify it completes successfully (green checkmark)
+
+### Step 3: Test Your Space
+24. [ ] Go to your HF Space URL: `https://your-username-your-space.hf.space`
+25. [ ] Wait for the app to build (first time takes 5-10 minutes)
+26. [ ] Test basic functionality:
+    - [ ] Enter a text prompt
+    - [ ] Generate an image
+    - [ ] Check that the interface loads properly
+
+## Phase 4.E: Production Workflow
+
+### For Future Updates
+- [ ] Create feature branches for new development
+- [ ] Test changes locally: `streamlit run src/ui/compi_phase3_final_dashboard.py`
+- [ ] Open Pull Request to `main`
+- [ ] Merge PR → Automatic deployment to HF Space
+
+### Rollback Process
+- [ ] If deployment breaks, revert the commit on `main`
+- [ ] GitHub Actions will automatically redeploy the previous version
+
+## Troubleshooting
+
+### Common Issues
+- **Space won't start**: Check the build logs in HF Space → Logs
+- **GitHub Action fails**: Check repo secrets are set correctly
+- **App crashes**: Verify `app_file` path in Space README is correct
+- **Missing dependencies**: Check `requirements.txt` and `packages.txt`
+
+### Support Resources
+- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Streamlit Documentation](https://docs.streamlit.io/)
+
+## Success! 🎉
+
+Once complete, your CompI platform will be:
+- ✅ Publicly accessible at your HF Space URL
+- ✅ Automatically deployed on every `main` branch update
+- ✅ Running on free Hugging Face infrastructure
+- ✅ Ready for users worldwide to create multimodal AI art
+
+**Share your Space URL**: `https://your-username-your-space.hf.space`

README.md

@@ -1,11 +1,368 @@
+# CompI - Compositional Intelligence Project
+
+A multi-modal AI system that generates creative content by combining text, images, audio, and emotional context.
+
+Note: All documentation has been consolidated under docs/. See docs/README.md for an index of guides.
+
+## 🚀 Project Overview
+
+CompI (Compositional Intelligence) is designed to create rich, contextually-aware content by:
+
+- Processing text prompts with emotional analysis
+- Generating images using Stable Diffusion
+- Creating audio compositions
+- Combining multiple modalities for enhanced creative output
+
+## 📁 Project Structure
+
+```
+Project CompI/
+├── src/                    # Source code
+│   ├── generators/        # Image generation modules
+│   ├── models/            # Model implementations
+│   ├── utils/             # Utility functions
+│   ├── data/              # Data processing
+│   ├── ui/                # User interface components
+│   └── setup_env.py       # Environment setup script
+├── notebooks/             # Jupyter notebooks for experimentation
+├── data/                  # Dataset storage
+├── outputs/               # Generated content
+├── tests/                 # Unit tests
+├── run_*.py               # Convenience scripts for generators
+├── requirements.txt       # Python dependencies
+└── README.md             # This file
+```
+
+## 🛠️ Setup Instructions
+
+### 1. Create Virtual Environment
+
+```bash
+# Using conda (recommended for ML projects)
+conda create -n compi-env python=3.10 -y
+conda activate compi-env
+
+# OR using venv
+python -m venv compi-env
+# Windows
+compi-env\Scripts\activate
+# Linux/Mac
+source compi-env/bin/activate
+```
+
+### 2. Install Dependencies
+
+**For GPU users (recommended for faster generation):**
+
+```bash
+# First, check your CUDA version
+nvidia-smi
+
+# Install PyTorch with CUDA support first (replace cu121 with your CUDA version)
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
+
+# Then install remaining requirements
+pip install -r requirements.txt
+```
+
+**For CPU-only users:**
+
+```bash
+pip install -r requirements.txt
+```
+
+### 3. Test Installation
+
+```bash
+python src/test_setup.py
+```
+
+## 🚀 Quick Start
+
+### Phase 1: Text-to-Image Generation
+
+```bash
+# Basic text-to-image generation
+python run_basic_generation.py "A magical forest, digital art"
+
+# Advanced generation with style conditioning
+python run_advanced_styling.py "dragon in a crystal cave" --style "oil painting" --mood "dramatic"
+
+# Interactive style selection
+python run_styled_generation.py
+
+# Quality evaluation and analysis
+python run_evaluation.py
+
+# Personal style training with LoRA
+python run_lora_training.py --dataset-dir datasets/my_style
+
+# Generate with personal style
+python run_style_generation.py --lora-path lora_models/my_style/checkpoint-1000 "artwork in my_style"
+```
+
+### Phase 2.A: Audio-to-Image Generation 🎵
+
+```bash
+# Install audio processing dependencies
+pip install openai-whisper
+
+# Streamlit UI (Recommended)
+streamlit run src/ui/compi_phase2a_streamlit_ui.py
+
+# Command line generation
+python run_phase2a_audio_to_image.py --prompt "mystical forest" --audio "music.mp3"
+
+# Interactive mode
+python run_phase2a_audio_to_image.py --interactive
+
+# Test installation
+python src/test_phase2a.py
+
+# Run examples
+python examples/phase2a_audio_examples.py --example all
+```
+
+### Phase 2.B: Data/Logic-to-Image Generation 📊
+
+```bash
+# Streamlit UI (Recommended)
+streamlit run src/ui/compi_phase2b_streamlit_ui.py
+
+# Command line generation with CSV data
+python run_phase2b_data_to_image.py --prompt "data visualization" --csv "data.csv"
+
+# Mathematical formula generation
+python run_phase2b_data_to_image.py --prompt "mathematical harmony" --formula "np.sin(np.linspace(0, 4*np.pi, 100))"
+
+# Batch processing
+python run_phase2b_data_to_image.py --batch-csv "data_folder/" --prompt "scientific patterns"
+
+# Interactive mode
+python run_phase2b_data_to_image.py --interactive
+```
+
+### Phase 2.C: Emotional/Contextual Input to Image Generation 🌀
+
+```bash
+# Streamlit UI (Recommended)
+streamlit run src/ui/compi_phase2c_streamlit_ui.py
+
+# Command line generation with preset emotion
+python run_phase2c_emotion_to_image.py --prompt "mystical forest" --emotion "mysterious"
+
+# Custom emotion generation
+python run_phase2c_emotion_to_image.py --prompt "urban landscape" --emotion "🤩" --type custom
+
+# Descriptive emotion generation
+python run_phase2c_emotion_to_image.py --prompt "mountain vista" --emotion "I feel a sense of wonder" --type text
+
+# Batch emotion processing
+python run_phase2c_emotion_to_image.py --batch-emotions "joyful,sad,mysterious" --prompt "abstract art"
+
+# Interactive mode
+python run_phase2c_emotion_to_image.py --interactive
+```
+
+### Phase 2.D: Real-Time Data Feeds to Image Generation 🌎
+
+```bash
+# Streamlit UI (Recommended)
+streamlit run src/ui/compi_phase2d_streamlit_ui.py
+
+# Command line generation with weather data
+python run_phase2d_realtime_to_image.py --prompt "cityscape" --weather --city "Tokyo"
+
+# News-driven generation
+python run_phase2d_realtime_to_image.py --prompt "abstract art" --news --category "technology"
+
+# Multi-source generation
+python run_phase2d_realtime_to_image.py --prompt "world state" --weather --news --financial
+
+# Temporal series generation
+python run_phase2d_realtime_to_image.py --prompt "evolving world" --weather --temporal "0,30,60"
+
+# Interactive mode
+python run_phase2d_realtime_to_image.py --interactive
+```
+
+### Phase 2.E: Style Reference/Example Image to AI Art 🖼️
+
+```bash
+# Streamlit UI (Recommended)
+streamlit run src/ui/compi_phase2e_streamlit_ui.py
+
+# Command line generation with reference image
+python run_phase2e_refimg_to_image.py --prompt "magical forest" --reference "path/to/image.jpg" --strength 0.6
+
+# Web URL reference
+python run_phase2e_refimg_to_image.py --prompt "cyberpunk city" --reference "https://example.com/artwork.jpg"
+
+# Batch generation with multiple variations
+python run_phase2e_refimg_to_image.py --prompt "fantasy landscape" --reference "image.png" --num-images 3
+
+# Style analysis only
+python run_phase2e_refimg_to_image.py --analyze-only --reference "artwork.jpg"
+
+# Interactive mode
+python run_phase2e_refimg_to_image.py --interactive
+```
+
+## 🧪 NEW: Ultimate Multimodal Dashboard (True Fusion) 🚀
+
+**Revolutionary upgrade with REAL processing of each input type!**
+
+```bash
+# Launch the upgraded dashboard with true multimodal fusion
+python run_ultimate_multimodal_dashboard.py
+
+# Or run directly
+streamlit run src/ui/compi_ultimate_multimodal_dashboard.py --server.port 8503
+```
+
+**Key Improvements:**
+
+- ✅ **Real Audio Analysis**: Whisper transcription + librosa features
+- ✅ **Actual Data Processing**: CSV analysis + formula evaluation
+- ✅ **True Emotion Analysis**: TextBlob sentiment classification
+- ✅ **Live Real-time Data**: Weather/news API integration
+- ✅ **Advanced References**: img2img + ControlNet processing
+- ✅ **Intelligent Fusion**: Actual content processing (not static keywords)
+
+**Access at:** `http://localhost:8503`
+
+**See:** `ULTIMATE_MULTIMODAL_DASHBOARD_README.md` for detailed documentation.
+
+## 🖼️ NEW: Phase 3.C Advanced Reference Integration 🚀
+
+**Professional multi-reference control with hybrid generation modes!**
+
+**Key Features:**
+
+- ✅ **Role-Based Reference Assignment**: Select images for style vs structure
+- ✅ **Live ControlNet Previews**: Real-time Canny/Depth preprocessing
+- ✅ **Hybrid Generation Modes**: CN + IMG2IMG simultaneous processing
+- ✅ **Professional Controls**: Independent strength tuning for style/structure
+- ✅ **Seamless Integration**: Works with all CompI multimodal phases
+
+**See:** `PHASE3C_ADVANCED_REFERENCE_INTEGRATION.md` for complete documentation.
+
+## 🗂️ NEW: Phase 3.D Professional Workflow Manager 🚀
+
+**Complete creative workflow platform with unified logging, presets, and export bundles!**
+
+**Key Features:**
+
+- ✅ **Unified Run Logging**: Auto-ingests from all CompI phases
+- ✅ **Professional Gallery**: Advanced filtering and search
+- ✅ **Preset System**: Save/load complete generation configs
+- ✅ **Export Bundles**: ZIP packages with metadata and reproducibility
+- ✅ **Annotation System**: Ratings, tags, and notes for workflow management
+
+**Launch:** `python run_phase3d_workflow_manager.py` | **Access:** `http://localhost:8504`
+
+**See:** `docs/PHASE3D_WORKFLOW_MANAGER_GUIDE.md` for complete documentation.
+
+## ⚙️ NEW: Phase 3.E Performance, Model Management & Reliability 🚀
+
+**Production-grade performance optimization, model switching, and intelligent reliability!**
+
+**Key Features:**
+
+- ✅ **Model Manager**: Dynamic SD 1.5 ↔ SDXL switching with auto-availability checking
+- ✅ **LoRA Integration**: Universal LoRA loading with scale control across all models
+- ✅ **Performance Controls**: xFormers, attention slicing, VAE optimizations, precision control
+- ✅ **VRAM Monitoring**: Real-time GPU memory usage tracking and alerts
+- ✅ **Reliability Engine**: OOM-safe auto-retry with intelligent fallbacks
+- ✅ **Batch Processing**: Seed-controlled batch generation with memory management
+- ✅ **Upscaler Integration**: Optional 2x latent upscaling for enhanced quality
+
+**Launch:** `python run_phase3e_performance_manager.py` | **Access:** `http://localhost:8505`
+
+**See:** `docs/PHASE3E_PERFORMANCE_GUIDE.md` for complete documentation.
+
+## 🧪 ULTIMATE: Phase 3 Final Dashboard - Complete Integration! 🎉
+
+**The ultimate CompI interface that integrates ALL Phase 3 components into one unified creative environment!**
+
+**Complete Feature Integration:**
+
+- ✅ **🧩 Multimodal Fusion (3.A/3.B)**: Real audio, data, emotion, real-time processing
+- ✅ **🖼️ Advanced References (3.C)**: Role assignment, ControlNet, live previews
+- ✅ **⚙️ Performance Management (3.E)**: Model switching, LoRA, VRAM monitoring
+- ✅ **🎛️ Intelligent Generation**: Hybrid modes with automatic fallback strategies
+- ✅ **🖼️ Professional Gallery (3.D)**: Filtering, rating, annotation system
+- ✅ **💾 Preset Management (3.D)**: Save/load complete configurations
+- ✅ **📦 Export System (3.D)**: Complete bundles with metadata and reproducibility
+
+**Professional Workflow:**
+
+1. **Configure multimodal inputs** (text, audio, data, emotion, real-time)
+2. **Upload and assign references** (style vs structure roles)
+3. **Choose model and optimize performance** (SD 1.5/SDXL, LoRA, optimizations)
+4. **Generate with intelligent fusion** (automatic mode selection)
+5. **Review and annotate results** (gallery with rating/tagging)
+6. **Save presets and export bundles** (complete reproducibility)
+
+**Launch:** `python run_phase3_final_dashboard.py` | **Access:** `http://localhost:8506`
+
+**See:** `docs/PHASE3_FINAL_DASHBOARD_GUIDE.md` for complete documentation.
+
 ---
-title: Comp I
-emoji: 🔥
-colorFrom: green
-colorTo: yellow
-sdk: static
-pinned: false
-license: mit
----
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## 🎯 **CompI Project Status: COMPLETE** ✅
+
+**CompI has achieved its ultimate vision: the world's most comprehensive and production-ready multimodal AI art generation platform!**
+
+### **✅ All Phases Complete:**
+
+- **✅ Phase 1**: Foundation (text-to-image, styling, evaluation, LoRA training)
+- **✅ Phase 2**: Multimodal integration (audio, data, emotion, real-time, references)
+- **✅ Phase 3**: Advanced features (fusion dashboard, advanced references, workflow management, performance optimization)
+
+### **🚀 What CompI Offers:**
+
+- **Complete Creative Platform**: From generation to professional workflow management
+- **Production-Grade Reliability**: Robust error handling and performance optimization
+- **Professional Tools**: Industry-standard features for serious creative and commercial work
+- **Universal Compatibility**: Works across different hardware configurations
+- **Extensible Foundation**: Ready for future enhancements and integrations
+
+**CompI is now the ultimate multimodal AI art generation platform - ready for professional creative work!** 🎨✨
+
+## 🎯 Core Features
+
+- **Text Analysis**: Emotion detection and sentiment analysis
+- **Image Generation**: Stable Diffusion integration with advanced conditioning
+- **Audio Processing**: Music and sound analysis with Whisper integration
+- **Data Processing**: CSV analysis and mathematical formula evaluation
+- **Emotion Processing**: Preset emotions, custom emotions, emoji, and contextual analysis
+- **Real-Time Integration**: Live weather, news, and financial data feeds
+- **Style Reference**: Upload/URL image guidance with AI-powered style analysis
+- **Multi-modal Fusion**: Combining text, audio, data, emotions, real-time feeds, and visual references
+- **Pattern Recognition**: Automatic detection of trends, correlations, and seasonality
+- **Poetic Interpretation**: Converting data patterns and emotions into artistic language
+- **Color Psychology**: Emotion-based color palette generation and conditioning
+- **Temporal Awareness**: Time-sensitive data processing and evolution tracking
+
+## 🔧 Tech Stack
+
+- **Deep Learning**: PyTorch, Transformers, Diffusers
+- **Audio**: librosa, soundfile
+- **UI**: Streamlit/Gradio
+- **Data**: pandas, numpy
+- **Visualization**: matplotlib, seaborn
+
+## 📝 Usage
+
+Coming soon - basic usage examples and API documentation.
+
+## 🤝 Contributing
+
+This is a development project. Feel free to experiment and extend functionality.
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+# Project_CompI

docs/PHASE1D_EVALUATION_GUIDE.md

@@ -0,0 +1,205 @@
+# CompI Phase 1.D: Baseline Output Quality Evaluation Guide
+
+## 🎯 Overview
+
+Phase 1.D provides comprehensive tools for systematically evaluating the quality, coherence, and consistency of images generated by your CompI pipeline. This phase is crucial for understanding your model's performance and tracking improvements over time.
+
+## 🛠️ Tools Provided
+
+### 1. **Streamlit Web Interface** (`compi_phase1d_evaluate_quality.py`)
+- **Interactive visual evaluation** with side-by-side image and metadata display
+- **Multi-criteria scoring system** (1-5 stars) for comprehensive assessment
+- **Objective metrics calculation** (perceptual hashes, file size, dimensions)
+- **Persistent evaluation logging** with CSV export
+- **Batch evaluation capabilities** for efficient processing
+
+### 2. **Command-Line Interface** (`compi_phase1d_cli_evaluation.py`)
+- **Batch processing** for automated evaluation workflows
+- **Statistical analysis** and performance summaries
+- **Detailed report generation** with recommendations
+- **Filtering and listing** capabilities for organized review
+
+### 3. **Convenient Launcher** (`run_evaluation.py`)
+- **One-click startup** for the web interface
+- **Automatic environment checking** and error handling
+
+## 📊 Evaluation Criteria
+
+The evaluation system uses **5 comprehensive criteria**, each scored on a **1-5 scale**:
+
+### 1. **Prompt Adherence** 
+- How well does the image match the text prompt?
+- Scale: 1=Poor match → 5=Perfect match
+
+### 2. **Style Consistency**
+- How well does the image reflect the intended artistic style?
+- Scale: 1=Style not evident → 5=Style perfectly executed
+
+### 3. **Mood & Atmosphere**
+- How well does the image convey the intended mood/atmosphere?
+- Scale: 1=Wrong mood → 5=Perfect mood
+
+### 4. **Technical Quality**
+- Overall image quality (resolution, composition, artifacts)
+- Scale: 1=Poor quality → 5=Excellent quality
+
+### 5. **Creative Appeal**
+- Subjective aesthetic and creative value
+- Scale: 1=Unappealing → 5=Highly appealing
+
+## 🚀 Quick Start
+
+### Web Interface (Recommended for Manual Review)
+
+```bash
+# Install required dependency
+pip install imagehash
+
+# Launch the evaluation interface
+python run_evaluation.py
+
+# Or run directly
+streamlit run src/generators/compi_phase1d_evaluate_quality.py
+```
+
+The web interface will open at `http://localhost:8501` with:
+- **Single Image Review**: Detailed evaluation of individual images
+- **Batch Evaluation**: Quick scoring for multiple images
+- **Summary Analysis**: Statistics and performance insights
+
+### Command-Line Interface (For Automation)
+
+```bash
+# Analyze existing evaluations
+python src/generators/compi_phase1d_cli_evaluation.py --analyze
+
+# List unevaluated images
+python src/generators/compi_phase1d_cli_evaluation.py --list-unevaluated
+
+# Batch score all unevaluated images (prompt, style, mood, quality, appeal)
+python src/generators/compi_phase1d_cli_evaluation.py --batch-score 4 3 4 4 3 --notes "Initial baseline evaluation"
+
+# Generate detailed report
+python src/generators/compi_phase1d_cli_evaluation.py --report --output evaluation_report.txt
+```
+
+## 📁 File Structure
+
+```
+outputs/
+├── [generated images].png          # Your CompI-generated images
+├── evaluation_log.csv              # Detailed evaluation data
+└── evaluation_summary.json         # Summary statistics
+
+src/generators/
+├── compi_phase1d_evaluate_quality.py    # Main Streamlit interface
+└── compi_phase1d_cli_evaluation.py      # Command-line tools
+
+run_evaluation.py                    # Convenient launcher
+```
+
+## 📈 Understanding Your Data
+
+### Evaluation Log (`outputs/evaluation_log.csv`)
+
+Contains detailed records with columns:
+- **Image metadata**: filename, prompt, style, mood, seed, variation
+- **Evaluation scores**: All 5 criteria scores (1-5)
+- **Objective metrics**: dimensions, file size, perceptual hashes
+- **Evaluation metadata**: timestamp, notes, evaluator comments
+
+### Key Metrics to Track
+
+1. **Overall Score Trends**: Are your images improving over time?
+2. **Criteria Performance**: Which aspects (prompt match, style, etc.) need work?
+3. **Style/Mood Effectiveness**: Which combinations work best?
+4. **Consistency**: Are similar prompts producing consistent results?
+
+## 🎯 Best Practices
+
+### Systematic Evaluation Workflow
+
+1. **Generate a batch** of images using your CompI tools
+2. **Evaluate systematically** using consistent criteria
+3. **Analyze patterns** in the data to identify strengths/weaknesses
+4. **Adjust generation parameters** based on insights
+5. **Re-evaluate** to measure improvements
+
+### Evaluation Tips
+
+- **Be consistent** in your scoring criteria across sessions
+- **Use notes** to capture specific observations and issues
+- **Evaluate in batches** of similar style/mood for better comparison
+- **Track changes** over time as you refine your generation process
+
+### Interpreting Scores
+
+- **4.0+ average**: Excellent performance, ready for production use
+- **3.0-3.9 average**: Good performance, minor improvements needed
+- **2.0-2.9 average**: Moderate performance, significant improvements needed
+- **Below 2.0**: Poor performance, major adjustments required
+
+## 🔧 Advanced Usage
+
+### Filtering and Analysis
+
+```bash
+# Analyze only specific styles
+python src/generators/compi_phase1d_cli_evaluation.py --analyze --style "anime"
+
+# List images by mood
+python src/generators/compi_phase1d_cli_evaluation.py --list-all --mood "dramatic"
+
+# Generate style-specific report
+python src/generators/compi_phase1d_cli_evaluation.py --report --style "oil painting" --output oil_painting_analysis.txt
+```
+
+### Custom Evaluation Workflows
+
+The evaluation tools are designed to be flexible:
+- **Modify criteria** by editing `EVALUATION_CRITERIA` in the source
+- **Add custom metrics** by extending the `get_image_metrics()` function
+- **Integrate with other tools** using the CSV export functionality
+
+## 📊 Sample Analysis Output
+
+```
+📊 CompI Phase 1.D - Evaluation Analysis
+==================================================
+Total Evaluated Images: 25
+
+📈 Score Statistics:
+  Prompt Adherence    : 3.84 ± 0.75 (range: 2-5)
+  Style Consistency   : 3.52 ± 0.87 (range: 2-5)
+  Mood & Atmosphere   : 3.68 ± 0.69 (range: 2-5)
+  Technical Quality   : 4.12 ± 0.60 (range: 3-5)
+  Creative Appeal     : 3.76 ± 0.83 (range: 2-5)
+
+🎨 Top Performing Styles (by Prompt Match):
+  anime          : 4.20
+  oil painting   : 3.90
+  digital art    : 3.75
+```
+
+## 🚀 Next Steps
+
+After completing Phase 1.D evaluation:
+
+1. **Identify improvement areas** from your evaluation data
+2. **Experiment with parameter adjustments** for low-scoring criteria
+3. **Document successful combinations** for future use
+4. **Consider Phase 2** development based on baseline performance
+5. **Set up regular evaluation cycles** for continuous improvement
+
+## 🤝 Integration with Other Phases
+
+Phase 1.D evaluation data can inform:
+- **Phase 1.A/1.B parameter tuning**: Adjust generation settings based on quality scores
+- **Phase 1.C UI improvements**: Highlight best-performing style/mood combinations
+- **Future phases**: Use baseline metrics to measure advanced feature improvements
+
+---
+
+**Happy Evaluating! 🎨📊**
+
+The systematic evaluation provided by Phase 1.D is essential for understanding and improving your CompI system's performance. Use these tools regularly to maintain high-quality output and track your progress over time.

docs/PHASE1E_LORA_GUIDE.md

@@ -0,0 +1,270 @@
+# CompI Phase 1.E: Personal Style Fine-tuning with LoRA
+
+## 🎯 Overview
+
+Phase 1.E enables you to train **personalized artistic styles** using LoRA (Low-Rank Adaptation) fine-tuning on Stable Diffusion. This allows you to create AI art that reflects your unique artistic vision or mimics specific artistic styles.
+
+**LoRA Benefits:**
+- ✅ **Lightweight**: Only trains a small adapter (~10-100MB vs full model ~4GB)
+- ✅ **Fast**: Training takes minutes to hours instead of days
+- ✅ **Flexible**: Can be combined with different base models
+- ✅ **Efficient**: Runs on consumer GPUs (8GB+ VRAM recommended)
+
+## 🛠️ Tools Provided
+
+### 1. **Dataset Preparation** (`compi_phase1e_dataset_prep.py`)
+- Organize and validate your style images
+- Generate appropriate training captions
+- Resize and format images for optimal training
+- Create train/validation splits
+
+### 2. **LoRA Training** (`compi_phase1e_lora_training.py`)
+- Full LoRA fine-tuning pipeline with PEFT integration
+- Configurable training parameters and monitoring
+- Automatic checkpoint saving and validation
+- Memory-efficient training with gradient checkpointing
+
+### 3. **Style Generation** (`compi_phase1e_style_generation.py`)
+- Generate images using your trained LoRA styles
+- Interactive and batch generation modes
+- Adjustable style strength and parameters
+- Integration with existing CompI pipeline
+
+### 4. **Style Management** (`compi_phase1e_style_manager.py`)
+- Manage multiple trained LoRA styles
+- Cleanup old checkpoints and organize models
+- Export style information and analytics
+- Switch between different personal styles
+
+## 🚀 Quick Start Guide
+
+### Step 1: Install Dependencies
+
+```bash
+# Install LoRA training dependencies
+pip install peft datasets bitsandbytes
+
+# Verify installation
+python -c "import peft, datasets; print('✅ Dependencies installed')"
+```
+
+### Step 2: Prepare Your Style Dataset
+
+```bash
+# Organize your style images in a folder
+mkdir my_artwork
+# Copy 10-50 images of your artistic style to my_artwork/
+
+# Prepare dataset for training
+python src/generators/compi_phase1e_dataset_prep.py \
+    --input-dir my_artwork \
+    --style-name "my_art_style" \
+    --trigger-word "myart"
+```
+
+**Dataset Requirements:**
+- **10-50 images** (more is better, but 20+ is usually sufficient)
+- **Consistent style** across all images
+- **512x512 pixels** recommended (will be auto-resized)
+- **High quality** images without watermarks or text
+
+### Step 3: Train Your LoRA Style
+
+```bash
+# Start LoRA training
+python run_lora_training.py \
+    --dataset-dir datasets/my_art_style \
+    --epochs 100 \
+    --learning-rate 1e-4
+
+# Or with custom settings
+python run_lora_training.py \
+    --dataset-dir datasets/my_art_style \
+    --epochs 200 \
+    --batch-size 2 \
+    --lora-rank 8 \
+    --lora-alpha 32
+```
+
+**Training Tips:**
+- **Start with 100 epochs** for initial testing
+- **Increase to 200-500 epochs** for stronger style learning
+- **Monitor validation loss** to avoid overfitting
+- **Use gradient checkpointing** if you run out of memory
+
+### Step 4: Generate with Your Style
+
+```bash
+# Generate images with your trained style
+python run_style_generation.py \
+    --lora-path lora_models/my_art_style/checkpoint-1000 \
+    "a cat in myart style" \
+    --variations 4
+
+# Interactive mode
+python run_style_generation.py \
+    --lora-path lora_models/my_art_style/checkpoint-1000 \
+    --interactive
+```
+
+## 📊 Advanced Usage
+
+### Training Configuration
+
+```bash
+# High-quality training (slower but better results)
+python run_lora_training.py \
+    --dataset-dir datasets/my_style \
+    --epochs 300 \
+    --learning-rate 5e-5 \
+    --lora-rank 16 \
+    --lora-alpha 32 \
+    --batch-size 1 \
+    --gradient-checkpointing
+
+# Fast training (quicker results for testing)
+python run_lora_training.py \
+    --dataset-dir datasets/my_style \
+    --epochs 50 \
+    --learning-rate 2e-4 \
+    --lora-rank 4 \
+    --lora-alpha 16
+```
+
+### Style Management
+
+```bash
+# List all trained styles
+python src/generators/compi_phase1e_style_manager.py --list
+
+# Get detailed info about a style
+python src/generators/compi_phase1e_style_manager.py --info my_art_style
+
+# Clean up old checkpoints (keep only 3 most recent)
+python src/generators/compi_phase1e_style_manager.py --cleanup my_art_style --keep 3
+
+# Export styles information to CSV
+python src/generators/compi_phase1e_style_manager.py --export my_styles_report.csv
+```
+
+### Generation Parameters
+
+```bash
+# Adjust style strength
+python run_style_generation.py \
+    --lora-path lora_models/my_style/checkpoint-1000 \
+    --lora-scale 0.8 \
+    "portrait in myart style"
+
+# High-quality generation
+python run_style_generation.py \
+    --lora-path lora_models/my_style/checkpoint-1000 \
+    --steps 50 \
+    --guidance 8.0 \
+    --width 768 \
+    --height 768 \
+    "landscape in myart style"
+```
+
+## 🎨 Best Practices
+
+### Dataset Preparation
+1. **Consistent Style**: All images should represent the same artistic style
+2. **Quality over Quantity**: 20 high-quality images > 100 low-quality ones
+3. **Diverse Subjects**: Include various subjects (people, objects, landscapes)
+4. **Clean Images**: Remove watermarks, text, and irrelevant elements
+5. **Proper Captions**: Use consistent trigger words in captions
+
+### Training Tips
+1. **Start Small**: Begin with 50-100 epochs to test
+2. **Monitor Progress**: Check validation loss and sample generations
+3. **Adjust Learning Rate**: Lower if loss oscillates, higher if learning is slow
+4. **Use Checkpoints**: Save frequently to avoid losing progress
+5. **Experiment with LoRA Rank**: Higher rank = more capacity but slower training
+
+### Generation Guidelines
+1. **Include Trigger Words**: Always use your trigger word in prompts
+2. **Adjust Style Strength**: Use `--lora-scale` to control style intensity
+3. **Combine with Techniques**: Mix with existing CompI style/mood systems
+4. **Iterate and Refine**: Generate multiple variations and select best results
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**Out of Memory Error:**
+```bash
+# Reduce batch size and enable gradient checkpointing
+python run_lora_training.py \
+    --dataset-dir datasets/my_style \
+    --batch-size 1 \
+    --gradient-checkpointing \
+    --mixed-precision
+```
+
+**Style Not Learning:**
+- Increase epochs (try 200-500)
+- Check dataset consistency
+- Increase LoRA rank (try 8 or 16)
+- Lower learning rate (try 5e-5)
+
+**Generated Images Don't Match Style:**
+- Include trigger word in prompts
+- Increase LoRA scale (try 1.2-1.5)
+- Train for more epochs
+- Check dataset quality
+
+**Training Too Slow:**
+- Reduce image resolution to 512x512
+- Use mixed precision training
+- Enable gradient checkpointing
+- Reduce LoRA rank to 4
+
+## 📁 File Structure
+
+```
+Project CompI/
+├── datasets/                    # Prepared training datasets
+│   └── my_art_style/
+│       ├── train/              # Training images
+│       ├── validation/         # Validation images
+│       ├── train_captions.txt  # Training captions
+│       └── dataset_info.json   # Dataset metadata
+├── lora_models/                # Trained LoRA models
+│   └── my_art_style/
+│       ├── checkpoint-100/     # Training checkpoints
+│       ├── checkpoint-200/
+│       └── training_info.json  # Training metadata
+├── src/generators/
+│   ├── compi_phase1e_dataset_prep.py     # Dataset preparation
+│   ├── compi_phase1e_lora_training.py    # LoRA training
+│   ├── compi_phase1e_style_generation.py # Style generation
+│   └── compi_phase1e_style_manager.py    # Style management
+├── run_lora_training.py        # Training launcher
+└── run_style_generation.py     # Generation launcher
+```
+
+## 🎯 Integration with CompI
+
+Phase 1.E integrates seamlessly with existing CompI tools:
+
+1. **Combine with Phase 1.B**: Use LoRA styles alongside predefined styles
+2. **Evaluate with Phase 1.D**: Assess your LoRA-generated images systematically
+3. **UI Integration**: Add LoRA styles to Streamlit/Gradio interfaces
+4. **Batch Processing**: Generate multiple variations for evaluation
+
+## 🚀 Next Steps
+
+After mastering Phase 1.E:
+
+1. **Experiment with Multiple Styles**: Train different LoRA adapters for various artistic approaches
+2. **Style Mixing**: Combine multiple LoRA styles for unique effects
+3. **Advanced Techniques**: Explore Textual Inversion, DreamBooth, or ControlNet integration
+4. **Community Sharing**: Share your trained styles with the CompI community
+5. **Phase 2 Preparation**: Use personal styles as foundation for multimodal integration
+
+---
+
+**Happy Style Training! 🎨✨**
+
+Phase 1.E opens up endless possibilities for personalized AI art generation. With LoRA fine-tuning, you can teach the AI to understand and replicate your unique artistic vision, creating truly personalized creative content.

docs/PHASE1_USAGE.md

@@ -0,0 +1,454 @@
+# CompI Phase 1: Text-to-Image Generation Usage Guide
+
+This guide covers the Phase 1 implementation of CompI's text-to-image generation capabilities using Stable Diffusion.
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```bash
+# Simple generation with interactive prompt
+python run_basic_generation.py
+
+# Generate from command line
+python run_basic_generation.py "A magical forest, digital art, highly detailed"
+
+# Or run directly from src/generators/
+python src/generators/compi_phase1_text2image.py "A magical forest"
+```
+
+### Advanced Usage
+
+```bash
+# Advanced script with more options
+python run_advanced_generation.py "cyberpunk city at sunset" --negative "blurry, low quality" --steps 50 --batch 3
+
+# Interactive mode for experimentation
+python run_advanced_generation.py --interactive
+
+# Or run directly from src/generators/
+python src/generators/compi_phase1_advanced.py --interactive
+```
+
+## 📋 Available Scripts
+
+### 1. `compi_phase1_text2image.py` - Basic Implementation
+
+**Features:**
+
+- Simple, standalone text-to-image generation
+- Automatic GPU/CPU detection
+- Command line or interactive prompts
+- Automatic output saving with descriptive filenames
+- Comprehensive logging
+
+**Usage:**
+
+```bash
+python compi_phase1_text2image.py [prompt]
+```
+
+### 2. `compi_phase1_advanced.py` - Enhanced Implementation
+
+**Features:**
+
+- Batch generation (multiple images)
+- Negative prompts (what to avoid)
+- Customizable parameters (steps, guidance, dimensions)
+- Interactive mode for experimentation
+- Metadata saving (JSON files with generation parameters)
+- Multiple model support
+
+**Command Line Options:**
+
+```bash
+python compi_phase1_advanced.py [OPTIONS] [PROMPT]
+
+Options:
+  --negative, -n TEXT     Negative prompt (what to avoid)
+  --steps, -s INTEGER     Number of inference steps (default: 30)
+  --guidance, -g FLOAT    Guidance scale (default: 7.5)
+  --seed INTEGER          Random seed for reproducibility
+  --batch, -b INTEGER     Number of images to generate
+  --width, -w INTEGER     Image width (default: 512)
+  --height INTEGER        Image height (default: 512)
+  --model, -m TEXT        Model to use (default: runwayml/stable-diffusion-v1-5)
+  --output, -o TEXT       Output directory (default: outputs)
+  --interactive, -i       Interactive mode
+```
+
+## 🎨 Example Commands
+
+### Basic Examples
+
+```bash
+# Simple landscape
+python run_basic_generation.py "serene mountain lake, golden hour, photorealistic"
+
+# Digital art style
+python run_basic_generation.py "futuristic robot, neon lights, cyberpunk style, digital art"
+```
+
+### Advanced Examples
+
+```bash
+# High-quality generation with negative prompts
+python run_advanced_generation.py "beautiful portrait of a woman, oil painting style" \
+  --negative "blurry, distorted, low quality, bad anatomy" \
+  --steps 50 --guidance 8.0
+
+# Batch generation with fixed seed
+python run_advanced_generation.py "abstract geometric patterns, colorful" \
+  --batch 5 --seed 12345 --steps 40
+
+# Custom dimensions for landscape
+python run_advanced_generation.py "panoramic view of alien landscape" \
+  --width 768 --height 512 --steps 35
+
+# Interactive experimentation
+python run_advanced_generation.py --interactive
+```
+
+## 📁 Output Structure
+
+Generated images are saved in the `outputs/` directory with descriptive filenames:
+
+```
+outputs/
+├── magical_forest_digital_art_20241225_143022_seed42.png
+├── magical_forest_digital_art_20241225_143022_seed42_metadata.json
+├── cyberpunk_city_sunset_20241225_143156_seed1337.png
+└── cyberpunk_city_sunset_20241225_143156_seed1337_metadata.json
+```
+
+### Metadata Files
+
+Each generated image (in advanced mode) includes a JSON metadata file with:
+
+- Original prompt and negative prompt
+- Generation parameters (steps, guidance, seed)
+- Image dimensions and model used
+- Timestamp and batch information
+
+## ⚙️ Configuration Tips
+
+### For Best Quality
+
+- Use 30-50 inference steps
+- Guidance scale 7.5-12.0
+- Include style descriptors ("digital art", "oil painting", "photorealistic")
+- Use negative prompts to avoid unwanted elements
+
+### For Speed
+
+- Use 20-25 inference steps
+- Lower guidance scale (6.0-7.5)
+- Stick to 512x512 resolution
+
+### For Experimentation
+
+- Use interactive mode
+- Try different seeds with the same prompt
+- Experiment with guidance scale values
+- Use batch generation to explore variations
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+1. **CUDA out of memory**: Reduce batch size or image dimensions
+2. **Slow generation**: Ensure CUDA is available and working
+3. **Poor quality**: Increase steps, adjust guidance scale, improve prompts
+4. **Model download fails**: Check internet connection, try again
+
+### Performance Optimization
+
+- The scripts automatically enable attention slicing for memory efficiency
+- GPU detection is automatic
+- Models are cached after first download
+
+## 🎨 Phase 1.B: Style Conditioning & Prompt Engineering
+
+### 3. `compi_phase1b_styled_generation.py` - Style Conditioning
+
+**Features:**
+
+- Interactive style and mood selection from curated lists
+- Intelligent prompt engineering and combination
+- Multiple variations with unique seeds
+- Comprehensive logging and filename organization
+
+**Usage:**
+
+```bash
+python run_styled_generation.py [prompt]
+# Or directly: python src/generators/compi_phase1b_styled_generation.py [prompt]
+```
+
+### 4. `compi_phase1b_advanced_styling.py` - Advanced Style Control
+
+**Features:**
+
+- 13 predefined art styles with optimized prompts and negative prompts
+- 9 mood categories with atmospheric conditioning
+- Quality presets (draft/standard/high)
+- Command line and interactive modes
+- Comprehensive metadata saving
+
+**Command Line Options:**
+
+```bash
+python run_advanced_styling.py [OPTIONS] [PROMPT]
+# Or directly: python src/generators/compi_phase1b_advanced_styling.py [OPTIONS] [PROMPT]
+
+Options:
+  --style, -s TEXT        Art style (or number from list)
+  --mood, -m TEXT         Mood/atmosphere (or number from list)
+  --variations, -v INT    Number of variations (default: 1)
+  --quality, -q CHOICE    Quality preset [draft/standard/high]
+  --negative, -n TEXT     Negative prompt
+  --interactive, -i       Interactive mode
+  --list-styles          List available styles and exit
+  --list-moods           List available moods and exit
+```
+
+### Style Conditioning Examples
+
+**Basic Style Selection:**
+
+```bash
+# Interactive mode with guided selection
+python run_styled_generation.py
+
+# Command line with style selection
+python run_advanced_styling.py "mountain landscape" --style cyberpunk --mood dramatic
+```
+
+**Advanced Style Control:**
+
+```bash
+# High quality with multiple variations
+python run_advanced_styling.py "portrait of a wizard" \
+  --style "oil painting" --mood "mysterious" \
+  --quality high --variations 3 \
+  --negative "blurry, distorted, amateur"
+
+# List available options
+python run_advanced_styling.py --list-styles
+python run_advanced_styling.py --list-moods
+```
+
+**Available Styles:**
+
+- digital art, oil painting, watercolor, cyberpunk
+- impressionist, concept art, anime, photorealistic
+- minimalist, surrealism, pixel art, steampunk, 3d render
+
+**Available Moods:**
+
+- dreamy, dark, peaceful, vibrant, melancholic
+- mysterious, whimsical, dramatic, retro
+
+## 🖥️ Phase 1.C: Interactive Web UI
+
+### 5. `compi_phase1c_streamlit_ui.py` - Streamlit Web Interface
+
+**Features:**
+
+- Complete web-based interface for text-to-image generation
+- Interactive style and mood selection with custom options
+- Advanced settings (steps, guidance, dimensions, negative prompts)
+- Real-time image generation and display
+- Progress tracking and generation logs
+- Automatic saving with comprehensive metadata
+
+**Usage:**
+
+```bash
+python run_ui.py
+# Or directly: streamlit run src/ui/compi_phase1c_streamlit_ui.py
+```
+
+### 6. `compi_phase1c_gradio_ui.py` - Gradio Web Interface
+
+**Features:**
+
+- Alternative web interface with Gradio framework
+- Gallery view for multiple image variations
+- Collapsible advanced settings
+- Real-time generation logs
+- Mobile-friendly responsive design
+
+**Usage:**
+
+```bash
+python run_gradio_ui.py
+# Or directly: python src/ui/compi_phase1c_gradio_ui.py
+```
+
+## 📊 Phase 1.D: Quality Evaluation Tools
+
+### 7. `compi_phase1d_evaluate_quality.py` - Comprehensive Evaluation Interface
+
+**Features:**
+
+- Systematic image quality assessment with 5-criteria scoring system
+- Interactive Streamlit web interface for detailed evaluation
+- Objective metrics calculation (perceptual hashes, dimensions, file size)
+- Batch evaluation capabilities for efficient processing
+- Comprehensive logging and CSV export for trend analysis
+- Summary analytics with performance insights and recommendations
+
+**Usage:**
+
+```bash
+python run_evaluation.py
+# Or directly: streamlit run src/generators/compi_phase1d_evaluate_quality.py
+```
+
+### 8. `compi_phase1d_cli_evaluation.py` - Command-Line Evaluation Tools
+
+**Features:**
+
+- Batch evaluation and analysis from command line
+- Statistical summaries and performance reports
+- Filtering by style, mood, and evaluation status
+- Automated scoring for large image sets
+- Detailed report generation with recommendations
+
+**Command Line Options:**
+
+```bash
+python src/generators/compi_phase1d_cli_evaluation.py [OPTIONS]
+
+Options:
+  --analyze                    Display evaluation summary and statistics
+  --report                     Generate detailed evaluation report
+  --batch-score P S M Q A      Batch score images (1-5 for each criteria)
+  --list-all                   List all images with evaluation status
+  --list-evaluated             List only evaluated images
+  --list-unevaluated          List only unevaluated images
+  --style TEXT                 Filter by style
+  --mood TEXT                  Filter by mood
+  --notes TEXT                 Notes for batch evaluation
+  --output FILE                Output file for reports
+```
+
+## 🎨 Phase 1.E: Personal Style Fine-tuning (LoRA)
+
+### 9. `compi_phase1e_dataset_prep.py` - Dataset Preparation for LoRA Training
+
+**Features:**
+
+- Organize and validate personal style images for training
+- Generate appropriate training captions with trigger words
+- Resize and format images for optimal LoRA training
+- Create train/validation splits with metadata tracking
+- Support for multiple image formats and quality validation
+
+**Usage:**
+
+```bash
+python src/generators/compi_phase1e_dataset_prep.py --input-dir my_artwork --style-name "my_art_style"
+# Or via wrapper: python run_dataset_prep.py --input-dir my_artwork --style-name "my_art_style"
+```
+
+### 10. `compi_phase1e_lora_training.py` - LoRA Fine-tuning Engine
+
+**Features:**
+
+- Full LoRA (Low-Rank Adaptation) fine-tuning pipeline
+- Memory-efficient training with gradient checkpointing
+- Configurable LoRA parameters (rank, alpha, learning rate)
+- Automatic checkpoint saving and validation monitoring
+- Integration with PEFT library for optimal performance
+
+**Command Line Options:**
+
+```bash
+python run_lora_training.py [OPTIONS] --dataset-dir DATASET_DIR
+
+Options:
+  --dataset-dir DIR            Required: Prepared dataset directory
+  --epochs INT                 Number of training epochs (default: 100)
+  --learning-rate FLOAT        Learning rate (default: 1e-4)
+  --lora-rank INT              LoRA rank (default: 4)
+  --lora-alpha INT             LoRA alpha (default: 32)
+  --batch-size INT             Training batch size (default: 1)
+  --save-steps INT             Save checkpoint every N steps
+  --gradient-checkpointing     Enable gradient checkpointing for memory efficiency
+  --mixed-precision            Use mixed precision training
+```
+
+### 11. `compi_phase1e_style_generation.py` - Personal Style Generation
+
+**Features:**
+
+- Generate images using trained LoRA personal styles
+- Adjustable style strength and generation parameters
+- Interactive and batch generation modes
+- Integration with existing CompI pipeline and metadata
+- Support for multiple LoRA styles and model switching
+
+**Usage:**
+
+```bash
+python run_style_generation.py --lora-path lora_models/my_style/checkpoint-1000 "a cat in my_style"
+# Or directly: python src/generators/compi_phase1e_style_generation.py --lora-path PATH PROMPT
+```
+
+### 12. `compi_phase1e_style_manager.py` - LoRA Style Management
+
+**Features:**
+
+- Manage multiple trained LoRA styles and checkpoints
+- Cleanup old checkpoints and organize model storage
+- Export style information and training analytics
+- Style database with automatic scanning and metadata
+- Batch operations for style maintenance and organization
+
+**Command Line Options:**
+
+```bash
+python src/generators/compi_phase1e_style_manager.py [OPTIONS]
+
+Options:
+  --list                       List all available LoRA styles
+  --info STYLE_NAME           Show detailed information about a style
+  --refresh                    Refresh the styles database
+  --cleanup STYLE_NAME         Clean up old checkpoints for a style
+  --export OUTPUT_FILE         Export styles information to CSV
+  --delete STYLE_NAME          Delete a LoRA style (requires --confirm)
+```
+
+### Web UI Examples
+
+**Streamlit Interface:**
+
+- Navigate to http://localhost:8501 after running
+- Full-featured interface with sidebar settings
+- Progress bars and status updates
+- Expandable sections for details
+
+**Gradio Interface:**
+
+- Navigate to http://localhost:7860 after running
+- Gallery-style image display
+- Compact, mobile-friendly design
+- Real-time generation feedback
+
+## 🎯 Next Steps
+
+Phase 1 establishes the foundation for CompI's text-to-image capabilities. Future phases will add:
+
+- Audio input processing
+- Emotion and style conditioning
+- Real-time data integration
+- Multimodal fusion
+- Advanced UI interfaces
+
+## 📚 Resources
+
+- [Stable Diffusion Documentation](https://huggingface.co/docs/diffusers)
+- [Prompt Engineering Guide](https://prompthero.com/stable-diffusion-prompt-guide)
+- [CompI Development Plan](development.md)

docs/PHASE2A_AUDIO_TO_IMAGE_GUIDE.md

@@ -0,0 +1,307 @@
+# CompI Phase 2.A: Audio-to-Image Generation Guide
+
+Welcome to **CompI Phase 2.A**, the next evolution in multimodal AI art generation! This phase introduces the ability to generate images influenced by audio input, combining the power of text prompts with the emotional and rhythmic qualities of sound.
+
+## 🎵 What's New in Phase 2.A
+
+### Core Features
+
+- **Audio Analysis**: Extract tempo, energy, spectral features, and harmonic content from audio files
+- **Audio Captioning**: Convert speech, music, and ambient sounds to descriptive text using OpenAI Whisper
+- **Multimodal Fusion**: Intelligently combine text prompts with audio-derived features
+- **Rich Metadata**: Comprehensive logging of audio features and generation context
+- **Multiple Interfaces**: Streamlit UI, CLI, and programmatic API
+
+### Supported Audio Formats
+
+- MP3, WAV, FLAC, M4A, OGG
+- Recommended: Under 60 seconds for optimal processing speed
+- Automatic resampling to 16kHz for analysis
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+First, ensure you have the Phase 2.A dependencies:
+
+```bash
+pip install openai-whisper
+```
+
+All other dependencies should already be installed from Phase 1.
+
+### 2. Streamlit UI (Recommended for Beginners)
+
+Launch the interactive web interface:
+
+```bash
+streamlit run src/ui/compi_phase2a_streamlit_ui.py
+```
+
+Features:
+
+- 🎵 Audio upload and playback
+- 📊 Real-time audio analysis visualization
+- 🎨 Interactive generation controls
+- 📝 Enhanced prompt preview
+- 🖼️ Instant results display
+
+### 3. Command Line Interface
+
+For power users and automation:
+
+```bash
+# Basic usage
+python run_phase2a_audio_to_image.py --prompt "mystical forest" --audio "music.mp3"
+
+# With style and mood
+python run_phase2a_audio_to_image.py \
+    --prompt "cyberpunk city" \
+    --style "digital art" \
+    --mood "neon, futuristic" \
+    --audio "electronic.wav"
+
+# Multiple variations
+python run_phase2a_audio_to_image.py \
+    --prompt "abstract art" \
+    --audio "ambient.flac" \
+    --num-images 3
+
+# Interactive mode
+python run_phase2a_audio_to_image.py --interactive
+```
+
+### 4. Programmatic Usage
+
+```python
+from src.generators.compi_phase2a_audio_to_image import CompIPhase2AAudioToImage
+
+# Initialize generator
+generator = CompIPhase2AAudioToImage()
+
+# Generate image with audio conditioning
+results = generator.generate_image(
+    text_prompt="A serene mountain landscape",
+    style="impressionist",
+    mood="peaceful, contemplative",
+    audio_path="nature_sounds.wav",
+    num_images=2
+)
+
+# Access results
+for result in results:
+    print(f"Generated: {result['filename']}")
+    result['image'].show()  # Display image
+```
+
+## 🎨 How Audio Influences Art
+
+### Audio Feature Extraction
+
+CompI Phase 2.A analyzes multiple aspects of your audio:
+
+1. **Tempo**: Beats per minute → influences rhythm and energy descriptors
+2. **Energy (RMS)**: Overall loudness → affects intensity and power descriptors
+3. **Zero Crossing Rate**: Rhythmic content → adds percussive/smooth qualities
+4. **Spectral Centroid**: Brightness → influences warm/bright color palettes
+5. **MFCC**: Timbre characteristics → affects texture and style
+6. **Chroma**: Harmonic content → influences mood and atmosphere
+
+### Intelligent Prompt Fusion
+
+The system automatically enhances your text prompt based on audio analysis:
+
+**Original Prompt**: "A mystical forest"
+**Audio**: Slow, ambient music with low energy
+**Enhanced Prompt**: "A mystical forest, slow and contemplative, gentle and subtle, warm and deep"
+
+### Audio Captioning
+
+Using OpenAI Whisper, the system can describe what it "hears":
+
+- **Speech**: Transcribes spoken words and incorporates meaning
+- **Music**: Identifies instruments, genres, and emotional qualities
+- **Ambient**: Describes environmental sounds and atmospheres
+
+## 📊 Understanding Audio Analysis
+
+### Tempo Classifications
+
+- **Very Slow** (< 60 BPM): Meditative, ethereal qualities
+- **Slow** (60-90 BPM): Contemplative, peaceful atmospheres
+- **Moderate** (90-120 BPM): Balanced, natural rhythms
+- **Fast** (120-140 BPM): Energetic, dynamic compositions
+- **Very Fast** (> 140 BPM): Intense, high-energy visuals
+
+### Energy Levels
+
+- **Low Energy** (< 0.02): Subtle, gentle, minimalist styles
+- **Medium Energy** (0.02-0.05): Balanced, harmonious compositions
+- **High Energy** (> 0.05): Vibrant, powerful, dramatic visuals
+
+### Spectral Characteristics
+
+- **Bright** (High Spectral Centroid): Light colors, sharp details
+- **Dark** (Low Spectral Centroid): Deep colors, soft textures
+- **Percussive** (High ZCR): Rhythmic patterns, geometric shapes
+- **Smooth** (Low ZCR): Flowing forms, organic shapes
+
+## 🎯 Best Practices
+
+### Audio Selection
+
+1. **Quality Matters**: Use clear, well-recorded audio for best results
+2. **Length**: 10-60 seconds is optimal for processing speed
+3. **Variety**: Experiment with different genres and sound types
+4. **Context**: Choose audio that complements your text prompt
+
+### Prompt Writing
+
+1. **Be Descriptive**: Rich text prompts work better with audio conditioning
+2. **Leave Room**: Let audio features add nuance to your base concept
+3. **Experiment**: Try the same prompt with different audio files
+4. **Balance**: Don't over-specify if you want audio to have strong influence
+
+### Generation Settings
+
+1. **Steps**: 30-50 steps for high quality (20 for quick tests)
+2. **Guidance**: 7.5 is balanced (lower for more audio influence)
+3. **Variations**: Generate multiple images to see different interpretations
+4. **Seeds**: Save seeds of favorite results for consistency
+
+## 🔧 Advanced Features
+
+### Batch Processing
+
+Process multiple audio files with the same prompt:
+
+```bash
+python run_phase2a_audio_to_image.py \
+    --prompt "abstract expressionism" \
+    --audio-dir "./music_collection/" \
+    --batch
+```
+
+### Custom Audio Analysis
+
+```python
+from src.utils.audio_utils import AudioProcessor, MultimodalPromptFusion
+
+# Analyze audio separately
+processor = AudioProcessor()
+features = processor.analyze_audio_file("my_audio.wav")
+
+# Create custom prompt fusion
+fusion = MultimodalPromptFusion()
+enhanced_prompt = fusion.fuse_prompt_with_audio(
+    "base prompt", "style", "mood", features, "audio caption"
+)
+```
+
+### Metadata and Tracking
+
+Every generated image includes comprehensive metadata:
+
+- Original and enhanced prompts
+- Complete audio analysis results
+- Generation parameters
+- Timestamps and seeds
+- Audio tags and classifications
+
+## 🎪 Example Use Cases
+
+### 1. Music Visualization
+
+Transform your favorite songs into visual art:
+
+- **Classical**: Orchestral pieces → elegant, flowing compositions
+- **Electronic**: Synthesized music → geometric, neon aesthetics
+- **Jazz**: Improvisational music → abstract, dynamic forms
+- **Ambient**: Atmospheric sounds → ethereal, dreamlike scenes
+
+### 2. Voice-to-Art
+
+Convert spoken content into visuals:
+
+- **Poetry Reading**: Emotional recitation → expressive, literary art
+- **Storytelling**: Narrative audio → scene illustrations
+- **Meditation**: Guided meditation → peaceful, spiritual imagery
+- **Lectures**: Educational content → informative, structured visuals
+
+### 3. Environmental Soundscapes
+
+Capture the essence of places and moments:
+
+- **Nature Sounds**: Forest, ocean, rain → organic, natural scenes
+- **Urban Audio**: City sounds, traffic → industrial, modern aesthetics
+- **Historical**: Period-appropriate audio → era-specific artwork
+- **Sci-Fi**: Futuristic sounds → otherworldly, technological visuals
+
+### 4. Therapeutic Applications
+
+Use audio-visual generation for wellness:
+
+- **Relaxation**: Calming audio → soothing, peaceful imagery
+- **Motivation**: Energetic music → inspiring, powerful visuals
+- **Focus**: Concentration aids → clean, organized compositions
+- **Creativity**: Experimental sounds → abstract, innovative art
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Audio Not Loading**
+
+- Check file format (MP3, WAV, FLAC, M4A, OGG supported)
+- Ensure file isn't corrupted
+- Try converting to WAV format
+
+**Whisper Model Loading Fails**
+
+- Install with: `pip install openai-whisper`
+- Check available disk space (models are 100MB-1GB)
+- Try smaller model size: `--whisper-model tiny`
+
+**Generation Too Slow**
+
+- Use `--no-caption` to skip audio captioning
+- Reduce `--steps` for faster generation
+- Use smaller Whisper model
+- Process shorter audio clips
+
+**Out of Memory**
+
+- Use CPU mode: `--device cpu`
+- Reduce image size: `--size 256x256`
+- Close other applications
+- Process one image at a time
+
+### Performance Tips
+
+1. **GPU Acceleration**: CUDA significantly speeds up generation
+2. **Model Caching**: First run downloads models (1-2GB total)
+3. **Audio Preprocessing**: Shorter clips process faster
+4. **Batch Processing**: More efficient for multiple files
+5. **Memory Management**: Close UI between large batches
+
+## 🔮 What's Next?
+
+Phase 2.A is just the beginning of CompI's multimodal journey. Coming soon:
+
+- **Phase 2.B**: Real-time audio processing and live generation
+- **Phase 2.C**: Video-to-image conditioning
+- **Phase 2.D**: Multi-sensor input fusion
+- **Phase 3.A**: 3D model generation from multimodal input
+
+## 📚 Additional Resources
+
+- [CompI Project Structure](PROJECT_STRUCTURE.md)
+- [Phase 1 Usage Guide](PHASE1_USAGE.md)
+- [Audio Processing Documentation](src/utils/audio_utils.py)
+- [Example Audio Files] (removed in cleanup)
+
+---
+
+**Happy Creating! 🎨🎵**
+
+_CompI Phase 2.A brings together the worlds of sound and vision, creating art that truly resonates with your audio experiences._

docs/PHASE2B_DATA_TO_IMAGE_GUIDE.md

@@ -0,0 +1,271 @@
+# CompI Phase 2.B: Data/Logic Input to Image Generation
+
+## 🚀 Overview
+
+Phase 2.B transforms structured data and mathematical formulas into stunning AI-generated art. This phase combines data analysis, pattern recognition, and poetic interpretation to create unique visual experiences that reflect the essence of your data.
+
+## ✨ Key Features
+
+### 📊 Data Processing
+- **CSV Data Analysis**: Upload spreadsheets, time series, measurements, or any numeric data
+- **Mathematical Formula Evaluation**: Enter Python/NumPy expressions for mathematical art
+- **Pattern Recognition**: Automatic detection of trends, correlations, and seasonality
+- **Statistical Analysis**: Comprehensive data profiling and feature extraction
+
+### 🎨 Artistic Integration
+- **Poetic Text Generation**: Convert data patterns into descriptive, artistic language
+- **Data Visualization**: Create beautiful charts and plots from your data
+- **Prompt Enhancement**: Intelligently merge data insights with your creative prompts
+- **Visual Conditioning**: Use data visualizations to inspire AI art generation
+
+### 🔧 Technical Capabilities
+- **Safe Formula Execution**: Secure evaluation of mathematical expressions
+- **Batch Processing**: Handle multiple datasets or formulas simultaneously
+- **Comprehensive Metadata**: Detailed logging of all generation parameters
+- **Flexible Output**: Save both generated art and data visualizations
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+Ensure you have the base CompI environment set up with all dependencies from `requirements.txt`.
+
+### Additional Dependencies
+Phase 2.B uses the existing CompI dependencies, specifically:
+- `pandas>=2.0.0` - Data manipulation and analysis
+- `numpy>=1.24.0` - Mathematical operations
+- `matplotlib>=3.7.0` - Data visualization
+- `seaborn>=0.12.0` - Statistical plotting
+
+## 🎯 Quick Start
+
+### 1. Launch the Streamlit Interface
+
+```bash
+# Navigate to your CompI project directory
+cd "C:\Users\Aksharajsinh\Documents\augment-projects\Project CompI"
+
+# Run the Phase 2.B interface
+streamlit run src/ui/compi_phase2b_streamlit_ui.py
+```
+
+### 2. Using CSV Data
+
+1. **Upload your CSV file** containing numeric data
+2. **Enter your creative prompt** (e.g., "A flowing river of data")
+3. **Set style and mood** (e.g., "abstract digital art", "serene and flowing")
+4. **Click Generate** and watch your data transform into art!
+
+### 3. Using Mathematical Formulas
+
+1. **Enter a mathematical formula** using Python/NumPy syntax
+2. **Combine with your prompt** for artistic interpretation
+3. **Generate unique mathematical art** based on your equations
+
+## 📚 Examples
+
+### CSV Data Examples
+
+#### Time Series Data
+```csv
+date,temperature,humidity,pressure
+2024-01-01,22.5,65,1013.2
+2024-01-02,23.1,62,1015.8
+2024-01-03,21.8,68,1012.4
+...
+```
+
+**Prompt**: "Weather patterns dancing across the sky"
+**Style**: "impressionist painting"
+**Result**: Art inspired by temperature fluctuations and atmospheric pressure
+
+#### Financial Data
+```csv
+date,price,volume,volatility
+2024-01-01,100.5,1000000,0.15
+2024-01-02,102.3,1200000,0.18
+2024-01-03,99.8,900000,0.22
+...
+```
+
+**Prompt**: "The rhythm of market forces"
+**Style**: "geometric abstract"
+**Result**: Visual representation of market dynamics
+
+### Mathematical Formula Examples
+
+#### Sine Wave with Decay
+```python
+np.sin(np.linspace(0, 4*np.pi, 100)) * np.exp(-np.linspace(0, 1, 100))
+```
+**Prompt**: "Fading echoes in a digital realm"
+**Result**: Art representing diminishing oscillations
+
+#### Spiral Pattern
+```python
+t = np.linspace(0, 4*np.pi, 200)
+np.sin(t) * t
+```
+**Prompt**: "The golden ratio in nature"
+**Result**: Spiral-inspired organic art
+
+#### Complex Harmonic
+```python
+x = np.linspace(0, 6*np.pi, 300)
+np.sin(x) + 0.5*np.cos(3*x) + 0.25*np.sin(5*x)
+```
+**Prompt**: "Musical harmonies visualized"
+**Result**: Multi-layered wave patterns
+
+## 🎨 Creative Workflow
+
+### 1. Data Preparation
+- **Clean your data**: Remove or handle missing values
+- **Choose meaningful columns**: Focus on numeric data that tells a story
+- **Consider time series**: Temporal data often creates compelling patterns
+
+### 2. Prompt Engineering
+- **Start with your data story**: What does your data represent?
+- **Add artistic style**: Choose styles that complement your data's nature
+- **Set the mood**: Match the emotional tone to your data's characteristics
+
+### 3. Style Recommendations
+
+| Data Type | Recommended Styles | Mood Suggestions |
+|-----------|-------------------|------------------|
+| Time Series | flowing, organic, wave-like | rhythmic, temporal, evolving |
+| Statistical | geometric, structured, minimal | analytical, precise, clean |
+| Financial | dynamic, angular, sharp | energetic, volatile, intense |
+| Scientific | technical, detailed, precise | methodical, systematic, clear |
+| Random/Chaotic | abstract, expressionist, wild | unpredictable, chaotic, free |
+
+## 🔧 Advanced Usage
+
+### Programmatic Access
+
+```python
+from src.generators.compi_phase2b_data_to_image import CompIPhase2BDataToImage
+
+# Initialize generator
+generator = CompIPhase2BDataToImage()
+
+# Generate from CSV
+results = generator.generate_image(
+    text_prompt="Data flowing like water",
+    style="fluid abstract",
+    mood="serene, continuous",
+    csv_path="path/to/your/data.csv",
+    num_images=2
+)
+
+# Generate from formula
+results = generator.generate_image(
+    text_prompt="Mathematical harmony",
+    style="geometric precision",
+    mood="balanced, rhythmic",
+    formula="np.sin(np.linspace(0, 4*np.pi, 100))",
+    num_images=1
+)
+```
+
+### Batch Processing
+
+```python
+# Process multiple CSV files
+results = generator.batch_process_csv_files(
+    csv_directory="data/experiments/",
+    text_prompt="Scientific visualization",
+    style="technical illustration",
+    mood="precise, analytical"
+)
+
+# Process multiple formulas
+formulas = [
+    "np.sin(x)",
+    "np.cos(x)",
+    "np.tan(x/2)"
+]
+results = generator.batch_process_formulas(
+    formulas=formulas,
+    text_prompt="Trigonometric art",
+    style="mathematical beauty"
+)
+```
+
+## 📊 Understanding Data Features
+
+Phase 2.B analyzes your data and extracts several key features:
+
+### Statistical Features
+- **Means, Medians, Standard Deviations**: Basic statistical measures
+- **Ranges and Distributions**: Data spread and shape
+- **Trends**: Increasing, decreasing, stable, or volatile patterns
+
+### Pattern Features
+- **Correlations**: Relationships between different data columns
+- **Seasonality**: Repeating patterns in time series data
+- **Complexity Score**: Measure of data intricacy (0-1)
+- **Variability Score**: Measure of data diversity (0-1)
+- **Pattern Strength**: Measure of detectable patterns (0-1)
+
+### Poetic Interpretation
+The system converts these features into artistic language:
+- **Trend descriptions**: "ascending", "flowing", "turbulent"
+- **Pattern adjectives**: "intricate", "harmonious", "dynamic"
+- **Artistic metaphors**: "like brushstrokes on canvas", "dancing with precision"
+
+## 🎯 Tips for Best Results
+
+### Data Tips
+1. **Quality over quantity**: Clean, meaningful data works better than large messy datasets
+2. **Numeric focus**: Ensure your CSV has numeric columns for analysis
+3. **Reasonable size**: Keep datasets under 10,000 rows for faster processing
+4. **Meaningful names**: Use descriptive column names for better interpretation
+
+### Formula Tips
+1. **Use NumPy functions**: Leverage `np.sin`, `np.cos`, `np.exp`, etc.
+2. **Define ranges**: Use `np.linspace()` to create smooth curves
+3. **Experiment with complexity**: Combine multiple functions for richer patterns
+4. **Consider scale**: Ensure your formula produces reasonable numeric ranges
+
+### Prompt Tips
+1. **Be descriptive**: Rich prompts lead to more interesting results
+2. **Match your data**: Align artistic style with data characteristics
+3. **Experiment**: Try different style/mood combinations
+4. **Use the preview**: Check the enhanced prompt before generating
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**"Error analyzing data"**
+- Check that your CSV has numeric columns
+- Ensure the file is properly formatted
+- Try with a smaller dataset first
+
+**"Invalid formula"**
+- Use only safe mathematical functions
+- Check your NumPy syntax
+- Ensure parentheses are balanced
+
+**"Generation failed"**
+- Check your GPU memory if using CUDA
+- Try reducing the number of inference steps
+- Ensure your prompt isn't too long
+
+### Performance Optimization
+- Use GPU acceleration when available
+- Reduce image dimensions for faster generation
+- Process smaller datasets for quicker analysis
+- Use fewer inference steps for rapid prototyping
+
+## 🚀 Next Steps
+
+After mastering Phase 2.B, consider:
+1. **Combining with Phase 2.A**: Use audio + data for multimodal art
+2. **Creating data stories**: Build narratives around your visualizations
+3. **Exploring advanced formulas**: Try complex mathematical expressions
+4. **Building datasets**: Create custom data for specific artistic goals
+
+---
+
+**Ready to transform your data into art?** Launch the Streamlit interface and start creating! 🎨📊✨

docs/PHASE2C_EMOTION_TO_IMAGE_GUIDE.md

@@ -0,0 +1,286 @@
+# CompI Phase 2.C: Emotional/Contextual Input to Image Generation
+
+## 🌀 Overview
+
+Phase 2.C transforms emotions, moods, and feelings into stunning AI-generated art. This phase combines emotion detection, sentiment analysis, and contextual understanding to create artwork that resonates with your emotional state and inner feelings.
+
+## ✨ Key Features
+
+### 🎭 Emotion Processing
+- **Preset Emotions**: Choose from 25+ carefully curated emotions
+- **Custom Emotions**: Enter any emotion word or feeling
+- **Emoji Support**: Use emojis to express emotions naturally
+- **Descriptive Text**: Describe complex emotional states in your own words
+- **Sentiment Analysis**: Automatic emotion detection from text using TextBlob
+
+### 🎨 Artistic Integration
+- **Emotion-to-Color Mapping**: Automatic color palette generation based on emotions
+- **Artistic Descriptors**: Emotion-specific visual styles and atmospheres
+- **Prompt Enhancement**: Intelligent fusion of emotions with creative prompts
+- **Intensity Levels**: Low, medium, and high emotional intensity processing
+- **Mood Modifiers**: Contextual atmosphere enhancement
+
+### 🔧 Technical Capabilities
+- **Multi-Input Support**: Preset, custom, emoji, and text-based emotion input
+- **Confidence Scoring**: Emotion detection confidence levels
+- **Batch Processing**: Generate art for multiple emotions simultaneously
+- **Color Conditioning**: Optional color palette integration into prompts
+- **Comprehensive Metadata**: Detailed emotion analysis and generation tracking
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+Ensure you have the base CompI environment set up with all dependencies from `requirements.txt`.
+
+### Additional Dependencies
+Phase 2.C uses existing CompI dependencies, specifically:
+- `textblob>=0.17.0` - Sentiment analysis and emotion detection
+- `emoji` (optional) - Enhanced emoji processing
+
+### Optional Setup
+For enhanced sentiment analysis, download TextBlob corpora:
+```bash
+python -m textblob.download_corpora
+```
+
+## 🎯 Quick Start
+
+### 1. Launch the Streamlit Interface
+
+```bash
+# Navigate to your CompI project directory
+cd "C:\Users\Aksharajsinh\Documents\augment-projects\Project CompI"
+
+# Run the Phase 2.C interface
+streamlit run src/ui/compi_phase2c_streamlit_ui.py
+
+# Or use the main CompI interface
+streamlit run compi_complete_app.py
+# Then select "🌀 Phase 2.C: Emotion-to-Image"
+```
+
+### 2. Using Preset Emotions
+
+1. **Select "Preset Emotions"** as your input method
+2. **Choose an emotion category** (Joy & Happiness, Love & Romance, etc.)
+3. **Pick a specific emotion** from the category
+4. **Enter your creative prompt** and style
+5. **Generate** and watch your emotion transform into art!
+
+### 3. Using Custom Emotions or Emojis
+
+1. **Select "Custom Emotion/Emoji"** as your input method
+2. **Type any emotion** (e.g., "contemplative", "bittersweet")
+3. **Or use emojis** (🤩, 💫, 🌙) to express feelings
+4. **Use quick emoji buttons** for common emotions
+5. **Generate** emotion-infused artwork
+
+### 4. Using Descriptive Text
+
+1. **Select "Descriptive Text"** as your input method
+2. **Describe your feeling** in natural language
+3. **Example**: "I feel hopeful after the rain" or "There's anticipation in the air"
+4. **AI analyzes sentiment** and extracts emotional context
+5. **Generate** art based on your emotional description
+
+## 📚 Emotion Categories & Examples
+
+### 🌟 Joy & Happiness
+- **joyful**: Bright, radiant, effervescent artwork
+- **ecstatic**: High-energy, explosive, vibrant creations
+- **cheerful**: Light, uplifting, warm compositions
+- **uplifting**: Inspiring, elevating, positive imagery
+
+### 💙 Sadness & Melancholy
+- **melancholic**: Wistful, contemplative, blue-toned art
+- **nostalgic**: Memory-tinged, sepia-like, reflective pieces
+- **somber**: Muted, serious, thoughtful compositions
+- **wistful**: Longing, gentle sadness, soft imagery
+
+### ❤️ Love & Romance
+- **romantic**: Warm, tender, passionate artwork
+- **loving**: Affectionate, caring, heart-centered pieces
+- **passionate**: Intense, fiery, deep emotional art
+- **tender**: Gentle, soft, intimate compositions
+
+### 🕊️ Peace & Serenity
+- **peaceful**: Calm, balanced, harmonious imagery
+- **serene**: Tranquil, still, meditative artwork
+- **tranquil**: Quiet, restful, soothing compositions
+- **harmonious**: Balanced, unified, flowing pieces
+
+### 🔮 Mystery & Drama
+- **mysterious**: Enigmatic, shadowy, intriguing art
+- **dramatic**: Bold, intense, theatrical compositions
+- **enigmatic**: Puzzling, cryptic, thought-provoking pieces
+- **suspenseful**: Tension-filled, anticipatory artwork
+
+### ⚡ Energy & Power
+- **energetic**: Dynamic, vibrant, high-movement art
+- **powerful**: Strong, bold, commanding compositions
+- **intense**: Deep, concentrated, focused imagery
+- **fierce**: Wild, untamed, strong emotional pieces
+
+## 🎨 Creative Workflow
+
+### 1. Emotion Selection Strategy
+- **Start with your current mood**: What are you feeling right now?
+- **Consider the artwork's purpose**: What emotion should it evoke?
+- **Match emotion to subject**: Align feelings with your prompt content
+- **Experiment with intensity**: Try different emotional strengths
+
+### 2. Prompt Engineering with Emotions
+- **Base prompt**: Start with your core visual concept
+- **Emotion integration**: Let the system enhance with emotional context
+- **Style coordination**: Choose styles that complement your emotion
+- **Atmosphere setting**: Use mood modifiers for deeper impact
+
+### 3. Emotion-Style Combinations
+
+| Emotion | Recommended Styles | Color Palettes | Atmosphere |
+|---------|-------------------|----------------|------------|
+| Joyful | impressionist, vibrant digital art | golds, oranges, bright blues | radiant, luminous |
+| Melancholic | oil painting, watercolor | blues, grays, muted tones | contemplative, wistful |
+| Romantic | soft digital art, renaissance | pinks, reds, warm tones | tender, passionate |
+| Mysterious | dark fantasy, gothic | purples, blacks, deep blues | enigmatic, shadowy |
+| Energetic | abstract, dynamic digital | bright colors, neons | electric, vibrant |
+| Peaceful | minimalist, zen art | soft greens, blues, whites | serene, harmonious |
+
+## 🔧 Advanced Usage
+
+### Programmatic Access
+
+```python
+from src.generators.compi_phase2c_emotion_to_image import CompIPhase2CEmotionToImage
+
+# Initialize generator
+generator = CompIPhase2CEmotionToImage()
+
+# Generate with preset emotion
+results = generator.generate_image(
+    text_prompt="A mystical forest",
+    style="digital painting",
+    emotion_input="mysterious",
+    emotion_type="preset",
+    enhancement_strength=0.8,
+    num_images=2
+)
+
+# Generate with custom emotion
+results = generator.generate_image(
+    text_prompt="Urban landscape",
+    style="cyberpunk",
+    emotion_input="🤖",
+    emotion_type="custom",
+    enhancement_strength=0.6
+)
+
+# Generate with descriptive text
+results = generator.generate_image(
+    text_prompt="Mountain vista",
+    style="landscape painting",
+    emotion_input="I feel a sense of wonder and awe",
+    emotion_type="text",
+    contextual_text="Standing at the peak, overwhelmed by nature's beauty"
+)
+```
+
+### Batch Processing
+
+```python
+# Process multiple emotions
+emotions = ["joyful", "melancholic", "mysterious", "energetic"]
+results = generator.batch_process_emotions(
+    text_prompt="Abstract composition",
+    style="modern art",
+    emotions=emotions,
+    enhancement_strength=0.7
+)
+
+# Color palette conditioning
+results = generator.generate_emotion_palette_art(
+    text_prompt="Flowing water",
+    style="fluid art",
+    emotion_input="peaceful",
+    use_color_conditioning=True
+)
+```
+
+## 📊 Understanding Emotion Analysis
+
+Phase 2.C analyzes emotions across multiple dimensions:
+
+### Emotion Detection
+- **Primary Emotion**: Main detected emotion category
+- **Confidence Score**: How certain the system is (0-1)
+- **Secondary Emotions**: Related emotional states
+- **Intensity Level**: Low, medium, or high emotional strength
+
+### Sentiment Analysis
+- **Polarity**: Negative (-1) to Positive (+1) sentiment
+- **Subjectivity**: Objective (0) to Subjective (1) content
+- **Keywords**: Emotion-related words detected in text
+- **Emojis**: Emotional emojis found in input
+
+### Artistic Mapping
+- **Color Palette**: 3-5 colors representing the emotion
+- **Artistic Descriptors**: Visual style words (vibrant, muted, etc.)
+- **Mood Modifiers**: Atmospheric enhancements
+- **Enhancement Tags**: Descriptive tags for the emotion
+
+## 🎯 Tips for Best Results
+
+### Emotion Selection Tips
+1. **Be specific**: "melancholic" is more precise than "sad"
+2. **Consider intensity**: Strong emotions create more dramatic art
+3. **Match context**: Align emotions with your prompt's subject matter
+4. **Experiment freely**: Try unexpected emotion-prompt combinations
+
+### Prompt Enhancement Tips
+1. **Start simple**: Let emotions enhance rather than complicate
+2. **Trust the system**: Emotion analysis often captures nuances you might miss
+3. **Adjust strength**: Use the enhancement slider to control emotional impact
+4. **Combine thoughtfully**: Ensure emotions complement your artistic vision
+
+### Style Coordination Tips
+1. **Emotional styles**: Some styles naturally align with certain emotions
+2. **Color harmony**: Consider how emotion colors work with your chosen style
+3. **Atmospheric consistency**: Ensure mood modifiers enhance rather than conflict
+4. **Intensity matching**: High-intensity emotions work well with bold styles
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**"Emotion not detected"**
+- Try more specific emotion words
+- Use descriptive phrases instead of single words
+- Check for typos in emotion input
+
+**"Weak emotional enhancement"**
+- Increase the enhancement strength slider
+- Use more emotionally charged language
+- Try preset emotions for stronger effects
+
+**"Conflicting emotional signals"**
+- Simplify your emotional input
+- Focus on one primary emotion
+- Avoid mixing opposing emotions
+
+### Performance Optimization
+- Use preset emotions for fastest processing
+- Shorter descriptive texts analyze faster
+- Batch processing is more efficient for multiple emotions
+- GPU acceleration improves generation speed
+
+## 🚀 Next Steps
+
+After mastering Phase 2.C, consider:
+1. **Multimodal combinations**: Combine emotions with audio (Phase 2.A) or data (Phase 2.B)
+2. **Emotional storytelling**: Create series of images with evolving emotions
+3. **Personal emotion mapping**: Develop your own emotion-to-art style
+4. **Therapeutic applications**: Use emotional art for self-expression and healing
+
+---
+
+**Ready to transform your emotions into art?** Launch the interface and start creating emotionally-rich artwork! 🌀🎨✨

docs/PHASE2D_REALTIME_DATA_TO_IMAGE_GUIDE.md

@@ -0,0 +1,337 @@
+# CompI Phase 2.D: Real-Time Data Feeds to Image Generation
+
+## 🌎 Overview
+
+Phase 2.D connects your art to the pulse of the world through real-time data feeds. This phase integrates live weather data, breaking news, financial markets, and other real-time information to create artwork that captures the current moment in time and reflects the world's dynamic state.
+
+## ✨ Key Features
+
+### 🌐 Real-Time Data Integration
+- **Weather Data**: Live weather conditions from OpenWeatherMap API
+- **News Headlines**: Breaking news from RSS feeds and NewsAPI
+- **Financial Data**: Cryptocurrency prices and exchange rates
+- **Social Trends**: Real-time social media and trending topics (extensible)
+- **Custom RSS Feeds**: Support for any RSS/XML data source
+
+### 🧠 Intelligent Context Processing
+- **Data Summarization**: Automatic summarization of multiple data sources
+- **Mood Detection**: Extract emotional context from real-time data
+- **Theme Analysis**: Identify key themes and topics
+- **Temporal Context**: Time-aware data processing and analysis
+- **Artistic Inspiration**: Convert data patterns into creative prompts
+
+### 🔧 Technical Capabilities
+- **Data Caching**: Intelligent caching to respect API rate limits
+- **Batch Processing**: Multiple data source configurations
+- **Temporal Series**: Generate art evolution over time
+- **Error Handling**: Robust fallback mechanisms for API failures
+- **Comprehensive Metadata**: Detailed real-time context tracking
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+Ensure you have the base CompI environment set up with all dependencies from `requirements.txt`.
+
+### Additional Dependencies
+Phase 2.D uses additional packages for real-time data processing:
+```bash
+pip install requests feedparser
+```
+
+### API Keys (Optional)
+While Phase 2.D works with free data sources, you can enhance functionality with API keys:
+
+#### OpenWeatherMap (Weather Data)
+1. Sign up at [OpenWeatherMap](https://openweathermap.org/api)
+2. Get your free API key (1000 calls/day)
+3. Enter in the interface or set as environment variable
+
+#### NewsAPI (News Data)
+1. Sign up at [NewsAPI](https://newsapi.org/)
+2. Get your free API key (100 requests/day)
+3. Enter in the interface or set as environment variable
+
+**Note**: Phase 2.D works without API keys using free RSS feeds and demo keys.
+
+## 🎯 Quick Start
+
+### 1. Launch the Interface
+
+```bash
+# Navigate to your CompI project directory
+cd "C:\Users\Aksharajsinh\Documents\augment-projects\Project CompI"
+
+# Run the Phase 2.D interface
+streamlit run src/ui/compi_phase2d_streamlit_ui.py
+
+# Or use the main CompI interface
+streamlit run compi_complete_app.py
+# Then select "🌎 Phase 2.D: Real-Time Data-to-Image"
+```
+
+### 2. Basic Real-Time Generation
+
+1. **Enter your creative prompt** (e.g., "A cityscape reflecting today's energy")
+2. **Choose your art style** (e.g., "cyberpunk digital art")
+3. **Enable data sources** (Weather, News, or Financial)
+4. **Configure data settings** (city for weather, news category, etc.)
+5. **Generate** and watch real-time data transform into art!
+
+### 3. Advanced Features
+
+- **Batch Processing**: Generate multiple images with different data combinations
+- **Temporal Series**: Create art evolution over time intervals
+- **Context Strength**: Control how strongly real-time data influences the art
+- **Data Preview**: See real-time context before generation
+
+## 📚 Data Sources & Examples
+
+### 🌤️ Weather Data Integration
+
+#### Current Weather Conditions
+```python
+# Example: Sunny weather in Paris
+Weather Context: "Clear skies, 22°C, low humidity"
+Artistic Influence: "bright and optimistic atmosphere"
+Enhanced Prompt: "Parisian street scene, impressionist style, bright and optimistic atmosphere"
+```
+
+#### Weather Mood Mapping
+- **Clear/Sunny**: Bright, optimistic, radiant
+- **Cloudy**: Contemplative, soft, muted
+- **Rainy**: Melancholic, reflective, dramatic
+- **Stormy**: Intense, powerful, dynamic
+- **Snowy**: Serene, peaceful, ethereal
+- **Foggy**: Mysterious, ethereal, dreamlike
+
+### 📰 News Data Integration
+
+#### Breaking News Headlines
+```python
+# Example: Technology news
+Headlines: "AI breakthrough in medical research; New space mission launched"
+Artistic Influence: "capturing the pulse of current events, inspired by innovation"
+Enhanced Prompt: "Futuristic laboratory, sci-fi art, capturing innovation and discovery"
+```
+
+#### News Category Mapping
+- **Technology**: Futuristic, innovative, digital
+- **Science**: Discovery, exploration, analytical
+- **World**: Global, diverse, interconnected
+- **Business**: Dynamic, structured, professional
+- **General**: Contemporary, relevant, timely
+
+### 💹 Financial Data Integration
+
+#### Market Conditions
+```python
+# Example: Rising Bitcoin price
+Financial Context: "Bitcoin: $45,000 USD, USD/EUR: 0.85"
+Artistic Influence: "reflecting market dynamics and economic energy"
+Enhanced Prompt: "Abstract composition, geometric art, reflecting economic energy and growth"
+```
+
+#### Market Mood Indicators
+- **Rising Markets**: Energetic, upward, optimistic
+- **Falling Markets**: Dramatic, intense, volatile
+- **Stable Markets**: Balanced, steady, calm
+- **High Volatility**: Dynamic, chaotic, electric
+
+## 🎨 Creative Workflows
+
+### 1. Moment Capture Workflow
+**Goal**: Capture the current moment in artistic form
+
+1. **Enable all data sources** (Weather + News + Financial)
+2. **Use high context strength** (0.8-1.0)
+3. **Choose responsive styles** (abstract, impressionist, contemporary)
+4. **Generate immediately** to capture the current moment
+
+### 2. Temporal Evolution Workflow
+**Goal**: Show how the world changes over time
+
+1. **Configure temporal series** (e.g., every 30 minutes)
+2. **Use consistent prompt and style**
+3. **Enable news feeds** for evolving content
+4. **Create time-lapse art series**
+
+### 3. Location-Based Workflow
+**Goal**: Create art reflecting specific locations
+
+1. **Enable weather data** for target city
+2. **Use location-specific news** if available
+3. **Choose appropriate styles** (landscape, urban, cultural)
+4. **Incorporate local context** in prompts
+
+### 4. Thematic Workflow
+**Goal**: Focus on specific themes or topics
+
+1. **Select relevant news categories** (technology, science, etc.)
+2. **Use thematic prompts** aligned with data
+3. **Adjust context strength** based on desired influence
+4. **Create thematic art series**
+
+## 🔧 Advanced Usage
+
+### Programmatic Access
+
+```python
+from src.generators.compi_phase2d_realtime_to_image import CompIPhase2DRealTimeToImage
+
+# Initialize generator
+generator = CompIPhase2DRealTimeToImage()
+
+# Generate with weather data
+results = generator.generate_image(
+    text_prompt="A landscape reflecting today's weather",
+    style="impressionist painting",
+    include_weather=True,
+    weather_city="Tokyo",
+    weather_api_key="your_api_key",  # Optional
+    context_strength=0.8,
+    num_images=2
+)
+
+# Generate with news data
+results = generator.generate_image(
+    text_prompt="Abstract representation of current events",
+    style="modern digital art",
+    include_news=True,
+    news_category="technology",
+    max_news=5,
+    context_strength=0.7
+)
+
+# Generate with all data sources
+results = generator.generate_image(
+    text_prompt="The world's current state",
+    style="surreal digital art",
+    include_weather=True,
+    weather_city="New York",
+    include_news=True,
+    news_category="world",
+    include_financial=True,
+    context_strength=0.9
+)
+```
+
+### Batch Processing
+
+```python
+# Multiple data source configurations
+data_configs = [
+    {"include_weather": True, "weather_city": "London"},
+    {"include_news": True, "news_category": "technology"},
+    {"include_financial": True},
+    {"include_weather": True, "include_news": True, "include_financial": True}
+]
+
+results = generator.batch_process_data_sources(
+    text_prompt="Global perspectives",
+    style="contemporary art",
+    data_source_configs=data_configs,
+    context_strength=0.7
+)
+```
+
+### Temporal Series Generation
+
+```python
+# Generate art evolution over time
+results = generator.generate_temporal_series(
+    text_prompt="The changing world",
+    style="abstract expressionism",
+    data_config={
+        "include_weather": True,
+        "weather_city": "Paris",
+        "include_news": True,
+        "news_category": "general"
+    },
+    time_intervals=[0, 30, 60, 120],  # 0, 30min, 1hr, 2hr
+    context_strength=0.8
+)
+```
+
+## 📊 Understanding Real-Time Context
+
+Phase 2.D processes real-time data across multiple dimensions:
+
+### Data Processing Pipeline
+1. **Data Fetching**: Retrieve data from multiple APIs and feeds
+2. **Caching**: Store data to respect rate limits and improve performance
+3. **Analysis**: Extract mood indicators, themes, and patterns
+4. **Summarization**: Create concise summaries of current context
+5. **Artistic Translation**: Convert data insights into creative prompts
+
+### Context Components
+- **Summary**: Concise description of all data sources
+- **Mood Indicators**: Emotional context derived from data
+- **Key Themes**: Main topics and subjects identified
+- **Temporal Context**: Time-aware contextual information
+- **Artistic Inspiration**: Creative interpretation for prompt enhancement
+
+### Context Strength Levels
+- **High (0.7-1.0)**: Strong data influence, detailed context integration
+- **Medium (0.4-0.6)**: Moderate data influence, balanced integration
+- **Low (0.1-0.3)**: Subtle data influence, minimal context addition
+
+## 🎯 Tips for Best Results
+
+### Data Source Selection
+1. **Weather**: Best for location-specific, atmospheric art
+2. **News**: Ideal for contemporary, socially-relevant themes
+3. **Financial**: Great for abstract, dynamic, economic themes
+4. **Combined**: Use multiple sources for rich, complex context
+
+### Prompt Engineering
+1. **Responsive prompts**: Use prompts that can adapt to data context
+2. **Flexible styles**: Choose styles that work with various moods
+3. **Context awareness**: Consider how data might influence your vision
+4. **Temporal relevance**: Use time-aware language when appropriate
+
+### Context Strength Guidelines
+1. **High strength**: When data should drive the artistic direction
+2. **Medium strength**: For balanced data-art integration
+3. **Low strength**: When data should provide subtle inspiration
+4. **Variable strength**: Experiment to find optimal balance
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**"No real-time data available"**
+- Check internet connection
+- Verify API keys if using premium features
+- Try different data sources
+- Check API rate limits
+
+**"API connection failed"**
+- Verify API keys are correct
+- Check if APIs are operational
+- Try using free RSS feeds instead
+- Reduce request frequency
+
+**"Weak data influence"**
+- Increase context strength
+- Use more responsive prompts
+- Enable multiple data sources
+- Check data quality and relevance
+
+### Performance Optimization
+- Use data caching to reduce API calls
+- Enable only needed data sources
+- Use appropriate context strength levels
+- Monitor API rate limits and usage
+
+## 🚀 Next Steps
+
+After mastering Phase 2.D, consider:
+1. **Multimodal Fusion**: Combine real-time data with emotions (2.C) or audio (2.A)
+2. **Custom Data Sources**: Add your own RSS feeds or APIs
+3. **Temporal Art Projects**: Create long-term data evolution series
+4. **Location-Based Art**: Develop city or region-specific art projects
+5. **News Art Automation**: Set up automated news-driven art generation
+
+---
+
+**Ready to connect your art to the world's pulse?** Launch the interface and start creating real-time responsive artwork! 🌎📡🎨

docs/PHASE2E_STYLE_REFERENCE_GUIDE.md

@@ -0,0 +1,271 @@
+# CompI Phase 2.E: Style Reference/Example Image to AI Art - User Guide
+
+## 🎨 Transform Any Image into AI Art Guidance
+
+Phase 2.E allows you to use **any reference image** (from your device or the web) to guide the style, mood, and composition of your AI-generated art. Upload local files or paste URLs from Google Images, Pinterest, Instagram, or any other source!
+
+## 🚀 Quick Start
+
+### 1. **Launch the Application**
+```bash
+streamlit run src/ui/compi_phase2e_streamlit_ui.py
+```
+
+### 2. **Basic Workflow**
+1. **Enter your text prompt** - Describe what you want to create
+2. **Add reference image** - Upload file or paste web URL
+3. **Review AI suggestions** - See automatic style analysis
+4. **Adjust settings** - Control reference strength and parameters
+5. **Generate art** - Create AI art guided by your reference
+6. **Download results** - Save images with full metadata
+
+## 📸 Reference Image Sources
+
+### **Supported Input Methods**
+
+#### 🖼️ **Local File Upload**
+- **Formats**: PNG, JPG, JPEG, BMP, TIFF, WebP
+- **Size Limit**: Up to 10MB per file
+- **Quality**: Higher resolution = better style analysis
+
+#### 🌐 **Web URL Input**
+- **Google Images**: Right-click → "Copy image address"
+- **Pinterest**: Click image → Copy URL from address bar
+- **Instagram**: Use image direct links
+- **Art Websites**: DeviantArt, ArtStation, Behance
+- **Any Website**: Direct image URLs (.jpg, .png, etc.)
+
+### **URL Examples**
+```
+✅ Good URLs:
+https://example.com/artwork.jpg
+https://pinterest.com/pin/123456789/
+https://images.unsplash.com/photo-123/image.jpg
+
+❌ Avoid:
+https://website.com/gallery-page (not direct image)
+https://social-media.com/post/123 (post page, not image)
+```
+
+## 🎛️ Interface Guide
+
+### **Main Controls**
+
+#### **Text Input Section**
+- **Main Prompt**: Primary description of what you want to generate
+- **Style Keywords**: Additional artistic style descriptors
+- **Mood/Atmosphere**: Emotional tone and feeling
+
+#### **Reference Image Section**
+- **Upload Tab**: Drag & drop or browse for local files
+- **URL Tab**: Paste any web image URL
+- **Analysis Display**: Real-time style analysis and suggestions
+
+#### **Generation Settings**
+- **Reference Strength**: How closely to follow the reference (0.1-0.9)
+- **Number of Images**: Generate 1-4 variations
+- **Quality Settings**: Inference steps and guidance scale
+- **Seed Control**: Random or fixed for reproducibility
+
+### **AI Style Analysis**
+
+When you load a reference image, the AI automatically analyzes:
+
+- **Visual Properties**: Brightness, contrast, color distribution
+- **Style Characteristics**: Artistic technique, complexity, mood
+- **Suggested Keywords**: Automatically generated style descriptors
+- **Enhancement Options**: One-click addition to your prompt
+
+## ⚙️ Settings Guide
+
+### **Reference Strength Control**
+
+The reference strength determines how closely your generated art follows the reference image:
+
+| Strength | Effect | Best For |
+|----------|--------|----------|
+| **0.1-0.3** | Loose inspiration, high creativity | Abstract concepts, creative freedom |
+| **0.4-0.6** | Balanced style transfer | Most use cases, artistic guidance |
+| **0.7-0.9** | Close adherence to reference | Style mimicking, specific looks |
+
+### **Quality vs Speed Settings**
+
+| Setting | Fast (10-15 steps) | Balanced (20-30 steps) | High Quality (40-50 steps) |
+|---------|-------------------|------------------------|---------------------------|
+| **Time** | 30-60 seconds | 1-2 minutes | 3-5 minutes |
+| **Quality** | Good for testing | Recommended | Best results |
+| **Use Case** | Quick iterations | Final generation | Professional work |
+
+### **Guidance Scale**
+
+| Scale | Effect | Best For |
+|-------|--------|----------|
+| **5-10** | More creative, loose interpretation | Artistic freedom, abstract art |
+| **10-15** | Balanced prompt following | Most use cases |
+| **15-20** | Strict prompt adherence | Precise requirements |
+
+## 🎨 Creative Techniques
+
+### **Effective Reference Selection**
+
+#### ✅ **Good References**
+- **Clear artistic style** (paintings, digital art, photography styles)
+- **Strong visual identity** (distinctive colors, techniques, moods)
+- **Good composition** (well-balanced, not cluttered)
+- **High contrast** (clear light/dark areas)
+
+#### ❌ **Challenging References**
+- **Cluttered images** with too many elements
+- **Low contrast** or very dark/bright images
+- **Screenshots** or UI elements
+- **Text-heavy** images
+
+### **Prompt Enhancement Tips**
+
+#### **Combine Multiple Styles**
+```
+Base: "A serene mountain landscape"
++ Style: "oil painting, impressionist"
++ Mood: "golden hour, peaceful"
++ AI Suggestions: "soft brushstrokes, warm colors"
+= Enhanced: "A serene mountain landscape, oil painting, impressionist, golden hour, peaceful, soft brushstrokes, warm colors"
+```
+
+#### **Layer Your Descriptions**
+1. **Subject**: What you want to see
+2. **Style**: Artistic technique or medium
+3. **Mood**: Emotional atmosphere
+4. **Details**: Specific elements or effects
+
+### **Reference Strength Strategies**
+
+#### **Creative Exploration** (Low Strength: 0.2-0.4)
+- Use reference for general mood/color inspiration
+- Allow AI maximum creative freedom
+- Good for abstract or conceptual art
+
+#### **Style Transfer** (Medium Strength: 0.5-0.7)
+- Balance between reference and creativity
+- Maintain reference style while changing content
+- Most versatile approach
+
+#### **Style Mimicking** (High Strength: 0.7-0.9)
+- Close adherence to reference technique
+- Minimal creative deviation
+- Good for specific artistic styles
+
+## 📁 Output Management
+
+### **File Naming Convention**
+
+Generated files follow a comprehensive naming pattern:
+```
+{prompt}_{style}_{mood}_{timestamp}_seed{number}_{REFIMG|NOREFIMG}_v{variation}.png
+```
+
+**Example:**
+```
+magical_forest_fantasy_mystical_20250701_143022_seed12345_REFIMG_v1.png
+```
+
+### **Metadata Files**
+
+Each image includes a JSON metadata file with:
+- Complete generation parameters
+- Reference image information
+- AI style analysis results
+- Reproducibility data
+
+### **Organization Tips**
+
+- **Create project folders** for different art series
+- **Use consistent naming** for easy searching
+- **Save metadata** for reproducing successful results
+- **Export favorites** to separate collections
+
+## 🔧 Troubleshooting
+
+### **Common Issues**
+
+#### **"Failed to load image from URL"**
+- ✅ Check URL is a direct image link
+- ✅ Try right-clicking image → "Copy image address"
+- ✅ Ensure URL ends with .jpg, .png, etc.
+- ✅ Test URL in browser first
+
+#### **"Generation taking too long"**
+- ✅ Reduce inference steps (try 15-20)
+- ✅ Lower image count (try 1-2 images)
+- ✅ Check GPU memory availability
+- ✅ Restart application if needed
+
+#### **"Poor quality results"**
+- ✅ Increase inference steps (try 30-40)
+- ✅ Adjust reference strength
+- ✅ Improve prompt specificity
+- ✅ Try different reference images
+
+#### **"Out of memory errors"**
+- ✅ Enable memory optimizations in settings
+- ✅ Reduce batch size to 1 image
+- ✅ Close other applications
+- ✅ Use CPU mode if necessary
+
+### **Performance Optimization**
+
+#### **For Better Speed**
+- Use GPU if available
+- Enable memory optimizations
+- Start with lower inference steps
+- Generate fewer images per batch
+
+#### **For Better Quality**
+- Use high-resolution reference images
+- Increase inference steps (30-50)
+- Fine-tune reference strength
+- Use descriptive, specific prompts
+
+## 🎯 Best Practices
+
+### **Reference Image Selection**
+1. **Choose clear, high-quality images**
+2. **Match the style you want to achieve**
+3. **Consider color palette and mood**
+4. **Test different reference strengths**
+
+### **Prompt Writing**
+1. **Be specific about desired elements**
+2. **Use artistic terminology**
+3. **Describe lighting and atmosphere**
+4. **Combine multiple style keywords**
+
+### **Iterative Improvement**
+1. **Start with medium reference strength**
+2. **Generate multiple variations**
+3. **Adjust settings based on results**
+4. **Save successful parameter combinations**
+
+### **Workflow Efficiency**
+1. **Prepare reference images in advance**
+2. **Use consistent naming conventions**
+3. **Save metadata for reproducibility**
+4. **Organize outputs by project/style**
+
+## 🚀 Advanced Tips
+
+### **Multi-Style Blending**
+- Use reference for base style
+- Add contrasting style keywords
+- Experiment with different strengths
+
+### **Series Creation**
+- Use same reference with different prompts
+- Maintain consistent style across images
+- Vary only specific elements
+
+### **Style Evolution**
+- Start with high reference strength
+- Gradually reduce for more creativity
+- Create progression series
+
+This guide provides everything you need to master CompI Phase 2.E and create stunning AI art guided by any reference image!

docs/PHASE3E_PERFORMANCE_GUIDE.md

@@ -0,0 +1,301 @@
+# ⚙️ CompI Phase 3.E: Performance, Model Management & Reliability - Complete Guide
+
+## 🎯 **What Phase 3.E Delivers**
+
+**Phase 3.E transforms CompI into a production-grade platform with professional performance management, intelligent reliability, and advanced model capabilities.**
+
+### **🤖 Model Manager**
+- **Dynamic Model Switching**: Switch between SD 1.5 and SDXL based on requirements
+- **Auto-Availability Checking**: Intelligent detection of model compatibility and VRAM requirements
+- **Universal LoRA Support**: Load and scale LoRA weights across all models and generation modes
+- **Smart Recommendations**: Hardware-based model suggestions and optimization advice
+
+### **⚡ Performance Controls**
+- **xFormers Integration**: Memory-efficient attention with automatic fallback
+- **Advanced Memory Optimization**: Attention slicing, VAE slicing/tiling, CPU offloading
+- **Precision Control**: Automatic dtype selection (fp16/bf16/fp32) based on hardware
+- **Batch Optimization**: Memory-aware batch processing with intelligent sizing
+
+### **📊 VRAM Monitoring**
+- **Real-time Tracking**: Live GPU memory usage monitoring and alerts
+- **Usage Analytics**: Memory usage patterns and optimization suggestions
+- **Threshold Warnings**: Automatic alerts when approaching memory limits
+- **Cache Management**: Intelligent GPU cache clearing and memory cleanup
+
+### **🛡️ Reliability Engine**
+- **OOM-Safe Generation**: Automatic retry with progressive fallback strategies
+- **Intelligent Fallbacks**: Reduce size → reduce steps → CPU fallback progression
+- **Error Classification**: Smart error detection and appropriate response strategies
+- **Graceful Degradation**: Maintain functionality even under resource constraints
+
+### **📦 Batch Processing**
+- **Seed-Controlled Batches**: Deterministic seed sequences for reproducible results
+- **Memory-Aware Batching**: Automatic batch size optimization based on available VRAM
+- **Progress Tracking**: Detailed progress monitoring with per-image status
+- **Failure Recovery**: Continue batch processing even if individual images fail
+
+### **🔍 Upscaler Integration**
+- **Latent Upscaler**: Optional 2x upscaling using Stable Diffusion Latent Upscaler
+- **Graceful Degradation**: Clean fallback when upscaler unavailable
+- **Memory Management**: Intelligent memory allocation for upscaling operations
+- **Quality Enhancement**: Professional-grade image enhancement capabilities
+
+---
+
+## 🚀 **Quick Start Guide**
+
+### **1. Launch Phase 3.E**
+```bash
+# Method 1: Using launcher script (recommended)
+python run_phase3e_performance_manager.py
+
+# Method 2: Direct Streamlit launch
+streamlit run src/ui/compi_phase3e_performance_manager.py --server.port 8505
+```
+
+### **2. System Requirements Check**
+The launcher automatically checks:
+- **GPU Setup**: CUDA availability and VRAM capacity
+- **Dependencies**: Required and optional packages
+- **Model Support**: SD 1.5 and SDXL availability
+- **Performance Features**: xFormers and upscaler support
+
+### **3. Access the Interface**
+- **URL:** `http://localhost:8505`
+- **Interface:** Professional Streamlit dashboard with real-time monitoring
+- **Sidebar:** Live VRAM monitoring and system status
+
+---
+
+## 🎨 **Professional Workflow**
+
+### **Step 1: Model Selection**
+1. **Choose Base Model**: SD 1.5 (fast, compatible) or SDXL (high quality, more VRAM)
+2. **Select Generation Mode**: txt2img or img2img
+3. **Check Compatibility**: System automatically validates model/mode combinations
+4. **Review VRAM Requirements**: See memory requirements and availability status
+
+### **Step 2: LoRA Integration (Optional)**
+1. **Enable LoRA**: Toggle LoRA support
+2. **Specify Path**: Enter path to LoRA weights (diffusers format)
+3. **Set Scale**: Adjust LoRA influence (0.1-2.0)
+4. **Verify Status**: Check LoRA loading status and compatibility
+
+### **Step 3: Performance Optimization**
+1. **Choose Optimization Level**: Conservative, Balanced, Aggressive, or Extreme
+2. **Monitor VRAM**: Watch real-time memory usage in sidebar
+3. **Adjust Settings**: Fine-tune individual optimization features
+4. **Enable Reliability**: Configure OOM retry and CPU fallback options
+
+### **Step 4: Generation**
+1. **Single Images**: Generate individual images with full control
+2. **Batch Processing**: Create multiple images with seed sequences
+3. **Monitor Progress**: Track generation progress and memory usage
+4. **Review Results**: Analyze generation statistics and performance metrics
+
+---
+
+## 🔧 **Advanced Features**
+
+### **🤖 Model Manager Deep Dive**
+
+#### **Model Compatibility Matrix**
+```python
+SD 1.5:
+  ✅ txt2img (512x512 optimal)
+  ✅ img2img (all strengths)
+  ✅ ControlNet (full support)
+  ✅ LoRA (universal compatibility)
+  💾 VRAM: 4+ GB recommended
+
+SDXL:
+  ✅ txt2img (1024x1024 optimal)
+  ✅ img2img (limited support)
+  ⚠️ ControlNet (requires special handling)
+  ✅ LoRA (SDXL-compatible weights only)
+  💾 VRAM: 8+ GB recommended
+```
+
+#### **Automatic Model Selection Logic**
+- **VRAM < 6GB**: Recommends SD 1.5 only
+- **VRAM 6-8GB**: SD 1.5 preferred, SDXL with warnings
+- **VRAM 8GB+**: Full SDXL support with optimizations
+- **CPU Mode**: SD 1.5 only with aggressive optimizations
+
+### **⚡ Performance Optimization Levels**
+
+#### **Conservative Mode**
+- Basic attention slicing
+- Standard precision (fp16/fp32)
+- Minimal memory optimizations
+- **Best for**: Stable systems, first-time users
+
+#### **Balanced Mode (Default)**
+- xFormers attention (if available)
+- Attention + VAE slicing
+- Automatic precision selection
+- **Best for**: Most users, good performance/stability balance
+
+#### **Aggressive Mode**
+- All memory optimizations enabled
+- VAE tiling for large images
+- Maximum memory efficiency
+- **Best for**: Limited VRAM, large batch processing
+
+#### **Extreme Mode**
+- CPU offloading enabled
+- Maximum memory savings
+- Slower but uses minimal VRAM
+- **Best for**: Very limited VRAM (<4GB)
+
+### **🛡️ Reliability Engine Strategies**
+
+#### **Fallback Progression**
+```python
+Strategy 1: Original settings (100% size, 100% steps)
+Strategy 2: Reduced size (75% size, 90% steps)  
+Strategy 3: Half size (50% size, 80% steps)
+Strategy 4: Minimal (50% size, 60% steps)
+Final: CPU fallback if all GPU attempts fail
+```
+
+#### **Error Classification**
+- **CUDA OOM**: Triggers progressive fallback
+- **Model Loading**: Suggests alternative models
+- **LoRA Errors**: Disables LoRA and retries
+- **General Errors**: Logs and reports with context
+
+### **📊 VRAM Monitoring System**
+
+#### **Real-time Metrics**
+- **Total VRAM**: Hardware capacity
+- **Used VRAM**: Currently allocated memory
+- **Free VRAM**: Available for new operations
+- **Usage Percentage**: Current utilization level
+
+#### **Smart Alerts**
+- **Green (0-60%)**: Optimal usage
+- **Yellow (60-80%)**: Moderate usage, monitor closely
+- **Red (80%+)**: High usage, optimization recommended
+
+#### **Memory Management**
+- **Automatic Cache Clearing**: Between batch generations
+- **Memory Leak Detection**: Identifies and resolves memory issues
+- **Optimization Suggestions**: Hardware-specific recommendations
+
+---
+
+## 📈 **Performance Benchmarks**
+
+### **Generation Speed Comparison**
+```
+SD 1.5 (512x512, 20 steps):
+  RTX 4090: ~15-25 seconds
+  RTX 3080: ~25-35 seconds  
+  RTX 2080: ~45-60 seconds
+  CPU: ~5-10 minutes
+
+SDXL (1024x1024, 20 steps):
+  RTX 4090: ~30-45 seconds
+  RTX 3080: ~60-90 seconds
+  RTX 2080: ~2-3 minutes (with optimizations)
+  CPU: ~15-30 minutes
+```
+
+### **Memory Usage Patterns**
+```
+SD 1.5:
+  Base: ~3.5GB VRAM
+  + LoRA: ~3.7GB VRAM
+  + Upscaler: ~5.5GB VRAM
+
+SDXL:
+  Base: ~6.5GB VRAM
+  + LoRA: ~7.0GB VRAM  
+  + Upscaler: ~9.0GB VRAM
+```
+
+---
+
+## 🔍 **Troubleshooting Guide**
+
+### **Common Issues & Solutions**
+
+#### **"CUDA Out of Memory" Errors**
+1. **Enable OOM Auto-Retry**: Automatic fallback handling
+2. **Reduce Image Size**: Use 512x512 instead of 1024x1024
+3. **Lower Batch Size**: Generate fewer images simultaneously
+4. **Enable Aggressive Optimizations**: Use VAE slicing/tiling
+5. **Clear GPU Cache**: Use sidebar "Clear GPU Cache" button
+
+#### **Slow Generation Speed**
+1. **Enable xFormers**: Significant speed improvement if available
+2. **Use Balanced Optimization**: Good speed/quality trade-off
+3. **Reduce Inference Steps**: 15-20 steps often sufficient
+4. **Check VRAM Usage**: Ensure not hitting memory limits
+
+#### **Model Loading Failures**
+1. **Check Internet Connection**: Models download on first use
+2. **Verify Disk Space**: Models require 2-7GB storage each
+3. **Try Alternative Model**: Switch between SD 1.5 and SDXL
+4. **Clear Model Cache**: Remove cached models and re-download
+
+#### **LoRA Loading Issues**
+1. **Verify Path**: Ensure LoRA files exist at specified path
+2. **Check Format**: Use diffusers-compatible LoRA weights
+3. **Model Compatibility**: Ensure LoRA matches base model type
+4. **Scale Adjustment**: Try different LoRA scale values
+
+---
+
+## 🎯 **Best Practices**
+
+### **📝 Performance Optimization**
+1. **Start Conservative**: Begin with balanced settings, adjust as needed
+2. **Monitor VRAM**: Keep usage below 80% for stability
+3. **Batch Wisely**: Use smaller batches on limited hardware
+4. **Clear Cache Regularly**: Prevent memory accumulation
+
+### **🤖 Model Selection**
+1. **SD 1.5 for Speed**: Faster generation, lower VRAM requirements
+2. **SDXL for Quality**: Higher resolution, better detail
+3. **Match Hardware**: Choose model based on available VRAM
+4. **Test Compatibility**: Verify model works with your use case
+
+### **🛡️ Reliability**
+1. **Enable Auto-Retry**: Let system handle OOM errors automatically
+2. **Use Fallbacks**: Allow progressive degradation for reliability
+3. **Monitor Logs**: Check run logs for patterns and issues
+4. **Plan for Failures**: Design workflows that handle generation failures
+
+---
+
+## 🚀 **Integration with CompI Ecosystem**
+
+### **Universal Enhancement**
+Phase 3.E enhances ALL existing CompI components:
+- **Ultimate Dashboard**: Model switching and performance controls
+- **Phase 2.A-2.E**: Reliability and optimization for all multimodal phases
+- **Phase 1.A-1.E**: Enhanced foundation with professional features
+- **Phase 3.D**: Performance metrics in workflow management
+
+### **Backward Compatibility**
+- **Graceful Degradation**: Works on all hardware configurations
+- **Default Settings**: Optimal defaults for most users
+- **Progressive Enhancement**: Advanced features when available
+- **Legacy Support**: Maintains compatibility with existing workflows
+
+---
+
+## 🎉 **Phase 3.E: Production-Grade CompI Complete**
+
+**Phase 3.E transforms CompI into a production-grade platform with professional performance management, intelligent reliability, and advanced model capabilities.**
+
+**Key Benefits:**
+- ✅ **Professional Performance**: Industry-standard optimization and monitoring
+- ✅ **Intelligent Reliability**: Automatic error handling and recovery
+- ✅ **Advanced Model Management**: Dynamic switching and LoRA integration
+- ✅ **Production Ready**: Suitable for commercial and professional use
+- ✅ **Universal Enhancement**: Improves all existing CompI features
+
+**CompI is now a complete, production-grade multimodal AI art generation platform!** 🎨✨

docs/PHASE3_FINAL_DASHBOARD_GUIDE.md

@@ -0,0 +1,274 @@
+# 🧪 CompI Phase 3 Final Dashboard - Complete Integration Guide
+
+## 🎯 **What This Delivers**
+
+**The Phase 3 Final Dashboard is the ultimate CompI interface that integrates ALL Phase 3 components into a single, unified creative environment.**
+
+### **🚀 Complete Feature Integration:**
+
+#### **🧩 Phase 3.A/3.B: True Multimodal Fusion**
+- **Real Audio Processing**: Whisper transcription + librosa feature analysis
+- **Actual Data Analysis**: CSV processing + mathematical formula evaluation
+- **Sentiment Analysis**: TextBlob emotion detection with polarity scoring
+- **Live Real-time Data**: Weather API + RSS news feeds integration
+- **Intelligent Fusion**: All inputs combined into enhanced prompts
+
+#### **🖼️ Phase 3.C: Advanced References**
+- **Multi-Reference Support**: Upload files + paste URLs simultaneously
+- **Role-Based Assignment**: Separate style vs structure reference selection
+- **Live ControlNet Previews**: Real-time Canny/Depth map generation
+- **Hybrid Generation**: CN+I2I with intelligent fallback to two-pass approach
+- **Professional Controls**: Fine-grained parameter control for all aspects
+
+#### **⚙️ Phase 3.E: Performance Management**
+- **Model Switching**: SD 1.5 ↔ SDXL with automatic availability checking
+- **LoRA Integration**: Load and scale LoRA weights with visual feedback
+- **Performance Optimizations**: xFormers, attention slicing, VAE optimizations
+- **VRAM Monitoring**: Real-time GPU memory usage tracking
+- **OOM Recovery**: Progressive fallback with intelligent retry strategies
+- **Optional Upscaling**: Latent upscaler integration for quality enhancement
+
+#### **🎛️ Phase 3.D: Professional Workflow**
+- **Advanced Gallery**: Image filtering by mode, prompt, steps with visual grid
+- **Annotation System**: Rating (1-5), tags, notes for comprehensive organization
+- **Preset Management**: Save/load complete generation configurations
+- **Export Bundles**: Complete ZIP packages with images, metadata, annotations, presets
+
+---
+
+## 🏗️ **Architecture Overview**
+
+### **7-Tab Unified Interface:**
+```python
+1. 🧩 Inputs (Text/Audio/Data/Emotion/Real‑time)  # Phase 3.A/3.B
+2. 🖼️ Advanced References                          # Phase 3.C
+3. ⚙️ Model & Performance                          # Phase 3.E
+4. 🎛️ Generate                                     # Unified generation
+5. 🖼️ Gallery & Annotate                          # Phase 3.D
+6. 💾 Presets                                      # Phase 3.D
+7. 📦 Export                                       # Phase 3.D
+```
+
+### **Intelligent Generation Modes:**
+```python
+# Smart mode selection based on available inputs:
+mode = "T2I"                                    # Text-to-Image (baseline)
+if have_cn and have_style: mode = "CN+I2I"     # Hybrid ControlNet + Img2Img
+elif have_cn: mode = "CN"                      # ControlNet only
+elif have_style: mode = "I2I"                  # Img2Img only
+```
+
+### **Real-time Performance Monitoring:**
+```python
+# Live VRAM tracking in header
+colA: Device (CUDA/CPU)
+colB: Total VRAM (GB)
+colC: Used VRAM (GB)  
+colD: PyTorch version + status
+```
+
+---
+
+## 🎨 **Professional Workflow**
+
+### **Complete Creative Process:**
+
+#### **1. Configure Multimodal Inputs (Tab 1)**
+- **Text & Style**: Main prompt, artistic style, mood, negative prompt
+- **Audio Analysis**: Upload audio → Whisper transcription → librosa features
+- **Data Processing**: CSV upload or mathematical formulas → visualization
+- **Emotion Analysis**: Sentiment analysis with TextBlob polarity scoring
+- **Real-time Feeds**: Weather data + news headlines integration
+
+#### **2. Advanced References (Tab 2)**
+- **Multi-Reference Upload**: Files + URLs simultaneously supported
+- **Role Assignment**: Select images for style influence vs structure control
+- **ControlNet Integration**: Choose Canny or Depth with live preview
+- **Parameter Control**: Conditioning scale, img2img strength adjustment
+
+#### **3. Model & Performance (Tab 3)**
+- **Model Selection**: SD 1.5 (fast) or SDXL (quality) based on VRAM
+- **LoRA Integration**: Load custom LoRA weights with scale control
+- **Performance Tuning**: xFormers, attention slicing, VAE optimizations
+- **Reliability Settings**: OOM auto-retry, batch processing, upscaling
+
+#### **4. Intelligent Generation (Tab 4)**
+- **Fusion Preview**: See combined prompt from all inputs
+- **Smart Mode Selection**: Automatic best approach based on available inputs
+- **Batch Processing**: Multiple images with seed control
+- **Real-time Feedback**: Progress tracking and error handling
+
+#### **5. Gallery Management (Tab 5)**
+- **Advanced Filtering**: By mode, prompt content, generation parameters
+- **Visual Gallery**: 4-column grid with image previews and metadata
+- **Annotation System**: Rate (1-5), tag, and add notes to images
+- **Batch Operations**: Select multiple images for annotation
+
+#### **6. Preset System (Tab 6)**
+- **Configuration Capture**: Save complete generation settings
+- **JSON Preview**: See exact preset structure before saving
+- **Load Management**: Browse and load existing presets
+- **Reusability**: Apply saved settings to new generations
+
+#### **7. Export Bundles (Tab 7)**
+- **Complete Packages**: Images + metadata + annotations + presets
+- **Reproducibility**: Full environment snapshots for exact reproduction
+- **Professional Format**: ZIP bundles with manifest and README
+- **Selective Export**: Choose specific images and include optional presets
+
+---
+
+## 🚀 **Quick Start Guide**
+
+### **1. Launch the Dashboard**
+```bash
+# Method 1: Using launcher (recommended)
+python run_phase3_final_dashboard.py
+
+# Method 2: Direct Streamlit launch
+streamlit run src/ui/compi_phase3_final_dashboard.py --server.port 8506
+```
+
+### **2. Access the Interface**
+- **URL:** `http://localhost:8506`
+- **Interface:** Professional 7-tab dashboard with real-time monitoring
+- **Header:** Live VRAM usage and system status
+
+### **3. Basic Workflow**
+1. **Configure Inputs**: Set up text, audio, data, emotion, real-time feeds
+2. **Add References**: Upload images and assign style/structure roles
+3. **Choose Model**: Select SD 1.5 or SDXL based on your hardware
+4. **Generate**: Create art with intelligent fusion of all inputs
+5. **Review & Annotate**: Rate and organize results in gallery
+6. **Save & Export**: Create presets and export complete bundles
+
+---
+
+## 🔧 **Advanced Features**
+
+### **🎵 Audio Processing Pipeline**
+```python
+# Complete audio analysis chain:
+1. Upload audio file (.wav/.mp3)
+2. Librosa feature extraction (tempo, energy, ZCR)
+3. Whisper transcription (base model)
+4. Intelligent tag generation
+5. Prompt enhancement with audio context
+```
+
+### **📊 Data Integration System**
+```python
+# Dual data processing modes:
+1. CSV Upload: Pandas analysis → statistical summary → visualization
+2. Formula Mode: NumPy evaluation → pattern generation → plotting
+3. Poetic summarization for prompt enhancement
+```
+
+### **🖼️ Advanced Reference System**
+```python
+# Role-based reference processing:
+Style References: Used for img2img artistic influence
+Structure References: Used for ControlNet composition control
+Live Previews: Real-time Canny/Depth map generation
+Hybrid Modes: CN+I2I with intelligent fallback strategies
+```
+
+### **⚡ Performance Optimization**
+```python
+# Multi-level optimization system:
+1. xFormers: Memory-efficient attention (if available)
+2. Attention Slicing: Reduce memory usage
+3. VAE Slicing/Tiling: Handle large images efficiently
+4. OOM Recovery: Progressive fallback (size → steps → CPU)
+5. VRAM Monitoring: Real-time usage tracking
+```
+
+### **🛡️ Reliability Features**
+```python
+# Production-grade error handling:
+1. Graceful Degradation: Features work even when components unavailable
+2. Intelligent Fallbacks: CN+I2I → two-pass approach when needed
+3. OOM Recovery: Automatic retry with reduced parameters
+4. Error Classification: Specific handling for different error types
+```
+
+---
+
+## 📊 **Performance Benchmarks**
+
+### **Generation Speed (Approximate)**
+```
+SD 1.5 (512x512, 20 steps):
+  RTX 4090: ~15-25 seconds
+  RTX 3080: ~25-35 seconds
+  RTX 2080: ~45-60 seconds
+  CPU: ~5-10 minutes
+
+SDXL (1024x1024, 20 steps):
+  RTX 4090: ~30-45 seconds
+  RTX 3080: ~60-90 seconds
+  RTX 2080: ~2-3 minutes (with optimizations)
+  CPU: ~15-30 minutes
+```
+
+### **Memory Requirements**
+```
+SD 1.5 Base: ~3.5GB VRAM
+SD 1.5 + LoRA: ~3.7GB VRAM
+SD 1.5 + Upscaler: ~5.5GB VRAM
+
+SDXL Base: ~6.5GB VRAM
+SDXL + LoRA: ~7.0GB VRAM
+SDXL + Upscaler: ~9.0GB VRAM
+```
+
+---
+
+## 🎯 **Best Practices**
+
+### **📝 Optimal Workflow**
+1. **Start Simple**: Begin with text-only generation to test setup
+2. **Add Gradually**: Introduce multimodal inputs one at a time
+3. **Monitor VRAM**: Keep usage below 80% for stability
+4. **Use Presets**: Save successful configurations for reuse
+5. **Export Regularly**: Create bundles of your best work
+
+### **🤖 Model Selection**
+1. **SD 1.5 for Speed**: Faster generation, lower VRAM, wide compatibility
+2. **SDXL for Quality**: Higher resolution, better detail, requires more VRAM
+3. **Match Hardware**: Choose model based on available VRAM
+4. **Test First**: Verify model works with your specific use case
+
+### **🖼️ Reference Usage**
+1. **Style References**: Use 2-4 images for artistic influence
+2. **Structure Reference**: Use 1 clear image for composition control
+3. **Quality Matters**: Higher quality references produce better results
+4. **Role Clarity**: Clearly separate style vs structure purposes
+
+### **⚡ Performance Tuning**
+1. **Enable xFormers**: Significant speed improvement if available
+2. **Use Attention Slicing**: Always enable for memory efficiency
+3. **Monitor Usage**: Watch VRAM meter and adjust accordingly
+4. **Batch Wisely**: Use smaller batches on limited hardware
+
+---
+
+## 🎉 **Phase 3 Complete Achievement**
+
+**The Phase 3 Final Dashboard represents the complete realization of the CompI vision: a unified, production-grade, multimodal AI art generation platform.**
+
+### **✅ All Phase 3 Components Integrated:**
+- **✅ Phase 3.A**: Multimodal input processing
+- **✅ Phase 3.B**: True fusion engine with real processing
+- **✅ Phase 3.C**: Advanced references with role assignment
+- **✅ Phase 3.D**: Professional workflow management
+- **✅ Phase 3.E**: Performance optimization and model management
+
+### **🚀 Key Benefits:**
+- **Single Interface**: All CompI features in one unified dashboard
+- **Professional Workflow**: From input to export in one seamless process
+- **Production Ready**: Robust error handling and performance optimization
+- **Universal Compatibility**: Works across different hardware configurations
+- **Complete Integration**: All phases work together harmoniously
+
+**CompI Phase 3 is now complete - the ultimate multimodal AI art generation platform!** 🎨✨

docs/PHASE4_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,110 @@
+# Phase 4: Web Deployment Guide
+
+## Overview
+
+Phase 4 deploys CompI to Hugging Face Spaces with automatic CI/CD from GitHub. This enables public access to your multimodal AI art generation platform.
+
+## 4.A: Repository Preparation ✅
+
+The following files have been added to your repo:
+
+- `packages.txt` - System dependencies for audio processing and OpenGL
+- `.gitattributes` - Git LFS configuration for model files
+- `requirements.txt` - Already present with Python dependencies
+
+## 4.B: Create Hugging Face Space
+
+### Step 1: Create New Space
+
+1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
+2. Click "Create new Space"
+3. Choose:
+   - **SDK**: Streamlit
+   - **Space name**: `compi-final-dashboard` (or your preference)
+   - **Visibility**: Public
+   - **Hardware**: CPU basic (free tier)
+
+### Step 2: Configure Space README
+
+Replace the default README.md in your Space with:
+
+```markdown
+---
+title: CompI — Final Dashboard
+emoji: 🎨
+sdk: streamlit
+app_file: src/ui/compi_phase3_final_dashboard.py
+pinned: false
+---
+
+# CompI - Multimodal AI Art Generation Platform
+
+The ultimate creative platform combining text, audio, data, emotion, and real-time inputs for AI art generation.
+
+## Features
+
+🧩 **Multimodal Inputs** - Text, Audio, Data, Emotion, Real-time feeds
+🖼️ **Advanced References** - Multi-image upload with role assignment  
+⚙️ **Model Management** - SD 1.5/SDXL switching, LoRA integration
+🖼️ **Professional Gallery** - Filtering, rating, annotation system
+💾 **Preset Management** - Save/load complete configurations
+📦 **Export System** - Complete bundles with metadata
+
+## Usage
+
+1. Configure your inputs in the "Inputs" tab
+2. Upload reference images in "Advanced References" 
+3. Choose your model and performance settings
+4. Generate with intelligent fusion of all inputs
+5. Review results in the gallery and export bundles
+
+Built with Streamlit, PyTorch, and Diffusers.
+```
+
+### Step 3: Add Secrets (Optional)
+
+In your Space Settings → Repository secrets, add:
+- `OPENWEATHER_KEY` - Your OpenWeatherMap API key for real-time weather data
+
+**Important**: Do NOT link the Space to GitHub yet. We'll deploy via CI/CD.
+
+## 4.C: GitHub Actions Setup
+
+### Step 1: Add GitHub Secrets
+
+In your GitHub repo, go to Settings → Secrets and variables → Actions:
+
+1. **New repository secret**: `HF_TOKEN`
+   - Value: Your Hugging Face **Write** token from [HF Settings → Access Tokens](https://huggingface.co/settings/tokens)
+
+2. **New repository secret**: `HF_SPACE_ID` 
+   - Value: `your-username/your-space-name` (e.g., `AXRZCE/compi-final-dashboard`)
+
+### Step 2: GitHub Actions Workflow
+
+The workflow file `.github/workflows/deploy-to-hf-spaces.yml` will be created next.
+
+## 4.D: Runtime Optimization
+
+Default settings optimized for free CPU tier:
+- **Model**: SD 1.5 (faster than SDXL)
+- **Resolution**: 512×512 (good quality/speed balance)
+- **Steps**: 20-24 (sufficient for good results)
+- **Batch size**: 1 (memory efficient)
+- **ControlNet**: Off by default (users can enable)
+
+## 4.E: Deployment Workflow
+
+1. **Development**: Work on feature branches
+2. **Testing**: Test locally with `streamlit run src/ui/compi_phase3_final_dashboard.py`
+3. **Deploy**: Merge to `main` → GitHub Actions automatically deploys to HF Space
+4. **Rollback**: Revert commit on `main` if issues occur
+
+## Next Steps
+
+1. Complete the HF Space setup above
+2. Add GitHub secrets
+3. The GitHub Actions workflow will be created automatically
+4. Test deployment by pushing to `main`
+
+Your deployed app will be available at: `https://your-username-your-space.hf.space`

docs/PHASE4_RUNTIME_OPTIMIZATION.md

@@ -0,0 +1,111 @@
+# Phase 4.D: Runtime Optimization for Free CPU Deployment
+
+## Current Default Settings Analysis
+
+The CompI Phase 3 Final Dashboard is already well-optimized for free CPU deployment with the following defaults:
+
+### Model Selection Defaults
+- **Base Model**: SD 1.5 (v1-5) - Fast and CPU-friendly
+- **Generation Mode**: txt2img - Most efficient mode
+- **SDXL**: Available but not default (requires more resources)
+
+### Image Generation Defaults
+- **Width**: 512px (optimal balance of quality/speed)
+- **Height**: 512px (standard square format)
+- **Steps**: 30 (good quality with reasonable speed)
+- **Guidance**: 7.5 (balanced prompt adherence)
+- **Batch Size**: 1 (memory efficient)
+- **Seed**: 0 (random, no additional computation)
+
+### Performance Optimizations (Already Enabled)
+- **xFormers**: Enabled by default for memory efficiency
+- **Attention Slicing**: Enabled to reduce VRAM usage
+- **VAE Slicing**: Enabled for memory optimization
+- **VAE Tiling**: Available for large images
+- **OOM Auto-retry**: Enabled with progressive size reduction
+
+### Advanced Features (Disabled by Default)
+- **ControlNet**: Off by default (users can enable in References tab)
+- **LoRA**: Off by default (optional enhancement)
+- **Upsampling**: Off by default (2x processing time)
+
+## CPU-Specific Optimizations
+
+### Automatic Fallback Sizes
+The app includes intelligent OOM recovery with progressive fallbacks:
+1. Original size (e.g., 512x512, 30 steps)
+2. Half size (384x384, 22 steps)
+3. Safe size (384x384, 18 steps)
+4. Minimal size (256x256, 14 steps)
+
+### Fast Preset Available
+Users can click "🧼 Reset to defaults" or use the "Fast" preset:
+- SD 1.5 model
+- 512x512 resolution
+- 30 steps
+- All optimizations enabled
+
+## Recommended Settings for Free Tier
+
+### For Best Performance
+```
+Model: SD 1.5 (v1-5)
+Resolution: 512x512 or 448x448
+Steps: 20-25
+Guidance: 7.5
+Batch: 1
+ControlNet: Off
+LoRA: Off
+Upsampling: Off
+```
+
+### For Higher Quality (Slower)
+```
+Model: SD 1.5 (v1-5)
+Resolution: 768x512 or 512x768
+Steps: 30-35
+Guidance: 7.0-8.0
+Batch: 1
+ControlNet: Optional
+LoRA: Optional (if available)
+```
+
+## User Guidance in UI
+
+The app provides helpful guidance:
+- VRAM safety indicators with color-coded warnings
+- Quick tips in expandable sections
+- Preset buttons for common use cases
+- Performance optimization toggles with explanations
+
+## Deployment Considerations
+
+### Hugging Face Spaces Free Tier
+- **CPU**: 2 vCPUs
+- **RAM**: 16GB
+- **Storage**: 50GB
+- **Timeout**: 48 hours idle
+
+### Expected Performance
+- **512x512, 20 steps**: ~30-60 seconds per image
+- **768x512, 30 steps**: ~60-120 seconds per image
+- **With ControlNet**: +50-100% generation time
+- **With LoRA**: +10-20% generation time
+
+## Monitoring and Optimization
+
+The dashboard includes:
+- Real-time VRAM monitoring (when available)
+- Generation time tracking
+- Automatic error recovery
+- Progressive quality degradation on resource constraints
+
+## Conclusion
+
+The CompI Phase 3 Final Dashboard is already optimized for free CPU deployment with:
+- Sensible defaults for speed/quality balance
+- Automatic fallback mechanisms
+- User-friendly performance controls
+- Clear guidance for optimization
+
+No code changes are required for Phase 4.D - the existing defaults are optimal for free tier deployment.

docs/PROJECT_STRUCTURE.md

@@ -0,0 +1,158 @@
+# CompI Project Structure
+
+This document outlines the organized structure of the CompI (Compositional Intelligence) project.
+
+## 📁 Directory Structure
+
+```
+Project CompI/
+├── 📁 src/                          # Source code (organized modules)
+│   ├── 📁 generators/               # Image generation modules
+│   │   ├── __init__.py             # Module initialization
+│   │   ├── compi_phase1_text2image.py          # Basic text-to-image
+│   │   ├── compi_phase1_advanced.py            # Advanced generation
+│   │   ├── compi_phase1b_styled_generation.py  # Style conditioning
+│   │   ├── compi_phase1b_advanced_styling.py   # Advanced styling
+│   │   ├── compi_phase1d_evaluate_quality.py   # Quality evaluation (Streamlit)
+│   │   ├── compi_phase1d_cli_evaluation.py     # Quality evaluation (CLI)
+│   │   ├── compi_phase1e_dataset_prep.py       # LoRA dataset preparation
+│   │   ├── compi_phase1e_lora_training.py      # LoRA fine-tuning
+│   │   ├── compi_phase1e_style_generation.py   # Personal style generation
+│   │   └── compi_phase1e_style_manager.py      # LoRA style management
+│   ├── 📁 models/                   # Model implementations (future)
+│   ├── 📁 utils/                    # Utility functions
+│   │   ├── __init__.py
+│   │   ├── logging_utils.py
+│   │   └── file_utils.py
+│   ├── 📁 data/                     # Data processing modules (future)
+│   ├── 📁 ui/                       # User interface components (future)
+│   ├── config.py                    # Project configuration
+│   ├── setup_env.py                 # Environment setup script
+│   └── test_setup.py                # Environment testing
+├── 📁 notebooks/                    # Jupyter notebooks
+│   └── 01_getting_started.ipynb    # Tutorial notebook
+├── 📁 data/                         # Dataset storage
+├── 📁 outputs/                      # Generated content
+│   ├── images/                      # Generated images
+│   └── metadata/                    # Generation metadata
+├── 📁 tests/                        # Unit tests (future)
+├── 🐍 run_basic_generation.py       # Convenience: Basic generation
+├── 🐍 run_advanced_generation.py    # Convenience: Advanced generation
+├── 🐍 run_styled_generation.py      # Convenience: Style conditioning
+├── 🐍 run_advanced_styling.py       # Convenience: Advanced styling
+├── 🐍 run_evaluation.py             # Convenience: Quality evaluation
+├── 🐍 run_lora_training.py          # Convenience: LoRA training
+├── 🐍 run_style_generation.py       # Convenience: Personal style generation
+├── 📄 requirements.txt              # Python dependencies
+├── 📄 development.md                # Development roadmap
+├── 📄 PHASE1_USAGE.md              # Phase 1 usage guide
+├── 📄 PROJECT_STRUCTURE.md         # This file
+├── 📄 .gitignore                   # Git ignore rules
+└── 📄 README.md                    # Project overview
+```
+
+## 🚀 Usage Patterns
+
+### Convenience Scripts (Recommended)
+
+Run from project root for easy access:
+
+```bash
+# Basic text-to-image generation
+python run_basic_generation.py "prompt here"
+
+# Advanced generation with options
+python run_advanced_generation.py "prompt" --negative "unwanted" --steps 50
+
+# Interactive style selection
+python run_styled_generation.py
+
+# Advanced style conditioning
+python run_advanced_styling.py "prompt" --style "oil painting" --mood "dramatic"
+
+# Quality evaluation interface
+python run_evaluation.py
+
+# LoRA personal style training
+python run_lora_training.py --dataset-dir datasets/my_style
+
+# Generate with personal style
+python run_style_generation.py --lora-path lora_models/my_style/checkpoint-1000 "prompt"
+
+# LoRA personal style training
+python run_lora_training.py --dataset-dir datasets/my_style
+
+# Generate with personal style
+python run_style_generation.py --lora-path lora_models/my_style/checkpoint-1000 "prompt"
+```
+
+### Direct Module Access
+
+Run generators directly from their organized location:
+
+```bash
+# Direct access to generators
+python src/generators/compi_phase1_text2image.py "prompt"
+python src/generators/compi_phase1b_advanced_styling.py --list-styles
+
+# Environment setup and testing
+python src/setup_env.py
+python src/test_setup.py
+```
+
+## 🎯 Benefits of This Organization
+
+### 1. **Clean Separation of Concerns**
+
+- **`src/generators/`** - All image generation logic
+- **`src/utils/`** - Reusable utility functions
+- **`src/`** - Core project modules and configuration
+- **Root level** - Convenience scripts and documentation
+
+### 2. **Professional Python Structure**
+
+- Proper module organization with `__init__.py` files
+- Clear import paths and dependencies
+- Scalable architecture for future expansion
+
+### 3. **Easy Access**
+
+- Convenience scripts provide simple access from project root
+- Direct module access for advanced users
+- Maintains backward compatibility
+
+### 4. **Future-Ready**
+
+- Organized structure ready for Phase 2+ implementations
+- Clear places for audio processing, UI components, etc.
+- Modular design supports easy testing and maintenance
+
+## 🔧 Development Guidelines
+
+### Adding New Generators
+
+1. Create new generator in `src/generators/`
+2. Add imports to `src/generators/__init__.py`
+3. Create convenience script in project root if needed
+4. Update documentation
+
+### Adding New Utilities
+
+1. Add utility functions to appropriate module in `src/utils/`
+2. Update `src/utils/__init__.py` imports
+3. Import in generators as needed
+
+### Testing
+
+1. Add tests to `tests/` directory
+2. Use `src/test_setup.py` for environment verification
+3. Test both convenience scripts and direct module access
+
+## 📚 Documentation
+
+- **README.md** - Project overview and quick start
+- **development.md** - Comprehensive development roadmap
+- **PHASE1_USAGE.md** - Detailed Phase 1 usage guide
+- **PROJECT_STRUCTURE.md** - This organizational guide
+
+This structure provides a solid foundation for the CompI project's continued development through all planned phases.

docs/README.md

@@ -0,0 +1,38 @@
+# CompI Documentation Index
+
+Welcome to the CompI docs. All phase guides and project structure are collected here.
+
+## Quick links
+
+- Project Structure — PROJECT_STRUCTURE.md
+- Phase 1
+  - Usage — PHASE1_USAGE.md
+  - Evaluation (1.D) — PHASE1D_EVALUATION_GUIDE.md
+  - LoRA (1.E) — PHASE1E_LORA_GUIDE.md
+- Phase 2
+  - Audio to Image (2.A) — PHASE2A_AUDIO_TO_IMAGE_GUIDE.md
+  - Data to Image (2.B) — PHASE2B_DATA_TO_IMAGE_GUIDE.md
+  - Emotion to Image (2.C) — PHASE2C_EMOTION_TO_IMAGE_GUIDE.md
+  - Real-time Data (2.D) — PHASE2D_REALTIME_DATA_TO_IMAGE_GUIDE.md
+  - Style Reference (2.E) — PHASE2E_STYLE_REFERENCE_GUIDE.md
+- Phase 3
+  - Final Dashboard — PHASE3_FINAL_DASHBOARD_GUIDE.md
+  - Performance (3.E) — PHASE3E_PERFORMANCE_GUIDE.md
+- Phase 4
+  - Deployment Guide — PHASE4_DEPLOYMENT_GUIDE.md
+  - Runtime Optimization — PHASE4_RUNTIME_OPTIMIZATION.md
+
+## Getting started
+
+- Launch the integrated Phase 3 dashboard:
+
+  - python run_phase3_final_dashboard.py
+  - Or: streamlit run src/ui/compi_phase3_final_dashboard.py --server.port 8506
+
+- Generated images and logs are stored in outputs/
+- Presets live in presets/, export bundles are saved to exports/
+
+## Notes
+
+- Some guides describe optional workflows (e.g., dataset preparation and LoRA training). Those features remain available via src/generators/\* scripts but are not required for using the Phase 3 Final Dashboard.
+- If you reorganize folders, ensure src/config.py and the Streamlit app constants continue to point to valid directories.

packages.txt

@@ -0,0 +1,3 @@
+ffmpeg
+libsndfile1
+libgl1

requirements.txt

@@ -0,0 +1,73 @@
+# Core Deep Learning
+torch>=2.1.0
+torchvision>=0.16.0
+torchaudio>=2.1.0
+transformers>=4.35.0
+diffusers>=0.24.0
+accelerate>=0.24.0
+
+# Audio Processing
+librosa>=0.10.0
+soundfile>=0.12.0
+audioread>=3.0.0
+
+# Data Processing & Analysis
+numpy>=1.24.0
+pandas>=2.0.0
+scipy>=1.10.0
+scikit-learn>=1.3.0
+
+# Computer Vision
+opencv-python>=4.8.0
+opencv-python-headless>=4.8.0
+Pillow>=10.0.0
+
+# Natural Language Processing
+textblob>=0.17.0
+nltk>=3.8.0
+spacy>=3.6.0
+
+# Visualization
+matplotlib>=3.7.0
+seaborn>=0.12.0
+plotly>=5.15.0
+
+# UI Frameworks
+streamlit>=1.28.0
+gradio>=4.0.0
+
+# Utilities
+requests>=2.31.0
+feedparser>=6.0.0
+tqdm>=4.65.0
+python-dotenv>=1.0.0
+
+# Development & Testing
+pytest>=7.4.0
+jupyter>=1.0.0
+jupyterlab>=4.0.0
+ipywidgets>=8.0.0
+
+# Image Analysis & Evaluation
+imagehash>=4.3.0
+
+# LoRA Fine-tuning & Personal Style Training
+peft>=0.7.0
+datasets>=2.14.0
+bitsandbytes>=0.41.0
+
+# Audio-to-Text Processing (Phase 2.A)
+openai-whisper>=20231117
+
+# Optional: Advanced ML Libraries
+# Uncomment as needed for advanced features
+open-clip-torch>=2.24.0
+controlnet-aux>=0.4.0
+xformers>=0.0.22  # For memory-efficient attention (GPU recommended)
+# wandb>=0.16.0     # Experiment tracking
+safetensors>=0.4.0  # Safe model loading
+
+# Optional: Cloud/API Integration
+# boto3>=1.34.0     # AWS SDK
+# google-cloud-storage>=2.10.0  # Google Cloud Platform
+# openai>=1.0.0     # OpenAI API (updated to v1+)

run_phase3_final_dashboard.py

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 3 Final Dashboard Launcher
+
+Launch the complete Phase 3 integrated dashboard that combines ALL CompI features:
+
+Phase 3.A/3.B: True multimodal fusion with real processing
+- Real audio transcription and analysis
+- Actual data processing and visualization  
+- Sentiment analysis and emotion detection
+- Live real-time data feeds (weather, news)
+
+Phase 3.C: Advanced references with role assignment
+- Multi-image upload and URL support
+- Style vs structure role assignment
+- Live ControlNet previews (Canny/Depth)
+- Hybrid CN+I2I generation modes
+
+Phase 3.D: Professional workflow management
+- Gallery with advanced filtering
+- Rating, tagging, and annotation system
+- Preset save/load functionality
+- Complete export bundles with metadata
+
+Phase 3.E: Performance management and model switching
+- SD 1.5 ↔ SDXL model switching
+- LoRA integration with scale control
+- Performance optimizations (xFormers, attention slicing, VAE)
+- VRAM monitoring and OOM auto-retry
+- Optional latent upscaling
+
+Usage:
+    python run_phase3_final_dashboard.py
+    
+    or
+    
+    streamlit run src/ui/compi_phase3_final_dashboard.py --server.port 8506
+"""
+
+import os
+import sys
+import subprocess
+from pathlib import Path
+
+def check_dependencies():
+    """Check for required dependencies"""
+    print("📦 Checking dependencies...")
+
+    required_packages = {
+        "torch": "PyTorch",
+        "diffusers": "Diffusers",
+        "transformers": "Transformers",
+        "accelerate": "Accelerate",
+        "streamlit": "Streamlit",
+        "pillow": "Pillow (PIL)",
+        "numpy": "NumPy",
+        "pandas": "Pandas",
+        "librosa": "Librosa (audio processing)",
+        "matplotlib": "Matplotlib (plotting)",
+        "requests": "Requests (HTTP)",
+        "feedparser": "FeedParser (RSS feeds)",
+        "textblob": "TextBlob (sentiment analysis)"
+    }
+
+    # Special check for OpenCV (accept either opencv-python or opencv-python-headless)
+    opencv_available = False
+    try:
+        import cv2
+        opencv_available = True
+        required_packages["cv2"] = "OpenCV (image processing)"
+    except ImportError:
+        pass
+
+    missing_packages = []
+    available_packages = []
+
+    for package, name in required_packages.items():
+        try:
+            __import__(package.replace("-", "_"))
+            available_packages.append(name)
+        except ImportError:
+            if package != "cv2":  # cv2 already checked above
+                missing_packages.append(package)
+
+    # Add opencv to missing if not available
+    if not opencv_available:
+        missing_packages.append("opencv-python")
+
+    print(f"✅ Available: {', '.join(available_packages)}")
+
+    if missing_packages:
+        print(f"❌ Missing: {', '.join(missing_packages)}")
+        return False
+
+    return True
+
+def check_optional_features():
+    """Check for optional features"""
+    print("\n🔍 Checking optional features...")
+    
+    # Check Whisper
+    try:
+        import whisper
+        print("✅ Whisper available for audio transcription")
+    except ImportError:
+        print("⚠️  Whisper not available (will be installed on first use)")
+    
+    # Check SDXL availability
+    try:
+        from diffusers import StableDiffusionXLPipeline
+        print("✅ SDXL support available")
+    except ImportError:
+        print("⚠️  SDXL not available (requires newer diffusers)")
+    
+    # Check ControlNet availability
+    try:
+        from diffusers import StableDiffusionControlNetPipeline
+        print("✅ ControlNet available")
+    except ImportError:
+        print("⚠️  ControlNet not available")
+    
+    # Check upscaler availability
+    try:
+        from diffusers import StableDiffusionLatentUpscalePipeline
+        print("✅ Latent Upscaler available")
+    except ImportError:
+        print("⚠️  Latent Upscaler not available")
+    
+    # Check xFormers
+    try:
+        import xformers
+        print("✅ xFormers available for memory optimization")
+    except ImportError:
+        print("⚠️  xFormers not available (optional performance boost)")
+
+def check_gpu_setup():
+    """Check GPU setup and provide recommendations"""
+    print("\n🔍 Checking GPU setup...")
+    
+    try:
+        import torch
+        
+        if torch.cuda.is_available():
+            gpu_count = torch.cuda.device_count()
+            gpu_name = torch.cuda.get_device_name(0)
+            total_memory = torch.cuda.get_device_properties(0).total_memory / (1024**3)
+            
+            print(f"✅ CUDA available: {gpu_count} GPU(s)")
+            print(f"   Primary GPU: {gpu_name}")
+            print(f"   VRAM: {total_memory:.1f} GB")
+            
+            if total_memory >= 12.0:
+                print("✅ Excellent VRAM for all features including SDXL")
+            elif total_memory >= 8.0:
+                print("✅ Good VRAM for SDXL and most features")
+            elif total_memory >= 6.0:
+                print("✅ Sufficient VRAM for SD 1.5 and most features")
+                print("⚠️  SDXL may require optimizations")
+            elif total_memory >= 4.0:
+                print("✅ Minimum VRAM for SD 1.5")
+                print("⚠️  Use aggressive optimizations for best performance")
+            else:
+                print("⚠️  Limited VRAM - consider CPU mode or cloud GPU")
+            
+            return True
+        else:
+            print("⚠️  CUDA not available - will use CPU mode")
+            print("💡 CPU mode is slower but still functional")
+            return False
+            
+    except ImportError:
+        print("❌ PyTorch not found")
+        return False
+
+def install_missing_dependencies():
+    """Install missing dependencies"""
+    print("\n📦 Installing missing dependencies...")
+    
+    try:
+        # Core dependencies
+        core_packages = [
+            "torch", "torchvision", "torchaudio",
+            "diffusers>=0.21.0", "transformers", "accelerate",
+            "streamlit", "pillow", "numpy", "pandas",
+            "librosa", "opencv-python", "matplotlib",
+            "requests", "feedparser", "textblob"
+        ]
+        
+        print("Installing core packages...")
+        subprocess.check_call([
+            sys.executable, "-m", "pip", "install"
+        ] + core_packages)
+        
+        print("✅ Core dependencies installed")
+        
+        # Optional performance packages (skip xformers due to compatibility issues)
+        print("⚠️  Skipping xFormers installation (compatibility issues with current PyTorch version)")
+        
+        return True
+        
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Installation failed: {e}")
+        return False
+
+def main():
+    """Launch Phase 3 Final Dashboard"""
+    
+    print("🧪 CompI Phase 3 Final Dashboard")
+    print("=" * 80)
+    print()
+    print("🎯 Complete Phase 3 Integration (3.A → 3.E):")
+    print("  • 🧩 Multimodal Inputs: Text, Audio, Data, Emotion, Real-time")
+    print("  • 🖼️ Advanced References: Role assignment, ControlNet, live previews")
+    print("  • ⚙️ Model & Performance: SD 1.5/SDXL, LoRA, VRAM monitoring")
+    print("  • 🎛️ Intelligent Generation: Hybrid modes, OOM recovery")
+    print("  • 🖼️ Professional Gallery: Filtering, rating, annotation")
+    print("  • 💾 Preset Management: Save/load configurations")
+    print("  • 📦 Export System: Complete bundles with metadata")
+    print()
+    
+    # Check if the UI file exists
+    ui_file = Path("src/ui/compi_phase3_final_dashboard.py")
+    if not ui_file.exists():
+        print(f"❌ Error: {ui_file} not found!")
+        print("Make sure you're running this from the project root directory.")
+        return 1
+    
+    # Check dependencies
+    if not check_dependencies():
+        print("\n❌ Missing dependencies detected.")
+        install = input("Install missing dependencies? (y/n): ").lower().strip()
+        
+        if install == 'y':
+            if not install_missing_dependencies():
+                print("❌ Failed to install dependencies")
+                return 1
+        else:
+            print("❌ Cannot proceed without required dependencies")
+            return 1
+    
+    # Check GPU setup
+    has_gpu = check_gpu_setup()
+    
+    # Check optional features
+    check_optional_features()
+    
+    print()
+    print("🚀 Launching Phase 3 Final Dashboard...")
+    print("📍 Access at: http://localhost:8506")
+    print()
+    
+    if has_gpu:
+        print("💡 GPU Tips:")
+        print("  • Monitor VRAM usage in the top metrics bar")
+        print("  • Use performance optimizations in Model & Performance tab")
+        print("  • Enable OOM auto-retry for reliability")
+        print("  • Try SDXL for higher quality (requires 8+ GB VRAM)")
+    else:
+        print("💡 CPU Tips:")
+        print("  • Generation will be slower but still functional")
+        print("  • Use smaller image sizes (512x512 or less)")
+        print("  • Reduce inference steps for faster generation")
+        print("  • Stick to SD 1.5 model for best performance")
+    
+    print()
+    print("🎨 Getting Started:")
+    print("  1. 🧩 Configure multimodal inputs (audio, data, emotion, real-time)")
+    print("  2. 🖼️ Upload reference images and assign roles (style vs structure)")
+    print("  3. ⚙️ Choose model and optimize performance settings")
+    print("  4. 🎛️ Generate with intelligent fusion of all inputs")
+    print("  5. 🖼️ Review results in gallery and add annotations")
+    print("  6. 💾 Save presets for reuse")
+    print("  7. 📦 Export complete bundles with metadata")
+    print()
+    
+    # Launch Streamlit
+    try:
+        cmd = [
+            sys.executable, "-m", "streamlit", "run",
+            str(ui_file),
+            "--server.port", "8506",
+            "--server.headless", "true",
+            "--browser.gatherUsageStats", "false"
+        ]
+        
+        subprocess.run(cmd)
+        
+    except KeyboardInterrupt:
+        print("\n👋 Phase 3 Final Dashboard stopped by user")
+        return 0
+    except Exception as e:
+        print(f"❌ Error launching Streamlit: {e}")
+        return 1
+    
+    return 0
+
+if __name__ == "__main__":
+    exit_code = main()
+    sys.exit(exit_code)

src/__init__.py

@@ -0,0 +1,7 @@
+"""
+CompI - Compositional Intelligence Project
+A multi-modal AI system for creative content generation.
+"""
+
+__version__ = "0.1.0"
+__author__ = "CompI Development Team"

src/config.py

@@ -0,0 +1,42 @@
+"""
+Configuration settings for CompI project.
+"""
+
+import os
+from pathlib import Path
+
+# Project paths
+PROJECT_ROOT = Path(__file__).parent.parent
+DATA_DIR = PROJECT_ROOT / "data"
+OUTPUTS_DIR = PROJECT_ROOT / "outputs"
+MODELS_DIR = PROJECT_ROOT / "models"
+
+# Create directories if they don't exist
+for dir_path in [DATA_DIR, OUTPUTS_DIR, MODELS_DIR]:
+    dir_path.mkdir(exist_ok=True)
+
+# Model configurations
+STABLE_DIFFUSION_MODEL = "runwayml/stable-diffusion-v1-5"
+STABLE_DIFFUSION_IMG2IMG_MODEL = "runwayml/stable-diffusion-v1-5"
+EMOTION_MODEL = "j-hartmann/emotion-english-distilroberta-base"
+SENTIMENT_MODEL = "cardiffnlp/twitter-roberta-base-sentiment-latest"
+
+# Generation settings
+DEFAULT_IMAGE_SIZE = (512, 512)
+DEFAULT_INFERENCE_STEPS = 20
+DEFAULT_GUIDANCE_SCALE = 7.5
+
+# Audio settings
+SAMPLE_RATE = 22050
+AUDIO_DURATION = 10  # seconds
+
+# Device settings
+DEVICE = "cuda" if os.getenv("CUDA_AVAILABLE", "false").lower() == "true" else "cpu"
+
+# API keys (load from environment)
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+HUGGINGFACE_TOKEN = os.getenv("HUGGINGFACE_TOKEN")
+
+# Logging
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
+LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

src/generators/__init__.py

@@ -0,0 +1,26 @@
+"""
+CompI Image Generators
+Text-to-image generation modules for the CompI platform.
+"""
+
+from .compi_phase1_text2image import *
+from .compi_phase1_advanced import *
+from .compi_phase1b_styled_generation import *
+from .compi_phase1b_advanced_styling import *
+from .compi_phase2a_audio_to_image import *
+from .compi_phase2b_data_to_image import *
+from .compi_phase2c_emotion_to_image import *
+from .compi_phase2d_realtime_to_image import *
+from .compi_phase2e_refimg_to_image import *
+
+__all__ = [
+    "compi_phase1_text2image",
+    "compi_phase1_advanced",
+    "compi_phase1b_styled_generation",
+    "compi_phase1b_advanced_styling",
+    "compi_phase2a_audio_to_image",
+    "compi_phase2b_data_to_image",
+    "compi_phase2c_emotion_to_image",
+    "compi_phase2d_realtime_to_image",
+    "compi_phase2e_refimg_to_image"
+]

src/generators/compi_phase1_advanced.py

@@ -0,0 +1,230 @@
+# compi_phase1_advanced.py
+# Enhanced text-to-image generation with batch processing, negative prompts, and style controls
+
+import os
+import sys
+import torch
+import argparse
+from datetime import datetime
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+import json
+
+# Add project root to path for imports
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+# ------------------ 1. SETUP AND ARGUMENT PARSING ------------------
+
+def setup_args():
+    parser = argparse.ArgumentParser(description="CompI Phase 1: Advanced Text-to-Image Generation")
+    parser.add_argument("prompt", nargs="*", help="Text prompt for image generation")
+    parser.add_argument("--negative", "-n", default="", help="Negative prompt (what to avoid)")
+    parser.add_argument("--steps", "-s", type=int, default=30, help="Number of inference steps (default: 30)")
+    parser.add_argument("--guidance", "-g", type=float, default=7.5, help="Guidance scale (default: 7.5)")
+    parser.add_argument("--seed", type=int, default=None, help="Random seed for reproducibility")
+    parser.add_argument("--batch", "-b", type=int, default=1, help="Number of images to generate")
+    parser.add_argument("--width", "-w", type=int, default=512, help="Image width (default: 512)")
+    parser.add_argument("--height", type=int, default=512, help="Image height (default: 512)")
+    parser.add_argument("--model", "-m", default="runwayml/stable-diffusion-v1-5", help="Model to use")
+    parser.add_argument("--output", "-o", default="outputs", help="Output directory")
+    parser.add_argument("--interactive", "-i", action="store_true", help="Interactive mode")
+    return parser.parse_args()
+
+# Check for GPU
+device = "cuda" if torch.cuda.is_available() else "cpu"
+print(f"Using device: {device}")
+
+# Logging function
+def log(msg):
+    now = datetime.now().strftime("[%Y-%m-%d %H:%M:%S]")
+    print(f"{now} {msg}")
+
+# ------------------ 2. MODEL LOADING ------------------
+
+def load_model(model_name):
+    log(f"Loading model: {model_name}")
+    
+    def dummy_safety_checker(images, **kwargs):
+        return images, [False] * len(images)
+    
+    try:
+        pipe = StableDiffusionPipeline.from_pretrained(
+            model_name,
+            torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+            safety_checker=dummy_safety_checker,
+        )
+        pipe = pipe.to(device)
+        
+        # Memory optimizations
+        pipe.enable_attention_slicing()
+        # Note: enable_memory_efficient_attention() is deprecated in newer versions
+        
+        log("Model loaded successfully")
+        return pipe
+    except Exception as e:
+        log(f"Error loading model: {e}")
+        sys.exit(1)
+
+# ------------------ 3. GENERATION FUNCTION ------------------
+
+def generate_image(pipe, prompt, negative_prompt="", **kwargs):
+    """Generate a single image with given parameters"""
+    
+    # Set up generator
+    seed = kwargs.get('seed', torch.seed())
+    if device == "cuda":
+        generator = torch.Generator(device).manual_seed(seed)
+    else:
+        generator = torch.manual_seed(seed)
+    
+    # Generation parameters
+    params = {
+        'prompt': prompt,
+        'negative_prompt': negative_prompt if negative_prompt else None,
+        'height': kwargs.get('height', 512),
+        'width': kwargs.get('width', 512),
+        'num_inference_steps': kwargs.get('steps', 30),
+        'guidance_scale': kwargs.get('guidance', 7.5),
+        'generator': generator,
+    }
+    
+    log(f"Generating: '{prompt[:50]}...' (seed: {seed})")
+    
+    with torch.autocast(device) if device == "cuda" else torch.no_grad():
+        result = pipe(**params)
+        return result.images[0], seed
+
+# ------------------ 4. SAVE FUNCTION ------------------
+
+def save_image(image, prompt, seed, output_dir, metadata=None):
+    """Save image with descriptive filename and metadata"""
+    os.makedirs(output_dir, exist_ok=True)
+    
+    # Create filename
+    prompt_slug = "_".join(prompt.lower().split()[:6])
+    prompt_slug = "".join(c for c in prompt_slug if c.isalnum() or c in "_-")[:40]
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"{prompt_slug}_{timestamp}_seed{seed}.png"
+    filepath = os.path.join(output_dir, filename)
+    
+    # Save image
+    image.save(filepath)
+    
+    # Save metadata
+    if metadata:
+        metadata_file = filepath.replace('.png', '_metadata.json')
+        with open(metadata_file, 'w') as f:
+            json.dump(metadata, f, indent=2)
+    
+    log(f"Saved: {filepath}")
+    return filepath
+
+# ------------------ 5. INTERACTIVE MODE ------------------
+
+def interactive_mode(pipe, output_dir):
+    """Interactive prompt mode for experimentation"""
+    log("Entering interactive mode. Type 'quit' to exit.")
+    
+    while True:
+        try:
+            prompt = input("\n🎨 Enter prompt: ").strip()
+            if prompt.lower() in ['quit', 'exit', 'q']:
+                break
+            
+            if not prompt:
+                continue
+                
+            negative = input("❌ Negative prompt (optional): ").strip()
+            
+            # Quick settings
+            print("⚙️  Quick settings (press Enter for defaults):")
+            steps = input(f"   Steps (30): ").strip()
+            steps = int(steps) if steps else 30
+            
+            guidance = input(f"   Guidance (7.5): ").strip()
+            guidance = float(guidance) if guidance else 7.5
+            
+            # Generate
+            image, seed = generate_image(
+                pipe, prompt, negative,
+                steps=steps, guidance=guidance
+            )
+            
+            # Save with metadata
+            metadata = {
+                'prompt': prompt,
+                'negative_prompt': negative,
+                'steps': steps,
+                'guidance_scale': guidance,
+                'seed': seed,
+                'timestamp': datetime.now().isoformat()
+            }
+            
+            save_image(image, prompt, seed, output_dir, metadata)
+            
+        except KeyboardInterrupt:
+            print("\n👋 Goodbye!")
+            break
+        except Exception as e:
+            log(f"Error: {e}")
+
+# ------------------ 6. MAIN FUNCTION ------------------
+
+def main():
+    args = setup_args()
+    
+    # Load model
+    pipe = load_model(args.model)
+    
+    # Interactive mode
+    if args.interactive:
+        interactive_mode(pipe, args.output)
+        return
+    
+    # Get prompt
+    if args.prompt:
+        prompt = " ".join(args.prompt)
+    else:
+        prompt = input("Enter your prompt: ").strip()
+    
+    if not prompt:
+        log("No prompt provided. Use --interactive for interactive mode.")
+        return
+    
+    # Generate batch
+    log(f"Generating {args.batch} image(s)")
+    
+    for i in range(args.batch):
+        try:
+            # Use provided seed or generate random one
+            seed = args.seed if args.seed else torch.seed()
+            
+            image, actual_seed = generate_image(
+                pipe, prompt, args.negative,
+                seed=seed, steps=args.steps, guidance=args.guidance,
+                width=args.width, height=args.height
+            )
+            
+            # Prepare metadata
+            metadata = {
+                'prompt': prompt,
+                'negative_prompt': args.negative,
+                'steps': args.steps,
+                'guidance_scale': args.guidance,
+                'seed': actual_seed,
+                'width': args.width,
+                'height': args.height,
+                'model': args.model,
+                'batch_index': i + 1,
+                'timestamp': datetime.now().isoformat()
+            }
+            
+            save_image(image, prompt, actual_seed, args.output, metadata)
+            
+        except Exception as e:
+            log(f"Error generating image {i+1}: {e}")
+    
+    log("Generation complete!")
+
+if __name__ == "__main__":
+    main()

src/generators/compi_phase1_text2image.py

@@ -0,0 +1,117 @@
+# compi_phase1_text2image.py
+
+import os
+import sys
+import torch
+from datetime import datetime
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+
+# Add project root to path for imports
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+# ------------------ 1. SETUP AND CHECKS ------------------
+
+# Check for GPU
+if torch.cuda.is_available():
+    device = "cuda"
+    print("CUDA GPU detected. Running on GPU for best performance.")
+else:
+    device = "cpu"
+    print("No CUDA GPU detected. Running on CPU. Generation will be slow.")
+
+# Set up output directory
+OUTPUT_DIR = os.path.join(os.path.dirname(__file__), '..', '..', "outputs")
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+# Logging function
+def log(msg):
+    now = datetime.now().strftime("[%Y-%m-%d %H:%M:%S]")
+    print(f"{now} {msg}")
+
+# ------------------ 2. LOAD MODEL ------------------
+
+MODEL_NAME = "runwayml/stable-diffusion-v1-5"
+log(f"Loading model: {MODEL_NAME} (this may take a minute on first run)")
+
+# Optionally, disable the safety checker for pure creative exploration
+def dummy_safety_checker(images, **kwargs):
+    return images, [False] * len(images)
+
+try:
+    pipe = StableDiffusionPipeline.from_pretrained(
+        MODEL_NAME,
+        torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+        safety_checker=dummy_safety_checker,  # Remove for production!
+    )
+except Exception as e:
+    log(f"Error loading model: {e}")
+    sys.exit(1)
+
+pipe = pipe.to(device)
+pipe.enable_attention_slicing()  # Reduce VRAM use
+
+log("Model loaded successfully.")
+
+# ------------------ 3. PROMPT HANDLING ------------------
+
+def main():
+    """Main function for command-line execution"""
+    if len(sys.argv) > 1:
+        prompt = " ".join(sys.argv[1:])
+        log(f"Prompt taken from command line: {prompt}")
+    else:
+        prompt = input("Enter your prompt (e.g. 'A magical forest, digital art'): ").strip()
+        log(f"Prompt entered: {prompt}")
+
+    if not prompt:
+        log("No prompt provided. Exiting.")
+        sys.exit(0)
+
+    # ------------------ 4. GENERATION PARAMETERS ------------------
+
+    SEED = torch.seed()  # You can use a fixed seed for reproducibility, e.g. 1234
+    generator = torch.manual_seed(SEED) if device == "cpu" else torch.Generator(device).manual_seed(torch.seed())
+
+    num_inference_steps = 30   # More steps = better quality, slower (default 50)
+    guidance_scale = 7.5       # Higher = follow prompt more strictly
+
+    # Output image size (SDv1.5 default 512x512)
+    height = 512
+    width = 512
+
+    # ------------------ 5. IMAGE GENERATION ------------------
+
+    log(f"Generating image for prompt: {prompt}")
+    log(f"Params: steps={num_inference_steps}, guidance_scale={guidance_scale}, seed={SEED}")
+
+    with torch.autocast(device) if device == "cuda" else torch.no_grad():
+        result = pipe(
+            prompt,
+            height=height,
+            width=width,
+            num_inference_steps=num_inference_steps,
+            guidance_scale=guidance_scale,
+            generator=generator,
+        )
+
+        image: Image.Image = result.images[0]
+
+    # ------------------ 6. SAVE OUTPUT ------------------
+
+    # Filename: prompt short, datetime, seed
+    prompt_slug = "_".join(prompt.lower().split()[:6])
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"{prompt_slug[:40]}_{timestamp}_seed{SEED}.png"
+    filepath = os.path.join(OUTPUT_DIR, filename)
+    image.save(filepath)
+    log(f"Image saved to {filepath}")
+
+    # Optionally, show image (uncomment next line if running locally)
+    # image.show()
+
+    # Log end
+    log("Generation complete.")
+
+if __name__ == "__main__":
+    main()

src/generators/compi_phase1b_advanced_styling.py

@@ -0,0 +1,338 @@
+# compi_phase1b_advanced_styling.py
+# Advanced style conditioning with negative prompts, quality settings, and enhanced prompt engineering
+
+import os
+import sys
+import torch
+import json
+import argparse
+from datetime import datetime
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+
+# Add project root to path for imports
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+# -------- 1. SETUP AND ARGUMENT PARSING --------
+
+def setup_args():
+    parser = argparse.ArgumentParser(description="CompI Phase 1.B: Advanced Style Conditioning")
+    parser.add_argument("prompt", nargs="*", help="Main scene/subject description")
+    parser.add_argument("--style", "-s", help="Art style (or number from list)")
+    parser.add_argument("--mood", "-m", help="Mood/atmosphere (or number from list)")
+    parser.add_argument("--variations", "-v", type=int, default=1, help="Number of variations")
+    parser.add_argument("--quality", "-q", choices=["draft", "standard", "high"], default="standard", help="Quality preset")
+    parser.add_argument("--negative", "-n", help="Negative prompt")
+    parser.add_argument("--interactive", "-i", action="store_true", help="Interactive mode")
+    parser.add_argument("--list-styles", action="store_true", help="List available styles and exit")
+    parser.add_argument("--list-moods", action="store_true", help="List available moods and exit")
+    return parser.parse_args()
+
+# Device setup
+device = "cuda" if torch.cuda.is_available() else "cpu"
+print(f"Using device: {device}")
+
+OUTPUT_DIR = os.path.join(os.path.dirname(__file__), '..', '..', "outputs")
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+def log(msg):
+    now = datetime.now().strftime("[%Y-%m-%d %H:%M:%S]")
+    print(f"{now} {msg}")
+
+# -------- 2. STYLE AND MOOD DEFINITIONS --------
+
+STYLES = {
+    "digital art": {
+        "prompt": "digital art, highly detailed",
+        "negative": "blurry, pixelated, low resolution"
+    },
+    "oil painting": {
+        "prompt": "oil painting, classical art, brushstrokes, canvas texture",
+        "negative": "digital, pixelated, modern"
+    },
+    "watercolor": {
+        "prompt": "watercolor painting, soft colors, flowing paint",
+        "negative": "harsh lines, digital, photographic"
+    },
+    "cyberpunk": {
+        "prompt": "cyberpunk style, neon lights, futuristic, sci-fi",
+        "negative": "natural, organic, pastoral"
+    },
+    "impressionist": {
+        "prompt": "impressionist painting, soft brushstrokes, light and color",
+        "negative": "sharp details, photorealistic, digital"
+    },
+    "concept art": {
+        "prompt": "concept art, professional illustration, detailed",
+        "negative": "amateur, sketch, unfinished"
+    },
+    "anime": {
+        "prompt": "anime style, manga, Japanese animation",
+        "negative": "realistic, western cartoon, photographic"
+    },
+    "photorealistic": {
+        "prompt": "photorealistic, high detail, professional photography",
+        "negative": "cartoon, painting, stylized"
+    },
+    "minimalist": {
+        "prompt": "minimalist art, clean lines, simple composition",
+        "negative": "cluttered, complex, detailed"
+    },
+    "surrealism": {
+        "prompt": "surrealist art, dreamlike, impossible, Salvador Dali style",
+        "negative": "realistic, logical, mundane"
+    },
+    "pixel art": {
+        "prompt": "pixel art, 8-bit style, retro gaming",
+        "negative": "smooth, high resolution, photorealistic"
+    },
+    "steampunk": {
+        "prompt": "steampunk style, Victorian era, brass and copper, gears",
+        "negative": "modern, digital, futuristic"
+    },
+    "3d render": {
+        "prompt": "3D render, CGI, computer graphics, ray tracing",
+        "negative": "2D, flat, hand-drawn"
+    }
+}
+
+MOODS = {
+    "dreamy": {
+        "prompt": "dreamy atmosphere, soft lighting, ethereal",
+        "negative": "harsh, stark, realistic"
+    },
+    "dark": {
+        "prompt": "dark and moody, dramatic shadows, mysterious",
+        "negative": "bright, cheerful, light"
+    },
+    "peaceful": {
+        "prompt": "peaceful, serene, calm, tranquil",
+        "negative": "chaotic, violent, disturbing"
+    },
+    "vibrant": {
+        "prompt": "vibrant and energetic, bright colors, dynamic",
+        "negative": "dull, muted, lifeless"
+    },
+    "melancholic": {
+        "prompt": "melancholic, sad, nostalgic, wistful",
+        "negative": "happy, joyful, upbeat"
+    },
+    "mysterious": {
+        "prompt": "mysterious, enigmatic, hidden secrets",
+        "negative": "obvious, clear, straightforward"
+    },
+    "whimsical": {
+        "prompt": "whimsical, playful, fantastical, magical",
+        "negative": "serious, realistic, mundane"
+    },
+    "dramatic": {
+        "prompt": "dramatic lighting, high contrast, cinematic",
+        "negative": "flat lighting, low contrast, amateur"
+    },
+    "retro": {
+        "prompt": "retro style, vintage, nostalgic, classic",
+        "negative": "modern, contemporary, futuristic"
+    }
+}
+
+QUALITY_PRESETS = {
+    "draft": {"steps": 20, "guidance": 6.0, "size": (512, 512)},
+    "standard": {"steps": 30, "guidance": 7.5, "size": (512, 512)},
+    "high": {"steps": 50, "guidance": 8.5, "size": (768, 768)}
+}
+
+# -------- 3. MODEL LOADING --------
+
+def load_model():
+    MODEL_NAME = "runwayml/stable-diffusion-v1-5"
+    log(f"Loading model: {MODEL_NAME}")
+    
+    def dummy_safety_checker(images, **kwargs):
+        return images, [False] * len(images)
+    
+    try:
+        pipe = StableDiffusionPipeline.from_pretrained(
+            MODEL_NAME,
+            torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+            safety_checker=dummy_safety_checker,
+        )
+        pipe = pipe.to(device)
+        pipe.enable_attention_slicing()
+        log("Model loaded successfully")
+        return pipe
+    except Exception as e:
+        log(f"Error loading model: {e}")
+        sys.exit(1)
+
+# -------- 4. INTERACTIVE FUNCTIONS --------
+
+def list_options(options_dict, title):
+    print(f"\n{title}:")
+    for idx, (key, value) in enumerate(options_dict.items(), 1):
+        prompt_preview = value["prompt"][:50] + "..." if len(value["prompt"]) > 50 else value["prompt"]
+        print(f"  {idx:2d}. {key:15s} - {prompt_preview}")
+
+def get_user_choice(options_dict, prompt_text, allow_custom=True):
+    choice = input(f"{prompt_text}: ").strip()
+    
+    if choice.isdigit():
+        idx = int(choice) - 1
+        keys = list(options_dict.keys())
+        if 0 <= idx < len(keys):
+            return keys[idx]
+    
+    if choice in options_dict:
+        return choice
+    
+    if allow_custom and choice:
+        return choice
+    
+    return None
+
+def interactive_mode(pipe):
+    log("Starting interactive style conditioning mode")
+    
+    # Get main prompt
+    main_prompt = input("\nEnter your main scene/subject: ").strip()
+    if not main_prompt:
+        log("No prompt provided")
+        return
+    
+    # Show and select style
+    list_options(STYLES, "Available Styles")
+    style_key = get_user_choice(STYLES, "Choose style (number/name/custom)")
+    
+    # Show and select mood
+    list_options(MOODS, "Available Moods")
+    mood_key = get_user_choice(MOODS, "Choose mood (number/name/custom/blank)", allow_custom=True)
+    
+    # Get additional parameters
+    variations = input("Number of variations (default 1): ").strip()
+    variations = int(variations) if variations.isdigit() else 1
+    
+    quality = input("Quality [draft/standard/high] (default standard): ").strip()
+    quality = quality if quality in QUALITY_PRESETS else "standard"
+    
+    negative = input("Negative prompt (optional): ").strip()
+    
+    # Generate images
+    generate_styled_images(pipe, main_prompt, style_key, mood_key, variations, quality, negative)
+
+# -------- 5. GENERATION FUNCTION --------
+
+def generate_styled_images(pipe, main_prompt, style_key, mood_key, variations, quality, custom_negative=""):
+    # Build the full prompt
+    full_prompt = main_prompt
+    style_negative = ""
+    mood_negative = ""
+    
+    if style_key and style_key in STYLES:
+        full_prompt += f", {STYLES[style_key]['prompt']}"
+        style_negative = STYLES[style_key]['negative']
+    elif style_key:
+        full_prompt += f", {style_key}"
+    
+    if mood_key and mood_key in MOODS:
+        full_prompt += f", {MOODS[mood_key]['prompt']}"
+        mood_negative = MOODS[mood_key]['negative']
+    elif mood_key:
+        full_prompt += f", {mood_key}"
+    
+    # Build negative prompt
+    negative_parts = [part for part in [style_negative, mood_negative, custom_negative] if part]
+    full_negative = ", ".join(negative_parts) if negative_parts else None
+    
+    # Get quality settings
+    quality_settings = QUALITY_PRESETS[quality]
+    
+    log(f"Full prompt: {full_prompt}")
+    log(f"Negative prompt: {full_negative or '[none]'}")
+    log(f"Quality: {quality} ({quality_settings['steps']} steps)")
+    log(f"Generating {variations} variation(s)")
+    
+    # Generate images
+    for i in range(variations):
+        seed = torch.seed()
+        generator = torch.manual_seed(seed) if device == "cpu" else torch.Generator(device).manual_seed(seed)
+        
+        with torch.autocast(device) if device == "cuda" else torch.no_grad():
+            result = pipe(
+                full_prompt,
+                negative_prompt=full_negative,
+                height=quality_settings["size"][1],
+                width=quality_settings["size"][0],
+                num_inference_steps=quality_settings["steps"],
+                guidance_scale=quality_settings["guidance"],
+                generator=generator,
+            )
+            
+            img = result.images[0]
+            
+            # Create filename
+            prompt_slug = "_".join(main_prompt.lower().split()[:4])
+            style_slug = (style_key or "nostyle").replace(" ", "")[:10]
+            mood_slug = (mood_key or "nomood").replace(" ", "")[:10]
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            
+            filename = f"{prompt_slug[:20]}_{style_slug}_{mood_slug}_{quality}_{timestamp}_seed{seed}_v{i+1}.png"
+            filepath = os.path.join(OUTPUT_DIR, filename)
+            
+            img.save(filepath)
+            
+            # Save metadata
+            metadata = {
+                "main_prompt": main_prompt,
+                "style": style_key,
+                "mood": mood_key,
+                "full_prompt": full_prompt,
+                "negative_prompt": full_negative,
+                "quality": quality,
+                "seed": seed,
+                "variation": i + 1,
+                "timestamp": datetime.now().isoformat(),
+                "settings": quality_settings
+            }
+            
+            metadata_file = filepath.replace('.png', '_metadata.json')
+            with open(metadata_file, 'w') as f:
+                json.dump(metadata, f, indent=2)
+            
+            log(f"Generated variation {i+1}: {filepath}")
+    
+    log(f"Phase 1.B complete - {variations} styled images generated")
+
+# -------- 6. MAIN FUNCTION --------
+
+def main():
+    args = setup_args()
+    
+    # Handle list commands
+    if args.list_styles:
+        list_options(STYLES, "Available Styles")
+        return
+    
+    if args.list_moods:
+        list_options(MOODS, "Available Moods")
+        return
+    
+    # Load model
+    pipe = load_model()
+    
+    # Interactive mode
+    if args.interactive:
+        interactive_mode(pipe)
+        return
+    
+    # Command line mode
+    main_prompt = " ".join(args.prompt) if args.prompt else input("Enter main prompt: ").strip()
+    if not main_prompt:
+        log("No prompt provided")
+        return
+    
+    generate_styled_images(
+        pipe, main_prompt, args.style, args.mood, 
+        args.variations, args.quality, args.negative or ""
+    )
+
+if __name__ == "__main__":
+    main()

src/generators/compi_phase1b_styled_generation.py

@@ -0,0 +1,172 @@
+# compi_phase1b_styled_generation.py
+
+import os
+import sys
+import torch
+from datetime import datetime
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+
+# Add project root to path for imports
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+# -------- 1. SETUP --------
+if torch.cuda.is_available():
+    device = "cuda"
+    print("Running on CUDA GPU.")
+else:
+    device = "cpu"
+    print("Running on CPU.")
+
+OUTPUT_DIR = os.path.join(os.path.dirname(__file__), '..', '..', "outputs")
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+def log(msg):
+    now = datetime.now().strftime("[%Y-%m-%d %H:%M:%S]")
+    print(f"{now} {msg}")
+
+# -------- 2. LOAD MODEL --------
+MODEL_NAME = "runwayml/stable-diffusion-v1-5"
+log(f"Loading model: {MODEL_NAME}")
+
+def dummy_safety_checker(images, **kwargs):
+    return images, [False] * len(images)
+
+try:
+    pipe = StableDiffusionPipeline.from_pretrained(
+        MODEL_NAME,
+        torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+        safety_checker=dummy_safety_checker,
+    )
+except Exception as e:
+    log(f"Error loading model: {e}")
+    sys.exit(1)
+
+pipe = pipe.to(device)
+pipe.enable_attention_slicing()
+
+log("Model loaded.")
+
+# -------- 3. STYLE & MOOD PROMPT ENGINEERING --------
+
+# Predefined styles and moods (add more as desired)
+STYLES = [
+    "digital art",
+    "oil painting",
+    "watercolor",
+    "cyberpunk",
+    "impressionist",
+    "concept art",
+    "anime",
+    "photorealistic",
+    "minimalist",
+    "surrealism",
+    "pixel art",
+    "steampunk",
+    "3d render"
+]
+
+MOODS = [
+    "dreamy atmosphere",
+    "dark and moody",
+    "peaceful",
+    "vibrant and energetic",
+    "melancholic",
+    "mysterious",
+    "whimsical",
+    "serene",
+    "uplifting",
+    "dramatic lighting",
+    "retro"
+]
+
+def main():
+    """Main function for command-line execution"""
+    # Input: main prompt
+    if len(sys.argv) > 1:
+        main_prompt = " ".join(sys.argv[1:])
+        log(f"Prompt from command line: {main_prompt}")
+    else:
+        main_prompt = input("Enter your main scene/subject (e.g., 'A forest of bioluminescent trees'): ").strip()
+
+    if not main_prompt:
+        log("No main prompt entered. Exiting.")
+        sys.exit(0)
+
+    # Style selector
+    print("\nChoose an art style from the list or enter your own:")
+    for idx, style in enumerate(STYLES, 1):
+        print(f"  {idx}. {style}")
+    style_choice = input(f"Enter style number [1-{len(STYLES)}] or type your own: ").strip()
+    if style_choice.isdigit() and 1 <= int(style_choice) <= len(STYLES):
+        style = STYLES[int(style_choice)-1]
+    else:
+        style = style_choice if style_choice else STYLES[0]
+    log(f"Style selected: {style}")
+
+    # Mood selector
+    print("\nChoose a mood from the list or enter your own:")
+    for idx, mood in enumerate(MOODS, 1):
+        print(f"  {idx}. {mood}")
+    mood_choice = input(f"Enter mood number [1-{len(MOODS)}] or type your own (or leave blank): ").strip()
+    if mood_choice.isdigit() and 1 <= int(mood_choice) <= len(MOODS):
+        mood = MOODS[int(mood_choice)-1]
+    elif mood_choice:
+        mood = mood_choice
+    else:
+        mood = ""
+    log(f"Mood selected: {mood if mood else '[none]'}")
+
+    # Combine all for final prompt
+    full_prompt = main_prompt
+    if style: full_prompt += f", {style}"
+    if mood:  full_prompt += f", {mood}"
+    log(f"Full prompt: {full_prompt}")
+
+    # -------- 4. GENERATION PARAMETERS --------
+
+    NUM_VARIATIONS = input("How many variations to generate? (default 1): ").strip()
+    try:
+        NUM_VARIATIONS = max(1, int(NUM_VARIATIONS))
+    except Exception:
+        NUM_VARIATIONS = 1
+
+    INFERENCE_STEPS = 30
+    GUIDANCE_SCALE = 7.5
+    HEIGHT = 512
+    WIDTH = 512
+
+    # -------- 5. IMAGE GENERATION --------
+
+    log(f"Generating {NUM_VARIATIONS} image(s) for prompt: '{full_prompt}'")
+    images = []
+
+    for i in range(NUM_VARIATIONS):
+        seed = torch.seed()  # random seed for each variation
+        generator = torch.manual_seed(seed) if device == "cpu" else torch.Generator(device).manual_seed(seed)
+        with torch.autocast(device) if device == "cuda" else torch.no_grad():
+            result = pipe(
+                full_prompt,
+                height=HEIGHT,
+                width=WIDTH,
+                num_inference_steps=INFERENCE_STEPS,
+                guidance_scale=GUIDANCE_SCALE,
+                generator=generator,
+            )
+            img: Image.Image = result.images[0]
+            # Compose filename
+            prompt_slug = "_".join(main_prompt.lower().split()[:5])
+            style_slug = style.replace(" ", "")[:10]
+            mood_slug = mood.replace(" ", "")[:10] if mood else "none"
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            fname = f"{prompt_slug[:25]}_{style_slug}_{mood_slug}_{timestamp}_seed{seed}_v{i+1}.png"
+            fpath = os.path.join(OUTPUT_DIR, fname)
+            img.save(fpath)
+            log(f"Image saved: {fpath}")
+            images.append(fpath)
+
+    log(f"All {NUM_VARIATIONS} images generated and saved.")
+    log("Phase 1.B complete.")
+
+if __name__ == "__main__":
+    main()

src/generators/compi_phase1d_cli_evaluation.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 1.D: Command-Line Quality Evaluation Tool
+
+Command-line interface for batch evaluation and analysis of generated images.
+
+Usage:
+    python src/generators/compi_phase1d_cli_evaluation.py --help
+    python src/generators/compi_phase1d_cli_evaluation.py --analyze
+    python src/generators/compi_phase1d_cli_evaluation.py --batch-score 4 3 4 4 3
+"""
+
+import os
+import argparse
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List
+
+import pandas as pd
+from PIL import Image
+
+# Import functions from the main evaluation module
+from compi_phase1d_evaluate_quality import (
+    parse_filename, get_image_metrics, load_existing_evaluations,
+    save_evaluation, EVALUATION_CRITERIA, OUTPUT_DIR, EVAL_CSV
+)
+
+def setup_args():
+    """Setup command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="CompI Phase 1.D: Command-Line Quality Evaluation",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Analyze existing evaluations
+  python %(prog)s --analyze
+  
+  # Batch score all unevaluated images (prompt_match, style, mood, quality, appeal)
+  python %(prog)s --batch-score 4 3 4 4 3 --notes "Batch evaluation - good quality"
+  
+  # Generate detailed report
+  python %(prog)s --report --output evaluation_report.txt
+  
+  # List unevaluated images
+  python %(prog)s --list-unevaluated
+        """
+    )
+    
+    parser.add_argument("--output-dir", default=OUTPUT_DIR, 
+                       help="Directory containing generated images")
+    
+    # Analysis commands
+    parser.add_argument("--analyze", action="store_true",
+                       help="Display evaluation summary and statistics")
+    
+    parser.add_argument("--report", action="store_true",
+                       help="Generate detailed evaluation report")
+    
+    parser.add_argument("--output", "-o", 
+                       help="Output file for report (default: stdout)")
+    
+    # Batch evaluation
+    parser.add_argument("--batch-score", nargs=5, type=int, metavar=("PROMPT", "STYLE", "MOOD", "QUALITY", "APPEAL"),
+                       help="Batch score all unevaluated images (1-5 for each criteria)")
+    
+    parser.add_argument("--notes", default="CLI batch evaluation",
+                       help="Notes for batch evaluation")
+    
+    # Listing commands
+    parser.add_argument("--list-all", action="store_true",
+                       help="List all images with evaluation status")
+    
+    parser.add_argument("--list-evaluated", action="store_true", 
+                       help="List only evaluated images")
+    
+    parser.add_argument("--list-unevaluated", action="store_true",
+                       help="List only unevaluated images")
+    
+    # Filtering
+    parser.add_argument("--style", help="Filter by style")
+    parser.add_argument("--mood", help="Filter by mood")
+    
+    return parser.parse_args()
+
+def load_images(output_dir: str) -> List[Dict]:
+    """Load and parse all images from output directory."""
+    if not os.path.exists(output_dir):
+        print(f"❌ Output directory '{output_dir}' not found!")
+        return []
+    
+    image_files = [f for f in os.listdir(output_dir) if f.lower().endswith('.png')]
+    parsed_images = []
+    
+    for fname in image_files:
+        metadata = parse_filename(fname)
+        if metadata:
+            parsed_images.append(metadata)
+    
+    return parsed_images
+
+def filter_images(images: List[Dict], style: str = None, mood: str = None) -> List[Dict]:
+    """Filter images by style and/or mood."""
+    filtered = images
+    
+    if style:
+        filtered = [img for img in filtered if img.get('style', '').lower() == style.lower()]
+    
+    if mood:
+        filtered = [img for img in filtered if img.get('mood', '').lower() == mood.lower()]
+    
+    return filtered
+
+def analyze_evaluations(existing_evals: Dict):
+    """Display evaluation analysis."""
+    if not existing_evals:
+        print("❌ No evaluations found.")
+        return
+    
+    df = pd.DataFrame.from_dict(existing_evals, orient='index')
+    
+    print("📊 CompI Phase 1.D - Evaluation Analysis")
+    print("=" * 50)
+    print(f"Total Evaluated Images: {len(df)}")
+    print()
+    
+    # Score statistics
+    print("📈 Score Statistics:")
+    for criterion_key, criterion_info in EVALUATION_CRITERIA.items():
+        if criterion_key in df.columns:
+            mean_score = df[criterion_key].mean()
+            std_score = df[criterion_key].std()
+            min_score = df[criterion_key].min()
+            max_score = df[criterion_key].max()
+            
+            print(f"  {criterion_info['name']:20}: {mean_score:.2f} ± {std_score:.2f} (range: {min_score}-{max_score})")
+    
+    print()
+    
+    # Style analysis
+    if 'style' in df.columns and 'prompt_match' in df.columns:
+        print("🎨 Top Performing Styles (by Prompt Match):")
+        style_scores = df.groupby('style')['prompt_match'].mean().sort_values(ascending=False)
+        for style, score in style_scores.head(5).items():
+            print(f"  {style:15}: {score:.2f}")
+        print()
+    
+    # Mood analysis  
+    if 'mood' in df.columns and 'creative_appeal' in df.columns:
+        print("🌟 Top Performing Moods (by Creative Appeal):")
+        mood_scores = df.groupby('mood')['creative_appeal'].mean().sort_values(ascending=False)
+        for mood, score in mood_scores.head(5).items():
+            print(f"  {mood:15}: {score:.2f}")
+        print()
+
+def generate_detailed_report(existing_evals: Dict) -> str:
+    """Generate detailed evaluation report."""
+    if not existing_evals:
+        return "No evaluations found."
+    
+    df = pd.DataFrame.from_dict(existing_evals, orient='index')
+    
+    report_lines = [
+        "# CompI Phase 1.D - Detailed Evaluation Report",
+        f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        f"Total Images Evaluated: {len(df)}",
+        "",
+        "## Overall Performance Summary"
+    ]
+    
+    # Overall statistics
+    for criterion_key, criterion_info in EVALUATION_CRITERIA.items():
+        if criterion_key in df.columns:
+            mean_score = df[criterion_key].mean()
+            std_score = df[criterion_key].std()
+            report_lines.append(f"- **{criterion_info['name']}**: {mean_score:.2f} ± {std_score:.2f}")
+    
+    # Distribution analysis
+    report_lines.extend([
+        "",
+        "## Score Distribution Analysis"
+    ])
+    
+    for criterion_key, criterion_info in EVALUATION_CRITERIA.items():
+        if criterion_key in df.columns:
+            scores = df[criterion_key]
+            report_lines.extend([
+                f"",
+                f"### {criterion_info['name']}",
+                f"- Mean: {scores.mean():.2f}",
+                f"- Median: {scores.median():.2f}",
+                f"- Mode: {scores.mode().iloc[0] if not scores.mode().empty else 'N/A'}",
+                f"- Range: {scores.min()}-{scores.max()}",
+                f"- Distribution: " + " | ".join([f"{i}★: {(scores == i).sum()}" for i in range(1, 6)])
+            ])
+    
+    # Style/Mood performance
+    if 'style' in df.columns:
+        report_lines.extend([
+            "",
+            "## Style Performance Analysis"
+        ])
+        
+        for criterion_key in EVALUATION_CRITERIA.keys():
+            if criterion_key in df.columns:
+                style_performance = df.groupby('style')[criterion_key].agg(['mean', 'count']).sort_values('mean', ascending=False)
+                report_lines.extend([
+                    f"",
+                    f"### {EVALUATION_CRITERIA[criterion_key]['name']} by Style",
+                ])
+                
+                for style, (mean_score, count) in style_performance.iterrows():
+                    report_lines.append(f"- {style}: {mean_score:.2f} (n={count})")
+    
+    # Recommendations
+    report_lines.extend([
+        "",
+        "## Recommendations",
+        "",
+        "### Areas for Improvement"
+    ])
+    
+    # Find lowest scoring criteria
+    criterion_means = {}
+    for criterion_key, criterion_info in EVALUATION_CRITERIA.items():
+        if criterion_key in df.columns:
+            criterion_means[criterion_info['name']] = df[criterion_key].mean()
+    
+    if criterion_means:
+        lowest_criteria = sorted(criterion_means.items(), key=lambda x: x[1])[:2]
+        for criterion_name, score in lowest_criteria:
+            report_lines.append(f"- Focus on improving **{criterion_name}** (current: {score:.2f}/5)")
+    
+    report_lines.extend([
+        "",
+        "### Best Practices",
+        "- Continue systematic evaluation for trend analysis",
+        "- Experiment with parameter adjustments for low-scoring areas", 
+        "- Consider A/B testing different generation approaches",
+        "- Document successful style/mood combinations for reuse"
+    ])
+    
+    return "\n".join(report_lines)
+
+def batch_evaluate_images(images: List[Dict], scores: List[int], notes: str, output_dir: str):
+    """Batch evaluate unevaluated images."""
+    existing_evals = load_existing_evaluations()
+    unevaluated = [img for img in images if img['filename'] not in existing_evals]
+    
+    if not unevaluated:
+        print("✅ All images are already evaluated!")
+        return
+    
+    print(f"📦 Batch evaluating {len(unevaluated)} images...")
+    
+    # Map scores to criteria
+    criteria_keys = list(EVALUATION_CRITERIA.keys())
+    score_dict = dict(zip(criteria_keys, scores))
+    
+    for i, img_data in enumerate(unevaluated):
+        fname = img_data["filename"]
+        img_path = os.path.join(output_dir, fname)
+        
+        try:
+            metrics = get_image_metrics(img_path)
+            save_evaluation(fname, img_data, score_dict, notes, metrics)
+            print(f"  ✅ Evaluated: {fname}")
+        except Exception as e:
+            print(f"  ❌ Error evaluating {fname}: {e}")
+    
+    print(f"🎉 Batch evaluation completed!")
+
+def list_images(images: List[Dict], existing_evals: Dict, show_evaluated: bool = True, show_unevaluated: bool = True):
+    """List images with evaluation status."""
+    print(f"📋 Image List ({len(images)} total)")
+    print("-" * 80)
+    
+    for img_data in images:
+        fname = img_data["filename"]
+        is_evaluated = fname in existing_evals
+        
+        if (show_evaluated and is_evaluated) or (show_unevaluated and not is_evaluated):
+            status = "✅" if is_evaluated else "❌"
+            prompt = img_data.get('prompt', 'unknown')[:30]
+            style = img_data.get('style', 'unknown')[:15]
+            mood = img_data.get('mood', 'unknown')[:15]
+            
+            print(f"{status} {fname}")
+            print(f"    Prompt: {prompt}... | Style: {style} | Mood: {mood}")
+            
+            if is_evaluated:
+                eval_data = existing_evals[fname]
+                scores = [f"{k}:{eval_data.get(k, 'N/A')}" for k in EVALUATION_CRITERIA.keys() if k in eval_data]
+                print(f"    Scores: {' | '.join(scores[:3])}...")
+            print()
+
+def main():
+    """Main CLI function."""
+    args = setup_args()
+    
+    # Load images
+    images = load_images(args.output_dir)
+    if not images:
+        return
+    
+    # Apply filters
+    images = filter_images(images, args.style, args.mood)
+    
+    # Load existing evaluations
+    existing_evals = load_existing_evaluations()
+    
+    # Execute commands
+    if args.analyze:
+        analyze_evaluations(existing_evals)
+    
+    elif args.report:
+        report = generate_detailed_report(existing_evals)
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(report)
+            print(f"📄 Report saved to: {args.output}")
+        else:
+            print(report)
+    
+    elif args.batch_score:
+        batch_evaluate_images(images, args.batch_score, args.notes, args.output_dir)
+    
+    elif args.list_all:
+        list_images(images, existing_evals, True, True)
+    
+    elif args.list_evaluated:
+        list_images(images, existing_evals, True, False)
+    
+    elif args.list_unevaluated:
+        list_images(images, existing_evals, False, True)
+    
+    else:
+        print("❓ No command specified. Use --help for usage information.")
+
+if __name__ == "__main__":
+    main()

src/generators/compi_phase1d_evaluate_quality.py

@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 1.D: Baseline Output Quality Evaluation Tool
+
+This tool provides systematic evaluation of generated images with:
+- Visual quality assessment
+- Prompt adherence scoring
+- Style/mood consistency evaluation
+- Objective metrics calculation
+- Comprehensive logging and tracking
+
+Usage:
+    python src/generators/compi_phase1d_evaluate_quality.py
+    # Or via wrapper: python run_evaluation.py
+"""
+
+import os
+import re
+import csv
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+import argparse
+
+import streamlit as st
+from PIL import Image
+import imagehash
+import pandas as pd
+
+# -------- 1. CONFIGURATION --------
+
+OUTPUT_DIR = "outputs"
+EVAL_CSV = "outputs/evaluation_log.csv"
+EVAL_SUMMARY = "outputs/evaluation_summary.json"
+
+# Filename patterns for different CompI phases
+FILENAME_PATTERNS = [
+    # Phase 1.B Advanced styling: prompt_style_mood_timestamp_seed_variation
+    re.compile(r"^(?P<prompt>[a-z0-9_,]+)_(?P<style>[a-zA-Z0-9]+)_(?P<mood>[a-zA-Z0-9]+)_(?P<timestamp>\d{8}_\d{6})_seed(?P<seed>\d+)_v(?P<variation>\d+)\.png$"),
+    # Phase 1.A Basic generation: prompt_timestamp_seed
+    re.compile(r"^(?P<prompt>[a-z0-9_,]+)_(?P<timestamp>\d{8}_\d{6})_seed(?P<seed>\d+)\.png$"),
+    # Alternative pattern: prompt_style_timestamp_seed
+    re.compile(r"^(?P<prompt>[a-z0-9_,]+)_(?P<style>[a-zA-Z0-9]+)_(?P<timestamp>\d{8}_\d{6})_seed(?P<seed>\d+)\.png$"),
+]
+
+# Evaluation criteria
+EVALUATION_CRITERIA = {
+    "prompt_match": {
+        "name": "Prompt Adherence",
+        "description": "How well does the image match the text prompt?",
+        "scale": "1=Poor match, 3=Good match, 5=Perfect match"
+    },
+    "style_consistency": {
+        "name": "Style Consistency", 
+        "description": "How well does the image reflect the intended artistic style?",
+        "scale": "1=Style not evident, 3=Style present, 5=Style perfectly executed"
+    },
+    "mood_atmosphere": {
+        "name": "Mood & Atmosphere",
+        "description": "How well does the image convey the intended mood/atmosphere?", 
+        "scale": "1=Wrong mood, 3=Neutral/adequate, 5=Perfect mood"
+    },
+    "technical_quality": {
+        "name": "Technical Quality",
+        "description": "Overall image quality (resolution, composition, artifacts)",
+        "scale": "1=Poor quality, 3=Acceptable, 5=Excellent quality"
+    },
+    "creative_appeal": {
+        "name": "Creative Appeal",
+        "description": "Subjective aesthetic and creative value",
+        "scale": "1=Unappealing, 3=Decent, 5=Highly appealing"
+    }
+}
+
+# -------- 2. UTILITY FUNCTIONS --------
+
+def parse_filename(filename: str) -> Optional[Dict]:
+    """Parse filename to extract metadata using multiple patterns."""
+    for pattern in FILENAME_PATTERNS:
+        match = pattern.match(filename)
+        if match:
+            data = match.groupdict()
+            data["filename"] = filename
+            # Set defaults for missing fields
+            data.setdefault("style", "unknown")
+            data.setdefault("mood", "unknown") 
+            data.setdefault("variation", "1")
+            return data
+    return None
+
+def get_image_metrics(image_path: str) -> Dict:
+    """Calculate objective image metrics."""
+    try:
+        img = Image.open(image_path)
+        file_size = os.path.getsize(image_path)
+        
+        # Perceptual hashes for similarity detection
+        phash = str(imagehash.phash(img))
+        dhash = str(imagehash.dhash(img))
+        
+        # Basic image stats
+        width, height = img.size
+        aspect_ratio = width / height
+        
+        # Color analysis
+        if img.mode == 'RGB':
+            colors = img.getcolors(maxcolors=256*256*256)
+            unique_colors = len(colors) if colors else 0
+        else:
+            unique_colors = 0
+            
+        return {
+            "width": width,
+            "height": height,
+            "aspect_ratio": round(aspect_ratio, 3),
+            "file_size_kb": round(file_size / 1024, 2),
+            "unique_colors": unique_colors,
+            "phash": phash,
+            "dhash": dhash,
+            "format": img.format,
+            "mode": img.mode
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+def load_existing_evaluations() -> Dict:
+    """Load existing evaluations from CSV."""
+    if not os.path.exists(EVAL_CSV):
+        return {}
+    
+    try:
+        df = pd.read_csv(EVAL_CSV)
+        return df.set_index('filename').to_dict('index')
+    except Exception:
+        return {}
+
+def save_evaluation(filename: str, metadata: Dict, scores: Dict, notes: str, metrics: Dict):
+    """Save evaluation to CSV file."""
+    # Prepare row data
+    row_data = {
+        "filename": filename,
+        "timestamp": datetime.now().isoformat(),
+        "prompt": metadata.get("prompt", ""),
+        "style": metadata.get("style", ""),
+        "mood": metadata.get("mood", ""),
+        "seed": metadata.get("seed", ""),
+        "variation": metadata.get("variation", ""),
+        "generation_timestamp": metadata.get("timestamp", ""),
+        "notes": notes,
+        **scores,  # Add all evaluation scores
+        **{f"metric_{k}": v for k, v in metrics.items() if k != "error"}  # Add metrics with prefix
+    }
+    
+    # Create CSV if it doesn't exist
+    file_exists = os.path.exists(EVAL_CSV)
+    
+    with open(EVAL_CSV, "a", newline='', encoding='utf-8') as f:
+        fieldnames = list(row_data.keys())
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        
+        if not file_exists:
+            writer.writeheader()
+        writer.writerow(row_data)
+
+# -------- 3. STREAMLIT UI --------
+
+def main():
+    st.set_page_config(
+        page_title="CompI - Quality Evaluation", 
+        layout="wide",
+        initial_sidebar_state="expanded"
+    )
+    
+    st.title("🕵️ CompI Phase 1.D: Baseline Output Quality Evaluation")
+    
+    st.markdown("""
+    **Systematic evaluation tool for CompI-generated images**
+    
+    This tool helps you:
+    - 📊 Assess image quality across multiple criteria
+    - 📈 Track improvements over time  
+    - 🔍 Calculate objective metrics
+    - 📝 Maintain detailed evaluation logs
+    """)
+    
+    # Sidebar configuration
+    with st.sidebar:
+        st.header("⚙️ Configuration")
+        
+        # Output directory selection
+        output_dir = st.text_input("Output Directory", OUTPUT_DIR)
+        
+        # Evaluation mode
+        eval_mode = st.selectbox(
+            "Evaluation Mode",
+            ["Single Image Review", "Batch Evaluation", "Summary Analysis"]
+        )
+        
+        # Filter options
+        st.subheader("🔍 Filters")
+        show_evaluated = st.checkbox("Show already evaluated", True)
+        show_unevaluated = st.checkbox("Show unevaluated", True)
+    
+    # Load images
+    if not os.path.exists(output_dir):
+        st.error(f"Output directory '{output_dir}' not found!")
+        return
+        
+    image_files = [f for f in os.listdir(output_dir) if f.lower().endswith('.png')]
+    parsed_images = []
+    
+    for fname in image_files:
+        metadata = parse_filename(fname)
+        if metadata:
+            parsed_images.append(metadata)
+    
+    if not parsed_images:
+        st.warning("No CompI-generated images found with recognizable filename patterns.")
+        st.info("Expected patterns: prompt_style_mood_timestamp_seed_variation.png")
+        return
+    
+    # Load existing evaluations
+    existing_evals = load_existing_evaluations()
+    
+    # Filter images based on evaluation status
+    filtered_images = []
+    for img_data in parsed_images:
+        fname = img_data["filename"]
+        is_evaluated = fname in existing_evals
+        
+        if (show_evaluated and is_evaluated) or (show_unevaluated and not is_evaluated):
+            img_data["is_evaluated"] = is_evaluated
+            filtered_images.append(img_data)
+    
+    st.info(f"Found {len(filtered_images)} images matching your filters")
+    
+    # Main evaluation interface
+    if eval_mode == "Single Image Review":
+        single_image_evaluation(filtered_images, existing_evals, output_dir)
+    elif eval_mode == "Batch Evaluation":
+        batch_evaluation(filtered_images, existing_evals, output_dir)
+    else:
+        summary_analysis(existing_evals)
+
+def single_image_evaluation(images: List[Dict], existing_evals: Dict, output_dir: str):
+    """Single image evaluation interface."""
+    if not images:
+        st.warning("No images available for evaluation.")
+        return
+    
+    # Image selection
+    image_options = [f"{img['filename']} {'✅' if img['is_evaluated'] else '❌'}" for img in images]
+    selected_idx = st.selectbox("Select Image to Evaluate", range(len(image_options)), format_func=lambda x: image_options[x])
+    
+    if selected_idx is None:
+        return
+        
+    img_data = images[selected_idx]
+    fname = img_data["filename"]
+    img_path = os.path.join(output_dir, fname)
+    
+    # Display image and metadata
+    col1, col2 = st.columns([1, 1])
+    
+    with col1:
+        st.subheader("🖼️ Image")
+        try:
+            image = Image.open(img_path)
+            st.image(image, use_container_width=True)
+
+            # Calculate metrics
+            metrics = get_image_metrics(img_path)
+            if "error" not in metrics:
+                st.subheader("📊 Objective Metrics")
+                st.json(metrics)
+        except Exception as e:
+            st.error(f"Error loading image: {e}")
+            return
+    
+    with col2:
+        st.subheader("📋 Metadata")
+        st.json({k: v for k, v in img_data.items() if k != "filename"})
+        
+        # Evaluation form
+        st.subheader("⭐ Evaluation")
+        
+        # Load existing scores if available
+        existing = existing_evals.get(fname, {})
+        
+        with st.form(f"eval_form_{fname}"):
+            scores = {}
+            for criterion_key, criterion_info in EVALUATION_CRITERIA.items():
+                scores[criterion_key] = st.slider(
+                    f"{criterion_info['name']}",
+                    min_value=1, max_value=5, 
+                    value=int(existing.get(criterion_key, 3)),
+                    help=f"{criterion_info['description']}\n{criterion_info['scale']}"
+                )
+            
+            notes = st.text_area(
+                "Notes & Comments",
+                value=existing.get("notes", ""),
+                help="Additional observations, issues, or suggestions"
+            )
+            
+            submitted = st.form_submit_button("💾 Save Evaluation")
+            
+            if submitted:
+                save_evaluation(fname, img_data, scores, notes, metrics)
+                st.success(f"✅ Evaluation saved for {fname}")
+                st.experimental_rerun()
+
+def batch_evaluation(images: List[Dict], existing_evals: Dict, output_dir: str):
+    """Batch evaluation interface for multiple images."""
+    st.subheader("📦 Batch Evaluation")
+
+    unevaluated = [img for img in images if not img['is_evaluated']]
+
+    if not unevaluated:
+        st.info("All images have been evaluated!")
+        return
+
+    st.info(f"{len(unevaluated)} images pending evaluation")
+
+    # Quick batch scoring
+    with st.form("batch_eval_form"):
+        st.write("**Quick Batch Scoring** (applies to all unevaluated images)")
+
+        batch_scores = {}
+        for criterion_key, criterion_info in EVALUATION_CRITERIA.items():
+            batch_scores[criterion_key] = st.slider(
+                f"Default {criterion_info['name']}",
+                min_value=1, max_value=5, value=3,
+                help=f"Default score for {criterion_info['description']}"
+            )
+
+        batch_notes = st.text_area("Default Notes", "Batch evaluation")
+
+        if st.form_submit_button("Apply to All Unevaluated"):
+            progress_bar = st.progress(0)
+
+            for i, img_data in enumerate(unevaluated):
+                fname = img_data["filename"]
+                img_path = os.path.join(output_dir, fname)
+                metrics = get_image_metrics(img_path)
+
+                save_evaluation(fname, img_data, batch_scores, batch_notes, metrics)
+                progress_bar.progress((i + 1) / len(unevaluated))
+
+            st.success(f"✅ Batch evaluation completed for {len(unevaluated)} images!")
+            st.experimental_rerun()
+
+def summary_analysis(existing_evals: Dict):
+    """Display evaluation summary and analytics."""
+    st.subheader("📈 Evaluation Summary & Analytics")
+
+    if not existing_evals:
+        st.warning("No evaluations found. Please evaluate some images first.")
+        return
+
+    # Convert to DataFrame for analysis
+    df = pd.DataFrame.from_dict(existing_evals, orient='index')
+
+    # Basic statistics
+    col1, col2, col3 = st.columns(3)
+
+    with col1:
+        st.metric("Total Evaluated", len(df))
+
+    with col2:
+        if 'prompt_match' in df.columns:
+            avg_prompt_match = df['prompt_match'].mean()
+            st.metric("Avg Prompt Match", f"{avg_prompt_match:.2f}/5")
+
+    with col3:
+        if 'technical_quality' in df.columns:
+            avg_quality = df['technical_quality'].mean()
+            st.metric("Avg Technical Quality", f"{avg_quality:.2f}/5")
+
+    # Detailed analytics
+    st.subheader("📊 Detailed Analytics")
+
+    # Score distribution
+    if any(col in df.columns for col in EVALUATION_CRITERIA.keys()):
+        st.write("**Score Distribution by Criteria**")
+
+        score_cols = [col for col in EVALUATION_CRITERIA.keys() if col in df.columns]
+        if score_cols:
+            score_data = df[score_cols].mean().sort_values(ascending=False)
+            st.bar_chart(score_data)
+
+    # Style/Mood analysis
+    if 'style' in df.columns and 'mood' in df.columns:
+        st.write("**Performance by Style & Mood**")
+
+        col1, col2 = st.columns(2)
+
+        with col1:
+            if 'prompt_match' in df.columns:
+                style_performance = df.groupby('style')['prompt_match'].mean().sort_values(ascending=False)
+                st.write("**Best Performing Styles (Prompt Match)**")
+                st.bar_chart(style_performance)
+
+        with col2:
+            if 'creative_appeal' in df.columns:
+                mood_performance = df.groupby('mood')['creative_appeal'].mean().sort_values(ascending=False)
+                st.write("**Best Performing Moods (Creative Appeal)**")
+                st.bar_chart(mood_performance)
+
+    # Recent evaluations
+    st.subheader("🕒 Recent Evaluations")
+
+    if 'timestamp' in df.columns:
+        recent_df = df.sort_values('timestamp', ascending=False).head(10)
+        display_cols = ['prompt', 'style', 'mood'] + [col for col in EVALUATION_CRITERIA.keys() if col in df.columns]
+        display_cols = [col for col in display_cols if col in recent_df.columns]
+
+        if display_cols:
+            st.dataframe(recent_df[display_cols])
+
+    # Export options
+    st.subheader("💾 Export Data")
+
+    col1, col2 = st.columns(2)
+
+    with col1:
+        if st.button("📊 Download CSV"):
+            csv_data = df.to_csv()
+            st.download_button(
+                label="Download Evaluation Data",
+                data=csv_data,
+                file_name=f"compi_evaluation_export_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv",
+                mime="text/csv"
+            )
+
+    with col2:
+        if st.button("📋 Generate Report"):
+            # Generate summary report
+            report = generate_evaluation_report(df)
+            st.text_area("Evaluation Report", report, height=300)
+
+def generate_evaluation_report(df: pd.DataFrame) -> str:
+    """Generate a text summary report of evaluations."""
+    report_lines = [
+        "# CompI Phase 1.D - Evaluation Report",
+        f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+        "",
+        "## Summary Statistics",
+        f"- Total Images Evaluated: {len(df)}",
+    ]
+
+    # Add score summaries
+    for criterion_key, criterion_info in EVALUATION_CRITERIA.items():
+        if criterion_key in df.columns:
+            mean_score = df[criterion_key].mean()
+            std_score = df[criterion_key].std()
+            report_lines.append(f"- {criterion_info['name']}: {mean_score:.2f} ± {std_score:.2f}")
+
+    # Add style/mood analysis
+    if 'style' in df.columns:
+        report_lines.extend([
+            "",
+            "## Style Performance",
+        ])
+
+        if 'prompt_match' in df.columns:
+            style_scores = df.groupby('style')['prompt_match'].mean().sort_values(ascending=False)
+            for style, score in style_scores.head(5).items():
+                report_lines.append(f"- {style}: {score:.2f}")
+
+    if 'mood' in df.columns:
+        report_lines.extend([
+            "",
+            "## Mood Performance",
+        ])
+
+        if 'creative_appeal' in df.columns:
+            mood_scores = df.groupby('mood')['creative_appeal'].mean().sort_values(ascending=False)
+            for mood, score in mood_scores.head(5).items():
+                report_lines.append(f"- {mood}: {score:.2f}")
+
+    # Add recommendations
+    report_lines.extend([
+        "",
+        "## Recommendations",
+        "- Focus on improving lowest-scoring criteria",
+        "- Experiment with best-performing style/mood combinations",
+        "- Consider adjusting generation parameters for consistency",
+        "- Continue systematic evaluation for trend analysis"
+    ])
+
+    return "\n".join(report_lines)
+
+if __name__ == "__main__":
+    main()

src/generators/compi_phase1e_dataset_prep.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 1.E: Dataset Preparation for LoRA Fine-tuning
+
+This tool helps prepare your personal style dataset for LoRA training:
+- Organize and validate style images
+- Generate appropriate captions
+- Resize and format images for training
+- Create training/validation splits
+
+Usage:
+    python src/generators/compi_phase1e_dataset_prep.py --help
+    python src/generators/compi_phase1e_dataset_prep.py --input-dir my_style_images --style-name "my_art_style"
+"""
+
+import os
+import argparse
+import json
+import shutil
+from pathlib import Path
+from typing import List, Dict, Tuple
+import random
+
+from PIL import Image, ImageOps
+import pandas as pd
+
+# -------- 1. CONFIGURATION --------
+
+DEFAULT_IMAGE_SIZE = 512
+SUPPORTED_FORMATS = {'.jpg', '.jpeg', '.png', '.bmp', '.tiff', '.webp'}
+MIN_IMAGES_RECOMMENDED = 10
+TRAIN_SPLIT_RATIO = 0.8
+
+# -------- 2. UTILITY FUNCTIONS --------
+
+def setup_args():
+    """Setup command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="CompI Phase 1.E: Dataset Preparation for LoRA Fine-tuning",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Prepare dataset from a folder of images
+  python %(prog)s --input-dir my_artwork --style-name "impressionist_style"
+  
+  # Custom output directory and image size
+  python %(prog)s --input-dir paintings --style-name "oil_painting" --output-dir datasets/oil_style --size 768
+  
+  # Generate captions with custom trigger word
+  python %(prog)s --input-dir sketches --style-name "pencil_sketch" --trigger-word "sketch_style"
+        """
+    )
+    
+    parser.add_argument("--input-dir", required=True,
+                       help="Directory containing your style images")
+    
+    parser.add_argument("--style-name", required=True,
+                       help="Name for your style (used in file naming and captions)")
+    
+    parser.add_argument("--output-dir", 
+                       help="Output directory for prepared dataset (default: datasets/{style_name})")
+    
+    parser.add_argument("--trigger-word",
+                       help="Trigger word for style (default: style_name)")
+    
+    parser.add_argument("--size", type=int, default=DEFAULT_IMAGE_SIZE,
+                       help=f"Target image size in pixels (default: {DEFAULT_IMAGE_SIZE})")
+    
+    parser.add_argument("--caption-template", 
+                       default="a painting in {trigger_word} style",
+                       help="Template for generating captions")
+    
+    parser.add_argument("--train-split", type=float, default=TRAIN_SPLIT_RATIO,
+                       help=f"Ratio for train/validation split (default: {TRAIN_SPLIT_RATIO})")
+    
+    parser.add_argument("--copy-images", action="store_true",
+                       help="Copy images instead of creating symlinks")
+    
+    parser.add_argument("--validate-only", action="store_true",
+                       help="Only validate input directory without processing")
+    
+    return parser.parse_args()
+
+def validate_image_directory(input_dir: str) -> Tuple[List[str], List[str]]:
+    """Validate input directory and return valid/invalid image files."""
+    if not os.path.exists(input_dir):
+        raise FileNotFoundError(f"Input directory not found: {input_dir}")
+    
+    all_files = os.listdir(input_dir)
+    valid_images = []
+    invalid_files = []
+    
+    for filename in all_files:
+        filepath = os.path.join(input_dir, filename)
+        
+        # Check if it's a file
+        if not os.path.isfile(filepath):
+            continue
+            
+        # Check extension
+        ext = Path(filename).suffix.lower()
+        if ext not in SUPPORTED_FORMATS:
+            invalid_files.append(f"{filename} (unsupported format: {ext})")
+            continue
+        
+        # Try to open image
+        try:
+            with Image.open(filepath) as img:
+                # Basic validation
+                if img.size[0] < 64 or img.size[1] < 64:
+                    invalid_files.append(f"{filename} (too small: {img.size})")
+                    continue
+                    
+                valid_images.append(filename)
+        except Exception as e:
+            invalid_files.append(f"{filename} (corrupt: {str(e)})")
+    
+    return valid_images, invalid_files
+
+def process_image(input_path: str, output_path: str, target_size: int) -> Dict:
+    """Process a single image for training."""
+    with Image.open(input_path) as img:
+        # Convert to RGB if needed
+        if img.mode != 'RGB':
+            img = img.convert('RGB')
+        
+        # Get original dimensions
+        original_size = img.size
+        
+        # Resize maintaining aspect ratio, then center crop
+        img = ImageOps.fit(img, (target_size, target_size), Image.Resampling.LANCZOS)
+        
+        # Save processed image
+        img.save(output_path, 'PNG', quality=95)
+        
+        return {
+            'original_size': original_size,
+            'processed_size': img.size,
+            'format': 'PNG'
+        }
+
+def generate_captions(image_files: List[str], caption_template: str, trigger_word: str) -> Dict[str, str]:
+    """Generate captions for training images."""
+    captions = {}
+    
+    for filename in image_files:
+        # Basic caption using template
+        caption = caption_template.format(trigger_word=trigger_word)
+        
+        # You could add more sophisticated caption generation here
+        # For example, using BLIP or other image captioning models
+        
+        captions[filename] = caption
+    
+    return captions
+
+def create_dataset_structure(output_dir: str, style_name: str):
+    """Create the dataset directory structure."""
+    dataset_dir = Path(output_dir)
+    
+    # Create main directories
+    dirs_to_create = [
+        dataset_dir,
+        dataset_dir / "images",
+        dataset_dir / "train",
+        dataset_dir / "validation"
+    ]
+    
+    for dir_path in dirs_to_create:
+        dir_path.mkdir(parents=True, exist_ok=True)
+    
+    return dataset_dir
+
+def split_dataset(image_files: List[str], train_ratio: float) -> Tuple[List[str], List[str]]:
+    """Split images into train and validation sets."""
+    random.shuffle(image_files)
+    
+    train_count = int(len(image_files) * train_ratio)
+    train_files = image_files[:train_count]
+    val_files = image_files[train_count:]
+    
+    return train_files, val_files
+
+def save_metadata(dataset_dir: Path, metadata: Dict):
+    """Save dataset metadata."""
+    metadata_file = dataset_dir / "dataset_info.json"
+    
+    with open(metadata_file, 'w') as f:
+        json.dump(metadata, f, indent=2)
+    
+    print(f"📄 Dataset metadata saved to: {metadata_file}")
+
+def create_captions_file(dataset_dir: Path, captions: Dict[str, str], split_name: str):
+    """Create captions file for training."""
+    captions_file = dataset_dir / f"{split_name}_captions.txt"
+    
+    with open(captions_file, 'w') as f:
+        for filename, caption in captions.items():
+            f.write(f"{filename}: {caption}\n")
+    
+    return captions_file
+
+# -------- 3. MAIN PROCESSING FUNCTION --------
+
+def prepare_dataset(args):
+    """Main dataset preparation function."""
+    print(f"🎨 CompI Phase 1.E: Preparing LoRA Dataset for '{args.style_name}'")
+    print("=" * 60)
+    
+    # Setup paths
+    input_dir = Path(args.input_dir)
+    if args.output_dir:
+        output_dir = Path(args.output_dir)
+    else:
+        output_dir = Path("datasets") / args.style_name
+    
+    trigger_word = args.trigger_word or args.style_name
+    
+    print(f"📁 Input directory: {input_dir}")
+    print(f"📁 Output directory: {output_dir}")
+    print(f"🎯 Style name: {args.style_name}")
+    print(f"🔤 Trigger word: {trigger_word}")
+    print(f"📐 Target size: {args.size}x{args.size}")
+    
+    # Validate input directory
+    print(f"\n🔍 Validating input directory...")
+    valid_images, invalid_files = validate_image_directory(str(input_dir))
+    
+    print(f"✅ Found {len(valid_images)} valid images")
+    if invalid_files:
+        print(f"⚠️  Found {len(invalid_files)} invalid files:")
+        for invalid in invalid_files[:5]:  # Show first 5
+            print(f"   - {invalid}")
+        if len(invalid_files) > 5:
+            print(f"   ... and {len(invalid_files) - 5} more")
+    
+    if len(valid_images) < MIN_IMAGES_RECOMMENDED:
+        print(f"⚠️  Warning: Only {len(valid_images)} images found. Recommended minimum: {MIN_IMAGES_RECOMMENDED}")
+        print("   Consider adding more images for better style learning.")
+    
+    if args.validate_only:
+        print("✅ Validation complete (--validate-only specified)")
+        return
+    
+    # Create dataset structure
+    print(f"\n📁 Creating dataset structure...")
+    dataset_dir = create_dataset_structure(str(output_dir), args.style_name)
+    
+    # Split dataset
+    train_files, val_files = split_dataset(valid_images, args.train_split)
+    print(f"📊 Dataset split: {len(train_files)} train, {len(val_files)} validation")
+    
+    # Generate captions
+    print(f"\n📝 Generating captions...")
+    all_captions = generate_captions(valid_images, args.caption_template, trigger_word)
+    
+    # Process images
+    print(f"\n🖼️  Processing images...")
+    processed_count = 0
+    processing_stats = []
+    
+    for split_name, file_list in [("train", train_files), ("validation", val_files)]:
+        if not file_list:
+            continue
+            
+        split_dir = dataset_dir / split_name
+        split_captions = {}
+        
+        for filename in file_list:
+            input_path = input_dir / filename
+            output_filename = f"{Path(filename).stem}.png"
+            output_path = split_dir / output_filename
+            
+            try:
+                stats = process_image(str(input_path), str(output_path), args.size)
+                processing_stats.append(stats)
+                split_captions[output_filename] = all_captions[filename]
+                processed_count += 1
+                
+                if processed_count % 10 == 0:
+                    print(f"   Processed {processed_count}/{len(valid_images)} images...")
+                    
+            except Exception as e:
+                print(f"❌ Error processing {filename}: {e}")
+        
+        # Create captions file for this split
+        if split_captions:
+            captions_file = create_captions_file(dataset_dir, split_captions, split_name)
+            print(f"📝 Created {split_name} captions: {captions_file}")
+    
+    # Save metadata
+    metadata = {
+        'style_name': args.style_name,
+        'trigger_word': trigger_word,
+        'total_images': len(valid_images),
+        'train_images': len(train_files),
+        'validation_images': len(val_files),
+        'image_size': args.size,
+        'caption_template': args.caption_template,
+        'created_at': pd.Timestamp.now().isoformat(),
+        'processing_stats': {
+            'processed_count': processed_count,
+            'failed_count': len(valid_images) - processed_count
+        }
+    }
+    
+    save_metadata(dataset_dir, metadata)
+    
+    print(f"\n🎉 Dataset preparation complete!")
+    print(f"📁 Dataset location: {dataset_dir}")
+    print(f"📊 Ready for LoRA training with {processed_count} processed images")
+    print(f"\n💡 Next steps:")
+    print(f"   1. Review the generated dataset in: {dataset_dir}")
+    print(f"   2. Run LoRA training: python src/generators/compi_phase1e_lora_training.py --dataset-dir {dataset_dir}")
+
+def main():
+    """Main function."""
+    args = setup_args()
+    
+    try:
+        prepare_dataset(args)
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        return 1
+    
+    return 0
+
+if __name__ == "__main__":
+    exit(main())

src/generators/compi_phase1e_lora_training.py

@@ -0,0 +1,458 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 1.E: LoRA Fine-tuning for Personal Style
+
+This script implements LoRA (Low-Rank Adaptation) fine-tuning for Stable Diffusion
+to learn your personal artistic style.
+
+Usage:
+    python src/generators/compi_phase1e_lora_training.py --dataset-dir datasets/my_style
+    python src/generators/compi_phase1e_lora_training.py --help
+"""
+
+import os
+import argparse
+import json
+import math
+from pathlib import Path
+from typing import Dict, List, Optional
+import logging
+
+import torch
+import torch.nn.functional as F
+from torch.utils.data import Dataset, DataLoader
+from PIL import Image
+import numpy as np
+from tqdm import tqdm
+
+# Diffusers and transformers
+from diffusers import (
+    StableDiffusionPipeline, 
+    UNet2DConditionModel, 
+    DDPMScheduler,
+    AutoencoderKL
+)
+from transformers import CLIPTextModel, CLIPTokenizer
+from peft import LoraConfig, get_peft_model, TaskType
+
+# -------- 1. CONFIGURATION --------
+
+DEFAULT_MODEL = "runwayml/stable-diffusion-v1-5"
+DEFAULT_RESOLUTION = 512
+DEFAULT_BATCH_SIZE = 1
+DEFAULT_LEARNING_RATE = 1e-4
+DEFAULT_EPOCHS = 100
+DEFAULT_LORA_RANK = 4
+DEFAULT_LORA_ALPHA = 32
+
+# -------- 2. DATASET CLASS --------
+
+class StyleDataset(Dataset):
+    """Dataset class for LoRA fine-tuning."""
+    
+    def __init__(self, dataset_dir: str, split: str = "train", resolution: int = 512):
+        self.dataset_dir = Path(dataset_dir)
+        self.split = split
+        self.resolution = resolution
+        
+        # Load images and captions
+        self.images_dir = self.dataset_dir / split
+        self.captions_file = self.dataset_dir / f"{split}_captions.txt"
+        
+        if not self.images_dir.exists():
+            raise FileNotFoundError(f"Images directory not found: {self.images_dir}")
+        
+        if not self.captions_file.exists():
+            raise FileNotFoundError(f"Captions file not found: {self.captions_file}")
+        
+        # Load captions
+        self.image_captions = {}
+        with open(self.captions_file, 'r') as f:
+            for line in f:
+                if ':' in line:
+                    filename, caption = line.strip().split(':', 1)
+                    self.image_captions[filename.strip()] = caption.strip()
+        
+        # Get list of images
+        self.image_files = [f for f in os.listdir(self.images_dir) 
+                           if f.lower().endswith(('.png', '.jpg', '.jpeg'))]
+        
+        # Filter to only images with captions
+        self.image_files = [f for f in self.image_files if f in self.image_captions]
+        
+        print(f"Loaded {len(self.image_files)} images for {split} split")
+    
+    def __len__(self):
+        return len(self.image_files)
+    
+    def __getitem__(self, idx):
+        filename = self.image_files[idx]
+        image_path = self.images_dir / filename
+        caption = self.image_captions[filename]
+        
+        # Load and preprocess image
+        image = Image.open(image_path).convert('RGB')
+        image = image.resize((self.resolution, self.resolution), Image.Resampling.LANCZOS)
+        
+        # Convert to tensor and normalize to [-1, 1]
+        image = np.array(image).astype(np.float32) / 255.0
+        image = (image - 0.5) / 0.5
+        image = torch.from_numpy(image).permute(2, 0, 1)
+        
+        return {
+            'pixel_values': image,
+            'caption': caption,
+            'filename': filename
+        }
+
+# -------- 3. TRAINING FUNCTIONS --------
+
+def setup_args():
+    """Setup command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="CompI Phase 1.E: LoRA Fine-tuning for Personal Style",
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    
+    parser.add_argument("--dataset-dir", required=True,
+                       help="Directory containing prepared dataset")
+    
+    parser.add_argument("--output-dir",
+                       help="Output directory for LoRA weights (default: lora_models/{style_name})")
+    
+    parser.add_argument("--model-name", default=DEFAULT_MODEL,
+                       help=f"Base Stable Diffusion model (default: {DEFAULT_MODEL})")
+    
+    parser.add_argument("--resolution", type=int, default=DEFAULT_RESOLUTION,
+                       help=f"Training resolution (default: {DEFAULT_RESOLUTION})")
+    
+    parser.add_argument("--batch-size", type=int, default=DEFAULT_BATCH_SIZE,
+                       help=f"Training batch size (default: {DEFAULT_BATCH_SIZE})")
+    
+    parser.add_argument("--learning-rate", type=float, default=DEFAULT_LEARNING_RATE,
+                       help=f"Learning rate (default: {DEFAULT_LEARNING_RATE})")
+    
+    parser.add_argument("--epochs", type=int, default=DEFAULT_EPOCHS,
+                       help=f"Number of training epochs (default: {DEFAULT_EPOCHS})")
+    
+    parser.add_argument("--lora-rank", type=int, default=DEFAULT_LORA_RANK,
+                       help=f"LoRA rank (default: {DEFAULT_LORA_RANK})")
+    
+    parser.add_argument("--lora-alpha", type=int, default=DEFAULT_LORA_ALPHA,
+                       help=f"LoRA alpha (default: {DEFAULT_LORA_ALPHA})")
+    
+    parser.add_argument("--save-steps", type=int, default=100,
+                       help="Save checkpoint every N steps")
+    
+    parser.add_argument("--validation-steps", type=int, default=50,
+                       help="Run validation every N steps")
+    
+    parser.add_argument("--mixed-precision", action="store_true",
+                       help="Use mixed precision training")
+    
+    parser.add_argument("--gradient-checkpointing", action="store_true",
+                       help="Use gradient checkpointing to save memory")
+    
+    return parser.parse_args()
+
+def load_models(model_name: str, device: str):
+    """Load Stable Diffusion components."""
+    print(f"Loading models from {model_name}...")
+    
+    # Load tokenizer and text encoder
+    tokenizer = CLIPTokenizer.from_pretrained(model_name, subfolder="tokenizer")
+    text_encoder = CLIPTextModel.from_pretrained(model_name, subfolder="text_encoder")
+    
+    # Load VAE
+    vae = AutoencoderKL.from_pretrained(model_name, subfolder="vae")
+    
+    # Load UNet
+    unet = UNet2DConditionModel.from_pretrained(model_name, subfolder="unet")
+    
+    # Load noise scheduler
+    noise_scheduler = DDPMScheduler.from_pretrained(model_name, subfolder="scheduler")
+    
+    # Move to device
+    text_encoder.to(device)
+    vae.to(device)
+    unet.to(device)
+    
+    # Set to eval mode (we only train LoRA adapters)
+    text_encoder.eval()
+    vae.eval()
+    unet.train()  # UNet needs to be in train mode for LoRA
+    
+    return tokenizer, text_encoder, vae, unet, noise_scheduler
+
+def setup_lora(unet: UNet2DConditionModel, lora_rank: int, lora_alpha: int):
+    """Setup LoRA adapters for UNet."""
+    print(f"Setting up LoRA with rank={lora_rank}, alpha={lora_alpha}")
+    
+    # Define LoRA config
+    lora_config = LoraConfig(
+        r=lora_rank,
+        lora_alpha=lora_alpha,
+        target_modules=[
+            "to_k", "to_q", "to_v", "to_out.0",
+            "proj_in", "proj_out",
+            "ff.net.0.proj", "ff.net.2"
+        ],
+        lora_dropout=0.1,
+    )
+    
+    # Apply LoRA to UNet
+    unet = get_peft_model(unet, lora_config)
+    
+    # Print trainable parameters
+    trainable_params = sum(p.numel() for p in unet.parameters() if p.requires_grad)
+    total_params = sum(p.numel() for p in unet.parameters())
+    
+    print(f"Trainable parameters: {trainable_params:,} ({100 * trainable_params / total_params:.2f}%)")
+    
+    return unet
+
+def encode_text(tokenizer, text_encoder, captions: List[str], device: str):
+    """Encode text captions."""
+    inputs = tokenizer(
+        captions,
+        padding="max_length",
+        max_length=tokenizer.model_max_length,
+        truncation=True,
+        return_tensors="pt"
+    )
+    
+    with torch.no_grad():
+        text_embeddings = text_encoder(inputs.input_ids.to(device))[0]
+    
+    return text_embeddings
+
+def training_step(batch, unet, vae, text_encoder, tokenizer, noise_scheduler, device):
+    """Single training step."""
+    pixel_values = batch['pixel_values'].to(device)
+    captions = batch['caption']
+    
+    # Encode images to latent space
+    with torch.no_grad():
+        latents = vae.encode(pixel_values).latent_dist.sample()
+        latents = latents * vae.config.scaling_factor
+    
+    # Sample noise
+    noise = torch.randn_like(latents)
+    batch_size = latents.shape[0]
+    
+    # Sample random timesteps
+    timesteps = torch.randint(
+        0, noise_scheduler.config.num_train_timesteps, 
+        (batch_size,), device=device
+    ).long()
+    
+    # Add noise to latents
+    noisy_latents = noise_scheduler.add_noise(latents, noise, timesteps)
+    
+    # Encode text
+    text_embeddings = encode_text(tokenizer, text_encoder, captions, device)
+    
+    # Predict noise
+    noise_pred = unet(noisy_latents, timesteps, text_embeddings).sample
+    
+    # Calculate loss
+    loss = F.mse_loss(noise_pred.float(), noise.float(), reduction="mean")
+    
+    return loss
+
+def validate_model(val_dataloader, unet, vae, text_encoder, tokenizer, noise_scheduler, device):
+    """Validation step."""
+    unet.eval()
+    total_loss = 0
+    num_batches = 0
+    
+    with torch.no_grad():
+        for batch in val_dataloader:
+            loss = training_step(batch, unet, vae, text_encoder, tokenizer, noise_scheduler, device)
+            total_loss += loss.item()
+            num_batches += 1
+    
+    unet.train()
+    return total_loss / num_batches if num_batches > 0 else 0
+
+def save_lora_weights(unet, output_dir: Path, step: int):
+    """Save LoRA weights."""
+    checkpoint_dir = output_dir / f"checkpoint-{step}"
+    checkpoint_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Save LoRA weights
+    unet.save_pretrained(checkpoint_dir)
+    
+    print(f"💾 Saved checkpoint to: {checkpoint_dir}")
+    return checkpoint_dir
+
+# -------- 4. MAIN TRAINING FUNCTION --------
+
+def train_lora(args):
+    """Main training function."""
+    print(f"🎨 CompI Phase 1.E: Starting LoRA Training")
+    print("=" * 50)
+    
+    # Setup device
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    print(f"🖥️  Using device: {device}")
+    
+    # Load dataset info
+    dataset_dir = Path(args.dataset_dir)
+    info_file = dataset_dir / "dataset_info.json"
+    
+    if info_file.exists():
+        with open(info_file) as f:
+            dataset_info = json.load(f)
+        style_name = dataset_info.get('style_name', 'custom_style')
+        print(f"🎯 Training style: {style_name}")
+    else:
+        style_name = dataset_dir.name
+        print(f"⚠️  No dataset info found, using directory name: {style_name}")
+    
+    # Setup output directory
+    if args.output_dir:
+        output_dir = Path(args.output_dir)
+    else:
+        output_dir = Path("lora_models") / style_name
+    
+    output_dir.mkdir(parents=True, exist_ok=True)
+    print(f"📁 Output directory: {output_dir}")
+    
+    # Load datasets
+    print(f"📊 Loading datasets...")
+    train_dataset = StyleDataset(args.dataset_dir, "train", args.resolution)
+    
+    try:
+        val_dataset = StyleDataset(args.dataset_dir, "validation", args.resolution)
+        has_validation = True
+    except FileNotFoundError:
+        print("⚠️  No validation set found, using train set for validation")
+        val_dataset = train_dataset
+        has_validation = False
+    
+    # Create data loaders
+    train_dataloader = DataLoader(
+        train_dataset, 
+        batch_size=args.batch_size, 
+        shuffle=True,
+        num_workers=2,
+        pin_memory=True
+    )
+    
+    val_dataloader = DataLoader(
+        val_dataset,
+        batch_size=args.batch_size,
+        shuffle=False,
+        num_workers=2,
+        pin_memory=True
+    )
+    
+    # Load models
+    tokenizer, text_encoder, vae, unet, noise_scheduler = load_models(args.model_name, device)
+    
+    # Setup LoRA
+    unet = setup_lora(unet, args.lora_rank, args.lora_alpha)
+    
+    # Setup optimizer
+    optimizer = torch.optim.AdamW(
+        unet.parameters(),
+        lr=args.learning_rate,
+        betas=(0.9, 0.999),
+        weight_decay=0.01,
+        eps=1e-08
+    )
+    
+    # Calculate total steps
+    total_steps = len(train_dataloader) * args.epochs
+    print(f"📈 Total training steps: {total_steps}")
+    
+    # Training loop
+    print(f"\n🚀 Starting training...")
+    global_step = 0
+    best_val_loss = float('inf')
+    
+    for epoch in range(args.epochs):
+        print(f"\n📅 Epoch {epoch + 1}/{args.epochs}")
+        
+        epoch_loss = 0
+        progress_bar = tqdm(train_dataloader, desc=f"Training")
+        
+        for batch in progress_bar:
+            # Training step
+            loss = training_step(batch, unet, vae, text_encoder, tokenizer, noise_scheduler, device)
+            
+            # Backward pass
+            loss.backward()
+            optimizer.step()
+            optimizer.zero_grad()
+            
+            # Update metrics
+            epoch_loss += loss.item()
+            global_step += 1
+            
+            # Update progress bar
+            progress_bar.set_postfix({
+                'loss': f"{loss.item():.4f}",
+                'avg_loss': f"{epoch_loss / (progress_bar.n + 1):.4f}"
+            })
+            
+            # Validation
+            if global_step % args.validation_steps == 0:
+                val_loss = validate_model(val_dataloader, unet, vae, text_encoder, tokenizer, noise_scheduler, device)
+                print(f"\n📊 Step {global_step}: Train Loss = {loss.item():.4f}, Val Loss = {val_loss:.4f}")
+                
+                # Save best model
+                if val_loss < best_val_loss:
+                    best_val_loss = val_loss
+                    save_lora_weights(unet, output_dir, global_step)
+            
+            # Save checkpoint
+            if global_step % args.save_steps == 0:
+                save_lora_weights(unet, output_dir, global_step)
+        
+        # End of epoch
+        avg_epoch_loss = epoch_loss / len(train_dataloader)
+        print(f"📊 Epoch {epoch + 1} complete. Average loss: {avg_epoch_loss:.4f}")
+    
+    # Save final model
+    final_checkpoint = save_lora_weights(unet, output_dir, global_step)
+    
+    # Save training info
+    training_info = {
+        'style_name': style_name,
+        'model_name': args.model_name,
+        'total_steps': global_step,
+        'epochs': args.epochs,
+        'learning_rate': args.learning_rate,
+        'lora_rank': args.lora_rank,
+        'lora_alpha': args.lora_alpha,
+        'final_checkpoint': str(final_checkpoint),
+        'best_val_loss': best_val_loss
+    }
+    
+    with open(output_dir / "training_info.json", 'w') as f:
+        json.dump(training_info, f, indent=2)
+    
+    print(f"\n🎉 Training complete!")
+    print(f"📁 LoRA weights saved to: {output_dir}")
+    print(f"💡 Next steps:")
+    print(f"   1. Test your style: python src/generators/compi_phase1e_style_generation.py --lora-path {final_checkpoint}")
+    print(f"   2. Integrate with UI: Use the style in your Streamlit interface")
+
+def main():
+    """Main function."""
+    args = setup_args()
+    
+    try:
+        train_lora(args)
+    except Exception as e:
+        print(f"❌ Training failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+    
+    return 0
+
+if __name__ == "__main__":
+    exit(main())

src/generators/compi_phase1e_style_generation.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 1.E: Personal Style Generation with LoRA
+
+Generate images using your trained LoRA personal style weights.
+
+Usage:
+    python src/generators/compi_phase1e_style_generation.py --lora-path lora_models/my_style/checkpoint-1000
+    python src/generators/compi_phase1e_style_generation.py --help
+"""
+
+import os
+import argparse
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, List
+
+import torch
+from PIL import Image
+from diffusers import StableDiffusionPipeline, DPMSolverMultistepScheduler
+from peft import PeftModel
+
+# -------- 1. CONFIGURATION --------
+
+DEFAULT_MODEL = "runwayml/stable-diffusion-v1-5"
+DEFAULT_STEPS = 30
+DEFAULT_GUIDANCE = 7.5
+DEFAULT_WIDTH = 512
+DEFAULT_HEIGHT = 512
+OUTPUT_DIR = "outputs"
+
+# -------- 2. UTILITY FUNCTIONS --------
+
+def setup_args():
+    """Setup command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="CompI Phase 1.E: Personal Style Generation with LoRA",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Generate with trained LoRA style
+  python %(prog)s --lora-path lora_models/my_style/checkpoint-1000 "a cat in my_style"
+  
+  # Interactive mode
+  python %(prog)s --lora-path lora_models/my_style/checkpoint-1000 --interactive
+  
+  # Multiple variations
+  python %(prog)s --lora-path lora_models/my_style/checkpoint-1000 "landscape" --variations 4
+        """
+    )
+    
+    parser.add_argument("prompt", nargs="*", help="Text prompt for generation")
+    
+    parser.add_argument("--lora-path", required=True,
+                       help="Path to trained LoRA checkpoint directory")
+    
+    parser.add_argument("--model-name", default=DEFAULT_MODEL,
+                       help=f"Base Stable Diffusion model (default: {DEFAULT_MODEL})")
+    
+    parser.add_argument("--variations", "-v", type=int, default=1,
+                       help="Number of variations to generate")
+    
+    parser.add_argument("--steps", type=int, default=DEFAULT_STEPS,
+                       help=f"Number of inference steps (default: {DEFAULT_STEPS})")
+    
+    parser.add_argument("--guidance", type=float, default=DEFAULT_GUIDANCE,
+                       help=f"Guidance scale (default: {DEFAULT_GUIDANCE})")
+    
+    parser.add_argument("--width", type=int, default=DEFAULT_WIDTH,
+                       help=f"Image width (default: {DEFAULT_WIDTH})")
+    
+    parser.add_argument("--height", type=int, default=DEFAULT_HEIGHT,
+                       help=f"Image height (default: {DEFAULT_HEIGHT})")
+    
+    parser.add_argument("--seed", type=int,
+                       help="Random seed for reproducible generation")
+    
+    parser.add_argument("--negative", "-n", default="",
+                       help="Negative prompt")
+    
+    parser.add_argument("--lora-scale", type=float, default=1.0,
+                       help="LoRA scale factor (0.0-2.0, default: 1.0)")
+    
+    parser.add_argument("--interactive", "-i", action="store_true",
+                       help="Interactive mode")
+    
+    parser.add_argument("--output-dir", default=OUTPUT_DIR,
+                       help=f"Output directory (default: {OUTPUT_DIR})")
+    
+    parser.add_argument("--list-styles", action="store_true",
+                       help="List available LoRA styles")
+    
+    return parser.parse_args()
+
+def load_lora_info(lora_path: str) -> dict:
+    """Load LoRA training information."""
+    lora_dir = Path(lora_path)
+    
+    # Try to find training info
+    info_files = [
+        lora_dir / "training_info.json",
+        lora_dir.parent / "training_info.json"
+    ]
+    
+    for info_file in info_files:
+        if info_file.exists():
+            with open(info_file) as f:
+                return json.load(f)
+    
+    # Fallback info
+    return {
+        'style_name': lora_dir.parent.name,
+        'model_name': DEFAULT_MODEL,
+        'lora_rank': 4,
+        'lora_alpha': 32
+    }
+
+def load_pipeline_with_lora(model_name: str, lora_path: str, device: str):
+    """Load Stable Diffusion pipeline with LoRA weights."""
+    print(f"🔄 Loading base model: {model_name}")
+    
+    # Load base pipeline
+    pipe = StableDiffusionPipeline.from_pretrained(
+        model_name,
+        torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+        safety_checker=None,
+        requires_safety_checker=False
+    )
+    
+    # Use DPM solver for faster inference
+    pipe.scheduler = DPMSolverMultistepScheduler.from_config(pipe.scheduler.config)
+    
+    print(f"🎨 Loading LoRA weights from: {lora_path}")
+    
+    # Load LoRA weights
+    lora_dir = Path(lora_path)
+    if not lora_dir.exists():
+        raise FileNotFoundError(f"LoRA path not found: {lora_path}")
+    
+    # Apply LoRA to UNet
+    pipe.unet = PeftModel.from_pretrained(pipe.unet, lora_path)
+    
+    # Move to device
+    pipe = pipe.to(device)
+    
+    # Enable memory efficient attention if available
+    if hasattr(pipe, "enable_xformers_memory_efficient_attention"):
+        try:
+            pipe.enable_xformers_memory_efficient_attention()
+        except Exception:
+            pass
+    
+    return pipe
+
+def generate_with_style(
+    pipe, 
+    prompt: str, 
+    negative_prompt: str = "",
+    num_inference_steps: int = DEFAULT_STEPS,
+    guidance_scale: float = DEFAULT_GUIDANCE,
+    width: int = DEFAULT_WIDTH,
+    height: int = DEFAULT_HEIGHT,
+    seed: Optional[int] = None,
+    lora_scale: float = 1.0
+):
+    """Generate image with LoRA style."""
+    
+    # Set LoRA scale
+    if hasattr(pipe.unet, 'set_adapter_scale'):
+        pipe.unet.set_adapter_scale(lora_scale)
+    
+    # Setup generator
+    if seed is not None:
+        generator = torch.Generator(device=pipe.device).manual_seed(seed)
+    else:
+        generator = None
+        seed = torch.seed()
+    
+    # Generate image
+    with torch.autocast(pipe.device.type):
+        result = pipe(
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+            num_inference_steps=num_inference_steps,
+            guidance_scale=guidance_scale,
+            width=width,
+            height=height,
+            generator=generator
+        )
+    
+    return result.images[0], seed
+
+def save_generated_image(
+    image: Image.Image, 
+    prompt: str, 
+    style_name: str,
+    seed: int,
+    variation: int,
+    output_dir: str,
+    metadata: dict = None
+):
+    """Save generated image with metadata."""
+    
+    # Create output directory
+    os.makedirs(output_dir, exist_ok=True)
+    
+    # Generate filename
+    prompt_slug = "_".join(prompt.lower().split()[:5])
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"{prompt_slug[:25]}_lora_{style_name}_{timestamp}_seed{seed}_v{variation}.png"
+    filepath = os.path.join(output_dir, filename)
+    
+    # Save image
+    image.save(filepath)
+    
+    # Save metadata if provided
+    if metadata:
+        metadata_file = filepath.replace('.png', '_metadata.json')
+        with open(metadata_file, 'w') as f:
+            json.dump(metadata, f, indent=2)
+    
+    return filepath
+
+def list_available_styles():
+    """List available LoRA styles."""
+    lora_dir = Path("lora_models")
+    
+    if not lora_dir.exists():
+        print("❌ No LoRA models directory found")
+        return
+    
+    print("🎨 Available LoRA Styles:")
+    print("=" * 40)
+    
+    styles_found = False
+    for style_dir in lora_dir.iterdir():
+        if style_dir.is_dir():
+            # Look for checkpoints
+            checkpoints = list(style_dir.glob("checkpoint-*"))
+            if checkpoints:
+                styles_found = True
+                latest_checkpoint = max(checkpoints, key=lambda x: int(x.name.split('-')[1]))
+                
+                # Load info if available
+                info_file = style_dir / "training_info.json"
+                if info_file.exists():
+                    with open(info_file) as f:
+                        info = json.load(f)
+                    print(f"📁 {style_dir.name}")
+                    print(f"   Latest: {latest_checkpoint.name}")
+                    print(f"   Steps: {info.get('total_steps', 'unknown')}")
+                    print(f"   Model: {info.get('model_name', 'unknown')}")
+                else:
+                    print(f"📁 {style_dir.name}")
+                    print(f"   Latest: {latest_checkpoint.name}")
+                print()
+    
+    if not styles_found:
+        print("❌ No trained LoRA styles found")
+        print("💡 Train a style first using: python src/generators/compi_phase1e_lora_training.py")
+
+def interactive_generation(pipe, lora_info: dict, args):
+    """Interactive generation mode."""
+    style_name = lora_info.get('style_name', 'custom')
+    
+    print(f"🎨 Interactive LoRA Style Generation - {style_name}")
+    print("=" * 50)
+    print("💡 Tips:")
+    print(f"   - Include '{style_name}' or trigger words in your prompts")
+    print(f"   - Adjust LoRA scale (0.0-2.0) to control style strength")
+    print("   - Type 'quit' to exit")
+    print()
+    
+    while True:
+        try:
+            # Get prompt
+            prompt = input("Enter prompt: ").strip()
+            if not prompt or prompt.lower() == 'quit':
+                break
+            
+            # Get optional parameters
+            variations = input(f"Variations (default: 1): ").strip()
+            variations = int(variations) if variations.isdigit() else 1
+            
+            lora_scale = input(f"LoRA scale (default: {args.lora_scale}): ").strip()
+            lora_scale = float(lora_scale) if lora_scale else args.lora_scale
+            
+            # Generate images
+            print(f"🎨 Generating {variations} variation(s)...")
+            
+            for i in range(variations):
+                image, seed = generate_with_style(
+                    pipe, prompt, args.negative,
+                    args.steps, args.guidance,
+                    args.width, args.height,
+                    args.seed, lora_scale
+                )
+                
+                # Save image
+                filepath = save_generated_image(
+                    image, prompt, style_name, seed, i + 1, args.output_dir,
+                    {
+                        'prompt': prompt,
+                        'negative_prompt': args.negative,
+                        'style_name': style_name,
+                        'lora_scale': lora_scale,
+                        'seed': seed,
+                        'steps': args.steps,
+                        'guidance_scale': args.guidance,
+                        'timestamp': datetime.now().isoformat()
+                    }
+                )
+                
+                print(f"✅ Saved: {filepath}")
+            
+            print()
+            
+        except KeyboardInterrupt:
+            break
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            print()
+
+def main():
+    """Main function."""
+    args = setup_args()
+    
+    # List styles if requested
+    if args.list_styles:
+        list_available_styles()
+        return 0
+    
+    # Check LoRA path
+    if not os.path.exists(args.lora_path):
+        print(f"❌ LoRA path not found: {args.lora_path}")
+        return 1
+    
+    # Load LoRA info
+    lora_info = load_lora_info(args.lora_path)
+    style_name = lora_info.get('style_name', 'custom')
+    
+    print(f"🎨 CompI Phase 1.E: Personal Style Generation")
+    print(f"Style: {style_name}")
+    print("=" * 50)
+    
+    # Setup device
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    print(f"🖥️  Using device: {device}")
+    
+    # Load pipeline
+    try:
+        pipe = load_pipeline_with_lora(args.model_name, args.lora_path, device)
+        print("✅ Pipeline loaded successfully")
+    except Exception as e:
+        print(f"❌ Failed to load pipeline: {e}")
+        return 1
+    
+    # Interactive mode
+    if args.interactive:
+        interactive_generation(pipe, lora_info, args)
+        return 0
+    
+    # Command line mode
+    prompt = " ".join(args.prompt) if args.prompt else input("Enter prompt: ").strip()
+    if not prompt:
+        print("❌ No prompt provided")
+        return 1
+    
+    print(f"🎨 Generating {args.variations} variation(s) for: {prompt}")
+    
+    # Generate images
+    for i in range(args.variations):
+        try:
+            image, seed = generate_with_style(
+                pipe, prompt, args.negative,
+                args.steps, args.guidance,
+                args.width, args.height,
+                args.seed, args.lora_scale
+            )
+            
+            # Save image
+            filepath = save_generated_image(
+                image, prompt, style_name, seed, i + 1, args.output_dir,
+                {
+                    'prompt': prompt,
+                    'negative_prompt': args.negative,
+                    'style_name': style_name,
+                    'lora_scale': args.lora_scale,
+                    'seed': seed,
+                    'steps': args.steps,
+                    'guidance_scale': args.guidance,
+                    'timestamp': datetime.now().isoformat()
+                }
+            )
+            
+            print(f"✅ Generated variation {i + 1}: {filepath}")
+            
+        except Exception as e:
+            print(f"❌ Error generating variation {i + 1}: {e}")
+    
+    print("🎉 Generation complete!")
+    return 0
+
+if __name__ == "__main__":
+    exit(main())

src/generators/compi_phase1e_style_manager.py

@@ -0,0 +1,386 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 1.E: LoRA Style Management System
+
+Manage multiple LoRA styles, switch between them, and organize trained models.
+
+Usage:
+    python src/generators/compi_phase1e_style_manager.py --list
+    python src/generators/compi_phase1e_style_manager.py --info my_style
+    python src/generators/compi_phase1e_style_manager.py --cleanup
+"""
+
+import os
+import argparse
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import pandas as pd
+
+# -------- 1. CONFIGURATION --------
+
+LORA_MODELS_DIR = "lora_models"
+STYLES_CONFIG_FILE = "lora_styles_config.json"
+
+# -------- 2. STYLE MANAGEMENT CLASS --------
+
+class LoRAStyleManager:
+    """Manager for LoRA styles and models."""
+    
+    def __init__(self, models_dir: str = LORA_MODELS_DIR):
+        self.models_dir = Path(models_dir)
+        self.models_dir.mkdir(exist_ok=True)
+        self.config_file = self.models_dir / STYLES_CONFIG_FILE
+        self.config = self.load_config()
+    
+    def load_config(self) -> Dict:
+        """Load styles configuration."""
+        if self.config_file.exists():
+            with open(self.config_file) as f:
+                return json.load(f)
+        return {"styles": {}, "last_updated": datetime.now().isoformat()}
+    
+    def save_config(self):
+        """Save styles configuration."""
+        self.config["last_updated"] = datetime.now().isoformat()
+        with open(self.config_file, 'w') as f:
+            json.dump(self.config, f, indent=2)
+    
+    def scan_styles(self) -> Dict[str, Dict]:
+        """Scan for available LoRA styles."""
+        styles = {}
+        
+        for style_dir in self.models_dir.iterdir():
+            if not style_dir.is_dir() or style_dir.name.startswith('.'):
+                continue
+            
+            # Look for checkpoints
+            checkpoints = list(style_dir.glob("checkpoint-*"))
+            if not checkpoints:
+                continue
+            
+            # Get latest checkpoint
+            latest_checkpoint = max(checkpoints, key=lambda x: int(x.name.split('-')[1]))
+            
+            # Load training info
+            info_file = style_dir / "training_info.json"
+            if info_file.exists():
+                with open(info_file) as f:
+                    training_info = json.load(f)
+            else:
+                training_info = {}
+            
+            # Load dataset info if available
+            dataset_info = {}
+            for dataset_dir in [style_dir / "dataset", Path("datasets") / style_dir.name]:
+                dataset_info_file = dataset_dir / "dataset_info.json"
+                if dataset_info_file.exists():
+                    with open(dataset_info_file) as f:
+                        dataset_info = json.load(f)
+                    break
+            
+            # Compile style information
+            style_info = {
+                "name": style_dir.name,
+                "path": str(style_dir),
+                "latest_checkpoint": str(latest_checkpoint),
+                "checkpoints": [str(cp) for cp in checkpoints],
+                "training_info": training_info,
+                "dataset_info": dataset_info,
+                "last_scanned": datetime.now().isoformat()
+            }
+            
+            styles[style_dir.name] = style_info
+        
+        return styles
+    
+    def refresh_styles(self):
+        """Refresh the styles database."""
+        print("🔄 Scanning for LoRA styles...")
+        scanned_styles = self.scan_styles()
+        
+        # Update config
+        self.config["styles"] = scanned_styles
+        self.save_config()
+        
+        print(f"✅ Found {len(scanned_styles)} LoRA style(s)")
+        return scanned_styles
+    
+    def list_styles(self, detailed: bool = False) -> List[Dict]:
+        """List available styles."""
+        styles = self.config.get("styles", {})
+        
+        if not styles:
+            styles = self.refresh_styles()
+        
+        if detailed:
+            return list(styles.values())
+        else:
+            return [{"name": name, "checkpoints": len(info["checkpoints"])} 
+                   for name, info in styles.items()]
+    
+    def get_style_info(self, style_name: str) -> Optional[Dict]:
+        """Get detailed information about a specific style."""
+        styles = self.config.get("styles", {})
+        return styles.get(style_name)
+    
+    def get_best_checkpoint(self, style_name: str) -> Optional[str]:
+        """Get the best checkpoint for a style."""
+        style_info = self.get_style_info(style_name)
+        if not style_info:
+            return None
+        
+        # For now, return the latest checkpoint
+        # Could be enhanced to track validation loss and return best performing
+        return style_info.get("latest_checkpoint")
+    
+    def delete_style(self, style_name: str, confirm: bool = False) -> bool:
+        """Delete a LoRA style."""
+        if not confirm:
+            print("⚠️  Use --confirm to actually delete the style")
+            return False
+        
+        style_dir = self.models_dir / style_name
+        if not style_dir.exists():
+            print(f"❌ Style not found: {style_name}")
+            return False
+        
+        try:
+            shutil.rmtree(style_dir)
+            
+            # Remove from config
+            if style_name in self.config.get("styles", {}):
+                del self.config["styles"][style_name]
+                self.save_config()
+            
+            print(f"✅ Deleted style: {style_name}")
+            return True
+            
+        except Exception as e:
+            print(f"❌ Error deleting style: {e}")
+            return False
+    
+    def cleanup_checkpoints(self, style_name: str, keep_last: int = 3) -> int:
+        """Clean up old checkpoints, keeping only the most recent ones."""
+        style_dir = self.models_dir / style_name
+        if not style_dir.exists():
+            print(f"❌ Style not found: {style_name}")
+            return 0
+        
+        checkpoints = list(style_dir.glob("checkpoint-*"))
+        if len(checkpoints) <= keep_last:
+            print(f"✅ No cleanup needed for {style_name} ({len(checkpoints)} checkpoints)")
+            return 0
+        
+        # Sort by step number
+        checkpoints.sort(key=lambda x: int(x.name.split('-')[1]))
+        
+        # Remove old checkpoints
+        to_remove = checkpoints[:-keep_last]
+        removed_count = 0
+        
+        for checkpoint in to_remove:
+            try:
+                shutil.rmtree(checkpoint)
+                removed_count += 1
+            except Exception as e:
+                print(f"⚠️  Failed to remove {checkpoint}: {e}")
+        
+        print(f"✅ Cleaned up {removed_count} old checkpoints for {style_name}")
+        return removed_count
+    
+    def export_style_info(self, output_file: str = None) -> str:
+        """Export styles information to CSV."""
+        styles = self.list_styles(detailed=True)
+        
+        if not styles:
+            print("❌ No styles found")
+            return ""
+        
+        # Prepare data for CSV
+        rows = []
+        for style in styles:
+            training_info = style.get("training_info", {})
+            dataset_info = style.get("dataset_info", {})
+            
+            row = {
+                "style_name": style["name"],
+                "checkpoints": len(style["checkpoints"]),
+                "latest_checkpoint": Path(style["latest_checkpoint"]).name,
+                "total_steps": training_info.get("total_steps", "unknown"),
+                "epochs": training_info.get("epochs", "unknown"),
+                "learning_rate": training_info.get("learning_rate", "unknown"),
+                "lora_rank": training_info.get("lora_rank", "unknown"),
+                "dataset_images": dataset_info.get("total_images", "unknown"),
+                "trigger_word": dataset_info.get("trigger_word", "unknown"),
+                "last_scanned": style.get("last_scanned", "unknown")
+            }
+            rows.append(row)
+        
+        # Create DataFrame and save
+        df = pd.DataFrame(rows)
+        
+        if output_file is None:
+            output_file = f"lora_styles_export_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+        
+        df.to_csv(output_file, index=False)
+        print(f"📊 Exported styles info to: {output_file}")
+        return output_file
+
+# -------- 3. COMMAND LINE INTERFACE --------
+
+def setup_args():
+    """Setup command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="CompI Phase 1.E: LoRA Style Management",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # List all available styles
+  python %(prog)s --list
+  
+  # Get detailed info about a specific style
+  python %(prog)s --info my_style
+  
+  # Refresh styles database
+  python %(prog)s --refresh
+  
+  # Clean up old checkpoints
+  python %(prog)s --cleanup my_style --keep 2
+  
+  # Export styles information
+  python %(prog)s --export styles_report.csv
+        """
+    )
+    
+    parser.add_argument("--list", action="store_true",
+                       help="List all available LoRA styles")
+    
+    parser.add_argument("--list-detailed", action="store_true",
+                       help="List styles with detailed information")
+    
+    parser.add_argument("--info", metavar="STYLE_NAME",
+                       help="Show detailed information about a specific style")
+    
+    parser.add_argument("--refresh", action="store_true",
+                       help="Refresh the styles database")
+    
+    parser.add_argument("--cleanup", metavar="STYLE_NAME",
+                       help="Clean up old checkpoints for a style")
+    
+    parser.add_argument("--keep", type=int, default=3,
+                       help="Number of recent checkpoints to keep during cleanup")
+    
+    parser.add_argument("--delete", metavar="STYLE_NAME",
+                       help="Delete a LoRA style")
+    
+    parser.add_argument("--confirm", action="store_true",
+                       help="Confirm destructive operations")
+    
+    parser.add_argument("--export", metavar="OUTPUT_FILE",
+                       help="Export styles information to CSV")
+    
+    parser.add_argument("--models-dir", default=LORA_MODELS_DIR,
+                       help=f"LoRA models directory (default: {LORA_MODELS_DIR})")
+    
+    return parser.parse_args()
+
+def print_style_info(style_info: Dict):
+    """Print detailed style information."""
+    print(f"🎨 Style: {style_info['name']}")
+    print("=" * 40)
+    
+    # Basic info
+    print(f"📁 Path: {style_info['path']}")
+    print(f"📊 Checkpoints: {len(style_info['checkpoints'])}")
+    print(f"🏆 Latest: {Path(style_info['latest_checkpoint']).name}")
+    
+    # Training info
+    training_info = style_info.get("training_info", {})
+    if training_info:
+        print(f"\n🚀 Training Information:")
+        print(f"   Steps: {training_info.get('total_steps', 'unknown')}")
+        print(f"   Epochs: {training_info.get('epochs', 'unknown')}")
+        print(f"   Learning Rate: {training_info.get('learning_rate', 'unknown')}")
+        print(f"   LoRA Rank: {training_info.get('lora_rank', 'unknown')}")
+        print(f"   LoRA Alpha: {training_info.get('lora_alpha', 'unknown')}")
+    
+    # Dataset info
+    dataset_info = style_info.get("dataset_info", {})
+    if dataset_info:
+        print(f"\n📊 Dataset Information:")
+        print(f"   Total Images: {dataset_info.get('total_images', 'unknown')}")
+        print(f"   Train Images: {dataset_info.get('train_images', 'unknown')}")
+        print(f"   Validation Images: {dataset_info.get('validation_images', 'unknown')}")
+        print(f"   Trigger Word: {dataset_info.get('trigger_word', 'unknown')}")
+        print(f"   Image Size: {dataset_info.get('image_size', 'unknown')}")
+    
+    print(f"\n🕒 Last Scanned: {style_info.get('last_scanned', 'unknown')}")
+
+def main():
+    """Main function."""
+    args = setup_args()
+    
+    # Initialize style manager
+    manager = LoRAStyleManager(args.models_dir)
+    
+    print("🎨 CompI Phase 1.E: LoRA Style Manager")
+    print("=" * 40)
+    
+    # Execute commands
+    if args.refresh:
+        manager.refresh_styles()
+    
+    elif args.list or args.list_detailed:
+        styles = manager.list_styles(detailed=args.list_detailed)
+        
+        if not styles:
+            print("❌ No LoRA styles found")
+            print("💡 Train a style first using: python src/generators/compi_phase1e_lora_training.py")
+        else:
+            print(f"📋 Available LoRA Styles ({len(styles)}):")
+            print("-" * 40)
+            
+            if args.list_detailed:
+                for style in styles:
+                    print_style_info(style)
+                    print()
+            else:
+                for style in styles:
+                    print(f"🎨 {style['name']} ({style['checkpoints']} checkpoints)")
+    
+    elif args.info:
+        style_info = manager.get_style_info(args.info)
+        if style_info:
+            print_style_info(style_info)
+        else:
+            print(f"❌ Style not found: {args.info}")
+            print("💡 Use --list to see available styles")
+    
+    elif args.cleanup:
+        removed = manager.cleanup_checkpoints(args.cleanup, args.keep)
+        if removed > 0:
+            manager.refresh_styles()
+    
+    elif args.delete:
+        manager.delete_style(args.delete, args.confirm)
+        if args.confirm:
+            manager.refresh_styles()
+    
+    elif args.export:
+        manager.export_style_info(args.export)
+    
+    else:
+        print("❓ No command specified. Use --help for usage information.")
+        print("💡 Common commands:")
+        print("   --list              List available styles")
+        print("   --info STYLE_NAME   Show style details")
+        print("   --refresh           Refresh styles database")
+    
+    return 0
+
+if __name__ == "__main__":
+    exit(main())

src/generators/compi_phase2a_audio_to_image.py

@@ -0,0 +1,350 @@
+"""
+CompI Phase 2.A: Audio-to-Image Generation
+
+This module implements multimodal AI art generation that combines:
+- Text prompts with style and mood conditioning
+- Audio analysis and feature extraction
+- Audio-to-text captioning
+- Intelligent prompt fusion for enhanced creativity
+
+Features:
+- Support for various audio formats (mp3, wav, flac, etc.)
+- Real-time audio analysis with tempo, energy, and spectral features
+- OpenAI Whisper integration for audio captioning
+- Comprehensive metadata logging and filename conventions
+- Batch processing capabilities
+"""
+
+import os
+import sys
+import torch
+import json
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Union
+from pathlib import Path
+import logging
+
+# Add project root to path
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+import numpy as np
+
+from src.utils.audio_utils import AudioProcessor, AudioCaptioner, MultimodalPromptFusion, AudioFeatures
+from src.utils.logging_utils import setup_logger
+from src.utils.file_utils import ensure_directory_exists, generate_filename
+
+# Setup logging
+logger = setup_logger(__name__)
+
+class CompIPhase2AAudioToImage:
+    """
+    CompI Phase 2.A: Audio-to-Image Generation System
+    
+    Combines text prompts with audio analysis to generate contextually rich AI art
+    """
+    
+    def __init__(
+        self,
+        model_name: str = "runwayml/stable-diffusion-v1-5",
+        device: str = "auto",
+        output_dir: str = "outputs",
+        whisper_model: str = "base"
+    ):
+        """
+        Initialize the audio-to-image generation system
+        
+        Args:
+            model_name: Stable Diffusion model to use
+            device: Device for inference (auto, cpu, cuda)
+            output_dir: Directory for saving generated images
+            whisper_model: Whisper model size for audio captioning
+        """
+        self.model_name = model_name
+        self.device = self._setup_device(device)
+        self.output_dir = Path(output_dir)
+        ensure_directory_exists(self.output_dir)
+        
+        # Initialize components
+        self.pipe = None
+        self.audio_processor = AudioProcessor()
+        self.audio_captioner = AudioCaptioner(model_size=whisper_model, device=self.device)
+        self.prompt_fusion = MultimodalPromptFusion()
+        
+        logger.info(f"Initialized CompI Phase 2.A on {self.device}")
+    
+    def _setup_device(self, device: str) -> str:
+        """Setup and validate device"""
+        if device == "auto":
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+        
+        if device == "cuda" and not torch.cuda.is_available():
+            logger.warning("CUDA requested but not available, falling back to CPU")
+            device = "cpu"
+        
+        return device
+    
+    def _load_pipeline(self):
+        """Lazy load the Stable Diffusion pipeline"""
+        if self.pipe is None:
+            logger.info(f"Loading Stable Diffusion model: {self.model_name}")
+            
+            # Custom safety checker that allows creative content
+            def dummy_safety_checker(images, **kwargs):
+                return images, [False] * len(images)
+            
+            self.pipe = StableDiffusionPipeline.from_pretrained(
+                self.model_name,
+                torch_dtype=torch.float16 if self.device == "cuda" else torch.float32,
+                safety_checker=dummy_safety_checker,
+                requires_safety_checker=False
+            )
+            
+            self.pipe = self.pipe.to(self.device)
+            self.pipe.enable_attention_slicing()
+            
+            if self.device == "cuda":
+                self.pipe.enable_model_cpu_offload()
+            
+            logger.info("Stable Diffusion pipeline loaded successfully")
+    
+    def analyze_audio(self, audio_path: str, include_caption: bool = True) -> Tuple[AudioFeatures, str]:
+        """
+        Comprehensive audio analysis
+        
+        Args:
+            audio_path: Path to audio file
+            include_caption: Whether to generate audio caption
+            
+        Returns:
+            Tuple of (AudioFeatures, audio_caption)
+        """
+        logger.info(f"Analyzing audio: {audio_path}")
+        
+        # Extract audio features
+        audio_features = self.audio_processor.analyze_audio_file(audio_path)
+        
+        # Generate audio caption if requested
+        audio_caption = ""
+        if include_caption:
+            try:
+                audio_caption = self.audio_captioner.caption_audio(audio_path)
+            except Exception as e:
+                logger.warning(f"Audio captioning failed: {e}")
+                audio_caption = ""
+        
+        return audio_features, audio_caption
+    
+    def generate_image(
+        self,
+        text_prompt: str,
+        style: str = "",
+        mood: str = "",
+        audio_path: Optional[str] = None,
+        num_images: int = 1,
+        height: int = 512,
+        width: int = 512,
+        num_inference_steps: int = 30,
+        guidance_scale: float = 7.5,
+        seed: Optional[int] = None
+    ) -> List[Dict]:
+        """
+        Generate images with optional audio conditioning
+        
+        Args:
+            text_prompt: Base text prompt
+            style: Art style
+            mood: Mood/atmosphere
+            audio_path: Optional path to audio file for conditioning
+            num_images: Number of images to generate
+            height: Image height
+            width: Image width
+            num_inference_steps: Number of diffusion steps
+            guidance_scale: Guidance scale for generation
+            seed: Random seed for reproducibility
+            
+        Returns:
+            List of generation results with metadata
+        """
+        self._load_pipeline()
+        
+        # Analyze audio if provided
+        audio_features = None
+        audio_caption = ""
+        if audio_path and os.path.exists(audio_path):
+            audio_features, audio_caption = self.analyze_audio(audio_path)
+        
+        # Create enhanced prompt
+        if audio_features:
+            enhanced_prompt = self.prompt_fusion.fuse_prompt_with_audio(
+                text_prompt, style, mood, audio_features, audio_caption
+            )
+        else:
+            enhanced_prompt = text_prompt
+            if style:
+                enhanced_prompt += f", {style}"
+            if mood:
+                enhanced_prompt += f", {mood}"
+        
+        logger.info(f"Generating {num_images} image(s) with prompt: {enhanced_prompt}")
+        
+        results = []
+        
+        for i in range(num_images):
+            # Set up generation parameters
+            current_seed = seed if seed is not None else torch.seed()
+            generator = torch.Generator(device=self.device).manual_seed(current_seed)
+            
+            # Generate image
+            with torch.autocast(self.device) if self.device == "cuda" else torch.no_grad():
+                result = self.pipe(
+                    enhanced_prompt,
+                    height=height,
+                    width=width,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    generator=generator
+                )
+                
+                image = result.images[0]
+            
+            # Create metadata
+            metadata = {
+                "timestamp": datetime.now().isoformat(),
+                "text_prompt": text_prompt,
+                "style": style,
+                "mood": mood,
+                "enhanced_prompt": enhanced_prompt,
+                "audio_path": audio_path,
+                "audio_caption": audio_caption,
+                "generation_params": {
+                    "height": height,
+                    "width": width,
+                    "num_inference_steps": num_inference_steps,
+                    "guidance_scale": guidance_scale,
+                    "seed": current_seed,
+                    "model": self.model_name
+                },
+                "device": self.device,
+                "phase": "2A_audio_to_image"
+            }
+            
+            # Add audio features to metadata
+            if audio_features:
+                metadata["audio_features"] = audio_features.to_dict()
+                metadata["audio_tags"] = self.prompt_fusion.generate_audio_tags(audio_features)
+            
+            # Generate filename
+            filename = self._generate_filename(
+                text_prompt, style, mood, current_seed, i + 1, 
+                has_audio=audio_path is not None
+            )
+            
+            # Save image and metadata
+            image_path = self.output_dir / f"{filename}.png"
+            metadata_path = self.output_dir / f"{filename}_metadata.json"
+            
+            image.save(image_path)
+            with open(metadata_path, 'w') as f:
+                json.dump(metadata, f, indent=2)
+            
+            results.append({
+                "image": image,
+                "image_path": str(image_path),
+                "metadata_path": str(metadata_path),
+                "metadata": metadata,
+                "filename": filename
+            })
+            
+            logger.info(f"Generated image {i+1}/{num_images}: {filename}")
+        
+        return results
+    
+    def _generate_filename(
+        self, 
+        prompt: str, 
+        style: str, 
+        mood: str, 
+        seed: int, 
+        variation: int,
+        has_audio: bool = False
+    ) -> str:
+        """Generate descriptive filename following CompI conventions"""
+        
+        # Create prompt slug (first 5 words)
+        prompt_words = prompt.lower().replace(',', '').split()[:5]
+        prompt_slug = "_".join(prompt_words)
+        
+        # Create style and mood slugs
+        style_slug = style.replace(" ", "").replace(",", "")[:10] if style else "standard"
+        mood_slug = mood.replace(" ", "").replace(",", "")[:10] if mood else "neutral"
+        
+        # Timestamp
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        # Audio indicator
+        audio_tag = "_AUDIO" if has_audio else ""
+        
+        # Combine all elements
+        filename = f"{prompt_slug}_{style_slug}_{mood_slug}_{timestamp}_seed{seed}{audio_tag}_v{variation}"
+        
+        return filename
+    
+    def batch_process(
+        self,
+        audio_directory: str,
+        text_prompt: str,
+        style: str = "",
+        mood: str = "",
+        **generation_kwargs
+    ) -> List[Dict]:
+        """
+        Process multiple audio files in batch
+        
+        Args:
+            audio_directory: Directory containing audio files
+            text_prompt: Base text prompt for all generations
+            style: Art style
+            mood: Mood/atmosphere
+            **generation_kwargs: Additional generation parameters
+            
+        Returns:
+            List of all generation results
+        """
+        audio_dir = Path(audio_directory)
+        if not audio_dir.exists():
+            raise ValueError(f"Audio directory not found: {audio_directory}")
+        
+        # Find audio files
+        audio_extensions = {'.mp3', '.wav', '.flac', '.m4a', '.ogg'}
+        audio_files = [
+            f for f in audio_dir.iterdir() 
+            if f.suffix.lower() in audio_extensions
+        ]
+        
+        if not audio_files:
+            raise ValueError(f"No audio files found in {audio_directory}")
+        
+        logger.info(f"Processing {len(audio_files)} audio files")
+        
+        all_results = []
+        for audio_file in audio_files:
+            logger.info(f"Processing: {audio_file.name}")
+            
+            try:
+                results = self.generate_image(
+                    text_prompt=text_prompt,
+                    style=style,
+                    mood=mood,
+                    audio_path=str(audio_file),
+                    **generation_kwargs
+                )
+                all_results.extend(results)
+                
+            except Exception as e:
+                logger.error(f"Error processing {audio_file.name}: {e}")
+                continue
+        
+        logger.info(f"Batch processing complete: {len(all_results)} images generated")
+        return all_results

src/generators/compi_phase2b_data_to_image.py

@@ -0,0 +1,432 @@
+"""
+CompI Phase 2.B: Data/Logic Input to Image Generation
+
+This module implements data-driven AI art generation that combines:
+- CSV data analysis and processing
+- Mathematical formula evaluation
+- Data-to-text conversion for prompt enhancement
+- Data visualization for artistic conditioning
+- Intelligent fusion of data insights with creative prompts
+
+Features:
+- Support for CSV files with comprehensive data analysis
+- Safe mathematical formula evaluation with NumPy
+- Poetic text generation from data patterns
+- Data visualization creation for artistic inspiration
+- Comprehensive metadata logging and filename conventions
+- Batch processing capabilities for multiple datasets
+"""
+
+import os
+import sys
+import torch
+import json
+import pandas as pd
+import numpy as np
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Union
+from pathlib import Path
+import logging
+
+# Add project root to path
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+
+from src.utils.data_utils import DataProcessor, DataToTextConverter, DataVisualizer, DataFeatures
+from src.utils.logging_utils import setup_logger
+from src.utils.file_utils import ensure_directory_exists, generate_filename
+
+# Setup logging
+logger = setup_logger(__name__)
+
+class CompIPhase2BDataToImage:
+    """
+    CompI Phase 2.B: Data/Logic Input to Image Generation System
+    
+    Transforms structured data and mathematical formulas into AI-generated art
+    """
+    
+    def __init__(
+        self,
+        model_name: str = "runwayml/stable-diffusion-v1-5",
+        device: str = "auto",
+        output_dir: str = "outputs",
+        visualization_style: str = "artistic"
+    ):
+        """
+        Initialize the data-to-image generation system
+        
+        Args:
+            model_name: Stable Diffusion model to use
+            device: Device for inference (auto, cpu, cuda)
+            output_dir: Directory for saving generated images
+            visualization_style: Style for data visualizations
+        """
+        self.model_name = model_name
+        self.device = self._setup_device(device)
+        self.output_dir = Path(output_dir)
+        ensure_directory_exists(self.output_dir)
+        
+        # Initialize components
+        self.pipe = None
+        self.data_processor = DataProcessor()
+        self.text_converter = DataToTextConverter()
+        self.visualizer = DataVisualizer(style=visualization_style)
+        
+        logger.info(f"Initialized CompI Phase 2.B on {self.device}")
+    
+    def _setup_device(self, device: str) -> str:
+        """Setup and validate device"""
+        if device == "auto":
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+        
+        if device == "cuda" and not torch.cuda.is_available():
+            logger.warning("CUDA requested but not available, falling back to CPU")
+            device = "cpu"
+        
+        return device
+    
+    def _load_pipeline(self):
+        """Lazy load the Stable Diffusion pipeline"""
+        if self.pipe is None:
+            logger.info(f"Loading Stable Diffusion model: {self.model_name}")
+            
+            # Custom safety checker that allows creative content
+            def dummy_safety_checker(images, **kwargs):
+                return images, [False] * len(images)
+            
+            self.pipe = StableDiffusionPipeline.from_pretrained(
+                self.model_name,
+                torch_dtype=torch.float16 if self.device == "cuda" else torch.float32,
+                safety_checker=dummy_safety_checker,
+                requires_safety_checker=False
+            )
+            
+            self.pipe = self.pipe.to(self.device)
+            self.pipe.enable_attention_slicing()
+            
+            if self.device == "cuda":
+                self.pipe.enable_model_cpu_offload()
+            
+            logger.info("Stable Diffusion pipeline loaded successfully")
+    
+    def analyze_csv_data(self, csv_path: str) -> Tuple[pd.DataFrame, DataFeatures, str, Image.Image]:
+        """
+        Comprehensive CSV data analysis
+        
+        Args:
+            csv_path: Path to CSV file
+            
+        Returns:
+            Tuple of (DataFrame, DataFeatures, poetic_description, visualization_image)
+        """
+        logger.info(f"Analyzing CSV data: {csv_path}")
+        
+        # Load and analyze data
+        df = pd.read_csv(csv_path)
+        features = self.data_processor.analyze_csv_data(df)
+        
+        # Generate poetic description
+        poetic_description = self.text_converter.generate_poetic_description(features)
+        
+        # Create visualization
+        visualization_image = self.visualizer.create_data_visualization(df, features)
+        
+        return df, features, poetic_description, visualization_image
+    
+    def evaluate_mathematical_formula(self, formula: str, num_points: int = 100) -> Tuple[np.ndarray, Dict, str, Image.Image]:
+        """
+        Evaluate mathematical formula and create artistic interpretation
+        
+        Args:
+            formula: Mathematical expression
+            num_points: Number of points to generate
+            
+        Returns:
+            Tuple of (result_array, metadata, poetic_description, visualization_image)
+        """
+        logger.info(f"Evaluating mathematical formula: {formula}")
+        
+        # Evaluate formula
+        result_array, metadata = self.data_processor.evaluate_formula(formula, num_points)
+        
+        # Generate poetic description
+        poetic_description = self.text_converter.generate_formula_description(formula, metadata)
+        
+        # Create visualization
+        visualization_image = self.visualizer.create_formula_visualization(result_array, formula, metadata)
+        
+        return result_array, metadata, poetic_description, visualization_image
+
+    def generate_image(
+        self,
+        text_prompt: str,
+        style: str = "",
+        mood: str = "",
+        csv_path: Optional[str] = None,
+        formula: Optional[str] = None,
+        num_images: int = 1,
+        height: int = 512,
+        width: int = 512,
+        num_inference_steps: int = 30,
+        guidance_scale: float = 7.5,
+        seed: Optional[int] = None,
+        save_data_visualization: bool = True
+    ) -> List[Dict]:
+        """
+        Generate images with data/formula conditioning
+
+        Args:
+            text_prompt: Base text prompt
+            style: Art style
+            mood: Mood/atmosphere
+            csv_path: Optional path to CSV file
+            formula: Optional mathematical formula
+            num_images: Number of images to generate
+            height: Image height
+            width: Image width
+            num_inference_steps: Number of diffusion steps
+            guidance_scale: Guidance scale for generation
+            seed: Random seed for reproducibility
+            save_data_visualization: Whether to save data visualization
+
+        Returns:
+            List of generation results with metadata
+        """
+        self._load_pipeline()
+
+        # Process data input
+        data_features = None
+        poetic_description = ""
+        data_visualization = None
+        data_type = "none"
+
+        if csv_path and os.path.exists(csv_path):
+            df, data_features, poetic_description, data_visualization = self.analyze_csv_data(csv_path)
+            data_type = "csv"
+        elif formula and formula.strip():
+            result_array, formula_metadata, poetic_description, data_visualization = self.evaluate_mathematical_formula(formula)
+            data_type = "formula"
+
+        # Create enhanced prompt
+        enhanced_prompt = text_prompt
+        if style:
+            enhanced_prompt += f", {style}"
+        if mood:
+            enhanced_prompt += f", {mood}"
+        if poetic_description:
+            enhanced_prompt += f", {poetic_description}"
+
+        logger.info(f"Generating {num_images} image(s) with enhanced prompt")
+
+        results = []
+
+        for i in range(num_images):
+            # Set up generation parameters
+            current_seed = seed if seed is not None else torch.seed()
+            generator = torch.Generator(device=self.device).manual_seed(current_seed)
+
+            # Generate image
+            with torch.autocast(self.device) if self.device == "cuda" else torch.no_grad():
+                result = self.pipe(
+                    enhanced_prompt,
+                    height=height,
+                    width=width,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    generator=generator
+                )
+
+                image = result.images[0]
+
+            # Create metadata
+            metadata = {
+                "timestamp": datetime.now().isoformat(),
+                "text_prompt": text_prompt,
+                "style": style,
+                "mood": mood,
+                "enhanced_prompt": enhanced_prompt,
+                "poetic_description": poetic_description,
+                "data_type": data_type,
+                "csv_path": csv_path,
+                "formula": formula,
+                "generation_params": {
+                    "height": height,
+                    "width": width,
+                    "num_inference_steps": num_inference_steps,
+                    "guidance_scale": guidance_scale,
+                    "seed": current_seed,
+                    "model": self.model_name
+                },
+                "device": self.device,
+                "phase": "2B_data_to_image"
+            }
+
+            # Add data features to metadata
+            if data_features:
+                metadata["data_features"] = data_features.to_dict()
+
+            # Generate filename
+            filename = self._generate_filename(
+                text_prompt, style, mood, current_seed, i + 1,
+                data_type=data_type
+            )
+
+            # Save image and metadata
+            image_path = self.output_dir / f"{filename}.png"
+            metadata_path = self.output_dir / f"{filename}_metadata.json"
+
+            image.save(image_path)
+            with open(metadata_path, 'w') as f:
+                json.dump(metadata, f, indent=2)
+
+            # Save data visualization if requested
+            data_viz_path = None
+            if save_data_visualization and data_visualization:
+                data_viz_path = self.output_dir / f"{filename}_data_viz.png"
+                data_visualization.save(data_viz_path)
+
+            results.append({
+                "image": image,
+                "image_path": str(image_path),
+                "metadata_path": str(metadata_path),
+                "data_visualization_path": str(data_viz_path) if data_viz_path else None,
+                "data_visualization": data_visualization,
+                "metadata": metadata,
+                "filename": filename,
+                "poetic_description": poetic_description
+            })
+
+            logger.info(f"Generated image {i+1}/{num_images}: {filename}")
+
+        return results
+
+    def _generate_filename(
+        self,
+        prompt: str,
+        style: str,
+        mood: str,
+        seed: int,
+        variation: int,
+        data_type: str = "none"
+    ) -> str:
+        """Generate descriptive filename following CompI conventions"""
+
+        # Create prompt slug (first 5 words)
+        prompt_words = prompt.lower().replace(',', '').split()[:5]
+        prompt_slug = "_".join(prompt_words)
+
+        # Create style and mood slugs
+        style_slug = style.replace(" ", "").replace(",", "")[:10] if style else "standard"
+        mood_slug = mood.replace(" ", "").replace(",", "")[:10] if mood else "neutral"
+
+        # Timestamp
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # Data type indicator
+        data_tag = f"_{data_type.upper()}" if data_type != "none" else ""
+
+        # Combine all elements
+        filename = f"{prompt_slug}_{style_slug}_{mood_slug}_{timestamp}_seed{seed}{data_tag}_v{variation}"
+
+        return filename
+
+    def batch_process_csv_files(
+        self,
+        csv_directory: str,
+        text_prompt: str,
+        style: str = "",
+        mood: str = "",
+        **generation_kwargs
+    ) -> List[Dict]:
+        """
+        Process multiple CSV files in batch
+
+        Args:
+            csv_directory: Directory containing CSV files
+            text_prompt: Base text prompt for all generations
+            style: Art style
+            mood: Mood/atmosphere
+            **generation_kwargs: Additional generation parameters
+
+        Returns:
+            List of all generation results
+        """
+        csv_dir = Path(csv_directory)
+        if not csv_dir.exists():
+            raise ValueError(f"CSV directory not found: {csv_directory}")
+
+        # Find CSV files
+        csv_files = list(csv_dir.glob("*.csv"))
+
+        if not csv_files:
+            raise ValueError(f"No CSV files found in {csv_directory}")
+
+        logger.info(f"Processing {len(csv_files)} CSV files")
+
+        all_results = []
+        for csv_file in csv_files:
+            logger.info(f"Processing: {csv_file.name}")
+
+            try:
+                results = self.generate_image(
+                    text_prompt=text_prompt,
+                    style=style,
+                    mood=mood,
+                    csv_path=str(csv_file),
+                    **generation_kwargs
+                )
+                all_results.extend(results)
+
+            except Exception as e:
+                logger.error(f"Error processing {csv_file.name}: {e}")
+                continue
+
+        logger.info(f"Batch processing complete: {len(all_results)} images generated")
+        return all_results
+
+    def batch_process_formulas(
+        self,
+        formulas: List[str],
+        text_prompt: str,
+        style: str = "",
+        mood: str = "",
+        **generation_kwargs
+    ) -> List[Dict]:
+        """
+        Process multiple mathematical formulas in batch
+
+        Args:
+            formulas: List of mathematical formulas
+            text_prompt: Base text prompt for all generations
+            style: Art style
+            mood: Mood/atmosphere
+            **generation_kwargs: Additional generation parameters
+
+        Returns:
+            List of all generation results
+        """
+        logger.info(f"Processing {len(formulas)} mathematical formulas")
+
+        all_results = []
+        for i, formula in enumerate(formulas):
+            logger.info(f"Processing formula {i+1}/{len(formulas)}: {formula}")
+
+            try:
+                results = self.generate_image(
+                    text_prompt=text_prompt,
+                    style=style,
+                    mood=mood,
+                    formula=formula,
+                    **generation_kwargs
+                )
+                all_results.extend(results)
+
+            except Exception as e:
+                logger.error(f"Error processing formula '{formula}': {e}")
+                continue
+
+        logger.info(f"Batch processing complete: {len(all_results)} images generated")
+        return all_results

src/generators/compi_phase2c_emotion_to_image.py

@@ -0,0 +1,408 @@
+"""
+CompI Phase 2.C: Emotional/Contextual Input to Image Generation
+
+This module implements emotion-driven AI art generation that combines:
+- Emotion detection and sentiment analysis
+- Contextual mood processing
+- Emoji and text-based emotion recognition
+- Color palette generation based on emotions
+- Intelligent fusion of emotional context with creative prompts
+
+Features:
+- Support for preset emotions, custom emotions, and emoji input
+- Automatic sentiment analysis with TextBlob
+- Emotion-to-color palette mapping
+- Contextual prompt enhancement
+- Comprehensive metadata logging and filename conventions
+- Batch processing capabilities for multiple emotional contexts
+"""
+
+import os
+import sys
+import torch
+import json
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Union
+from pathlib import Path
+import logging
+
+# Add project root to path
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+
+from src.utils.emotion_utils import EmotionProcessor, EmotionalPromptEnhancer, EmotionAnalysis, EmotionCategory
+from src.utils.logging_utils import setup_logger
+from src.utils.file_utils import ensure_directory_exists, generate_filename
+
+# Setup logging
+logger = setup_logger(__name__)
+
+class CompIPhase2CEmotionToImage:
+    """
+    CompI Phase 2.C: Emotional/Contextual Input to Image Generation System
+    
+    Transforms emotions, moods, and contextual feelings into AI-generated art
+    """
+    
+    def __init__(
+        self,
+        model_name: str = "runwayml/stable-diffusion-v1-5",
+        device: str = "auto",
+        output_dir: str = "outputs"
+    ):
+        """
+        Initialize the emotion-to-image generation system
+        
+        Args:
+            model_name: Stable Diffusion model to use
+            device: Device for inference (auto, cpu, cuda)
+            output_dir: Directory for saving generated images
+        """
+        self.model_name = model_name
+        self.device = self._setup_device(device)
+        self.output_dir = Path(output_dir)
+        ensure_directory_exists(self.output_dir)
+        
+        # Initialize components
+        self.pipe = None
+        self.emotion_processor = EmotionProcessor()
+        self.prompt_enhancer = EmotionalPromptEnhancer()
+        
+        logger.info(f"Initialized CompI Phase 2.C on {self.device}")
+    
+    def _setup_device(self, device: str) -> str:
+        """Setup and validate device"""
+        if device == "auto":
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+        
+        if device == "cuda" and not torch.cuda.is_available():
+            logger.warning("CUDA requested but not available, falling back to CPU")
+            device = "cpu"
+        
+        return device
+    
+    def _load_pipeline(self):
+        """Lazy load the Stable Diffusion pipeline"""
+        if self.pipe is None:
+            logger.info(f"Loading Stable Diffusion model: {self.model_name}")
+            
+            # Custom safety checker that allows creative content
+            def dummy_safety_checker(images, **kwargs):
+                return images, [False] * len(images)
+            
+            self.pipe = StableDiffusionPipeline.from_pretrained(
+                self.model_name,
+                torch_dtype=torch.float16 if self.device == "cuda" else torch.float32,
+                safety_checker=dummy_safety_checker,
+                requires_safety_checker=False
+            )
+            
+            self.pipe = self.pipe.to(self.device)
+            self.pipe.enable_attention_slicing()
+            
+            if self.device == "cuda":
+                self.pipe.enable_model_cpu_offload()
+            
+            logger.info("Stable Diffusion pipeline loaded successfully")
+    
+    def analyze_emotion(
+        self,
+        emotion_input: str,
+        emotion_type: str = "auto",
+        contextual_text: Optional[str] = None
+    ) -> EmotionAnalysis:
+        """
+        Comprehensive emotion analysis
+        
+        Args:
+            emotion_input: Emotion input (preset, custom, emoji, or text)
+            emotion_type: Type of input ('preset', 'custom', 'emoji', 'text', 'auto')
+            contextual_text: Additional contextual text for analysis
+            
+        Returns:
+            EmotionAnalysis object with complete analysis
+        """
+        logger.info(f"Analyzing emotion input: {emotion_input}")
+        
+        # Combine inputs for analysis
+        analysis_text = emotion_input
+        if contextual_text:
+            analysis_text += f" {contextual_text}"
+        
+        # Determine selected emotion for preset types
+        selected_emotion = None
+        if emotion_type == "preset" or (emotion_type == "auto" and emotion_input.lower() in self.emotion_processor.preset_emotions):
+            selected_emotion = emotion_input.lower()
+        
+        # Perform emotion analysis
+        emotion_analysis = self.emotion_processor.analyze_emotion(analysis_text, selected_emotion)
+        
+        return emotion_analysis
+    
+    def generate_image(
+        self,
+        text_prompt: str,
+        style: str = "",
+        emotion_input: str = "",
+        emotion_type: str = "auto",
+        contextual_text: str = "",
+        enhancement_strength: float = 0.7,
+        num_images: int = 1,
+        height: int = 512,
+        width: int = 512,
+        num_inference_steps: int = 30,
+        guidance_scale: float = 7.5,
+        seed: Optional[int] = None
+    ) -> List[Dict]:
+        """
+        Generate images with emotional conditioning
+        
+        Args:
+            text_prompt: Base text prompt
+            style: Art style
+            emotion_input: Emotion input (preset, custom, emoji, or descriptive text)
+            emotion_type: Type of emotion input
+            contextual_text: Additional contextual description
+            enhancement_strength: How strongly to apply emotion (0-1)
+            num_images: Number of images to generate
+            height: Image height
+            width: Image width
+            num_inference_steps: Number of diffusion steps
+            guidance_scale: Guidance scale for generation
+            seed: Random seed for reproducibility
+            
+        Returns:
+            List of generation results with metadata
+        """
+        self._load_pipeline()
+        
+        # Analyze emotion if provided
+        emotion_analysis = None
+        if emotion_input.strip():
+            emotion_analysis = self.analyze_emotion(emotion_input, emotion_type, contextual_text)
+        
+        # Create enhanced prompt
+        if emotion_analysis:
+            enhanced_prompt = self.prompt_enhancer.enhance_prompt_with_emotion(
+                text_prompt, style, emotion_analysis, enhancement_strength
+            )
+        else:
+            enhanced_prompt = text_prompt
+            if style:
+                enhanced_prompt += f", {style}"
+        
+        logger.info(f"Generating {num_images} image(s) with enhanced prompt")
+        
+        results = []
+        
+        for i in range(num_images):
+            # Set up generation parameters
+            current_seed = seed if seed is not None else torch.seed()
+            generator = torch.Generator(device=self.device).manual_seed(current_seed)
+            
+            # Generate image
+            with torch.autocast(self.device) if self.device == "cuda" else torch.no_grad():
+                result = self.pipe(
+                    enhanced_prompt,
+                    height=height,
+                    width=width,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    generator=generator
+                )
+                
+                image = result.images[0]
+            
+            # Create metadata
+            metadata = {
+                "timestamp": datetime.now().isoformat(),
+                "text_prompt": text_prompt,
+                "style": style,
+                "emotion_input": emotion_input,
+                "emotion_type": emotion_type,
+                "contextual_text": contextual_text,
+                "enhancement_strength": enhancement_strength,
+                "enhanced_prompt": enhanced_prompt,
+                "generation_params": {
+                    "height": height,
+                    "width": width,
+                    "num_inference_steps": num_inference_steps,
+                    "guidance_scale": guidance_scale,
+                    "seed": current_seed,
+                    "model": self.model_name
+                },
+                "device": self.device,
+                "phase": "2C_emotion_to_image"
+            }
+            
+            # Add emotion analysis to metadata
+            if emotion_analysis:
+                metadata["emotion_analysis"] = emotion_analysis.to_dict()
+                metadata["emotion_tags"] = self.prompt_enhancer.generate_emotion_tags(emotion_analysis)
+            
+            # Generate filename
+            filename = self._generate_filename(
+                text_prompt, style, emotion_analysis, current_seed, i + 1
+            )
+            
+            # Save image and metadata
+            image_path = self.output_dir / f"{filename}.png"
+            metadata_path = self.output_dir / f"{filename}_metadata.json"
+            
+            image.save(image_path)
+            with open(metadata_path, 'w') as f:
+                json.dump(metadata, f, indent=2)
+            
+            results.append({
+                "image": image,
+                "image_path": str(image_path),
+                "metadata_path": str(metadata_path),
+                "metadata": metadata,
+                "filename": filename,
+                "emotion_analysis": emotion_analysis
+            })
+            
+            logger.info(f"Generated image {i+1}/{num_images}: {filename}")
+        
+        return results
+
+    def _generate_filename(
+        self,
+        prompt: str,
+        style: str,
+        emotion_analysis: Optional[EmotionAnalysis],
+        seed: int,
+        variation: int
+    ) -> str:
+        """Generate descriptive filename following CompI conventions"""
+
+        # Create prompt slug (first 5 words)
+        prompt_words = prompt.lower().replace(',', '').split()[:5]
+        prompt_slug = "_".join(prompt_words)
+
+        # Create style slug
+        style_slug = style.replace(" ", "").replace(",", "")[:10] if style else "standard"
+
+        # Create emotion slug
+        if emotion_analysis:
+            emotion_slug = f"{emotion_analysis.primary_emotion.value}_{emotion_analysis.intensity_level}"[:15]
+        else:
+            emotion_slug = "neutral"
+
+        # Timestamp
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # Combine all elements
+        filename = f"{prompt_slug}_{style_slug}_{emotion_slug}_{timestamp}_seed{seed}_EMO_v{variation}"
+
+        return filename
+
+    def batch_process_emotions(
+        self,
+        text_prompt: str,
+        style: str,
+        emotions: List[str],
+        emotion_type: str = "auto",
+        **generation_kwargs
+    ) -> List[Dict]:
+        """
+        Process multiple emotions in batch
+
+        Args:
+            text_prompt: Base text prompt for all generations
+            style: Art style
+            emotions: List of emotions to process
+            emotion_type: Type of emotion input
+            **generation_kwargs: Additional generation parameters
+
+        Returns:
+            List of all generation results
+        """
+        logger.info(f"Processing {len(emotions)} emotions in batch")
+
+        all_results = []
+        for i, emotion in enumerate(emotions):
+            logger.info(f"Processing emotion {i+1}/{len(emotions)}: {emotion}")
+
+            try:
+                results = self.generate_image(
+                    text_prompt=text_prompt,
+                    style=style,
+                    emotion_input=emotion,
+                    emotion_type=emotion_type,
+                    **generation_kwargs
+                )
+                all_results.extend(results)
+
+            except Exception as e:
+                logger.error(f"Error processing emotion '{emotion}': {e}")
+                continue
+
+        logger.info(f"Batch processing complete: {len(all_results)} images generated")
+        return all_results
+
+    def generate_emotion_palette_art(
+        self,
+        text_prompt: str,
+        style: str,
+        emotion_input: str,
+        use_color_conditioning: bool = True,
+        **generation_kwargs
+    ) -> List[Dict]:
+        """
+        Generate art using emotion-derived color palettes
+
+        Args:
+            text_prompt: Base text prompt
+            style: Art style
+            emotion_input: Emotion input
+            use_color_conditioning: Whether to add color palette to prompt
+            **generation_kwargs: Additional generation parameters
+
+        Returns:
+            List of generation results with color palette conditioning
+        """
+        # Analyze emotion to get color palette
+        emotion_analysis = self.analyze_emotion(emotion_input)
+
+        # Enhance prompt with color information if requested
+        if use_color_conditioning and emotion_analysis:
+            color_names = self._hex_to_color_names(emotion_analysis.color_palette)
+            color_prompt = f"with a color palette of {', '.join(color_names)}"
+            enhanced_text_prompt = f"{text_prompt}, {color_prompt}"
+        else:
+            enhanced_text_prompt = text_prompt
+
+        return self.generate_image(
+            text_prompt=enhanced_text_prompt,
+            style=style,
+            emotion_input=emotion_input,
+            **generation_kwargs
+        )
+
+    def _hex_to_color_names(self, hex_colors: List[str]) -> List[str]:
+        """Convert hex colors to approximate color names"""
+        color_mapping = {
+            "#FFD700": "golden", "#FFA500": "orange", "#FF69B4": "pink",
+            "#00CED1": "turquoise", "#32CD32": "lime", "#4169E1": "blue",
+            "#6495ED": "cornflower", "#708090": "slate", "#2F4F4F": "dark slate",
+            "#191970": "midnight blue", "#DC143C": "crimson", "#B22222": "firebrick",
+            "#8B0000": "dark red", "#FF4500": "orange red", "#FF6347": "tomato",
+            "#800080": "purple", "#4B0082": "indigo", "#2E2E2E": "dark gray",
+            "#696969": "dim gray", "#A9A9A9": "dark gray", "#FF1493": "deep pink",
+            "#FFB6C1": "light pink", "#FFC0CB": "pink", "#FFFF00": "yellow",
+            "#C71585": "medium violet", "#DB7093": "pale violet", "#20B2AA": "light sea green",
+            "#48D1CC": "medium turquoise", "#40E0D0": "turquoise", "#AFEEEE": "pale turquoise",
+            "#9370DB": "medium purple", "#8A2BE2": "blue violet", "#7B68EE": "medium slate blue",
+            "#6A5ACD": "slate blue", "#483D8B": "dark slate blue", "#808080": "gray",
+            "#C0C0C0": "silver", "#D3D3D3": "light gray", "#DCDCDC": "gainsboro"
+        }
+
+        color_names = []
+        for hex_color in hex_colors:
+            color_name = color_mapping.get(hex_color.upper(), "colorful")
+            color_names.append(color_name)
+
+        return color_names

src/generators/compi_phase2d_realtime_to_image.py

@@ -0,0 +1,483 @@
+"""
+CompI Phase 2.D: Real-Time Data Feeds to Image Generation
+
+This module implements real-time data-driven AI art generation that combines:
+- Weather data integration from multiple APIs
+- News headlines and RSS feed processing
+- Financial market data incorporation
+- Real-time context analysis and summarization
+- Intelligent fusion of real-time data with creative prompts
+
+Features:
+- Support for weather, news, and financial data feeds
+- Automatic data caching and rate limiting
+- Context-aware prompt enhancement
+- Temporal and thematic analysis
+- Comprehensive metadata logging and filename conventions
+- Batch processing capabilities for multiple data sources
+"""
+
+import os
+import sys
+import torch
+import json
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Union
+from pathlib import Path
+import logging
+
+# Add project root to path
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+from diffusers import StableDiffusionPipeline
+from PIL import Image
+
+from src.utils.realtime_data_utils import (
+    RealTimeDataProcessor, RealTimeContext, DataFeedType, RealTimeDataPoint
+)
+from src.utils.logging_utils import setup_logger
+from src.utils.file_utils import ensure_directory_exists, generate_filename
+
+# Setup logging
+logger = setup_logger(__name__)
+
+class CompIPhase2DRealTimeToImage:
+    """
+    CompI Phase 2.D: Real-Time Data Feeds to Image Generation System
+    
+    Transforms real-time data feeds into AI-generated art
+    """
+    
+    def __init__(
+        self,
+        model_name: str = "runwayml/stable-diffusion-v1-5",
+        device: str = "auto",
+        output_dir: str = "outputs"
+    ):
+        """
+        Initialize the real-time data-to-image generation system
+        
+        Args:
+            model_name: Stable Diffusion model to use
+            device: Device for inference (auto, cpu, cuda)
+            output_dir: Directory for saving generated images
+        """
+        self.model_name = model_name
+        self.device = self._setup_device(device)
+        self.output_dir = Path(output_dir)
+        ensure_directory_exists(self.output_dir)
+        
+        # Initialize components
+        self.pipe = None
+        self.data_processor = RealTimeDataProcessor()
+        
+        logger.info(f"Initialized CompI Phase 2.D on {self.device}")
+    
+    def _setup_device(self, device: str) -> str:
+        """Setup and validate device"""
+        if device == "auto":
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+        
+        if device == "cuda" and not torch.cuda.is_available():
+            logger.warning("CUDA requested but not available, falling back to CPU")
+            device = "cpu"
+        
+        return device
+    
+    def _load_pipeline(self):
+        """Lazy load the Stable Diffusion pipeline"""
+        if self.pipe is None:
+            logger.info(f"Loading Stable Diffusion model: {self.model_name}")
+            
+            # Custom safety checker that allows creative content
+            def dummy_safety_checker(images, **kwargs):
+                return images, [False] * len(images)
+            
+            self.pipe = StableDiffusionPipeline.from_pretrained(
+                self.model_name,
+                torch_dtype=torch.float16 if self.device == "cuda" else torch.float32,
+                safety_checker=dummy_safety_checker,
+                requires_safety_checker=False
+            )
+            
+            self.pipe = self.pipe.to(self.device)
+            self.pipe.enable_attention_slicing()
+            
+            if self.device == "cuda":
+                self.pipe.enable_model_cpu_offload()
+            
+            logger.info("Stable Diffusion pipeline loaded successfully")
+    
+    def fetch_realtime_context(
+        self,
+        include_weather: bool = False,
+        weather_city: str = "New York",
+        weather_api_key: Optional[str] = None,
+        include_news: bool = False,
+        news_category: str = "general",
+        max_news: int = 3,
+        news_api_key: Optional[str] = None,
+        include_financial: bool = False
+    ) -> RealTimeContext:
+        """
+        Fetch real-time context from various data sources
+        
+        Args:
+            include_weather: Whether to include weather data
+            weather_city: City for weather data
+            weather_api_key: Optional weather API key
+            include_news: Whether to include news data
+            news_category: Category of news to fetch
+            max_news: Maximum number of news items
+            news_api_key: Optional news API key
+            include_financial: Whether to include financial data
+            
+        Returns:
+            RealTimeContext with processed data
+        """
+        logger.info("Fetching real-time context for art generation")
+        
+        return self.data_processor.fetch_realtime_context(
+            include_weather=include_weather,
+            weather_city=weather_city,
+            include_news=include_news,
+            news_category=news_category,
+            max_news=max_news,
+            include_financial=include_financial,
+            weather_api_key=weather_api_key,
+            news_api_key=news_api_key
+        )
+    
+    def generate_image(
+        self,
+        text_prompt: str,
+        style: str = "",
+        mood: str = "",
+        include_weather: bool = False,
+        weather_city: str = "New York",
+        weather_api_key: Optional[str] = None,
+        include_news: bool = False,
+        news_category: str = "general",
+        max_news: int = 3,
+        news_api_key: Optional[str] = None,
+        include_financial: bool = False,
+        context_strength: float = 0.7,
+        num_images: int = 1,
+        height: int = 512,
+        width: int = 512,
+        num_inference_steps: int = 30,
+        guidance_scale: float = 7.5,
+        seed: Optional[int] = None
+    ) -> List[Dict]:
+        """
+        Generate images with real-time data conditioning
+        
+        Args:
+            text_prompt: Base text prompt
+            style: Art style
+            mood: Mood/atmosphere
+            include_weather: Whether to include weather data
+            weather_city: City for weather data
+            weather_api_key: Optional weather API key
+            include_news: Whether to include news data
+            news_category: Category of news to fetch
+            max_news: Maximum number of news items
+            news_api_key: Optional news API key
+            include_financial: Whether to include financial data
+            context_strength: How strongly to apply real-time context (0-1)
+            num_images: Number of images to generate
+            height: Image height
+            width: Image width
+            num_inference_steps: Number of diffusion steps
+            guidance_scale: Guidance scale for generation
+            seed: Random seed for reproducibility
+            
+        Returns:
+            List of generation results with metadata
+        """
+        self._load_pipeline()
+        
+        # Fetch real-time context if any data sources are enabled
+        realtime_context = None
+        if include_weather or include_news or include_financial:
+            realtime_context = self.fetch_realtime_context(
+                include_weather=include_weather,
+                weather_city=weather_city,
+                weather_api_key=weather_api_key,
+                include_news=include_news,
+                news_category=news_category,
+                max_news=max_news,
+                news_api_key=news_api_key,
+                include_financial=include_financial
+            )
+        
+        # Create enhanced prompt
+        enhanced_prompt = self._create_enhanced_prompt(
+            text_prompt, style, mood, realtime_context, context_strength
+        )
+        
+        logger.info(f"Generating {num_images} image(s) with real-time context")
+        
+        results = []
+        
+        for i in range(num_images):
+            # Set up generation parameters
+            current_seed = seed if seed is not None else torch.seed()
+            generator = torch.Generator(device=self.device).manual_seed(current_seed)
+            
+            # Generate image
+            with torch.autocast(self.device) if self.device == "cuda" else torch.no_grad():
+                result = self.pipe(
+                    enhanced_prompt,
+                    height=height,
+                    width=width,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    generator=generator
+                )
+                
+                image = result.images[0]
+            
+            # Create metadata
+            metadata = {
+                "timestamp": datetime.now().isoformat(),
+                "text_prompt": text_prompt,
+                "style": style,
+                "mood": mood,
+                "enhanced_prompt": enhanced_prompt,
+                "context_strength": context_strength,
+                "data_sources": {
+                    "weather": include_weather,
+                    "news": include_news,
+                    "financial": include_financial
+                },
+                "generation_params": {
+                    "height": height,
+                    "width": width,
+                    "num_inference_steps": num_inference_steps,
+                    "guidance_scale": guidance_scale,
+                    "seed": current_seed,
+                    "model": self.model_name
+                },
+                "device": self.device,
+                "phase": "2D_realtime_to_image"
+            }
+            
+            # Add real-time context to metadata
+            if realtime_context:
+                metadata["realtime_context"] = realtime_context.to_dict()
+            
+            # Generate filename
+            filename = self._generate_filename(
+                text_prompt, style, realtime_context, current_seed, i + 1
+            )
+            
+            # Save image and metadata
+            image_path = self.output_dir / f"{filename}.png"
+            metadata_path = self.output_dir / f"{filename}_metadata.json"
+            
+            image.save(image_path)
+            with open(metadata_path, 'w') as f:
+                json.dump(metadata, f, indent=2)
+            
+            results.append({
+                "image": image,
+                "image_path": str(image_path),
+                "metadata_path": str(metadata_path),
+                "metadata": metadata,
+                "filename": filename,
+                "realtime_context": realtime_context
+            })
+            
+            logger.info(f"Generated image {i+1}/{num_images}: {filename}")
+        
+        return results
+
+    def _create_enhanced_prompt(
+        self,
+        text_prompt: str,
+        style: str,
+        mood: str,
+        realtime_context: Optional[RealTimeContext],
+        context_strength: float
+    ) -> str:
+        """
+        Create enhanced prompt with real-time context
+
+        Args:
+            text_prompt: Base text prompt
+            style: Art style
+            mood: Mood/atmosphere
+            realtime_context: Real-time context data
+            context_strength: How strongly to apply context (0-1)
+
+        Returns:
+            Enhanced prompt with real-time context
+        """
+        enhanced_prompt = text_prompt.strip()
+
+        # Add style
+        if style:
+            enhanced_prompt += f", {style}"
+
+        # Add mood
+        if mood:
+            enhanced_prompt += f", {mood}"
+
+        # Add real-time context based on strength
+        if realtime_context and context_strength > 0:
+            if context_strength > 0.7:
+                # Strong context integration
+                enhanced_prompt += f", {realtime_context.artistic_inspiration}"
+                if realtime_context.mood_indicators:
+                    mood_text = ", ".join(realtime_context.mood_indicators[:2])
+                    enhanced_prompt += f", with {mood_text} influences"
+
+            elif context_strength > 0.4:
+                # Moderate context integration
+                enhanced_prompt += f", {realtime_context.artistic_inspiration}"
+
+            else:
+                # Subtle context integration
+                if realtime_context.key_themes:
+                    theme = realtime_context.key_themes[0]
+                    enhanced_prompt += f", inspired by {theme}"
+
+        return enhanced_prompt
+
+    def _generate_filename(
+        self,
+        prompt: str,
+        style: str,
+        realtime_context: Optional[RealTimeContext],
+        seed: int,
+        variation: int
+    ) -> str:
+        """Generate descriptive filename following CompI conventions"""
+
+        # Create prompt slug (first 5 words)
+        prompt_words = prompt.lower().replace(',', '').split()[:5]
+        prompt_slug = "_".join(prompt_words)
+
+        # Create style slug
+        style_slug = style.replace(" ", "").replace(",", "")[:10] if style else "standard"
+
+        # Create context slug
+        if realtime_context and realtime_context.data_points:
+            context_types = []
+            for dp in realtime_context.data_points:
+                context_types.append(dp.feed_type.value[:3])  # First 3 chars
+            context_slug = "_".join(set(context_types))[:15]
+        else:
+            context_slug = "static"
+
+        # Timestamp
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # Combine all elements
+        filename = f"{prompt_slug}_{style_slug}_{context_slug}_{timestamp}_seed{seed}_RTDATA_v{variation}"
+
+        return filename
+
+    def batch_process_data_sources(
+        self,
+        text_prompt: str,
+        style: str,
+        data_source_configs: List[Dict],
+        **generation_kwargs
+    ) -> List[Dict]:
+        """
+        Process multiple data source configurations in batch
+
+        Args:
+            text_prompt: Base text prompt for all generations
+            style: Art style
+            data_source_configs: List of data source configuration dictionaries
+            **generation_kwargs: Additional generation parameters
+
+        Returns:
+            List of all generation results
+        """
+        logger.info(f"Processing {len(data_source_configs)} data source configurations")
+
+        all_results = []
+        for i, config in enumerate(data_source_configs):
+            logger.info(f"Processing configuration {i+1}/{len(data_source_configs)}")
+
+            try:
+                results = self.generate_image(
+                    text_prompt=text_prompt,
+                    style=style,
+                    **config,
+                    **generation_kwargs
+                )
+                all_results.extend(results)
+
+            except Exception as e:
+                logger.error(f"Error processing configuration {i+1}: {e}")
+                continue
+
+        logger.info(f"Batch processing complete: {len(all_results)} images generated")
+        return all_results
+
+    def generate_temporal_series(
+        self,
+        text_prompt: str,
+        style: str,
+        data_config: Dict,
+        time_intervals: List[int],
+        **generation_kwargs
+    ) -> List[Dict]:
+        """
+        Generate a series of images with real-time data at different time intervals
+
+        Args:
+            text_prompt: Base text prompt
+            style: Art style
+            data_config: Data source configuration
+            time_intervals: List of time intervals in minutes between generations
+            **generation_kwargs: Additional generation parameters
+
+        Returns:
+            List of generation results across time
+        """
+        import time
+
+        logger.info(f"Generating temporal series with {len(time_intervals)} intervals")
+
+        all_results = []
+
+        for i, interval in enumerate(time_intervals):
+            if i > 0:  # Don't wait before first generation
+                logger.info(f"Waiting {interval} minutes before next generation...")
+                time.sleep(interval * 60)  # Convert minutes to seconds
+
+            logger.info(f"Generating image {i+1}/{len(time_intervals)}")
+
+            try:
+                # Clear cache to ensure fresh data
+                self.data_processor.cache.cache.clear()
+
+                results = self.generate_image(
+                    text_prompt=text_prompt,
+                    style=style,
+                    **data_config,
+                    **generation_kwargs
+                )
+
+                # Add temporal metadata
+                for result in results:
+                    result["metadata"]["temporal_series"] = {
+                        "series_index": i,
+                        "total_in_series": len(time_intervals),
+                        "interval_minutes": interval if i > 0 else 0
+                    }
+
+                all_results.extend(results)
+
+            except Exception as e:
+                logger.error(f"Error in temporal generation {i+1}: {e}")
+                continue
+
+        logger.info(f"Temporal series complete: {len(all_results)} images generated")
+        return all_results

src/generators/compi_phase2e_refimg_to_image.py

@@ -0,0 +1,578 @@
+"""
+CompI Phase 2.E: Style Reference/Example Image to AI Art Generation
+
+This module implements multimodal AI art generation that combines:
+- Text prompts with style and mood conditioning
+- Reference image style transfer and guidance
+- Image-to-image generation with controllable strength
+- Support for both local files and web URLs
+- Advanced style analysis and prompt enhancement
+
+Features:
+- Support for various image formats and web sources
+- Real-time image analysis and style suggestion
+- Controllable reference strength for creative flexibility
+- Comprehensive metadata logging and filename conventions
+- Batch processing capabilities with multiple variations
+"""
+
+import os
+import sys
+import torch
+import json
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Union
+from pathlib import Path
+import logging
+
+# Add project root to path
+sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..'))
+
+from diffusers import StableDiffusionImg2ImgPipeline, StableDiffusionPipeline
+from PIL import Image
+import numpy as np
+
+from src.utils.image_utils import ImageProcessor, StyleAnalyzer
+from src.utils.logging_utils import setup_logger
+from src.utils.file_utils import ensure_directory_exists, generate_filename
+from src.config import (
+    STABLE_DIFFUSION_IMG2IMG_MODEL, 
+    OUTPUTS_DIR, 
+    DEFAULT_IMAGE_SIZE,
+    DEFAULT_INFERENCE_STEPS,
+    DEFAULT_GUIDANCE_SCALE
+)
+
+# Setup logging
+logger = setup_logger(__name__)
+
+class CompIPhase2ERefImageToImage:
+    """
+    CompI Phase 2.E: Style Reference/Example Image to AI Art Generation System
+    
+    Combines text prompts with reference image style guidance for enhanced creativity
+    """
+    
+    def __init__(
+        self,
+        model_name: str = STABLE_DIFFUSION_IMG2IMG_MODEL,
+        device: Optional[str] = None,
+        enable_attention_slicing: bool = True,
+        enable_memory_efficient_attention: bool = True
+    ):
+        """
+        Initialize the CompI Phase 2.E system
+        
+        Args:
+            model_name: Hugging Face model identifier
+            device: Device to run on ('cuda', 'cpu', or None for auto)
+            enable_attention_slicing: Enable attention slicing for memory efficiency
+            enable_memory_efficient_attention: Enable memory efficient attention
+        """
+        self.model_name = model_name
+        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        
+        # Initialize components
+        self.image_processor = ImageProcessor()
+        self.style_analyzer = StyleAnalyzer()
+        
+        # Initialize pipelines (lazy loading)
+        self._img2img_pipeline = None
+        self._txt2img_pipeline = None
+        
+        # Configuration
+        self.enable_attention_slicing = enable_attention_slicing
+        self.enable_memory_efficient_attention = enable_memory_efficient_attention
+        
+        logger.info(f"Initialized CompI Phase 2.E on device: {self.device}")
+        
+    @property
+    def img2img_pipeline(self) -> StableDiffusionImg2ImgPipeline:
+        """Lazy load img2img pipeline"""
+        if self._img2img_pipeline is None:
+            logger.info(f"Loading img2img pipeline: {self.model_name}")
+            self._img2img_pipeline = StableDiffusionImg2ImgPipeline.from_pretrained(
+                self.model_name,
+                torch_dtype=torch.float16 if self.device == "cuda" else torch.float32,
+                safety_checker=None,  # Disabled for creative use
+                requires_safety_checker=False
+            )
+            self._img2img_pipeline = self._img2img_pipeline.to(self.device)
+            
+            if self.enable_attention_slicing:
+                self._img2img_pipeline.enable_attention_slicing()
+            if self.enable_memory_efficient_attention and hasattr(self._img2img_pipeline, 'enable_memory_efficient_attention'):
+                self._img2img_pipeline.enable_memory_efficient_attention()
+                
+        return self._img2img_pipeline
+        
+    @property
+    def txt2img_pipeline(self) -> StableDiffusionPipeline:
+        """Lazy load txt2img pipeline for fallback"""
+        if self._txt2img_pipeline is None:
+            logger.info(f"Loading txt2img pipeline: {self.model_name}")
+            self._txt2img_pipeline = StableDiffusionPipeline.from_pretrained(
+                self.model_name,
+                torch_dtype=torch.float16 if self.device == "cuda" else torch.float32,
+                safety_checker=None,  # Disabled for creative use
+                requires_safety_checker=False
+            )
+            self._txt2img_pipeline = self._txt2img_pipeline.to(self.device)
+            
+            if self.enable_attention_slicing:
+                self._txt2img_pipeline.enable_attention_slicing()
+            if self.enable_memory_efficient_attention and hasattr(self._txt2img_pipeline, 'enable_memory_efficient_attention'):
+                self._txt2img_pipeline.enable_memory_efficient_attention()
+                
+        return self._txt2img_pipeline
+        
+    def load_reference_image(
+        self, 
+        source: Union[str, Path, Image.Image],
+        preprocess: bool = True
+    ) -> Optional[Tuple[Image.Image, Dict]]:
+        """
+        Load and analyze reference image from various sources
+        
+        Args:
+            source: Image source (file path, URL, or PIL Image)
+            preprocess: Whether to preprocess the image
+            
+        Returns:
+            Tuple of (processed_image, analysis_results) or None if failed
+        """
+        try:
+            # Load image based on source type
+            if isinstance(source, Image.Image):
+                image = source.convert('RGB')
+                source_info = "PIL Image object"
+            elif isinstance(source, (str, Path)):
+                source_str = str(source)
+                if source_str.startswith(('http://', 'https://')):
+                    image = self.image_processor.load_image_from_url(source_str)
+                    source_info = f"URL: {source_str}"
+                else:
+                    image = self.image_processor.load_image_from_file(source_str)
+                    source_info = f"File: {source_str}"
+                    
+                if image is None:
+                    return None
+            else:
+                logger.error(f"Unsupported source type: {type(source)}")
+                return None
+                
+            # Preprocess if requested
+            if preprocess:
+                image = self.image_processor.preprocess_image(image, DEFAULT_IMAGE_SIZE)
+                
+            # Analyze image properties
+            properties = self.image_processor.analyze_image_properties(image)
+            style_suggestions = self.style_analyzer.suggest_style_keywords(properties)
+            image_hash = self.image_processor.generate_image_hash(image)
+            
+            analysis = {
+                'source': source_info,
+                'properties': properties,
+                'style_suggestions': style_suggestions,
+                'hash': image_hash,
+                'processed_size': image.size
+            }
+            
+            logger.info(f"Successfully loaded and analyzed reference image: {analysis}")
+            return image, analysis
+            
+        except Exception as e:
+            logger.error(f"Error loading reference image: {e}")
+            return None
+            
+    def enhance_prompt_with_style(
+        self, 
+        base_prompt: str,
+        style: str = "",
+        mood: str = "",
+        style_suggestions: List[str] = None
+    ) -> str:
+        """
+        Enhance prompt with style information from reference image
+        
+        Args:
+            base_prompt: Base text prompt
+            style: Additional style keywords
+            mood: Mood/atmosphere keywords
+            style_suggestions: Suggested keywords from image analysis
+            
+        Returns:
+            Enhanced prompt string
+        """
+        try:
+            prompt_parts = [base_prompt.strip()]
+            
+            # Add explicit style
+            if style.strip():
+                prompt_parts.append(style.strip())
+                
+            # Add mood
+            if mood.strip():
+                prompt_parts.append(mood.strip())
+                
+            # Add style suggestions from image analysis
+            if style_suggestions:
+                # Limit to top 3 suggestions to avoid prompt bloat
+                top_suggestions = style_suggestions[:3]
+                prompt_parts.extend(top_suggestions)
+                
+            enhanced_prompt = ", ".join(prompt_parts)
+            logger.info(f"Enhanced prompt: {enhanced_prompt}")
+            return enhanced_prompt
+            
+        except Exception as e:
+            logger.error(f"Error enhancing prompt: {e}")
+            return base_prompt
+
+    def generate_with_reference(
+        self,
+        prompt: str,
+        reference_image: Image.Image,
+        style: str = "",
+        mood: str = "",
+        strength: float = 0.5,
+        num_images: int = 1,
+        num_inference_steps: int = DEFAULT_INFERENCE_STEPS,
+        guidance_scale: float = DEFAULT_GUIDANCE_SCALE,
+        seed: Optional[int] = None,
+        style_suggestions: List[str] = None
+    ) -> List[Dict]:
+        """
+        Generate images using reference image guidance
+
+        Args:
+            prompt: Text prompt
+            reference_image: Reference PIL Image
+            style: Style keywords
+            mood: Mood keywords
+            strength: Reference strength (0.0-1.0, higher = closer to reference)
+            num_images: Number of images to generate
+            num_inference_steps: Number of denoising steps
+            guidance_scale: Classifier-free guidance scale
+            seed: Random seed for reproducibility
+            style_suggestions: Style suggestions from image analysis
+
+        Returns:
+            List of generation results with metadata
+        """
+        try:
+            # Enhance prompt with style information
+            enhanced_prompt = self.enhance_prompt_with_style(
+                prompt, style, mood, style_suggestions
+            )
+
+            results = []
+
+            for i in range(num_images):
+                # Set up random seed
+                if seed is not None:
+                    current_seed = seed + i
+                else:
+                    current_seed = torch.seed()
+
+                generator = torch.Generator(device=self.device).manual_seed(current_seed)
+
+                # Generate image
+                logger.info(f"Generating image {i+1}/{num_images} with reference guidance")
+
+                with torch.autocast(self.device) if self.device == "cuda" else torch.no_grad():
+                    result = self.img2img_pipeline(
+                        prompt=enhanced_prompt,
+                        image=reference_image,
+                        strength=strength,
+                        num_inference_steps=num_inference_steps,
+                        guidance_scale=guidance_scale,
+                        generator=generator
+                    )
+
+                generated_image = result.images[0]
+
+                # Create metadata
+                metadata = {
+                    'prompt': prompt,
+                    'enhanced_prompt': enhanced_prompt,
+                    'style': style,
+                    'mood': mood,
+                    'strength': strength,
+                    'num_inference_steps': num_inference_steps,
+                    'guidance_scale': guidance_scale,
+                    'seed': current_seed,
+                    'model': self.model_name,
+                    'generation_type': 'img2img_reference',
+                    'timestamp': datetime.now().isoformat(),
+                    'device': self.device,
+                    'reference_size': reference_image.size,
+                    'output_size': generated_image.size,
+                    'style_suggestions': style_suggestions or []
+                }
+
+                results.append({
+                    'image': generated_image,
+                    'metadata': metadata,
+                    'index': i
+                })
+
+            logger.info(f"Successfully generated {len(results)} images with reference guidance")
+            return results
+
+        except Exception as e:
+            logger.error(f"Error generating images with reference: {e}")
+            return []
+
+    def generate_without_reference(
+        self,
+        prompt: str,
+        style: str = "",
+        mood: str = "",
+        num_images: int = 1,
+        num_inference_steps: int = DEFAULT_INFERENCE_STEPS,
+        guidance_scale: float = DEFAULT_GUIDANCE_SCALE,
+        seed: Optional[int] = None
+    ) -> List[Dict]:
+        """
+        Generate images without reference (fallback to text-to-image)
+
+        Args:
+            prompt: Text prompt
+            style: Style keywords
+            mood: Mood keywords
+            num_images: Number of images to generate
+            num_inference_steps: Number of denoising steps
+            guidance_scale: Classifier-free guidance scale
+            seed: Random seed for reproducibility
+
+        Returns:
+            List of generation results with metadata
+        """
+        try:
+            # Enhance prompt
+            enhanced_prompt = self.enhance_prompt_with_style(prompt, style, mood)
+
+            results = []
+
+            for i in range(num_images):
+                # Set up random seed
+                if seed is not None:
+                    current_seed = seed + i
+                else:
+                    current_seed = torch.seed()
+
+                generator = torch.Generator(device=self.device).manual_seed(current_seed)
+
+                # Generate image
+                logger.info(f"Generating image {i+1}/{num_images} without reference")
+
+                with torch.autocast(self.device) if self.device == "cuda" else torch.no_grad():
+                    result = self.txt2img_pipeline(
+                        prompt=enhanced_prompt,
+                        height=DEFAULT_IMAGE_SIZE[1],
+                        width=DEFAULT_IMAGE_SIZE[0],
+                        num_inference_steps=num_inference_steps,
+                        guidance_scale=guidance_scale,
+                        generator=generator
+                    )
+
+                generated_image = result.images[0]
+
+                # Create metadata
+                metadata = {
+                    'prompt': prompt,
+                    'enhanced_prompt': enhanced_prompt,
+                    'style': style,
+                    'mood': mood,
+                    'num_inference_steps': num_inference_steps,
+                    'guidance_scale': guidance_scale,
+                    'seed': current_seed,
+                    'model': self.model_name,
+                    'generation_type': 'txt2img_fallback',
+                    'timestamp': datetime.now().isoformat(),
+                    'device': self.device,
+                    'output_size': generated_image.size
+                }
+
+                results.append({
+                    'image': generated_image,
+                    'metadata': metadata,
+                    'index': i
+                })
+
+            logger.info(f"Successfully generated {len(results)} images without reference")
+            return results
+
+        except Exception as e:
+            logger.error(f"Error generating images without reference: {e}")
+            return []
+
+    def save_results(
+        self,
+        results: List[Dict],
+        output_dir: Path = OUTPUTS_DIR,
+        reference_info: Optional[Dict] = None
+    ) -> List[str]:
+        """
+        Save generation results with comprehensive metadata
+
+        Args:
+            results: List of generation results
+            output_dir: Output directory
+            reference_info: Reference image information
+
+        Returns:
+            List of saved file paths
+        """
+        try:
+            ensure_directory_exists(output_dir)
+            saved_files = []
+
+            for result in results:
+                image = result['image']
+                metadata = result['metadata']
+                index = result['index']
+
+                # Generate filename
+                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+                prompt_slug = "_".join(metadata['prompt'].lower().split()[:5])
+                style_slug = metadata.get('style', '').replace(' ', '')[:10]
+                mood_slug = metadata.get('mood', '').replace(' ', '')[:10]
+
+                # Add reference indicator
+                ref_indicator = "REFIMG" if metadata['generation_type'] == 'img2img_reference' else "NOREFIMG"
+
+                filename = f"{prompt_slug}_{style_slug}_{mood_slug}_{timestamp}_seed{metadata['seed']}_{ref_indicator}_v{index+1}.png"
+                filepath = output_dir / filename
+
+                # Save image
+                image.save(filepath)
+
+                # Add reference info to metadata if available
+                if reference_info:
+                    metadata['reference_info'] = reference_info
+
+                # Save metadata
+                metadata_filename = filepath.stem + "_metadata.json"
+                metadata_filepath = output_dir / metadata_filename
+
+                with open(metadata_filepath, 'w') as f:
+                    json.dump(metadata, f, indent=2, default=str)
+
+                saved_files.extend([str(filepath), str(metadata_filepath)])
+                logger.info(f"Saved: {filepath}")
+
+            return saved_files
+
+        except Exception as e:
+            logger.error(f"Error saving results: {e}")
+            return []
+
+    def generate_batch(
+        self,
+        prompt: str,
+        reference_source: Optional[Union[str, Path, Image.Image]] = None,
+        style: str = "",
+        mood: str = "",
+        strength: float = 0.5,
+        num_images: int = 1,
+        num_inference_steps: int = DEFAULT_INFERENCE_STEPS,
+        guidance_scale: float = DEFAULT_GUIDANCE_SCALE,
+        seed: Optional[int] = None,
+        save_results: bool = True,
+        output_dir: Path = OUTPUTS_DIR
+    ) -> Dict:
+        """
+        Complete batch generation pipeline
+
+        Args:
+            prompt: Text prompt
+            reference_source: Reference image source (file, URL, or PIL Image)
+            style: Style keywords
+            mood: Mood keywords
+            strength: Reference strength (only used if reference provided)
+            num_images: Number of images to generate
+            num_inference_steps: Number of denoising steps
+            guidance_scale: Classifier-free guidance scale
+            seed: Random seed for reproducibility
+            save_results: Whether to save results to disk
+            output_dir: Output directory for saved files
+
+        Returns:
+            Dictionary with results and metadata
+        """
+        try:
+            logger.info(f"Starting batch generation: {num_images} images")
+
+            reference_image = None
+            reference_info = None
+            style_suggestions = []
+
+            # Load and analyze reference image if provided
+            if reference_source is not None:
+                ref_result = self.load_reference_image(reference_source)
+                if ref_result:
+                    reference_image, reference_info = ref_result
+                    style_suggestions = reference_info.get('style_suggestions', [])
+                    logger.info(f"Using reference image with suggestions: {style_suggestions}")
+                else:
+                    logger.warning("Failed to load reference image, falling back to text-only generation")
+
+            # Generate images
+            if reference_image is not None:
+                results = self.generate_with_reference(
+                    prompt=prompt,
+                    reference_image=reference_image,
+                    style=style,
+                    mood=mood,
+                    strength=strength,
+                    num_images=num_images,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    seed=seed,
+                    style_suggestions=style_suggestions
+                )
+            else:
+                results = self.generate_without_reference(
+                    prompt=prompt,
+                    style=style,
+                    mood=mood,
+                    num_images=num_images,
+                    num_inference_steps=num_inference_steps,
+                    guidance_scale=guidance_scale,
+                    seed=seed
+                )
+
+            # Save results if requested
+            saved_files = []
+            if save_results and results:
+                saved_files = self.save_results(results, output_dir, reference_info)
+
+            # Compile final results
+            batch_result = {
+                'results': results,
+                'reference_info': reference_info,
+                'saved_files': saved_files,
+                'generation_summary': {
+                    'total_images': len(results),
+                    'prompt': prompt,
+                    'style': style,
+                    'mood': mood,
+                    'has_reference': reference_image is not None,
+                    'style_suggestions': style_suggestions,
+                    'timestamp': datetime.now().isoformat()
+                }
+            }
+
+            logger.info(f"Batch generation complete: {len(results)} images generated")
+            return batch_result
+
+        except Exception as e:
+            logger.error(f"Error in batch generation: {e}")
+            return {
+                'results': [],
+                'reference_info': None,
+                'saved_files': [],
+                'error': str(e)
+            }

src/setup_env.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+Environment setup script for CompI project.
+Run this script to check and install dependencies.
+"""
+
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+def run_command(command, description):
+    """Run a shell command and handle errors."""
+    print(f"\n🔄 {description}...")
+    try:
+        result = subprocess.run(command, shell=True, check=True, 
+                              capture_output=True, text=True)
+        print(f"✅ {description} completed successfully")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"❌ {description} failed:")
+        print(f"Error: {e.stderr}")
+        return False
+
+def check_python_version():
+    """Check if Python version is compatible."""
+    version = sys.version_info
+    if version.major == 3 and version.minor >= 8:
+        print(f"✅ Python {version.major}.{version.minor}.{version.micro} is compatible")
+        return True
+    else:
+        print(f"❌ Python {version.major}.{version.minor}.{version.micro} is not compatible")
+        print("Please use Python 3.8 or higher")
+        return False
+
+def check_gpu():
+    """Check for CUDA availability."""
+    try:
+        import torch
+        if torch.cuda.is_available():
+            gpu_count = torch.cuda.device_count()
+            gpu_name = torch.cuda.get_device_name(0)
+            print(f"✅ CUDA available with {gpu_count} GPU(s): {gpu_name}")
+            return True
+        else:
+            print("⚠️  CUDA not available, will use CPU")
+            return False
+    except ImportError:
+        print("⚠️  PyTorch not installed yet, GPU check will be done after installation")
+        return False
+
+def install_requirements():
+    """Install requirements from requirements.txt."""
+    if not Path("requirements.txt").exists():
+        print("❌ requirements.txt not found")
+        return False
+    
+    return run_command(
+        f"{sys.executable} -m pip install -r requirements.txt",
+        "Installing requirements"
+    )
+
+def download_nltk_data():
+    """Download required NLTK data."""
+    try:
+        import nltk
+        print("\n🔄 Downloading NLTK data...")
+        nltk.download('punkt', quiet=True)
+        nltk.download('vader_lexicon', quiet=True)
+        nltk.download('stopwords', quiet=True)
+        print("✅ NLTK data downloaded")
+        return True
+    except ImportError:
+        print("⚠️  NLTK not installed, skipping data download")
+        return False
+
+def setup_textblob():
+    """Setup TextBlob corpora."""
+    try:
+        import textblob
+        print("\n🔄 Setting up TextBlob...")
+        run_command(f"{sys.executable} -m textblob.download_corpora", 
+                   "Downloading TextBlob corpora")
+        return True
+    except ImportError:
+        print("⚠️  TextBlob not installed, skipping setup")
+        return False
+
+def main():
+    """Main setup function."""
+    print("🚀 Setting up CompI Development Environment")
+    print("=" * 50)
+    
+    # Check Python version
+    if not check_python_version():
+        sys.exit(1)
+    
+    # Install requirements
+    if not install_requirements():
+        print("❌ Failed to install requirements")
+        sys.exit(1)
+    
+    # Check GPU after PyTorch installation
+    check_gpu()
+    
+    # Setup additional components
+    download_nltk_data()
+    setup_textblob()
+    
+    print("\n" + "=" * 50)
+    print("🎉 Environment setup completed!")
+    print("\nNext steps:")
+    print("1. Run: python src/test_setup.py")
+    print("2. Start experimenting with notebooks/")
+    print("3. Check out the README.md for usage examples")
+
+if __name__ == "__main__":
+    main()

src/ui/__init__.py

@@ -0,0 +1,14 @@
+"""
+CompI User Interface Components
+Interactive web interfaces for the CompI platform.
+"""
+
+__all__ = [
+    "compi_phase1c_streamlit_ui",
+    "compi_phase1c_gradio_ui",
+    "compi_phase2a_streamlit_ui",
+    "compi_phase2b_streamlit_ui",
+    "compi_phase2c_streamlit_ui",
+    "compi_phase2d_streamlit_ui",
+    "compi_phase2e_streamlit_ui"
+]

src/ui/compi_phase3_final_dashboard.py

@@ -0,0 +1,1709 @@
+#!/usr/bin/env python3
+"""
+CompI Phase 3 Final Dashboard - Complete Integration (3.A → 3.E)
+
+This is the ultimate CompI interface that integrates ALL Phase 3 components:
+- Phase 3.A/3.B: True multimodal fusion with real processing
+- Phase 3.C: Advanced references with role assignment and live ControlNet previews
+- Phase 3.D: Professional workflow management (gallery, presets, export)
+- Phase 3.E: Performance management and model switching
+
+Features:
+- All multimodal inputs (Text, Audio, Data, Emotion, Real-time, Multi-Reference)
+- Advanced References: multi-image upload/URLs, style vs structure roles, ControlNet with live previews
+- Model & Performance: SD 1.5/SDXL switching, LoRA integration, VRAM monitoring, OOM auto-retry
+- Workflow & Export: gallery, filters, rating/tags/notes, presets save/load, portable export ZIP
+- True fusion engine: real processing for all inputs, intelligent generation mode selection
+"""
+
+import os
+import io
+import csv
+import json
+import zipfile
+import shutil
+import platform
+import requests
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, List
+
+import numpy as np
+import pandas as pd
+import streamlit as st
+from PIL import Image
+import torch
+
+# --- Diffusers base (txt2img, img2img) ---
+from diffusers import (
+    StableDiffusionPipeline,
+    StableDiffusionImg2ImgPipeline,
+)
+
+# --- ControlNet (optional, with graceful fallback) ---
+HAS_CONTROLNET = True
+CN_IMG2IMG_AVAILABLE = True
+try:
+    from diffusers import (
+        StableDiffusionControlNetPipeline,
+        StableDiffusionControlNetImg2ImgPipeline,
+        ControlNetModel,
+    )
+except Exception:
+    HAS_CONTROLNET = False
+    CN_IMG2IMG_AVAILABLE = False
+
+# --- SDXL & Upscaler (optional) ---
+HAS_SDXL = True
+HAS_UPSCALER = True
+try:
+    from diffusers import StableDiffusionXLPipeline
+except Exception:
+    HAS_SDXL = False
+
+try:
+    from diffusers import StableDiffusionLatentUpscalePipeline
+except Exception:
+    HAS_UPSCALER = False
+
+# --- Audio, Emotion, Real-time, Plots, Previews ---
+def _lazy_install(pkgs: str):
+    """Install packages on demand"""
+    os.system(f"pip install -q {pkgs}")
+
+try:
+    import librosa
+    import soundfile as sf
+except Exception:
+    _lazy_install("librosa soundfile")
+    import librosa
+    import soundfile as sf
+
+try:
+    import whisper
+except Exception:
+    _lazy_install("git+https://github.com/openai/whisper.git")
+    import whisper
+
+try:
+    from textblob import TextBlob
+except Exception:
+    _lazy_install("textblob")
+    from textblob import TextBlob
+
+try:
+    import feedparser
+except Exception:
+    _lazy_install("feedparser")
+    import feedparser
+
+try:
+    import matplotlib.pyplot as plt
+except Exception:
+    _lazy_install("matplotlib")
+    import matplotlib.pyplot as plt
+
+try:
+    import cv2
+except Exception:
+    _lazy_install("opencv-python-headless")
+    import cv2
+
+# ==================== CONSTANTS & PATHS ====================
+
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+
+# Directory structure
+OUTPUT_DIR = Path("outputs")
+OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+EXPORTS_DIR = Path("exports")
+EXPORTS_DIR.mkdir(parents=True, exist_ok=True)
+
+PRESETS_DIR = Path("presets")
+PRESETS_DIR.mkdir(parents=True, exist_ok=True)
+
+# Log files for different phases
+RUNLOG = OUTPUT_DIR / "phase3_run_log.csv"          # fusion logs (3.B)
+RUNLOG_3C = OUTPUT_DIR / "phase3c_runs.csv"         # advanced ref logs (3.C)
+RUNLOG_3E = OUTPUT_DIR / "phase3e_runlog.csv"       # perf/model logs (3.E)
+ANNOT_CSV = OUTPUT_DIR / "phase3d_annotations.csv"  # annotations (3.D)
+
+# ==================== UTILITY FUNCTIONS ====================
+
+def slugify(s: str, n=30):
+    """Create safe filename from string"""
+    if not s:
+        return "none"
+    return "_".join(s.lower().split())[:n]
+
+def save_image(img: Image.Image, name: str) -> str:
+    """Save image to outputs directory"""
+    p = OUTPUT_DIR / name
+    img.save(p)
+    return str(p)
+
+def vram_gb() -> Optional[float]:
+    """Get total VRAM in GB"""
+    if DEVICE == "cuda":
+        try:
+            return torch.cuda.get_device_properties(0).total_memory / (1024**3)
+        except Exception:
+            return None
+    return None
+
+def vram_used_gb() -> Optional[float]:
+    """Get used VRAM in GB"""
+    if DEVICE == "cuda":
+        try:
+            torch.cuda.synchronize()
+            return torch.cuda.memory_allocated() / (1024**3)
+        except Exception:
+            return None
+    return None
+
+def attempt_enable_xformers(pipe):
+    """Try to enable xFormers memory efficient attention"""
+    try:
+        pipe.enable_xformers_memory_efficient_attention()
+        return True
+    except Exception:
+        return False
+
+def apply_perf(pipe, attn_slice=True, vae_slice=True, vae_tile=False):
+    """Apply performance optimizations to pipeline"""
+    if attn_slice:
+        pipe.enable_attention_slicing()
+    if vae_slice:
+        try:
+            pipe.enable_vae_slicing()
+        except Exception:
+            pass
+    if vae_tile:
+        try:
+            pipe.enable_vae_tiling()
+        except Exception:
+            pass
+
+def safe_retry_sizes(h, w, steps):
+    """Generate progressive fallback sizes for OOM recovery"""
+    sizes = [
+        (h, w, steps),
+        (max(384, h//2), max(384, w//2), max(steps-8, 12)),
+        (384, 384, max(steps-12, 12)),
+        (256, 256, max(steps-16, 10)),
+    ]
+    seen = set()
+    for it in sizes:
+        if it not in seen:
+            seen.add(it)
+            yield it
+
+def canny_map(img: Image.Image) -> Image.Image:
+    """Create Canny edge map from image"""
+    arr = np.array(img.convert("RGB"))
+    edges = cv2.Canny(arr, 100, 200)
+    edges_rgb = cv2.cvtColor(edges, cv2.COLOR_GRAY2RGB)
+    return Image.fromarray(edges_rgb)
+
+def depth_proxy(img: Image.Image) -> Image.Image:
+    """Create depth-like proxy using grayscale"""
+    gray = img.convert("L")
+    return Image.merge("RGB", (gray, gray, gray))
+
+def save_plot(fig) -> Image.Image:
+    """Save matplotlib figure as PIL Image"""
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png", bbox_inches="tight")
+    plt.close(fig)
+    buf.seek(0)
+    return Image.open(buf).convert("RGB")
+
+def env_snapshot() -> Dict:
+    """Create environment snapshot for reproducibility"""
+    import sys
+    try:
+        import importlib.metadata as im
+    except Exception:
+        import importlib_metadata as im
+
+    pkgs = {}
+    for pkg in ["torch", "diffusers", "transformers", "accelerate", "opencv-python-headless",
+                "librosa", "whisper", "textblob", "pandas", "numpy", "matplotlib",
+                "feedparser", "streamlit", "Pillow"]:
+        try:
+            pkgs[pkg] = im.version(pkg)
+        except Exception:
+            pass
+
+    return {
+        "timestamp": datetime.now().isoformat(),
+        "python_version": sys.version,
+        "platform": platform.platform(),
+        "packages": pkgs
+    }
+
+def mk_readme(bundle_meta: Dict, df_meta: pd.DataFrame) -> str:
+    """Generate README for export bundle"""
+    L = []
+    L.append(f"# CompI Export — {bundle_meta['bundle_name']}\n")
+    L.append(f"_Created: {bundle_meta['created_at']}_\n")
+    L += [
+        "## What's inside",
+        "- Selected images",
+        "- `manifest.json` (environment + settings)",
+        "- `metadata.csv` (merged logs)",
+        "- `annotations.csv` (ratings/tags/notes)",
+    ]
+    if bundle_meta.get("preset"):
+        L.append("- `preset.json` (saved generation settings)")
+
+    L.append("\n## Summary of selected runs")
+    if not df_meta.empty and "mode" in df_meta.columns:
+        counts = df_meta["mode"].value_counts().to_dict()
+        L.append("Modes:")
+        for k, v in counts.items():
+            L.append(f"- {k}: {v}")
+
+    L.append("\n## Reproducing")
+    L.append("1. Install versions in `manifest.json`.")
+    L.append("2. Use `preset.json` or copy prompt/params from `metadata.csv`.")
+    L.append("3. Run the dashboard with these settings.")
+
+    return "\n".join(L)
+
+# ==================== CACHED MODEL LOADERS ====================
+
+@st.cache_resource(show_spinner=True)
+def load_sd15(txt2img=True):
+    """Load Stable Diffusion 1.5 pipeline"""
+    if txt2img:
+        pipe = StableDiffusionPipeline.from_pretrained(
+            "runwayml/stable-diffusion-v1-5",
+            safety_checker=None,
+            torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32,
+        )
+    else:
+        pipe = StableDiffusionImg2ImgPipeline.from_pretrained(
+            "runwayml/stable-diffusion-v1-5",
+            safety_checker=None,
+            torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32,
+        )
+    return pipe.to(DEVICE)
+
+@st.cache_resource(show_spinner=True)
+def load_sdxl():
+    """Load SDXL pipeline"""
+    if not HAS_SDXL:
+        return None
+    pipe = StableDiffusionXLPipeline.from_pretrained(
+        "stabilityai/stable-diffusion-xl-base-1.0",
+        safety_checker=None,
+        torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32,
+    )
+    return pipe.to(DEVICE)
+
+@st.cache_resource(show_spinner=True)
+def load_upscaler():
+    """Load latent upscaler pipeline"""
+    if not HAS_UPSCALER:
+        return None
+    up = StableDiffusionLatentUpscalePipeline.from_pretrained(
+        "stabilityai/sd-x2-latent-upscaler",
+        safety_checker=None,
+        torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32,
+    )
+    return up.to(DEVICE)
+
+@st.cache_resource(show_spinner=True)
+def load_controlnet(cn_type: str):
+    """Load ControlNet pipeline"""
+    if not HAS_CONTROLNET:
+        return None
+    cn_id = "lllyasviel/sd-controlnet-canny" if cn_type == "Canny" else "lllyasviel/sd-controlnet-depth"
+    controlnet = ControlNetModel.from_pretrained(
+        cn_id, torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32
+    )
+    pipe = StableDiffusionControlNetPipeline.from_pretrained(
+        "runwayml/stable-diffusion-v1-5",
+        controlnet=controlnet,
+        safety_checker=None,
+        torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32,
+    ).to(DEVICE)
+    try:
+        pipe.enable_xformers_memory_efficient_attention()
+    except Exception:
+        pass
+    pipe.enable_attention_slicing()
+    return pipe
+
+@st.cache_resource(show_spinner=True)
+def load_controlnet_img2img(cn_type: str):
+    """Load ControlNet + Img2Img hybrid pipeline"""
+    global CN_IMG2IMG_AVAILABLE
+    if not HAS_CONTROLNET:
+        return None
+    try:
+        cn_id = "lllyasviel/sd-controlnet-canny" if cn_type == "Canny" else "lllyasviel/sd-controlnet-depth"
+        controlnet = ControlNetModel.from_pretrained(
+            cn_id, torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32
+        )
+        pipe = StableDiffusionControlNetImg2ImgPipeline.from_pretrained(
+            "runwayml/stable-diffusion-v1-5",
+            controlnet=controlnet,
+            safety_checker=None,
+            torch_dtype=torch.float16 if DEVICE == "cuda" else torch.float32,
+        ).to(DEVICE)
+        try:
+            pipe.enable_xformers_memory_efficient_attention()
+        except Exception:
+            pass
+        pipe.enable_attention_slicing()
+        return pipe
+    except Exception:
+        CN_IMG2IMG_AVAILABLE = False
+        return None
+
+# ==================== STREAMLIT LAYOUT ====================
+
+st.set_page_config(page_title="CompI — Phase 3 Final Dashboard", layout="wide")
+st.title("🧪 CompI — Final Integrated Dashboard (3.A → 3.E)")
+
+# ---- Minimal, clean UI styling ----
+
+def inject_minimal_css():
+    st.markdown(
+        """
+        <style>
+            .block-container {padding-top: 1.2rem; padding-bottom: 2rem; max-width: 1200px;}
+            .stTabs [role="tablist"] {gap: 6px;}
+            .stTabs [role="tab"] {padding: 6px 10px; border-radius: 8px; background: rgba(255,255,255,0.02); border: 1px solid rgba(255,255,255,0.08);}
+            .stTabs [aria-selected="true"] {background: rgba(255,255,255,0.04); border-color: rgba(255,255,255,0.16);}
+            h1, h2, h3 {margin-bottom: .3rem;}
+            .section {padding: 14px 16px; border: 1px solid rgba(255,255,255,0.08); border-radius: 12px; background: rgba(255,255,255,0.02); margin-bottom: 14px;}
+            .muted {color: rgba(255,255,255,0.6); text-transform: uppercase; letter-spacing: .08em; font-size: .75rem; margin-bottom: .25rem;}
+            .stButton>button {border-radius: 10px; height: 44px;}
+            .stButton>button[kind="primary"] {background: #2563eb; border-color: #2563eb;}
+            .stTextInput input, .stTextArea textarea {border-radius: 10px;}
+            .stMultiSelect [data-baseweb="tag"] {border-radius: 8px;}
+            pre, code {border-radius: 10px;}
+            #MainMenu, footer {visibility: hidden;}
+        </style>
+        """,
+        unsafe_allow_html=True,
+    )
+
+# Apply minimal styling early
+inject_minimal_css()
+
+# Top metrics (Phase 3.E VRAM monitoring)
+colA, colB, colC, colD = st.columns(4)
+with colA:
+    st.metric("Device", DEVICE)
+with colB:
+    st.metric("VRAM (GB)", f"{vram_gb():.2f}" if vram_gb() else "N/A")
+with colC:
+    st.metric("Used VRAM (GB)", f"{vram_used_gb():.2f}" if vram_used_gb() else "N/A")
+with colD:
+    st.caption(f"PyTorch {torch.__version__} • diffusers ready")
+
+# Handle deferred clear request BEFORE creating any widgets
+if st.session_state.get("clear_inputs", False):
+    # Pop ALL relevant input/widget keys so widgets re-initialize to defaults
+    keys_to_clear = [
+        # Text inputs
+        "main_prompt_input", "style_input", "mood_input", "neg_prompt_input", "style_ms", "mood_ms",
+        # Optional text areas
+        "emo_free_textarea", "ref_urls_textarea",
+        # Uploaders & inputs
+        "audio_file_uploader", "data_file_uploader", "formula_input", "ref_images_uploader",
+        # Toggles / checkboxes / selects / sliders (with explicit keys)
+        "enable_emo_checkbox", "enable_rt_checkbox", "enable_ref_checkbox",
+        "model_choice_selectbox", "gen_mode_selectbox",
+        "use_lora_checkbox", "lora_path_input", "lora_scale_slider",
+        "width_input", "height_input", "steps_input", "guidance_input",
+        "batch_input", "seed_input", "upsample_checkbox",
+        "use_xformers_checkbox", "attn_slice_checkbox", "vae_slice_checkbox", "vae_tile_checkbox",
+        "oom_retry_checkbox",
+        # Real-time extras
+        "city_input", "headlines_slider",
+    ]
+    for k in keys_to_clear:
+        st.session_state.pop(k, None)
+
+    # Clear outputs/state
+    st.session_state["generated_images"] = []
+    st.session_state["generation_results"] = []
+
+    # Unset the flag and rerun
+    st.session_state["clear_inputs"] = False
+
+
+# Main tabs - Complete Phase 3 integration
+# Moved generation below Inputs per UX request; removed separate Generate tab
+tab_inputs, tab_refs, tab_model, tab_gallery, tab_presets, tab_export = st.tabs([
+    "🧩 Inputs (Text/Audio/Data/Emotion/Real‑time)",
+    "🖼️ Advanced References",
+    "⚙️ Model & Performance",
+    "🖼️ Gallery & Annotate",
+    "💾 Presets",
+    "📦 Export"
+])
+
+# ==================== INPUTS TAB (Phase 3.A/3.B) ====================
+
+with tab_inputs:
+    st.markdown("<div class='section'>", unsafe_allow_html=True)
+    st.subheader("🧩 Multimodal Inputs")
+
+    # Text & Style (always enabled)
+    st.markdown("<div class='muted'>Text & Style</div>", unsafe_allow_html=True)
+    main_prompt = st.text_input(
+        "Main prompt",
+        value=st.session_state.get("main_prompt_input", ""),
+        placeholder="A serene cyberpunk alley at dawn",
+        key="main_prompt_input",
+    )
+
+    # Style and Mood as multi-select dropdowns
+    STYLE_OPTIONS = [
+        "digital painting", "watercolor", "oil painting", "pixel art", "anime",
+        "3D render", "photorealistic", "line art", "low poly", "cyberpunk",
+        "isometric", "concept art", "cel shading", "comic book", "impressionist"
+    ]
+    MOOD_OPTIONS = [
+        "dreamy", "luminous", "dark and moody", "whimsical", "serene",
+        "epic", "melancholic", "vibrant", "mysterious", "dystopian",
+        "hopeful", "playful", "contemplative", "energetic", "ethereal"
+    ]
+
+    style_selected = st.multiselect(
+        "Style (choose one or more)",
+        options=STYLE_OPTIONS,
+        default=st.session_state.get("style_ms", []),
+        key="style_ms",
+        help="Pick one or more styles to condition the artwork"
+    )
+    mood_selected = st.multiselect(
+        "Mood (choose one or more)",
+        options=MOOD_OPTIONS,
+        default=st.session_state.get("mood_ms", []),
+        key="mood_ms",
+        help="Pick one or more moods to influence the atmosphere"
+    )
+
+    # Join lists into strings for downstream prompt fusion
+    style = ", ".join(style_selected)
+    mood = ", ".join(mood_selected)
+
+    neg_prompt = st.text_input(
+        "Negative prompt (optional)",
+        value=st.session_state.get("neg_prompt_input", ""),
+        placeholder="e.g., low quality, bad anatomy",
+        key="neg_prompt_input",
+    )
+
+    st.markdown("</div>", unsafe_allow_html=True)
+
+    # Four columns for aligned sections
+    col1, col2, col3, col4 = st.columns(4)
+
+    # AUDIO PROCESSING (Phase 2.A)
+    with col1:
+        st.markdown("### 🎵 Audio Analysis")
+        enable_audio = st.checkbox("Enable Audio Processing", value=False)
+        audio_caption = ""
+        audio_tags = []
+        tempo = None
+
+        if enable_audio:
+            audio_file = st.file_uploader("Upload audio (.wav/.mp3)", type=["wav", "mp3"], key="audio_file_uploader")
+            if audio_file:
+                # Save temporary audio file
+                audio_path = OUTPUT_DIR / "tmp_audio.wav"
+                with open(audio_path, "wb") as f:
+                    f.write(audio_file.read())
+
+                # Load and analyze audio
+                y, sr = librosa.load(audio_path.as_posix(), sr=16000)
+                dur = librosa.get_duration(y=y, sr=sr)
+                st.caption(f"Duration: {dur:.1f}s")
+
+                # Extract tempo
+                try:
+                    tempo, _ = librosa.beat.beat_track(y=y, sr=sr)
+                except Exception:
+                    tempo = None
+
+                # Extract audio features
+                rms = float(np.sqrt(np.mean(y**2)))
+                zcr = float(np.mean(librosa.feature.zero_crossing_rate(y)))
+
+                # Generate audio tags based on features
+                if tempo:
+                    if tempo < 90:
+                        audio_tags.append("slow tempo")
+                    elif tempo > 140:
+                        audio_tags.append("fast tempo")
+
+                if rms > 0.04:
+                    audio_tags.append("energetic")
+                if zcr > 0.12:
+                    audio_tags.append("percussive")
+
+                # Whisper transcription
+                st.info("Transcribing audio (Whisper base)…")
+                w = whisper.load_model("base", device=DEVICE)
+                wav = whisper.load_audio(audio_path.as_posix())
+                wav = whisper.pad_or_trim(wav)
+                mel = whisper.log_mel_spectrogram(wav).to(DEVICE)
+                dec = whisper.DecodingOptions(language="en", fp16=(DEVICE=="cuda"))
+                res = whisper.decode(w, mel, dec)
+                audio_caption = res.text.strip()
+
+                st.success(f"Caption: '{audio_caption}'")
+                if audio_tags:
+                    st.write("Audio tags:", ", ".join(audio_tags))
+
+    # DATA PROCESSING (Phase 2.B)
+    with col2:
+        st.markdown("### 📊 Data Analysis")
+        enable_data = st.checkbox("Enable Data Processing", value=False)
+        data_summary = ""
+        data_plot = None
+
+        if enable_data:
+            data_file = st.file_uploader("Upload CSV", type=["csv"], key="data_file_uploader")
+            formula = st.text_input("Or numpy formula", placeholder="np.sin(np.linspace(0, 20, 200))", key="formula_input")
+
+            if data_file is not None:
+                df = pd.read_csv(data_file)
+                st.dataframe(df.head(), use_container_width=True)
+
+                # Analyze numeric columns
+                num = df.select_dtypes(include=np.number)
+                if not num.empty:
+                    means, mins, maxs, stds = num.mean(), num.min(), num.max(), num.std()
+                    data_summary = f"{len(num)} rows x {num.shape[1]} cols; " + " ".join([
+                        f"{c}: avg {means[c]:.2f}, min {mins[c]:.2f}, max {maxs[c]:.2f}."
+                        for c in num.columns[:3]
+                    ])
+                    data_summary += " Variability " + ("high." if stds.mean() > 1 else "gentle.")
+
+                    # Create visualization
+                    fig = plt.figure(figsize=(6, 3))
+                    if num.shape[1] == 1:
+                        plt.plot(num.iloc[:, 0])
+                        plt.title(f"Pattern: {num.columns[0]}")
+                    else:
+                        plt.plot(num.iloc[:, 0], label=num.columns[0])
+                        plt.plot(num.iloc[:, 1], label=num.columns[1])
+                        plt.legend()
+                        plt.title("Data Patterns")
+                    plt.tight_layout()
+                    data_plot = save_plot(fig)
+                    st.image(data_plot, caption="Data pattern")
+
+            elif formula.strip():
+                try:
+                    arr = eval(formula, {"np": np, "__builtins__": {}})
+                    arr = np.array(arr)
+                    data_summary = f"Mathematical pattern with {arr.size} points."
+
+                    fig = plt.figure(figsize=(6, 3))
+                    plt.plot(arr)
+                    plt.title("Formula Pattern")
+                    plt.tight_layout()
+                    data_plot = save_plot(fig)
+                    st.image(data_plot, caption="Formula pattern")
+                except Exception as e:
+                    st.error(f"Formula error: {e}")
+
+    # EMOTION (Phase 2.C)
+    with col3:
+        st.markdown("### 💭 Emotion Analysis")
+        enable_emo = st.checkbox("Enable Emotion Processing", value=False, key="enable_emo_checkbox")
+        emo_free = st.text_area(
+            "Describe a feeling/context",
+            value=st.session_state.get("emo_free_textarea", ""),
+            key="emo_free_textarea",
+        ) if enable_emo else ""
+        emo_label = ""
+
+        if enable_emo and emo_free.strip():
+            tb = TextBlob(emo_free)
+            pol = tb.sentiment.polarity
+            emo_label = "positive, uplifting" if pol > 0.3 else (
+                "sad, melancholic" if pol < -0.3 else "neutral, contemplative"
+            )
+            st.info(f"Sentiment: {emo_label} (polarity {pol:.2f})")
+
+    # REAL-TIME (Phase 2.D)
+    with col4:
+        st.markdown("### 🌎 Real-time Data")
+        enable_rt = st.checkbox("Enable Real-time Feeds", value=False, key="enable_rt_checkbox")
+        rt_context = ""
+
+        if enable_rt:
+            city = st.text_input("City (weather)", "Toronto", key="city_input")
+            headlines_num = st.slider("Headlines", 1, 5, 3, key="headlines_slider")
+
+            def get_weather(city):
+                try:
+                    key = st.secrets.get("OPENWEATHER_KEY", None) if hasattr(st, "secrets") else None
+                    url = "https://api.openweathermap.org/data/2.5/weather"
+                    params = {
+                        "q": city,
+                        "units": "metric",
+                        "appid": key or "9a524f695a4940f392150142250107"
+                    }
+                    r = requests.get(url, params=params, timeout=6).json()
+                    return f"{r['weather'][0]['description']}, {r['main']['temp']:.1f}°C"
+                except Exception as e:
+                    return f"unavailable ({e})"
+
+            def get_news(n):
+                try:
+                    feed = feedparser.parse("https://feeds.bbci.co.uk/news/rss.xml")
+                    return "; ".join([e["title"] for e in feed.entries[:n]])
+                except Exception as e:
+                    return f"unavailable ({e})"
+
+            w = get_weather(city)
+            n = get_news(headlines_num)
+            st.caption(f"Weather: {w}")
+            st.caption(f"News: {n}")
+            rt_context = f"Current weather in {city}: {w}. Today's news: {n}."
+
+# ==================== ADVANCED REFERENCES TAB (Phase 3.C) ====================
+
+with tab_refs:
+    st.subheader("🖼️ Advanced Multi‑Reference + ControlNet")
+    enable_ref = st.checkbox("Enable Multi-Reference Processing", value=False, key="enable_ref_checkbox")
+    ref_images: List[Image.Image] = []
+    style_idxs = []
+    cn_images = []
+    img2img_strength = 0.55
+    cn_type = "Canny"
+    cn_scale = 1.0
+
+    if enable_ref:
+        # Multi-reference upload (files + URLs)
+        colU, colURL = st.columns(2)
+
+        with colU:
+            st.markdown("**���� Upload Images**")
+            uploads = st.file_uploader(
+                "Upload reference images",
+                type=["png", "jpg", "jpeg"],
+                accept_multiple_files=True,
+                key="ref_images_uploader"
+            )
+            if uploads:
+                for u in uploads:
+                    try:
+                        im = Image.open(u).convert("RGB")
+                        ref_images.append(im)
+                    except Exception as e:
+                        st.warning(f"Upload failed: {e}")
+
+        with colURL:
+            st.markdown("**🔗 Image URLs**")
+            block = st.text_area(
+                "Paste image URLs (one per line)",
+                value=st.session_state.get("ref_urls_textarea", ""),
+                key="ref_urls_textarea",
+            )
+            if block.strip():
+                for line in block.splitlines():
+                    url = line.strip()
+                    if not url:
+                        continue
+                    try:
+                        r = requests.get(url, timeout=8)
+                        if r.status_code == 200:
+                            im = Image.open(io.BytesIO(r.content)).convert("RGB")
+                            ref_images.append(im)
+                    except Exception as e:
+                        st.warning(f"URL failed: {e}")
+
+        if ref_images:
+            # Display reference images
+            st.image(
+                ref_images,
+                width=180,
+                caption=[f"Ref {i+1}" for i in range(len(ref_images))]
+            )
+
+            # Role-based assignment (Phase 3.C key feature)
+            st.markdown("### 🎨 Reference Role Assignment")
+            style_idxs = st.multiselect(
+                "Use as **Style References (img2img)**",
+                list(range(1, len(ref_images)+1)),
+                default=list(range(1, len(ref_images)+1)),
+                help="These images will influence the artistic style and mood"
+            )
+
+            # ControlNet structure conditioning
+            use_cn = st.checkbox("Use **ControlNet** for structure", value=HAS_CONTROLNET)
+            if use_cn and not HAS_CONTROLNET:
+                st.warning("ControlNet not available in this environment.")
+                use_cn = False
+
+            if use_cn:
+                cn_type = st.selectbox("ControlNet type", ["Canny", "Depth"], index=0)
+                pick = st.selectbox(
+                    "Pick **one** structural reference",
+                    list(range(1, len(ref_images)+1)),
+                    index=0,
+                    help="This image will control the composition and structure"
+                )
+
+                # Live ControlNet preview (Phase 3.C key feature)
+                base = ref_images[int(pick)-1].resize((512, 512))
+                cn_map = canny_map(base) if cn_type == "Canny" else depth_proxy(base)
+
+                st.markdown("**🔍 Live ControlNet Preview**")
+                st.image(
+                    [base, cn_map],
+                    width=240,
+                    caption=["Selected Reference", f"{cn_type} Map"]
+                )
+                cn_images = [cn_map]
+                cn_scale = st.slider("ControlNet conditioning scale", 0.1, 2.0, 1.0, 0.05)
+
+            # Style strength control
+            img2img_strength = st.slider(
+                "img2img strength (style adherence)",
+                0.2, 0.85, 0.55, 0.05,
+                help="Higher values follow style references more closely"
+            )
+
+# ==================== MODEL & PERFORMANCE TAB (Phase 3.E) ====================
+
+with tab_model:
+    st.subheader("⚙️ Model & Performance Management")
+    st.caption("Choose a base model, optional style add‑ons (LoRA), and tune speed/quality settings.")
+
+    # Presets and Glossary helpers
+    @st.dialog("Glossary: Common terms")
+    def show_glossary():
+        st.markdown(
+            """
+            - Base model: The foundation that generates images (SD 1.5 = fast, SDXL = higher detail).
+            - Generation mode:
+              - txt2img: Create from your text prompt only.
+              - img2img: Start from an input image and transform it using your text.
+            - LoRA: A small add‑on that injects a trained style or subject. Use a .safetensors/.pt file.
+            - Width/Height: Image size in pixels. Bigger = more detail but slower and more VRAM.
+            - Steps: How long the model refines the image. More steps usually means cleaner details.
+            - Guidance: How strongly to follow your text. 6–9 is a good range; too high can look unnatural.
+            - Batch size: How many images at once. Higher uses more VRAM.
+            - Seed: Randomness control. Reuse the same non‑zero seed to reproduce a result.
+            - Upscale ×2: Quickly doubles resolution after generation.
+            - xFormers attention: GPU speed‑up if supported.
+            - Attention/VAE slicing: Reduce VRAM usage (slightly slower). Keep on for stability.
+            - VAE tiling: For very large images; decodes in tiles.
+            - Auto‑retry on CUDA OOM: If VRAM runs out, try again with safer settings.
+            """
+        )
+        st.button("Close", use_container_width=True)
+
+    def apply_preset(name: str):
+        ss = st.session_state
+        def s(k, v):
+            ss[k] = v
+        if name == "fast":
+            s("model_choice_selectbox", "SD 1.5 (v1-5)")
+            s("gen_mode_selectbox", "txt2img")
+            s("width_input", 512); s("height_input", 512)
+            s("steps_input", 30); s("guidance_input", 7.5)
+            s("batch_input", 1); s("seed_input", 0)
+            s("upsample_checkbox", False)
+            s("use_xformers_checkbox", True); s("attn_slice_checkbox", True)
+            s("vae_slice_checkbox", True); s("vae_tile_checkbox", False)
+            s("oom_retry_checkbox", True)
+        elif name == "high":
+            model = "SDXL Base 1.0" if HAS_SDXL else "SD 1.5 (v1-5)"
+            s("model_choice_selectbox", model)
+            s("gen_mode_selectbox", "txt2img")
+            s("width_input", 768); s("height_input", 768)
+            s("steps_input", 40); s("guidance_input", 7.0)
+            s("batch_input", 1); s("seed_input", 0)
+            s("upsample_checkbox", True)
+
+
+            s("use_xformers_checkbox", True); s("attn_slice_checkbox", True)
+            s("vae_slice_checkbox", True); s("vae_tile_checkbox", False)
+            s("oom_retry_checkbox", True)
+        elif name == "low_vram":
+            s("model_choice_selectbox", "SD 1.5 (v1-5)")
+            s("gen_mode_selectbox", "txt2img")
+            s("width_input", 448); s("height_input", 448)
+            s("steps_input", 25); s("guidance_input", 7.5)
+            s("batch_input", 1); s("seed_input", 0)
+            s("upsample_checkbox", False)
+            s("use_xformers_checkbox", True); s("attn_slice_checkbox", True)
+            s("vae_slice_checkbox", True); s("vae_tile_checkbox", False)
+            s("oom_retry_checkbox", True)
+        elif name == "portrait":
+            s("gen_mode_selectbox", "txt2img")
+            s("width_input", 512); s("height_input", 768)
+            s("steps_input", 30); s("guidance_input", 7.5)
+            s("batch_input", 1)
+        elif name == "landscape":
+            s("gen_mode_selectbox", "txt2img")
+            s("width_input", 768); s("height_input", 512)
+            s("steps_input", 30); s("guidance_input", 7.5)
+            s("batch_input", 1)
+        elif name == "instagram":
+            s("gen_mode_selectbox", "txt2img")
+            s("width_input", 1024); s("height_input", 1024)
+            s("steps_input", 35); s("guidance_input", 7.0)
+            s("batch_input", 1); s("upsample_checkbox", False)
+        elif name == "defaults":
+            s("model_choice_selectbox", "SD 1.5 (v1-5)")
+            s("gen_mode_selectbox", "txt2img")
+            s("width_input", 512); s("height_input", 512)
+            s("steps_input", 30); s("guidance_input", 7.5)
+            s("batch_input", 1); s("seed_input", 0)
+            s("upsample_checkbox", False)
+            s("use_xformers_checkbox", True); s("attn_slice_checkbox", True)
+            s("vae_slice_checkbox", True); s("vae_tile_checkbox", False)
+            s("oom_retry_checkbox", True)
+        st.rerun()
+
+    colA, colB, colC, colD = st.columns(4)
+    with colA:
+        if st.button("⚡ Fast Start"):
+            apply_preset("fast")
+    with colB:
+        if st.button("🔍 High Detail"):
+            apply_preset("high")
+    with colC:
+        if st.button("💻 Low VRAM"):
+            apply_preset("low_vram")
+    with colD:
+        if st.button("❓ Glossary"):
+            show_glossary()
+
+    # Simple VRAM safety indicator (placed after preset buttons for visibility)
+    def estimate_pixels(w, h):
+        return int(w) * int(h)
+    def vram_risk_level(w, h, steps, batch, model_name):
+        px = estimate_pixels(w, h)
+        multiplier = 1.0 if "1.5" in model_name else 2.0  # SDXL ~2x heavier
+        load = (px / (512*512)) * (steps / 30.0) * max(1, batch) * multiplier
+        if load < 1.2:
+            return "✅ Likely safe"
+        elif load < 2.2:
+            return "⚠️ May be heavy — consider smaller size or steps"
+        else:
+            return "🟥 High risk of OOM — reduce size/batch/steps"
+
+    risk_msg = vram_risk_level(
+        st.session_state.get("width_input", 512),
+        st.session_state.get("height_input", 512),
+        st.session_state.get("steps_input", 30),
+        st.session_state.get("batch_input", 1),
+        st.session_state.get("model_choice_selectbox", "SD 1.5 (v1-5)")
+    )
+    st.info(f"VRAM safety: {risk_msg}")
+
+
+
+    # Additional simple layout for more presets and reset
+    colP0, colP1a, colP2a, colP3a, colP4a = st.columns(5)
+    with colP0:
+        if st.button("🧼 Reset to defaults"):
+            apply_preset("defaults")
+    with colP1a:
+        if st.button("🧍 Portrait"):
+            apply_preset("portrait")
+    with colP2a:
+        if st.button("🏞️ Landscape"):
+            apply_preset("landscape")
+    with colP3a:
+        if st.button("📸 Instagram Post"):
+            apply_preset("instagram")
+    with colP4a:
+        st.write("")
+
+    # Model selection
+    st.markdown("### 🤖 Model Selection")
+    model_choice = st.selectbox(
+        "Base model",
+        ["SD 1.5 (v1-5)"] + (["SDXL Base 1.0"] if HAS_SDXL else []),
+        index=0,
+        help="Choose SD 1.5 for speed/low VRAM. Choose SDXL for higher detail (needs more VRAM/CPU).",
+        key="model_choice_selectbox"
+    )
+    gen_mode = st.selectbox(
+        "Generation mode",
+        ["txt2img", "img2img"],
+        index=0,
+        help="txt2img: make an image from your text. img2img: start from a reference image and transform it.",
+        key="gen_mode_selectbox"
+    )
+
+    # LoRA integration
+    st.markdown("### 🎭 LoRA Integration")
+    use_lora = st.checkbox("Attach LoRA", value=False, help="LoRA = small add-on that injects a learned style or subject into the base model.", key="use_lora_checkbox")
+    lora_path = st.text_input("LoRA path", "", help="Path to the .safetensors/.pt LoRA file.", key="lora_path_input") if use_lora else ""
+    lora_scale = st.slider("LoRA scale", 0.1, 1.5, 0.8, 0.05, help="How strongly to apply the LoRA. Start at 0.7–0.9.", key="lora_scale_slider") if use_lora else 0.0
+
+    # Generation parameters
+    st.markdown("### 🎛️ Generation Parameters")
+    colP1, colP2, colP3, colP4 = st.columns(4)
+    with colP1:
+        width = st.number_input("Width", 256, 1536, 512, 64, help="Image width in pixels. Larger = more detail but slower and more VRAM.", key="width_input")
+    with colP2:
+        height = st.number_input("Height", 256, 1536, 512, 64, help="Image height in pixels. Common pairs: 512x512 (square), 768x512 (wide).", key="height_input")
+    with colP3:
+        steps = st.number_input("Steps", 10, 100, 30, 1, help="How long to refine the image. More steps = better quality but slower.", key="steps_input")
+    with colP4:
+        guidance = st.number_input("Guidance", 1.0, 20.0, 7.5, 0.5, help="How strongly to follow your text prompt. 6–9 is a good range.", key="guidance_input")
+
+    colP5, colP6, colP7 = st.columns(3)
+    with colP5:
+        batch = st.number_input("Batch size", 1, 6, 1, 1, help="How many images to generate at once. Higher uses more VRAM.", key="batch_input")
+    with colP6:
+        seed = st.number_input("Seed (0=random)", 0, 2**31-1, 0, 1, help="Use the same seed to reproduce a result. 0 picks a random seed.", key="seed_input")
+    with colP7:
+        upsample_x2 = st.checkbox("Upscale ×2 (latent upscaler)", value=False, help="Quickly doubles the resolution after generation.", key="upsample_checkbox")
+
+    # Performance optimizations
+    st.markdown("### ⚡ Performance & Reliability")
+    st.caption("These options help run on limited VRAM and reduce crashes. If you are new, keep the defaults on.")
+    colT1, colT2, colT3, colT4 = st.columns(4)
+    with colT1:
+        use_xformers = st.checkbox("xFormers attention", value=True, help="Speeds up attention on GPUs that support it.", key="use_xformers_checkbox")
+    with colT2:
+        attn_slice = st.checkbox("Attention slicing", value=True, help="Reduces VRAM usage, slightly slower.", key="attn_slice_checkbox")
+    with colT3:
+        vae_slice = st.checkbox("VAE slicing", value=True, help="Lower VRAM for the decoder, usually safe to keep on.", key="vae_slice_checkbox")
+    with colT4:
+        vae_tile = st.checkbox("VAE tiling", value=False, help="For very large images. Uses tiles to decode.", key="vae_tile_checkbox")
+
+    oom_retry = st.checkbox("Auto‑retry on CUDA OOM", value=True, help="If out‑of‑memory happens, try again with safer settings.", key="oom_retry_checkbox")
+
+    with st.expander("New to this? Quick tips"):
+        st.markdown(
+            "- For fast, reliable results: SD 1.5, 512×512, Steps 25–35, Guidance 7.5, Batch 1.\n"
+            "- Higher detail: try SDXL (needs more VRAM), Steps 30–50, bigger size like 768×768.\n"
+            "- Seed: 0 = random. Reuse a non‑zero seed to recreate a result.\n"
+            "- Out‑of‑memory? Lower width/height, set Batch = 1, keep slicing options on.\n"
+            "- LoRA: paste path to a .safetensors/.pt file. Start scale at 0.7–0.9.\n"
+            "- Modes: txt2img = from text; img2img = transform an existing image.\n"
+            "- Upscale ×2: quickly increases resolution after generation."
+        )
+
+
+# ==================== GENERATION SECTION BELOW INPUTS (Phase 3.B + 3.C + 3.E) ====================
+
+with tab_inputs:
+    st.markdown("<div class='section'>", unsafe_allow_html=True)
+    st.subheader("🎛️ Fusion & Generation")
+
+    # Build final prompt from real processed inputs (Phase 3.B True Fusion)
+    parts = [p for p in [main_prompt, style, mood] if p and p.strip()]
+
+    # Audio fusion - REAL processing
+    if 'audio_caption' in locals() and enable_audio and audio_caption:
+        parts.append(f"(sound of: {audio_caption})")
+    if 'tempo' in locals() and enable_audio and tempo:
+        tempo_desc = "slow tempo" if tempo < 90 else ("fast tempo" if tempo > 140 else "")
+        if tempo_desc:
+            parts.append(tempo_desc)
+    if 'audio_tags' in locals() and enable_audio and audio_tags:
+        parts.extend(audio_tags)
+
+    # Data fusion - REAL processing
+    if 'data_summary' in locals() and enable_data and data_summary:
+        parts.append(f"reflecting data patterns: {data_summary}")
+
+    # Emotion fusion - REAL processing
+    if 'emo_label' in locals() and enable_emo and emo_label:
+        parts.append(f"with a {emo_label} atmosphere")
+    elif enable_emo and emo_free.strip():
+        parts.append(f"evoking the feeling: {emo_free.strip()}")
+
+    # Real-time fusion - REAL processing
+    if 'rt_context' in locals() and enable_rt and rt_context:
+        parts.append(rt_context)
+
+    # Build final fused prompt
+    final_prompt = ", ".join([p for p in parts if p])
+    st.markdown("</div>", unsafe_allow_html=True)
+
+    st.markdown("### 🔮 Fused Prompt Preview")
+    st.code(final_prompt, language="text")
+
+    # Initialize image for img2img
+    init_image = None
+    if gen_mode == "img2img" and enable_ref and style_idxs:
+        # Use first chosen style reference as init image
+        init_image = ref_images[style_idxs[0]-1].resize((int(width), int(height)))
+
+    # Generation + Clear buttons side-by-side
+    col_gen, col_clear = st.columns([3, 1])
+    with col_gen:
+        go = st.button("🚀 Generate Multimodal Art", type="primary", use_container_width=True)
+    with col_clear:
+        clear = st.button("🧹 Clear", use_container_width=True)
+
+    # Clear logic: reset prompt fields and any generated output state
+    if 'generated_images' not in st.session_state:
+        st.session_state.generated_images = []
+    if 'generation_results' not in st.session_state:
+        st.session_state.generation_results = []
+
+    if clear:
+        # Defer clearing input widgets by setting a flag, then rerun
+        st.session_state["clear_inputs"] = True
+        st.success("Cleared current prompt and output. Ready for a new prompt.")
+        st.rerun()
+
+    # Cached pipeline getters
+    @st.cache_resource(show_spinner=True)
+    def get_txt2img():
+        return load_sd15(txt2img=True)
+
+    @st.cache_resource(show_spinner=True)
+    def get_img2img():
+        return load_sd15(txt2img=False)
+
+    @st.cache_resource(show_spinner=True)
+    def get_sdxl():
+        return load_sdxl()
+
+    @st.cache_resource(show_spinner=True)
+    def get_upscaler():
+        return load_upscaler()
+
+    @st.cache_resource(show_spinner=True)
+    def get_cn(cn_type: str):
+        return load_controlnet(cn_type)
+
+    @st.cache_resource(show_spinner=True)
+    def get_cn_i2i(cn_type: str):
+        return load_controlnet_img2img(cn_type)
+
+    def apply_lora(pipe, lora_path, lora_scale):
+        """Apply LoRA to pipeline"""
+        if not lora_path:
+            return "No LoRA"
+        try:
+            pipe.load_lora_weights(lora_path)
+            try:
+                pipe.fuse_lora(lora_scale=lora_scale)
+            except Exception:
+                try:
+                    pipe.set_adapters(["default"], adapter_weights=[lora_scale])
+                except Exception:
+                    pass
+            return f"LoRA loaded: {os.path.basename(lora_path)} (scale {lora_scale})"
+        except Exception as e:
+            return f"LoRA failed: {e}"
+
+    def upsample_if_any(img: Image.Image):
+        """Apply upscaling if enabled"""
+        if not upsample_x2 or not HAS_UPSCALER:
+            return img, False, "none"
+        try:
+            up = get_upscaler()
+            with (torch.autocast(DEVICE) if DEVICE == "cuda" else torch.no_grad()):
+                out = up(prompt="sharp, detailed, high quality", image=img)
+            return out.images[0], True, "latent_x2"
+        except Exception as e:
+            return img, False, f"fail:{e}"
+
+    def log_rows(rows, log_path):
+        """Log generation results"""
+        exists = Path(log_path).exists()
+        # Union header across Phase 3 logs
+        header = [
+            "filepath", "prompt", "neg_prompt", "steps", "guidance", "mode", "seed",
+            "width", "height", "model", "img2img_strength", "cn_type", "cn_scale",
+            "upscaled", "timestamp"
+        ]
+        with open(log_path, "a", newline="", encoding="utf-8") as f:
+            w = csv.writer(f)
+            if not exists:
+                w.writerow(header)
+            for r in rows:
+                w.writerow([r.get(k, "") for k in header])
+
+    # GENERATION EXECUTION
+    if go:
+        images, paths = [], []
+
+        # Choose pipeline based on model selection
+        if model_choice.startswith("SDXL") and HAS_SDXL and gen_mode == "txt2img":
+            pipe = get_sdxl()
+            model_id = "SDXL-Base-1.0"
+        else:
+            if gen_mode == "txt2img":
+                pipe = get_txt2img()
+                model_id = "SD-1.5"
+            else:
+                pipe = get_img2img()
+                model_id = "SD-1.5 (img2img)"
+
+        # Apply performance optimizations
+        xformed = attempt_enable_xformers(pipe) if use_xformers else False
+        apply_perf(pipe, attn_slice, vae_slice, vae_tile)
+
+        # Apply LoRA if specified
+        lora_msg = ""
+        if use_lora:
+            lora_msg = apply_lora(pipe, lora_path, lora_scale)
+        if lora_msg:
+            st.caption(lora_msg)
+
+        # Determine generation mode based on available inputs (Phase 3.C intelligence)
+        have_style = bool(style_idxs)
+        have_cn = enable_ref and bool(cn_images)
+
+        # MODE PRIORITY: CN+I2I > CN only > I2I only > T2I
+        mode = "T2I"
+        if have_cn and have_style and HAS_CONTROLNET:
+            mode = "CN+I2I"
+        elif have_cn and HAS_CONTROLNET:
+            mode = "CN"
+        elif have_style:
+            mode = "I2I"
+
+        st.info(f"Mode: **{mode}** • Model: **{model_id}** • xFormers: `{xformed}`")
+
+        rows = []
+        attempt_list = list(safe_retry_sizes(height, width, steps)) if oom_retry else [(height, width, steps)]
+
+        # Generate batch
+        for b in range(int(batch)):
+            ok = False
+            last_err = None
+
+            for (h_try, w_try, s_try) in attempt_list:
+                try:
+                    # Seed management
+                    seed_eff = torch.seed() if seed == 0 else seed + b
+                    gen = torch.manual_seed(seed_eff) if DEVICE == "cpu" else torch.Generator(DEVICE).manual_seed(seed_eff)
+
+                    with (torch.autocast(DEVICE) if DEVICE == "cuda" else torch.no_grad()):
+                        if mode == "CN+I2I":
+                            # Hybrid ControlNet + Img2Img (Phase 3.C advanced mode)
+                            if CN_IMG2IMG_AVAILABLE:
+                                cn_pipe = get_cn_i2i(cn_type)
+                                init_ref = ref_images[style_idxs[min(b, len(style_idxs)-1)]-1].resize((w_try, h_try))
+                                out = cn_pipe(
+                                    prompt=final_prompt,
+                                    image=init_ref,
+                                    control_image=[im for im in cn_images],
+                                    controlnet_conditioning_scale=cn_scale,
+                                    strength=img2img_strength,
+                                    num_inference_steps=s_try,
+                                    guidance_scale=guidance,
+                                    negative_prompt=neg_prompt if neg_prompt.strip() else None,
+                                    generator=gen,
+                                )
+                                img = out.images[0]
+                            else:
+                                # Fallback two-pass approach
+                                cn_pipe = get_cn(cn_type)
+                                cn_out = cn_pipe(
+                                    prompt=final_prompt,
+                                    image=[im for im in cn_images],
+                                    controlnet_conditioning_scale=cn_scale,
+                                    num_inference_steps=max(s_try//2, 12),
+                                    guidance_scale=guidance,
+                                    negative_prompt=neg_prompt if neg_prompt.strip() else None,
+                                    generator=gen,
+                                )
+                                struct_img = cn_out.images[0].resize((w_try, h_try))
+                                i2i = get_img2img()
+                                init_ref = ref_images[style_idxs[min(b, len(style_idxs)-1)]-1].resize((w_try, h_try))
+                                blend = Image.blend(init_ref, struct_img, 0.5)
+                                out = i2i(
+                                    prompt=final_prompt,
+                                    image=blend,
+                                    strength=img2img_strength,
+                                    num_inference_steps=s_try,
+                                    guidance_scale=guidance,
+                                    negative_prompt=neg_prompt if neg_prompt.strip() else None,
+                                    generator=gen,
+                                )
+                                img = out.images[0]
+
+                        elif mode == "CN":
+                            # ControlNet only
+                            cn_pipe = get_cn(cn_type)
+                            out = cn_pipe(
+                                prompt=final_prompt,
+                                image=[im for im in cn_images],
+                                controlnet_conditioning_scale=cn_scale,
+                                num_inference_steps=s_try,
+                                guidance_scale=guidance,
+                                negative_prompt=neg_prompt if neg_prompt.strip() else None,
+                                generator=gen,
+                            )
+                            img = out.images[0]
+
+                        elif mode == "I2I":
+                            # Img2Img only
+                            i2i = get_img2img()
+                            init_ref = ref_images[style_idxs[min(b, len(style_idxs)-1)]-1].resize((w_try, h_try))
+                            out = i2i(
+                                prompt=final_prompt,
+                                image=init_ref,
+                                strength=img2img_strength,
+                                num_inference_steps=s_try,
+                                guidance_scale=guidance,
+                                negative_prompt=neg_prompt if neg_prompt.strip() else None,
+                                generator=gen,
+                            )
+                            img = out.images[0]
+
+                        else:
+                            # Text-to-Image
+                            kwargs = dict(
+                                prompt=final_prompt,
+                                num_inference_steps=s_try,
+                                guidance_scale=guidance,
+                                negative_prompt=neg_prompt if neg_prompt.strip() else None,
+                                generator=gen,
+                            )
+                            if not (model_choice.startswith("SDXL") and HAS_SDXL):
+                                kwargs.update({"height": h_try, "width": w_try})
+                            out = pipe(**kwargs)
+                            img = out.images[0]
+
+                    # Optional upscaling
+                    upscaled = "none"
+                    if upsample_x2 and HAS_UPSCALER:
+                        img, did_upscale, upscaled = upsample_if_any(img)
+
+                    # Save image
+                    fname = f"{datetime.now().strftime('%Y%m%d_%H%M%S')}_{mode}_{w_try}x{h_try}_s{s_try}_g{guidance}_seed{seed_eff}.png"
+                    path = save_image(img, fname)
+                    st.image(img, caption=fname, use_container_width=True)
+                    paths.append(path)
+                    images.append(img)
+
+                    # Log generation
+                    rows.append({
+                        "filepath": path,
+                        "prompt": final_prompt,
+                        "neg_prompt": neg_prompt,
+                        "steps": s_try,
+                        "guidance": guidance,
+                        "mode": mode,
+                        "seed": seed_eff,
+                        "width": w_try,
+                        "height": h_try,
+                        "model": model_id,
+                        "img2img_strength": img2img_strength if mode in ["I2I", "CN+I2I"] else "",
+                        "cn_type": cn_type if mode in ["CN", "CN+I2I"] else "",
+                        "cn_scale": cn_scale if mode in ["CN", "CN+I2I"] else "",
+                        "upscaled": upscaled,
+                        "timestamp": datetime.now().isoformat()
+                    })
+                    ok = True
+                    break
+
+                except RuntimeError as e:
+                    if "out of memory" in str(e).lower() and oom_retry and DEVICE == "cuda":
+                        torch.cuda.empty_cache()
+                        st.warning(f"CUDA OOM — retrying at smaller size/steps…")
+                        continue
+                    else:
+                        st.error(f"Runtime error: {e}")
+                        last_err = str(e)
+                        break
+                except Exception as e:
+                    st.error(f"Error: {e}")
+                    last_err = str(e)
+                    break
+
+            if not ok and last_err:
+                st.error(f"Failed item {b+1}: {last_err}")
+
+        # Save results
+        if rows:
+            # Write unified run log (3.B/3.C/3.E compatible)
+            log_rows(rows, RUNLOG)
+            st.success(f"Saved {len(rows)} image(s). Run log updated: {RUNLOG}")
+
+# ==================== GALLERY & ANNOTATE TAB (Phase 3.D) ====================
+
+with tab_gallery:
+    st.subheader("🖼️ Gallery & Filters")
+
+    # Helper functions for Phase 3.D workflow management
+    def read_logs():
+        """Read and merge all log files"""
+        frames = []
+        for p in [RUNLOG, RUNLOG_3C, RUNLOG_3E]:
+            if Path(p).exists():
+                try:
+                    df = pd.read_csv(p)
+                    df["source_log"] = Path(p).name
+                    frames.append(df)
+                except Exception as e:
+                    st.warning(f"Failed reading {p}: {e}")
+        if not frames:
+            return pd.DataFrame(columns=["filepath"])
+        return pd.concat(frames, ignore_index=True).drop_duplicates(subset=["filepath"])
+
+    def scan_images():
+        """Scan output directory for images"""
+        rows = [{"filepath": str(p), "filename": p.name} for p in OUTPUT_DIR.glob("*.png")]
+        return pd.DataFrame(rows)
+
+    def load_annotations():
+        """Load existing annotations"""
+        if ANNOT_CSV.exists():
+            try:
+                return pd.read_csv(ANNOT_CSV)
+            except Exception:
+                pass
+        return pd.DataFrame(columns=["filepath", "rating", "tags", "notes"])
+
+    def save_annotations(df):
+        """Save annotations to CSV"""
+        df.to_csv(ANNOT_CSV, index=False)
+
+    # Load data
+    imgs_df = scan_images()
+    logs_df = read_logs()
+    ann_df = load_annotations()
+    meta_df = imgs_df.merge(logs_df, on="filepath", how="left")
+
+    if meta_df.empty:
+        st.info("No images found in outputs/. Generate some images first.")
+    else:
+        # Filtering controls
+        st.markdown("### 🔍 Filter Images")
+        colf1, colf2, colf3 = st.columns(3)
+
+        with colf1:
+            mode_opt = ["(all)"] + sorted([m for m in meta_df.get("mode", pd.Series([])).dropna().unique()])
+            sel_mode = st.selectbox("Filter by mode", mode_opt, index=0)
+
+        with colf2:
+            prompt_filter = st.text_input("Filter prompt contains", "")
+
+        with colf3:
+            min_steps = st.number_input("Min steps", 0, 200, 0, 1)
+
+        # Apply filters
+        filtered = meta_df.copy()
+        if sel_mode != "(all)" and "mode" in filtered.columns:
+            filtered = filtered[filtered["mode"] == sel_mode]
+        if prompt_filter.strip() and "prompt" in filtered.columns:
+            filtered = filtered[filtered["prompt"].fillna("").str.contains(prompt_filter, case=False)]
+        if "steps" in filtered.columns:
+            try:
+                filtered = filtered[pd.to_numeric(filtered["steps"], errors="coerce").fillna(0) >= min_steps]
+            except Exception:
+                pass
+
+        st.caption(f"{len(filtered)} image(s) match filters.")
+
+        # Display gallery
+        if not filtered.empty:
+            st.markdown("### 🖼️ Image Gallery")
+            cols = st.columns(4)
+            for i, row in filtered.reset_index(drop=True).iterrows():
+                with cols[i % 4]:
+                    p = row["filepath"]
+                    try:
+                        st.image(p, use_container_width=True, caption=os.path.basename(p))
+                    except Exception:
+                        st.write(os.path.basename(p))
+                    if "prompt" in row and pd.notna(row["prompt"]):
+                        st.caption(row["prompt"][:120])
+
+        # Annotation system
+        st.markdown("---")
+        st.subheader("✍️ Annotate / Rate / Tag")
+        choose = st.multiselect("Pick images to annotate", meta_df["filepath"].tolist())
+
+        if choose:
+            for path in choose:
+                st.markdown("---")
+                st.write(f"**{os.path.basename(path)}**")
+                try:
+                    st.image(path, width=320)
+                except Exception:
+                    pass
+
+                # Get existing annotation values
+                prev = ann_df[ann_df["filepath"] == path]
+                rating_val = int(prev.iloc[0]["rating"]) if not prev.empty and not pd.isna(prev.iloc[0]["rating"]) else 3
+                tags_val = prev.iloc[0]["tags"] if not prev.empty else ""
+                notes_val = prev.iloc[0]["notes"] if not prev.empty else ""
+
+                # Annotation controls
+                colE1, colE2, colE3 = st.columns([1, 1, 2])
+                with colE1:
+                    rating = st.slider(
+                        f"Rating {os.path.basename(path)}",
+                        1, 5, rating_val, 1,
+                        key=f"rate_{path}"
+                    )
+                with colE2:
+                    tags = st.text_input("Tags", tags_val, key=f"tags_{path}")
+                with colE3:
+                    notes = st.text_area("Notes", notes_val, key=f"notes_{path}")
+
+                # Update annotations dataframe
+                if (ann_df["filepath"] == path).any():
+                    ann_df.loc[ann_df["filepath"] == path, ["rating", "tags", "notes"]] = [rating, tags, notes]
+                else:
+                    ann_df.loc[len(ann_df)] = [path, rating, tags, notes]
+
+            if st.button("💾 Save annotations", use_container_width=True):
+                save_annotations(ann_df)
+                st.success("Annotations saved!")
+        else:
+            st.info("Select images above to annotate them.")
+
+# ==================== PRESETS TAB (Phase 3.D) ====================
+
+with tab_presets:
+    st.subheader("💾 Create / Save / Load Presets")
+
+    # Preset creation
+    st.markdown("### 🎛️ Create New Preset")
+    colP1, colP2 = st.columns(2)
+
+    with colP1:
+        preset_name = st.text_input("Preset name", "my_style", key="preset_name_input")
+        p_prompt = st.text_input("Prompt", main_prompt or "A serene cyberpunk alley at dawn", key="preset_prompt_input")
+        p_style = st.text_input("Style", style or "digital painting", key="preset_style_input")
+        p_mood = st.text_input("Mood", mood or ", ".join(MOOD_OPTIONS[:2]), key="preset_mood_input")
+        p_neg = st.text_input("Negative", neg_prompt or "", key="preset_neg_input")
+
+    with colP2:
+        p_steps = st.number_input("Steps", 10, 100, steps or 30, 1, key="preset_steps_input")
+        p_guid = st.number_input("Guidance", 1.0, 20.0, guidance or 7.5, 0.5, key="preset_guidance_input")
+        p_i2i = st.slider("img2img strength", 0.2, 0.9, 0.55, 0.05, key="preset_i2i_slider")
+        p_cn_type = st.selectbox("ControlNet type", ["Canny", "Depth"], key="preset_cn_type_selectbox")
+        p_cn_scale = st.slider("ControlNet scale", 0.1, 2.0, 1.0, 0.05, key="preset_cn_scale_slider")
+
+    # Build preset object
+    preset = {
+        "name": preset_name,
+        "prompt": p_prompt,
+        "style": p_style,
+        "mood": p_mood,
+        "negative": p_neg,
+        "steps": p_steps,
+        "guidance": p_guid,
+        "img2img_strength": p_i2i,
+        "controlnet": {"type": p_cn_type, "scale": p_cn_scale},
+        "created_at": datetime.now().isoformat()
+    }
+
+    st.markdown("### 📋 Preset Preview")
+    st.code(json.dumps(preset, indent=2), language="json")
+
+    # Save/Load controls
+    colPS1, colPS2 = st.columns(2)
+
+    with colPS1:
+        st.markdown("### 💾 Save Preset")
+        if st.button("💾 Save preset", use_container_width=True, key="save_preset_button"):
+            if preset_name.strip():
+                fp = PRESETS_DIR / f"{preset_name}.json"
+                with open(fp, "w", encoding="utf-8") as f:
+                    json.dump(preset, f, indent=2)
+                st.success(f"Saved {fp}")
+            else:
+                st.error("Please enter a preset name")
+
+    with colPS2:
+        st.markdown("### 📂 Load Preset")
+        existing = sorted([p.name for p in PRESETS_DIR.glob("*.json")])
+        if existing:
+            sel = st.selectbox("Load preset", ["(choose)"] + existing, key="load_preset_selectbox")
+            if sel != "(choose)":
+                with open(PRESETS_DIR / sel, "r", encoding="utf-8") as f:
+                    loaded = json.load(f)
+                st.success(f"Loaded {sel}")
+                st.code(json.dumps(loaded, indent=2), language="json")
+        else:
+            st.info("No presets found. Create your first preset above!")
+
+# ==================== EXPORT TAB (Phase 3.D) ====================
+
+with tab_export:
+    st.subheader("📦 Export Bundle (ZIP)")
+
+    # Helper functions for export
+    def read_logs_all():
+        """Read all logs for export"""
+        frames = []
+        for p in [RUNLOG, RUNLOG_3C, RUNLOG_3E]:
+            if Path(p).exists():
+                try:
+                    df = pd.read_csv(p)
+                    df["source_log"] = Path(p).name
+                    frames.append(df)
+                except Exception as e:
+                    st.warning(f"Read fail {p}: {e}")
+        if not frames:
+            return pd.DataFrame(columns=["filepath"])
+        return pd.concat(frames, ignore_index=True).drop_duplicates(subset=["filepath"])
+
+    def scan_imgs():
+        """Scan images for export"""
+        return pd.DataFrame([
+            {"filepath": str(p), "filename": p.name}
+            for p in OUTPUT_DIR.glob("*.png")
+        ])
+
+    # Load export data
+    imgs_df = scan_imgs()
+    logs_df = read_logs_all()
+
+    if imgs_df.empty:
+        st.info("No images to export yet. Generate some images first.")
+    else:
+        meta_df = imgs_df.merge(logs_df, on="filepath", how="left")
+
+        # Display available images
+        st.markdown("### 📋 Available Images")
+        display_cols = ["filepath", "prompt", "mode", "steps", "guidance"]
+        available_cols = [col for col in display_cols if col in meta_df.columns]
+        st.dataframe(
+            meta_df[available_cols].fillna("").astype(str),
+            use_container_width=True,
+            height=240
+        )
+
+        # Export selection
+        st.markdown("### 🎯 Export Selection")
+        sel = st.multiselect(
+            "Select images to export",
+            meta_df["filepath"].tolist(),
+            default=meta_df["filepath"].tolist()[:8],
+            key="export_images_multiselect"
+        )
+
+        # Preset inclusion
+        include_preset = st.checkbox("Include preset.json", value=False, key="include_preset_checkbox")
+        preset_blob = None
+        if include_preset:
+            ex = sorted([p.name for p in PRESETS_DIR.glob("*.json")])
+            if ex:
+                choose = st.selectbox("Choose preset", ex, key="export_preset_selectbox")
+                with open(PRESETS_DIR / choose, "r", encoding="utf-8") as f:
+                    preset_blob = json.load(f)
+            else:
+                st.warning("No presets found in /presets")
+                include_preset = False
+
+        # Bundle configuration
+        bundle_name = st.text_input(
+            "Bundle name (no spaces)",
+            f"compi_export_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
+            key="bundle_name_input"
+        )
+
+        # Create export bundle
+        if st.button("📦 Create Export Bundle", type="primary", use_container_width=True, key="create_bundle_button"):
+            if not sel:
+                st.error("Pick at least one image.")
+            elif not bundle_name.strip():
+                st.error("Please enter a bundle name.")
+            else:
+                with st.spinner("Creating export bundle..."):
+                    # Create temporary directory
+                    tmp_dir = EXPORTS_DIR / bundle_name
+                    if tmp_dir.exists():
+                        shutil.rmtree(tmp_dir)
+                    (tmp_dir / "images").mkdir(parents=True, exist_ok=True)
+
+                    # Copy images
+                    for p in sel:
+                        try:
+                            shutil.copy2(p, tmp_dir / "images" / os.path.basename(p))
+                        except Exception as e:
+                            st.warning(f"Copy failed: {p} ({e})")
+
+                    # Export metadata
+                    msel = meta_df[meta_df["filepath"].isin(sel)].copy()
+                    msel.to_csv(tmp_dir / "metadata.csv", index=False)
+
+                    # Export annotations
+                    if ANNOT_CSV.exists():
+                        shutil.copy2(ANNOT_CSV, tmp_dir / "annotations.csv")
+                    else:
+                        pd.DataFrame(columns=["filepath", "rating", "tags", "notes"]).to_csv(
+                            tmp_dir / "annotations.csv", index=False
+                        )
+
+                    # Create manifest
+                    manifest = {
+                        "bundle_name": bundle_name,
+                        "created_at": datetime.now().isoformat(),
+                        "environment": env_snapshot(),
+                        "includes": {
+                            "images": True,
+                            "metadata_csv": True,
+                            "annotations_csv": True,
+                            "preset_json": bool(preset_blob),
+                            "readme_md": True
+                        }
+                    }
+                    with open(tmp_dir / "manifest.json", "w", encoding="utf-8") as f:
+                        json.dump(manifest, f, indent=2)
+
+                    # Include preset if specified
+                    if preset_blob:
+                        with open(tmp_dir / "preset.json", "w", encoding="utf-8") as f:
+                            json.dump(preset_blob, f, indent=2)
+
+                    # Create README
+                    with open(tmp_dir / "README.md", "w", encoding="utf-8") as f:
+                        f.write(mk_readme(manifest, msel))
+
+                    # Create ZIP file
+                    zpath = EXPORTS_DIR / f"{bundle_name}.zip"
+                    if zpath.exists():
+                        zpath.unlink()
+
+                    with zipfile.ZipFile(zpath, 'w', zipfile.ZIP_DEFLATED) as zf:
+                        for root, _, files in os.walk(tmp_dir):
+                            for file in files:
+                                full = Path(root) / file
+                                zf.write(full, full.relative_to(tmp_dir))
+
+                    # Cleanup temporary directory
+                    shutil.rmtree(tmp_dir, ignore_errors=True)
+
+                    st.success(f"✅ Export created: {zpath}")
+                    st.info(f"📁 Bundle size: {zpath.stat().st_size / (1024*1024):.1f} MB")
+
+                    # Provide download link
+                    with open(zpath, "rb") as f:
+                        st.download_button(
+                            label="📥 Download Export Bundle",
+                            data=f.read(),
+                            file_name=f"{bundle_name}.zip",
+                            mime="application/zip",
+                            use_container_width=True
+                        )
+
+# ==================== FOOTER ====================
+
+st.markdown("---")
+st.markdown("""
+<div style='text-align: center; color: #666; padding: 20px;'>
+    <strong>🧪 CompI Phase 3 Final Dashboard</strong><br>
+    Complete integration of all Phase 3 components (3.A → 3.E)<br>
+    <em>Multimodal AI Art Generation • Advanced References • Performance Management • Professional Workflow</em>
+</div>
+""", unsafe_allow_html=True)

src/utils/__init__.py

@@ -0,0 +1,16 @@
+"""
+Utility functions for CompI project.
+"""
+
+from .logging_utils import setup_logger
+from .file_utils import save_image, save_audio, load_config
+from .image_utils import ImageProcessor, StyleAnalyzer
+
+__all__ = [
+    "setup_logger",
+    "save_image",
+    "save_audio",
+    "load_config",
+    "ImageProcessor",
+    "StyleAnalyzer"
+]

src/utils/audio_utils.py

@@ -0,0 +1,342 @@
+"""
+Audio processing utilities for CompI Phase 2.A: Audio Input Integration
+
+This module provides comprehensive audio analysis capabilities including:
+- Audio feature extraction (tempo, energy, spectral features)
+- Audio preprocessing and normalization
+- Audio-to-text captioning using OpenAI Whisper
+- Multimodal prompt fusion combining audio features with text prompts
+"""
+
+import os
+import numpy as np
+import librosa
+import soundfile as sf
+from typing import Dict, List, Optional, Tuple, Union
+import logging
+from dataclasses import dataclass
+
+# Setup logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+@dataclass
+class AudioFeatures:
+    """Container for extracted audio features"""
+    tempo: float
+    energy: float  # RMS energy
+    zero_crossing_rate: float
+    spectral_centroid: float
+    spectral_rolloff: float
+    mfcc_mean: np.ndarray
+    chroma_mean: np.ndarray
+    duration: float
+    sample_rate: int
+    
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            'tempo': float(self.tempo),
+            'energy': float(self.energy),
+            'zero_crossing_rate': float(self.zero_crossing_rate),
+            'spectral_centroid': float(self.spectral_centroid),
+            'spectral_rolloff': float(self.spectral_rolloff),
+            'mfcc_mean': self.mfcc_mean.tolist() if hasattr(self.mfcc_mean, 'tolist') else list(self.mfcc_mean),
+            'chroma_mean': self.chroma_mean.tolist() if hasattr(self.chroma_mean, 'tolist') else list(self.chroma_mean),
+            'duration': float(self.duration),
+            'sample_rate': int(self.sample_rate)
+        }
+
+class AudioProcessor:
+    """Comprehensive audio processing and analysis"""
+    
+    def __init__(self, target_sr: int = 16000, max_duration: float = 60.0):
+        """
+        Initialize audio processor
+        
+        Args:
+            target_sr: Target sample rate for processing
+            max_duration: Maximum audio duration to process (seconds)
+        """
+        self.target_sr = target_sr
+        self.max_duration = max_duration
+        
+    def load_audio(self, audio_path: str) -> Tuple[np.ndarray, int]:
+        """
+        Load and preprocess audio file
+        
+        Args:
+            audio_path: Path to audio file
+            
+        Returns:
+            Tuple of (audio_data, sample_rate)
+        """
+        try:
+            # Load audio with librosa
+            audio, sr = librosa.load(
+                audio_path, 
+                sr=self.target_sr, 
+                duration=self.max_duration
+            )
+            
+            # Normalize audio
+            audio = librosa.util.normalize(audio)
+            
+            logger.info(f"Loaded audio: {audio_path}, duration: {len(audio)/sr:.2f}s")
+            return audio, sr
+            
+        except Exception as e:
+            logger.error(f"Error loading audio {audio_path}: {e}")
+            raise
+    
+    def extract_features(self, audio: np.ndarray, sr: int) -> AudioFeatures:
+        """
+        Extract comprehensive audio features
+        
+        Args:
+            audio: Audio signal
+            sr: Sample rate
+            
+        Returns:
+            AudioFeatures object containing all extracted features
+        """
+        try:
+            # Basic features
+            duration = len(audio) / sr
+            
+            # Tempo and beat tracking
+            tempo, _ = librosa.beat.beat_track(y=audio, sr=sr)
+            
+            # Energy (RMS)
+            rms = librosa.feature.rms(y=audio)[0]
+            energy = np.sqrt(np.mean(rms**2))
+            
+            # Zero crossing rate
+            zcr = librosa.feature.zero_crossing_rate(audio)[0]
+            zcr_mean = np.mean(zcr)
+            
+            # Spectral features
+            spectral_centroids = librosa.feature.spectral_centroid(y=audio, sr=sr)[0]
+            spectral_centroid = np.mean(spectral_centroids)
+            
+            spectral_rolloff = librosa.feature.spectral_rolloff(y=audio, sr=sr)[0]
+            spectral_rolloff_mean = np.mean(spectral_rolloff)
+            
+            # MFCC features
+            mfccs = librosa.feature.mfcc(y=audio, sr=sr, n_mfcc=13)
+            mfcc_mean = np.mean(mfccs, axis=1)
+            
+            # Chroma features
+            chroma = librosa.feature.chroma_stft(y=audio, sr=sr)
+            chroma_mean = np.mean(chroma, axis=1)
+            
+            features = AudioFeatures(
+                tempo=float(tempo),
+                energy=float(energy),
+                zero_crossing_rate=float(zcr_mean),
+                spectral_centroid=float(spectral_centroid),
+                spectral_rolloff=float(spectral_rolloff_mean),
+                mfcc_mean=mfcc_mean,
+                chroma_mean=chroma_mean,
+                duration=float(duration),
+                sample_rate=int(sr)
+            )
+            
+            logger.info(f"Extracted features: tempo={float(tempo):.1f}, energy={float(energy):.4f}")
+            return features
+            
+        except Exception as e:
+            logger.error(f"Error extracting audio features: {e}")
+            raise
+    
+    def analyze_audio_file(self, audio_path: str) -> AudioFeatures:
+        """
+        Complete audio analysis pipeline
+        
+        Args:
+            audio_path: Path to audio file
+            
+        Returns:
+            AudioFeatures object
+        """
+        audio, sr = self.load_audio(audio_path)
+        return self.extract_features(audio, sr)
+
+class AudioCaptioner:
+    """Audio-to-text captioning using OpenAI Whisper"""
+    
+    def __init__(self, model_size: str = "base", device: str = "auto"):
+        """
+        Initialize audio captioner
+        
+        Args:
+            model_size: Whisper model size (tiny, base, small, medium, large)
+            device: Device to run on (auto, cpu, cuda)
+        """
+        self.model_size = model_size
+        self.device = device
+        self._model = None
+        
+    def _load_model(self):
+        """Lazy load Whisper model"""
+        if self._model is None:
+            try:
+                import whisper
+                self._model = whisper.load_model(self.model_size, device=self.device)
+                logger.info(f"Loaded Whisper model: {self.model_size}")
+            except ImportError:
+                logger.error("OpenAI Whisper not installed. Install with: pip install openai-whisper")
+                raise
+            except Exception as e:
+                logger.error(f"Error loading Whisper model: {e}")
+                raise
+    
+    def caption_audio(self, audio_path: str, language: str = "en") -> str:
+        """
+        Generate text caption from audio
+        
+        Args:
+            audio_path: Path to audio file
+            language: Language code for transcription
+            
+        Returns:
+            Text caption of the audio content
+        """
+        self._load_model()
+        
+        try:
+            import whisper
+            
+            # Load and preprocess audio for Whisper
+            audio = whisper.load_audio(audio_path)
+            audio = whisper.pad_or_trim(audio)
+            
+            # Generate mel spectrogram
+            mel = whisper.log_mel_spectrogram(audio).to(self._model.device)
+            
+            # Decode audio
+            options = whisper.DecodingOptions(language=language, fp16=False)
+            result = whisper.decode(self._model, mel, options)
+            
+            caption = result.text.strip()
+            logger.info(f"Generated audio caption: '{caption[:50]}...'")
+            
+            return caption
+            
+        except Exception as e:
+            logger.error(f"Error captioning audio: {e}")
+            return ""
+
+class MultimodalPromptFusion:
+    """Intelligent fusion of text prompts with audio features and captions"""
+    
+    def __init__(self):
+        """Initialize prompt fusion system"""
+        pass
+    
+    def fuse_prompt_with_audio(
+        self, 
+        text_prompt: str,
+        style: str,
+        mood: str,
+        audio_features: AudioFeatures,
+        audio_caption: str = ""
+    ) -> str:
+        """
+        Create enhanced prompt by fusing text with audio analysis
+        
+        Args:
+            text_prompt: Original text prompt
+            style: Art style
+            mood: Mood/atmosphere
+            audio_features: Extracted audio features
+            audio_caption: Audio caption from Whisper
+            
+        Returns:
+            Enhanced multimodal prompt
+        """
+        # Start with base prompt
+        enhanced_prompt = text_prompt.strip()
+        
+        # Add style and mood
+        if style:
+            enhanced_prompt += f", {style}"
+        if mood:
+            enhanced_prompt += f", {mood}"
+        
+        # Add audio caption if available
+        if audio_caption:
+            enhanced_prompt += f", inspired by the sound of: {audio_caption}"
+        
+        # Add tempo-based descriptors
+        if audio_features.tempo < 80:
+            enhanced_prompt += ", slow and contemplative"
+        elif audio_features.tempo > 140:
+            enhanced_prompt += ", fast-paced and energetic"
+        elif audio_features.tempo > 120:
+            enhanced_prompt += ", upbeat and dynamic"
+        
+        # Add energy-based descriptors
+        if audio_features.energy > 0.05:
+            enhanced_prompt += ", vibrant and powerful"
+        elif audio_features.energy < 0.02:
+            enhanced_prompt += ", gentle and subtle"
+        
+        # Add rhythm-based descriptors
+        if audio_features.zero_crossing_rate > 0.15:
+            enhanced_prompt += ", rhythmic and percussive"
+        
+        # Add tonal descriptors based on spectral features
+        if audio_features.spectral_centroid > 3000:
+            enhanced_prompt += ", bright and crisp"
+        elif audio_features.spectral_centroid < 1500:
+            enhanced_prompt += ", warm and deep"
+        
+        logger.info(f"Enhanced prompt: {enhanced_prompt}")
+        return enhanced_prompt
+    
+    def generate_audio_tags(self, audio_features: AudioFeatures) -> List[str]:
+        """
+        Generate descriptive tags based on audio features
+        
+        Args:
+            audio_features: Extracted audio features
+            
+        Returns:
+            List of descriptive tags
+        """
+        tags = []
+        
+        # Tempo tags
+        if audio_features.tempo < 60:
+            tags.append("very_slow")
+        elif audio_features.tempo < 90:
+            tags.append("slow")
+        elif audio_features.tempo < 120:
+            tags.append("moderate")
+        elif audio_features.tempo < 140:
+            tags.append("fast")
+        else:
+            tags.append("very_fast")
+        
+        # Energy tags
+        if audio_features.energy > 0.06:
+            tags.append("high_energy")
+        elif audio_features.energy > 0.03:
+            tags.append("medium_energy")
+        else:
+            tags.append("low_energy")
+        
+        # Rhythm tags
+        if audio_features.zero_crossing_rate > 0.15:
+            tags.append("percussive")
+        elif audio_features.zero_crossing_rate < 0.05:
+            tags.append("smooth")
+        
+        # Spectral tags
+        if audio_features.spectral_centroid > 3000:
+            tags.append("bright")
+        elif audio_features.spectral_centroid < 1500:
+            tags.append("dark")
+        
+        return tags

src/utils/data_utils.py

@@ -0,0 +1,654 @@
+"""
+CompI Data Processing Utilities
+
+This module provides utilities for Phase 2.B: Data/Logic Input Integration
+- CSV data analysis and processing
+- Mathematical formula evaluation
+- Data-to-text conversion (poetic descriptions)
+- Data visualization generation
+- Statistical analysis and pattern detection
+"""
+
+import os
+import io
+import ast
+import math
+import numpy as np
+import pandas as pd
+import matplotlib
+matplotlib.use('Agg')  # Use non-interactive backend for Streamlit
+import matplotlib.pyplot as plt
+import seaborn as sns
+from typing import Dict, List, Optional, Tuple, Union, Any
+from dataclasses import dataclass
+from PIL import Image
+import logging
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class DataFeatures:
+    """Container for extracted data features and statistics"""
+    
+    # Basic properties
+    shape: Tuple[int, int]
+    columns: List[str]
+    numeric_columns: List[str]
+    data_types: Dict[str, str]
+    
+    # Statistical features
+    means: Dict[str, float]
+    medians: Dict[str, float]
+    stds: Dict[str, float]
+    mins: Dict[str, float]
+    maxs: Dict[str, float]
+    ranges: Dict[str, float]
+    
+    # Pattern features
+    trends: Dict[str, str]  # 'increasing', 'decreasing', 'stable', 'volatile'
+    correlations: Dict[str, float]  # strongest correlations
+    seasonality: Dict[str, bool]  # detected patterns
+    
+    # Derived insights
+    complexity_score: float  # 0-1 measure of data complexity
+    variability_score: float  # 0-1 measure of data variability
+    pattern_strength: float  # 0-1 measure of detectable patterns
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            'shape': self.shape,
+            'columns': self.columns,
+            'numeric_columns': self.numeric_columns,
+            'data_types': self.data_types,
+            'means': self.means,
+            'medians': self.medians,
+            'stds': self.stds,
+            'mins': self.mins,
+            'maxs': self.maxs,
+            'ranges': self.ranges,
+            'trends': self.trends,
+            'correlations': self.correlations,
+            'seasonality': self.seasonality,
+            'complexity_score': self.complexity_score,
+            'variability_score': self.variability_score,
+            'pattern_strength': self.pattern_strength
+        }
+
+class DataProcessor:
+    """Core data processing and analysis functionality"""
+    
+    def __init__(self):
+        """Initialize the data processor"""
+        self.safe_functions = {
+            # Math functions
+            'abs': abs, 'round': round, 'min': min, 'max': max,
+            'sum': sum, 'len': len, 'pow': pow,
+            
+            # NumPy functions
+            'np': np, 'numpy': np,
+            'sin': np.sin, 'cos': np.cos, 'tan': np.tan,
+            'exp': np.exp, 'log': np.log, 'sqrt': np.sqrt,
+            'pi': np.pi, 'e': np.e,
+            
+            # Math module functions
+            'math': math,
+            
+            # Restricted builtins
+            '__builtins__': {}
+        }
+    
+    def analyze_csv_data(self, df: pd.DataFrame) -> DataFeatures:
+        """
+        Comprehensive analysis of CSV data
+        
+        Args:
+            df: Input DataFrame
+            
+        Returns:
+            DataFeatures object with extracted insights
+        """
+        logger.info(f"Analyzing CSV data with shape {df.shape}")
+        
+        # Basic properties
+        shape = df.shape
+        columns = df.columns.tolist()
+        numeric_df = df.select_dtypes(include=[np.number])
+        numeric_columns = numeric_df.columns.tolist()
+        data_types = {col: str(df[col].dtype) for col in columns}
+        
+        # Statistical features
+        means = {col: float(numeric_df[col].mean()) for col in numeric_columns}
+        medians = {col: float(numeric_df[col].median()) for col in numeric_columns}
+        stds = {col: float(numeric_df[col].std()) for col in numeric_columns}
+        mins = {col: float(numeric_df[col].min()) for col in numeric_columns}
+        maxs = {col: float(numeric_df[col].max()) for col in numeric_columns}
+        ranges = {col: maxs[col] - mins[col] for col in numeric_columns}
+        
+        # Pattern analysis
+        trends = self._analyze_trends(numeric_df)
+        correlations = self._find_strongest_correlations(numeric_df)
+        seasonality = self._detect_seasonality(numeric_df)
+        
+        # Derived scores
+        complexity_score = self._calculate_complexity_score(numeric_df)
+        variability_score = self._calculate_variability_score(stds, ranges)
+        pattern_strength = self._calculate_pattern_strength(trends, correlations)
+        
+        return DataFeatures(
+            shape=shape,
+            columns=columns,
+            numeric_columns=numeric_columns,
+            data_types=data_types,
+            means=means,
+            medians=medians,
+            stds=stds,
+            mins=mins,
+            maxs=maxs,
+            ranges=ranges,
+            trends=trends,
+            correlations=correlations,
+            seasonality=seasonality,
+            complexity_score=complexity_score,
+            variability_score=variability_score,
+            pattern_strength=pattern_strength
+        )
+    
+    def evaluate_formula(self, formula: str, num_points: int = 100) -> Tuple[np.ndarray, Dict[str, Any]]:
+        """
+        Safely evaluate mathematical formula
+        
+        Args:
+            formula: Mathematical expression (Python/NumPy syntax)
+            num_points: Number of points to generate
+            
+        Returns:
+            Tuple of (result_array, metadata)
+        """
+        logger.info(f"Evaluating formula: {formula}")
+        
+        try:
+            # Create default x values if not specified in formula
+            if 'x' in formula and 'linspace' not in formula and 'arange' not in formula:
+                # Add default x range if x is used but not defined
+                x = np.linspace(0, 10, num_points)
+                self.safe_functions['x'] = x
+            
+            # Evaluate the formula
+            result = eval(formula, self.safe_functions)
+            
+            # Ensure result is a numpy array
+            if not isinstance(result, np.ndarray):
+                if isinstance(result, (list, tuple)):
+                    result = np.array(result)
+                else:
+                    # Single value - create array
+                    result = np.full(num_points, result)
+            
+            # Analyze the result
+            metadata = {
+                'length': len(result),
+                'min': float(np.min(result)),
+                'max': float(np.max(result)),
+                'mean': float(np.mean(result)),
+                'std': float(np.std(result)),
+                'range': float(np.max(result) - np.min(result)),
+                'formula': formula,
+                'has_pattern': self._detect_mathematical_pattern(result)
+            }
+            
+            return result, metadata
+            
+        except Exception as e:
+            logger.error(f"Formula evaluation failed: {e}")
+            raise ValueError(f"Invalid formula: {e}")
+
+    def _analyze_trends(self, df: pd.DataFrame) -> Dict[str, str]:
+        """Analyze trends in numeric columns"""
+        trends = {}
+        for col in df.columns:
+            values = df[col].dropna()
+            if len(values) < 3:
+                trends[col] = 'insufficient_data'
+                continue
+
+            # Calculate trend using linear regression slope
+            x = np.arange(len(values))
+            slope = np.polyfit(x, values, 1)[0]
+            std_val = values.std()
+
+            if abs(slope) < std_val * 0.1:
+                trends[col] = 'stable'
+            elif std_val > values.mean() * 0.5:
+                trends[col] = 'volatile'
+            elif slope > 0:
+                trends[col] = 'increasing'
+            else:
+                trends[col] = 'decreasing'
+
+        return trends
+
+    def _find_strongest_correlations(self, df: pd.DataFrame) -> Dict[str, float]:
+        """Find strongest correlations between columns"""
+        if len(df.columns) < 2:
+            return {}
+
+        corr_matrix = df.corr()
+        correlations = {}
+
+        for i, col1 in enumerate(df.columns):
+            for j, col2 in enumerate(df.columns):
+                if i < j:  # Avoid duplicates and self-correlation
+                    corr_val = corr_matrix.loc[col1, col2]
+                    if not np.isnan(corr_val):
+                        correlations[f"{col1}_vs_{col2}"] = float(corr_val)
+
+        # Return top 3 strongest correlations
+        sorted_corr = sorted(correlations.items(), key=lambda x: abs(x[1]), reverse=True)
+        return dict(sorted_corr[:3])
+
+    def _detect_seasonality(self, df: pd.DataFrame) -> Dict[str, bool]:
+        """Simple seasonality detection"""
+        seasonality = {}
+        for col in df.columns:
+            values = df[col].dropna()
+            if len(values) < 12:  # Need at least 12 points for seasonality
+                seasonality[col] = False
+                continue
+
+            # Simple autocorrelation check
+            try:
+                autocorr = np.corrcoef(values[:-1], values[1:])[0, 1]
+                seasonality[col] = not np.isnan(autocorr) and abs(autocorr) > 0.3
+            except:
+                seasonality[col] = False
+
+        return seasonality
+
+    def _calculate_complexity_score(self, df: pd.DataFrame) -> float:
+        """Calculate data complexity score (0-1)"""
+        if df.empty:
+            return 0.0
+
+        # Factors: number of columns, data types variety, missing values
+        num_cols = len(df.columns)
+        col_score = min(num_cols / 10, 1.0)  # Normalize to 0-1
+
+        # Missing data complexity
+        missing_ratio = df.isnull().sum().sum() / (df.shape[0] * df.shape[1])
+        missing_score = min(missing_ratio * 2, 1.0)
+
+        return (col_score + missing_score) / 2
+
+    def _calculate_variability_score(self, stds: Dict[str, float], ranges: Dict[str, float]) -> float:
+        """Calculate data variability score (0-1)"""
+        if not stds:
+            return 0.0
+
+        # Normalize standard deviations by their ranges
+        normalized_vars = []
+        for col in stds:
+            if ranges[col] > 0:
+                normalized_vars.append(stds[col] / ranges[col])
+
+        if not normalized_vars:
+            return 0.0
+
+        return min(np.mean(normalized_vars) * 2, 1.0)
+
+    def _calculate_pattern_strength(self, trends: Dict[str, str], correlations: Dict[str, float]) -> float:
+        """Calculate pattern strength score (0-1)"""
+        pattern_score = 0.0
+
+        # Trend strength
+        trend_patterns = sum(1 for trend in trends.values() if trend in ['increasing', 'decreasing'])
+        trend_score = min(trend_patterns / max(len(trends), 1), 1.0)
+
+        # Correlation strength
+        if correlations:
+            max_corr = max(abs(corr) for corr in correlations.values())
+            corr_score = max_corr
+        else:
+            corr_score = 0.0
+
+        return (trend_score + corr_score) / 2
+
+    def _detect_mathematical_pattern(self, data: np.ndarray) -> bool:
+        """Detect if mathematical data has recognizable patterns"""
+        if len(data) < 10:
+            return False
+
+        # Check for periodicity using autocorrelation
+        try:
+            # Simple pattern detection
+            autocorr = np.corrcoef(data[:-1], data[1:])[0, 1]
+            return not np.isnan(autocorr) and abs(autocorr) > 0.5
+        except:
+            return False
+
+
+class DataToTextConverter:
+    """Convert data patterns into poetic/narrative text descriptions"""
+
+    def __init__(self):
+        """Initialize the converter with descriptive vocabularies"""
+        self.trend_descriptions = {
+            'increasing': ['ascending', 'rising', 'climbing', 'growing', 'soaring'],
+            'decreasing': ['descending', 'falling', 'declining', 'diminishing', 'fading'],
+            'stable': ['steady', 'constant', 'balanced', 'harmonious', 'peaceful'],
+            'volatile': ['chaotic', 'turbulent', 'dynamic', 'energetic', 'wild']
+        }
+
+        self.pattern_adjectives = {
+            'high_complexity': ['intricate', 'complex', 'sophisticated', 'elaborate'],
+            'low_complexity': ['simple', 'pure', 'minimal', 'clean'],
+            'high_variability': ['diverse', 'varied', 'rich', 'multifaceted'],
+            'low_variability': ['consistent', 'uniform', 'regular', 'predictable'],
+            'strong_patterns': ['rhythmic', 'structured', 'organized', 'patterned'],
+            'weak_patterns': ['random', 'scattered', 'free-flowing', 'organic']
+        }
+
+        self.artistic_metaphors = [
+            'like brushstrokes on a canvas',
+            'resembling musical notes in harmony',
+            'flowing like water through landscapes',
+            'dancing with mathematical precision',
+            'weaving patterns of light and shadow',
+            'creating symphonies of numbers',
+            'painting stories with data points',
+            'sculpting meaning from statistics'
+        ]
+
+    def generate_poetic_description(self, features: DataFeatures) -> str:
+        """
+        Generate poetic description from data features
+
+        Args:
+            features: DataFeatures object
+
+        Returns:
+            Poetic text description
+        """
+        descriptions = []
+
+        # Basic data description
+        descriptions.append(f"A tapestry woven from {features.shape[0]} data points across {features.shape[1]} dimensions")
+
+        # Trend descriptions
+        trend_desc = self._describe_trends(features.trends)
+        if trend_desc:
+            descriptions.append(trend_desc)
+
+        # Variability description
+        var_desc = self._describe_variability(features.variability_score)
+        if var_desc:
+            descriptions.append(var_desc)
+
+        # Pattern description
+        pattern_desc = self._describe_patterns(features.pattern_strength, features.correlations)
+        if pattern_desc:
+            descriptions.append(pattern_desc)
+
+        # Add artistic metaphor
+        import random
+        metaphor = random.choice(self.artistic_metaphors)
+        descriptions.append(f"The data flows {metaphor}")
+
+        return '. '.join(descriptions) + '.'
+
+    def generate_formula_description(self, formula: str, metadata: Dict[str, Any]) -> str:
+        """
+        Generate poetic description for mathematical formula
+
+        Args:
+            formula: Original formula
+            metadata: Formula evaluation metadata
+
+        Returns:
+            Poetic text description
+        """
+        descriptions = []
+
+        # Formula introduction
+        descriptions.append(f"Mathematical harmony emerges from the expression: {formula}")
+
+        # Range description
+        range_val = metadata['range']
+        if range_val > 10:
+            descriptions.append("The function soars across vast numerical landscapes")
+        elif range_val > 1:
+            descriptions.append("Values dance within moderate bounds")
+        else:
+            descriptions.append("Numbers whisper in gentle, subtle variations")
+
+        # Pattern description
+        if metadata['has_pattern']:
+            descriptions.append("Revealing intricate patterns that speak to the soul")
+        else:
+            descriptions.append("Creating unique, unrepeatable mathematical poetry")
+
+        # Add artistic metaphor
+        import random
+        metaphor = random.choice(self.artistic_metaphors)
+        descriptions.append(f"Each calculation {metaphor}")
+
+        return '. '.join(descriptions) + '.'
+
+    def _describe_trends(self, trends: Dict[str, str]) -> str:
+        """Describe overall trends in the data"""
+        if not trends:
+            return ""
+
+        trend_counts = {}
+        for trend in trends.values():
+            trend_counts[trend] = trend_counts.get(trend, 0) + 1
+
+        dominant_trend = max(trend_counts, key=trend_counts.get)
+
+        if dominant_trend in self.trend_descriptions:
+            import random
+            adj = random.choice(self.trend_descriptions[dominant_trend])
+            return f"The data reveals {adj} patterns throughout its structure"
+
+        return ""
+
+    def _describe_variability(self, variability_score: float) -> str:
+        """Describe data variability"""
+        import random
+
+        if variability_score > 0.7:
+            adj = random.choice(self.pattern_adjectives['high_variability'])
+            return f"With {adj} expressions of numerical diversity"
+        elif variability_score < 0.3:
+            adj = random.choice(self.pattern_adjectives['low_variability'])
+            return f"Maintaining {adj} elegance in its values"
+        else:
+            return "Balancing consistency with creative variation"
+
+    def _describe_patterns(self, pattern_strength: float, correlations: Dict[str, float]) -> str:
+        """Describe pattern strength and correlations"""
+        import random
+
+        if pattern_strength > 0.6:
+            adj = random.choice(self.pattern_adjectives['strong_patterns'])
+            return f"Displaying {adj} relationships between its elements"
+        elif pattern_strength < 0.3:
+            adj = random.choice(self.pattern_adjectives['weak_patterns'])
+            return f"Embracing {adj} freedom in its numerical expression"
+        else:
+            return "Weaving subtle connections throughout its numerical fabric"
+
+
+class DataVisualizer:
+    """Create visualizations from data for artistic conditioning"""
+
+    def __init__(self, style: str = 'artistic'):
+        """
+        Initialize visualizer
+
+        Args:
+            style: Visualization style ('artistic', 'scientific', 'minimal')
+        """
+        self.style = style
+        self.color_palettes = {
+            'artistic': ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7'],
+            'scientific': ['#2E86AB', '#A23B72', '#F18F01', '#C73E1D', '#592E83'],
+            'minimal': ['#2C3E50', '#34495E', '#7F8C8D', '#95A5A6', '#BDC3C7']
+        }
+
+    def create_data_visualization(self, df: pd.DataFrame, features: DataFeatures) -> Image.Image:
+        """
+        Create artistic visualization from DataFrame
+
+        Args:
+            df: Input DataFrame
+            features: DataFeatures object
+
+        Returns:
+            PIL Image of the visualization
+        """
+        plt.style.use('default')
+        fig, axes = plt.subplots(2, 2, figsize=(12, 10))
+        fig.suptitle('Data Pattern Visualization', fontsize=16, fontweight='bold')
+
+        numeric_df = df.select_dtypes(include=[np.number])
+        colors = self.color_palettes[self.style]
+
+        # Plot 1: Line plot of first few columns
+        ax1 = axes[0, 0]
+        for i, col in enumerate(numeric_df.columns[:3]):
+            ax1.plot(numeric_df[col], color=colors[i % len(colors)],
+                    linewidth=2, alpha=0.8, label=col)
+        ax1.set_title('Data Trends', fontweight='bold')
+        ax1.legend()
+        ax1.grid(True, alpha=0.3)
+
+        # Plot 2: Distribution/histogram
+        ax2 = axes[0, 1]
+        if len(numeric_df.columns) > 0:
+            col = numeric_df.columns[0]
+            ax2.hist(numeric_df[col].dropna(), bins=20, color=colors[0],
+                    alpha=0.7, edgecolor='black')
+            ax2.set_title(f'Distribution: {col}', fontweight='bold')
+            ax2.grid(True, alpha=0.3)
+
+        # Plot 3: Correlation heatmap (if multiple columns)
+        ax3 = axes[1, 0]
+        if len(numeric_df.columns) > 1:
+            corr_matrix = numeric_df.corr()
+            im = ax3.imshow(corr_matrix, cmap='RdBu_r', aspect='auto', vmin=-1, vmax=1)
+            ax3.set_xticks(range(len(corr_matrix.columns)))
+            ax3.set_yticks(range(len(corr_matrix.columns)))
+            ax3.set_xticklabels(corr_matrix.columns, rotation=45)
+            ax3.set_yticklabels(corr_matrix.columns)
+            ax3.set_title('Correlations', fontweight='bold')
+            plt.colorbar(im, ax=ax3, shrink=0.8)
+        else:
+            ax3.text(0.5, 0.5, 'Single Column\nNo Correlations',
+                    ha='center', va='center', transform=ax3.transAxes)
+            ax3.set_title('Correlations', fontweight='bold')
+
+        # Plot 4: Summary statistics
+        ax4 = axes[1, 1]
+        if len(numeric_df.columns) > 0:
+            stats_data = [features.means[col] for col in numeric_df.columns[:5]]
+            bars = ax4.bar(range(len(stats_data)), stats_data, color=colors[:len(stats_data)])
+            ax4.set_title('Mean Values', fontweight='bold')
+            ax4.set_xticks(range(len(stats_data)))
+            ax4.set_xticklabels([col[:8] for col in numeric_df.columns[:5]], rotation=45)
+            ax4.grid(True, alpha=0.3)
+
+        plt.tight_layout()
+
+        # Convert to PIL Image
+        buf = io.BytesIO()
+        plt.savefig(buf, format='png', dpi=150, bbox_inches='tight')
+        plt.close()
+        buf.seek(0)
+
+        return Image.open(buf)
+
+    def create_formula_visualization(self, data: np.ndarray, formula: str, metadata: Dict[str, Any]) -> Image.Image:
+        """
+        Create artistic visualization from formula result
+
+        Args:
+            data: Formula result array
+            formula: Original formula
+            metadata: Formula metadata
+
+        Returns:
+            PIL Image of the visualization
+        """
+        try:
+            logger.info(f"Creating visualization for formula: {formula}")
+            logger.info(f"Data shape: {data.shape}, Data range: [{np.min(data):.3f}, {np.max(data):.3f}]")
+
+            plt.style.use('default')
+            fig, axes = plt.subplots(2, 2, figsize=(12, 10))
+            fig.suptitle(f'Mathematical Pattern: {formula}', fontsize=14, fontweight='bold')
+
+            colors = self.color_palettes[self.style]
+            x = np.arange(len(data))
+
+            # Plot 1: Main function plot
+            ax1 = axes[0, 0]
+            ax1.plot(x, data, color=colors[0], linewidth=3, alpha=0.8)
+            ax1.fill_between(x, data, alpha=0.3, color=colors[0])
+            ax1.set_title('Function Values', fontweight='bold')
+            ax1.grid(True, alpha=0.3)
+
+            # Plot 2: Derivative approximation
+            ax2 = axes[0, 1]
+            if len(data) > 1:
+                derivative = np.gradient(data)
+                ax2.plot(x, derivative, color=colors[1], linewidth=2)
+                ax2.set_title('Rate of Change', fontweight='bold')
+                ax2.grid(True, alpha=0.3)
+
+            # Plot 3: Distribution
+            ax3 = axes[1, 0]
+            ax3.hist(data, bins=30, color=colors[2], alpha=0.7, edgecolor='black')
+            ax3.set_title('Value Distribution', fontweight='bold')
+            ax3.grid(True, alpha=0.3)
+
+            # Plot 4: Phase space (if applicable)
+            ax4 = axes[1, 1]
+            if len(data) > 1:
+                ax4.scatter(data[:-1], data[1:], c=x[:-1], cmap='viridis', alpha=0.6)
+                ax4.set_xlabel('f(t)')
+                ax4.set_ylabel('f(t+1)')
+                ax4.set_title('Phase Space', fontweight='bold')
+                ax4.grid(True, alpha=0.3)
+
+            plt.tight_layout()
+
+            # Convert to PIL Image
+            buf = io.BytesIO()
+            plt.savefig(buf, format='png', dpi=150, bbox_inches='tight')
+            plt.close()
+            buf.seek(0)
+
+            image = Image.open(buf)
+            logger.info(f"Successfully created visualization image: {image.size}")
+            return image
+
+        except Exception as e:
+            logger.error(f"Error creating formula visualization: {e}")
+            plt.close('all')  # Clean up any open figures
+
+            # Return a simple error image
+            fig, ax = plt.subplots(figsize=(8, 6))
+            ax.text(0.5, 0.5, f'Visualization Error:\n{str(e)}',
+                   ha='center', va='center', fontsize=12,
+                   bbox=dict(boxstyle="round,pad=0.3", facecolor="lightcoral"))
+            ax.set_xlim(0, 1)
+            ax.set_ylim(0, 1)
+            ax.axis('off')
+
+            buf = io.BytesIO()
+            plt.savefig(buf, format='png', dpi=150, bbox_inches='tight')
+            plt.close()
+            buf.seek(0)
+
+            return Image.open(buf)

src/utils/emotion_utils.py

@@ -0,0 +1,446 @@
+"""
+CompI Emotion Processing Utilities
+
+This module provides utilities for Phase 2.C: Emotional/Contextual Input Integration
+- Emotion detection and sentiment analysis
+- Mood mapping and emotional context processing
+- Color palette generation based on emotions
+- Contextual prompt enhancement
+- Emoji and text-based emotion recognition
+"""
+
+import re
+import json
+from typing import Dict, List, Optional, Tuple, Union, Any
+from dataclasses import dataclass
+from enum import Enum
+import logging
+
+# Optional imports with fallbacks
+try:
+    from textblob import TextBlob
+    TEXTBLOB_AVAILABLE = True
+except ImportError:
+    TEXTBLOB_AVAILABLE = False
+    TextBlob = None
+
+try:
+    import emoji
+    EMOJI_AVAILABLE = True
+except ImportError:
+    EMOJI_AVAILABLE = False
+    emoji = None
+
+logger = logging.getLogger(__name__)
+
+class EmotionCategory(Enum):
+    """Primary emotion categories"""
+    JOY = "joy"
+    SADNESS = "sadness"
+    ANGER = "anger"
+    FEAR = "fear"
+    SURPRISE = "surprise"
+    DISGUST = "disgust"
+    LOVE = "love"
+    ANTICIPATION = "anticipation"
+    TRUST = "trust"
+    NEUTRAL = "neutral"
+
+@dataclass
+class EmotionAnalysis:
+    """Container for emotion analysis results"""
+    
+    # Primary emotion detection
+    primary_emotion: EmotionCategory
+    emotion_confidence: float  # 0-1 confidence score
+    
+    # Sentiment analysis
+    sentiment_polarity: float  # -1 to 1 (negative to positive)
+    sentiment_subjectivity: float  # 0 to 1 (objective to subjective)
+    
+    # Detected emotions with scores
+    emotion_scores: Dict[str, float]
+    
+    # Contextual information
+    detected_emojis: List[str]
+    emotion_keywords: List[str]
+    intensity_level: str  # 'low', 'medium', 'high'
+    
+    # Generated artistic attributes
+    color_palette: List[str]
+    artistic_descriptors: List[str]
+    mood_modifiers: List[str]
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization"""
+        return {
+            'primary_emotion': self.primary_emotion.value,
+            'emotion_confidence': self.emotion_confidence,
+            'sentiment_polarity': self.sentiment_polarity,
+            'sentiment_subjectivity': self.sentiment_subjectivity,
+            'emotion_scores': self.emotion_scores,
+            'detected_emojis': self.detected_emojis,
+            'emotion_keywords': self.emotion_keywords,
+            'intensity_level': self.intensity_level,
+            'color_palette': self.color_palette,
+            'artistic_descriptors': self.artistic_descriptors,
+            'mood_modifiers': self.mood_modifiers
+        }
+
+class EmotionProcessor:
+    """Core emotion processing and analysis functionality"""
+    
+    def __init__(self):
+        """Initialize the emotion processor with predefined mappings"""
+        
+        # Predefined emotion sets
+        self.preset_emotions = {
+            "joyful": {"category": EmotionCategory.JOY, "intensity": "high", "emoji": "😊"},
+            "happy": {"category": EmotionCategory.JOY, "intensity": "medium", "emoji": "😄"},
+            "ecstatic": {"category": EmotionCategory.JOY, "intensity": "high", "emoji": "🤩"},
+            "sad": {"category": EmotionCategory.SADNESS, "intensity": "medium", "emoji": "😢"},
+            "melancholic": {"category": EmotionCategory.SADNESS, "intensity": "high", "emoji": "😔"},
+            "depressed": {"category": EmotionCategory.SADNESS, "intensity": "high", "emoji": "😞"},
+            "angry": {"category": EmotionCategory.ANGER, "intensity": "high", "emoji": "😡"},
+            "frustrated": {"category": EmotionCategory.ANGER, "intensity": "medium", "emoji": "😤"},
+            "furious": {"category": EmotionCategory.ANGER, "intensity": "high", "emoji": "🤬"},
+            "fearful": {"category": EmotionCategory.FEAR, "intensity": "high", "emoji": "😱"},
+            "anxious": {"category": EmotionCategory.FEAR, "intensity": "medium", "emoji": "😰"},
+            "nervous": {"category": EmotionCategory.FEAR, "intensity": "low", "emoji": "😬"},
+            "surprised": {"category": EmotionCategory.SURPRISE, "intensity": "medium", "emoji": "😲"},
+            "amazed": {"category": EmotionCategory.SURPRISE, "intensity": "high", "emoji": "🤯"},
+            "romantic": {"category": EmotionCategory.LOVE, "intensity": "high", "emoji": "💖"},
+            "loving": {"category": EmotionCategory.LOVE, "intensity": "medium", "emoji": "❤️"},
+            "peaceful": {"category": EmotionCategory.TRUST, "intensity": "medium", "emoji": "🕊️"},
+            "serene": {"category": EmotionCategory.TRUST, "intensity": "high", "emoji": "🌱"},
+            "mysterious": {"category": EmotionCategory.ANTICIPATION, "intensity": "medium", "emoji": "🕵️‍♂️"},
+            "nostalgic": {"category": EmotionCategory.SADNESS, "intensity": "medium", "emoji": "🕰️"},
+            "energetic": {"category": EmotionCategory.JOY, "intensity": "high", "emoji": "⚡"},
+            "whimsical": {"category": EmotionCategory.JOY, "intensity": "medium", "emoji": "🎠"},
+            "uplifting": {"category": EmotionCategory.JOY, "intensity": "high", "emoji": "🌞"},
+            "dark": {"category": EmotionCategory.SADNESS, "intensity": "high", "emoji": "🌑"},
+            "moody": {"category": EmotionCategory.SADNESS, "intensity": "medium", "emoji": "🌫️"}
+        }
+        
+        # Emotion-to-color mappings
+        self.emotion_colors = {
+            EmotionCategory.JOY: ["#FFD700", "#FFA500", "#FF69B4", "#00CED1", "#32CD32"],
+            EmotionCategory.SADNESS: ["#4169E1", "#6495ED", "#708090", "#2F4F4F", "#191970"],
+            EmotionCategory.ANGER: ["#DC143C", "#B22222", "#8B0000", "#FF4500", "#FF6347"],
+            EmotionCategory.FEAR: ["#800080", "#4B0082", "#2E2E2E", "#696969", "#A9A9A9"],
+            EmotionCategory.SURPRISE: ["#FF1493", "#FF69B4", "#FFB6C1", "#FFC0CB", "#FFFF00"],
+            EmotionCategory.LOVE: ["#FF69B4", "#DC143C", "#FF1493", "#C71585", "#DB7093"],
+            EmotionCategory.TRUST: ["#00CED1", "#20B2AA", "#48D1CC", "#40E0D0", "#AFEEEE"],
+            EmotionCategory.ANTICIPATION: ["#9370DB", "#8A2BE2", "#7B68EE", "#6A5ACD", "#483D8B"],
+            EmotionCategory.NEUTRAL: ["#808080", "#A9A9A9", "#C0C0C0", "#D3D3D3", "#DCDCDC"]
+        }
+        
+        # Artistic descriptors for each emotion
+        self.artistic_descriptors = {
+            EmotionCategory.JOY: ["vibrant", "luminous", "radiant", "effervescent", "sparkling"],
+            EmotionCategory.SADNESS: ["muted", "somber", "melancholic", "wistful", "contemplative"],
+            EmotionCategory.ANGER: ["intense", "fiery", "bold", "dramatic", "powerful"],
+            EmotionCategory.FEAR: ["shadowy", "mysterious", "ethereal", "haunting", "enigmatic"],
+            EmotionCategory.SURPRISE: ["dynamic", "explosive", "unexpected", "striking", "vivid"],
+            EmotionCategory.LOVE: ["warm", "tender", "passionate", "romantic", "intimate"],
+            EmotionCategory.TRUST: ["serene", "peaceful", "harmonious", "balanced", "tranquil"],
+            EmotionCategory.ANTICIPATION: ["electric", "suspenseful", "charged", "expectant", "tense"],
+            EmotionCategory.NEUTRAL: ["balanced", "calm", "steady", "composed", "neutral"]
+        }
+        
+        # Emoji to emotion mapping
+        self.emoji_emotions = {
+            "😊": EmotionCategory.JOY, "😄": EmotionCategory.JOY, "😃": EmotionCategory.JOY,
+            "🤩": EmotionCategory.JOY, "😍": EmotionCategory.LOVE, "🥰": EmotionCategory.LOVE,
+            "😢": EmotionCategory.SADNESS, "😭": EmotionCategory.SADNESS, "😔": EmotionCategory.SADNESS,
+            "😡": EmotionCategory.ANGER, "🤬": EmotionCategory.ANGER, "😤": EmotionCategory.ANGER,
+            "😱": EmotionCategory.FEAR, "😰": EmotionCategory.FEAR, "😨": EmotionCategory.FEAR,
+            "😲": EmotionCategory.SURPRISE, "😮": EmotionCategory.SURPRISE, "🤯": EmotionCategory.SURPRISE,
+            "❤️": EmotionCategory.LOVE, "💖": EmotionCategory.LOVE, "💕": EmotionCategory.LOVE,
+            "🕊️": EmotionCategory.TRUST, "🌱": EmotionCategory.TRUST, "☮️": EmotionCategory.TRUST
+        }
+        
+        # Keyword patterns for emotion detection
+        self.emotion_keywords = {
+            EmotionCategory.JOY: ["happy", "joyful", "cheerful", "delighted", "elated", "euphoric", "blissful"],
+            EmotionCategory.SADNESS: ["sad", "depressed", "melancholy", "sorrowful", "gloomy", "dejected"],
+            EmotionCategory.ANGER: ["angry", "furious", "rage", "irritated", "annoyed", "livid", "irate"],
+            EmotionCategory.FEAR: ["afraid", "scared", "terrified", "anxious", "worried", "nervous", "fearful"],
+            EmotionCategory.SURPRISE: ["surprised", "amazed", "astonished", "shocked", "stunned", "bewildered"],
+            EmotionCategory.LOVE: ["love", "romantic", "affectionate", "tender", "passionate", "adoring"],
+            EmotionCategory.TRUST: ["peaceful", "serene", "calm", "tranquil", "secure", "confident"],
+            EmotionCategory.ANTICIPATION: ["excited", "eager", "hopeful", "expectant", "anticipating"]
+        }
+    
+    def analyze_emotion(self, text: str, selected_emotion: Optional[str] = None) -> EmotionAnalysis:
+        """
+        Comprehensive emotion analysis of input text
+        
+        Args:
+            text: Input text to analyze
+            selected_emotion: Optional pre-selected emotion
+            
+        Returns:
+            EmotionAnalysis object with complete analysis
+        """
+        logger.info(f"Analyzing emotion for text: {text[:100]}...")
+        
+        # Initialize analysis components
+        detected_emojis = self._extract_emojis(text)
+        emotion_keywords = self._extract_emotion_keywords(text)
+        
+        # Determine primary emotion
+        if selected_emotion and selected_emotion.lower() in self.preset_emotions:
+            # Use selected emotion
+            emotion_info = self.preset_emotions[selected_emotion.lower()]
+            primary_emotion = emotion_info["category"]
+            emotion_confidence = 0.9
+            intensity_level = emotion_info["intensity"]
+        else:
+            # Analyze text for emotion
+            primary_emotion, emotion_confidence, intensity_level = self._analyze_text_emotion(text, detected_emojis, emotion_keywords)
+        
+        # Sentiment analysis
+        sentiment_polarity, sentiment_subjectivity = self._analyze_sentiment(text)
+        
+        # Generate emotion scores
+        emotion_scores = self._generate_emotion_scores(primary_emotion, emotion_confidence)
+        
+        # Generate artistic attributes
+        color_palette = self.emotion_colors.get(primary_emotion, self.emotion_colors[EmotionCategory.NEUTRAL])
+        artistic_descriptors = self.artistic_descriptors.get(primary_emotion, ["neutral"])
+        mood_modifiers = self._generate_mood_modifiers(primary_emotion, intensity_level)
+        
+        return EmotionAnalysis(
+            primary_emotion=primary_emotion,
+            emotion_confidence=emotion_confidence,
+            sentiment_polarity=sentiment_polarity,
+            sentiment_subjectivity=sentiment_subjectivity,
+            emotion_scores=emotion_scores,
+            detected_emojis=detected_emojis,
+            emotion_keywords=emotion_keywords,
+            intensity_level=intensity_level,
+            color_palette=color_palette[:3],  # Top 3 colors
+            artistic_descriptors=artistic_descriptors[:3],  # Top 3 descriptors
+            mood_modifiers=mood_modifiers
+        )
+
+    def _extract_emojis(self, text: str) -> List[str]:
+        """Extract emojis from text"""
+        if not EMOJI_AVAILABLE:
+            # Simple emoji detection using Unicode ranges
+            emoji_pattern = re.compile(
+                "["
+                "\U0001F600-\U0001F64F"  # emoticons
+                "\U0001F300-\U0001F5FF"  # symbols & pictographs
+                "\U0001F680-\U0001F6FF"  # transport & map symbols
+                "\U0001F1E0-\U0001F1FF"  # flags (iOS)
+                "\U00002702-\U000027B0"
+                "\U000024C2-\U0001F251"
+                "]+",
+                flags=re.UNICODE
+            )
+            return emoji_pattern.findall(text)
+        else:
+            return [char for char in text if char in emoji.UNICODE_EMOJI['en']]
+
+    def _extract_emotion_keywords(self, text: str) -> List[str]:
+        """Extract emotion-related keywords from text"""
+        text_lower = text.lower()
+        found_keywords = []
+
+        for emotion, keywords in self.emotion_keywords.items():
+            for keyword in keywords:
+                if keyword in text_lower:
+                    found_keywords.append(keyword)
+
+        return found_keywords
+
+    def _analyze_text_emotion(self, text: str, emojis: List[str], keywords: List[str]) -> Tuple[EmotionCategory, float, str]:
+        """Analyze emotion from text, emojis, and keywords"""
+
+        # Check emojis first
+        for emoji_char in emojis:
+            if emoji_char in self.emoji_emotions:
+                return self.emoji_emotions[emoji_char], 0.8, "medium"
+
+        # Check keywords
+        emotion_votes = {}
+        for keyword in keywords:
+            for emotion, emotion_keywords in self.emotion_keywords.items():
+                if keyword in emotion_keywords:
+                    emotion_votes[emotion] = emotion_votes.get(emotion, 0) + 1
+
+        if emotion_votes:
+            primary_emotion = max(emotion_votes, key=emotion_votes.get)
+            confidence = min(emotion_votes[primary_emotion] * 0.3, 0.9)
+            intensity = "high" if emotion_votes[primary_emotion] > 2 else "medium"
+            return primary_emotion, confidence, intensity
+
+        # Fallback to sentiment analysis
+        sentiment_polarity, _ = self._analyze_sentiment(text)
+
+        if sentiment_polarity > 0.3:
+            return EmotionCategory.JOY, 0.6, "medium"
+        elif sentiment_polarity < -0.3:
+            return EmotionCategory.SADNESS, 0.6, "medium"
+        else:
+            return EmotionCategory.NEUTRAL, 0.5, "low"
+
+    def _analyze_sentiment(self, text: str) -> Tuple[float, float]:
+        """Analyze sentiment using TextBlob or fallback method"""
+        if not text.strip():
+            return 0.0, 0.0
+
+        if TEXTBLOB_AVAILABLE:
+            try:
+                blob = TextBlob(text)
+                return blob.sentiment.polarity, blob.sentiment.subjectivity
+            except Exception as e:
+                logger.warning(f"TextBlob sentiment analysis failed: {e}")
+
+        # Simple fallback sentiment analysis
+        positive_words = ["good", "great", "excellent", "amazing", "wonderful", "fantastic", "love", "like", "happy", "joy"]
+        negative_words = ["bad", "terrible", "awful", "hate", "dislike", "sad", "angry", "fear", "worried", "depressed"]
+
+        text_lower = text.lower()
+        positive_count = sum(1 for word in positive_words if word in text_lower)
+        negative_count = sum(1 for word in negative_words if word in text_lower)
+
+        total_words = len(text.split())
+        if total_words == 0:
+            return 0.0, 0.0
+
+        polarity = (positive_count - negative_count) / max(total_words, 1)
+        subjectivity = (positive_count + negative_count) / max(total_words, 1)
+
+        return max(-1.0, min(1.0, polarity)), max(0.0, min(1.0, subjectivity))
+
+    def _generate_emotion_scores(self, primary_emotion: EmotionCategory, confidence: float) -> Dict[str, float]:
+        """Generate scores for all emotions"""
+        scores = {emotion.value: 0.1 for emotion in EmotionCategory}
+        scores[primary_emotion.value] = confidence
+
+        # Add some secondary emotions based on primary
+        secondary_emotions = {
+            EmotionCategory.JOY: [EmotionCategory.LOVE, EmotionCategory.TRUST],
+            EmotionCategory.SADNESS: [EmotionCategory.FEAR, EmotionCategory.NEUTRAL],
+            EmotionCategory.ANGER: [EmotionCategory.DISGUST, EmotionCategory.FEAR],
+            EmotionCategory.FEAR: [EmotionCategory.SADNESS, EmotionCategory.SURPRISE],
+            EmotionCategory.LOVE: [EmotionCategory.JOY, EmotionCategory.TRUST],
+            EmotionCategory.TRUST: [EmotionCategory.JOY, EmotionCategory.LOVE]
+        }
+
+        if primary_emotion in secondary_emotions:
+            for secondary in secondary_emotions[primary_emotion]:
+                scores[secondary.value] = min(0.4, confidence * 0.5)
+
+        return scores
+
+    def _generate_mood_modifiers(self, emotion: EmotionCategory, intensity: str) -> List[str]:
+        """Generate mood modifiers for prompt enhancement"""
+        base_modifiers = {
+            EmotionCategory.JOY: ["bright", "cheerful", "uplifting", "radiant"],
+            EmotionCategory.SADNESS: ["melancholic", "somber", "wistful", "contemplative"],
+            EmotionCategory.ANGER: ["intense", "dramatic", "powerful", "bold"],
+            EmotionCategory.FEAR: ["mysterious", "dark", "ethereal", "haunting"],
+            EmotionCategory.SURPRISE: ["dynamic", "striking", "unexpected", "vivid"],
+            EmotionCategory.LOVE: ["romantic", "warm", "tender", "passionate"],
+            EmotionCategory.TRUST: ["peaceful", "serene", "harmonious", "tranquil"],
+            EmotionCategory.ANTICIPATION: ["electric", "suspenseful", "charged", "expectant"],
+            EmotionCategory.NEUTRAL: ["balanced", "calm", "neutral", "composed"]
+        }
+
+        modifiers = base_modifiers.get(emotion, ["neutral"])
+
+        # Adjust based on intensity
+        if intensity == "high":
+            intensity_modifiers = ["very", "extremely", "deeply", "intensely"]
+            return [f"{intensity_modifiers[0]} {mod}" for mod in modifiers[:2]]
+        elif intensity == "low":
+            return [f"subtly {mod}" for mod in modifiers[:2]]
+        else:
+            return modifiers[:3]
+
+
+class EmotionalPromptEnhancer:
+    """Enhance prompts with emotional context"""
+
+    def __init__(self):
+        """Initialize the prompt enhancer"""
+        self.emotion_processor = EmotionProcessor()
+
+    def enhance_prompt_with_emotion(
+        self,
+        base_prompt: str,
+        style: str,
+        emotion_analysis: EmotionAnalysis,
+        enhancement_strength: float = 0.7
+    ) -> str:
+        """
+        Enhance prompt with emotional context
+
+        Args:
+            base_prompt: Original text prompt
+            style: Art style
+            emotion_analysis: Emotion analysis results
+            enhancement_strength: How strongly to apply emotion (0-1)
+
+        Returns:
+            Enhanced prompt with emotional context
+        """
+        enhanced_prompt = base_prompt.strip()
+
+        # Add style
+        if style:
+            enhanced_prompt += f", {style}"
+
+        # Add emotional descriptors based on strength
+        if enhancement_strength > 0.5:
+            # Strong emotional enhancement
+            descriptors = emotion_analysis.artistic_descriptors[:2]
+            mood_modifiers = emotion_analysis.mood_modifiers[:2]
+
+            enhanced_prompt += f", {', '.join(descriptors)}"
+            enhanced_prompt += f", with a {', '.join(mood_modifiers)} atmosphere"
+
+            # Add intensity if high
+            if emotion_analysis.intensity_level == "high":
+                enhanced_prompt += f", deeply {emotion_analysis.primary_emotion.value}"
+
+        elif enhancement_strength > 0.2:
+            # Moderate emotional enhancement
+            descriptor = emotion_analysis.artistic_descriptors[0]
+            mood = emotion_analysis.mood_modifiers[0]
+
+            enhanced_prompt += f", {descriptor}, {mood}"
+
+        else:
+            # Subtle emotional enhancement
+            if emotion_analysis.artistic_descriptors:
+                enhanced_prompt += f", {emotion_analysis.artistic_descriptors[0]}"
+
+        return enhanced_prompt
+
+    def generate_emotion_tags(self, emotion_analysis: EmotionAnalysis) -> List[str]:
+        """Generate descriptive tags for the emotion"""
+        tags = []
+
+        # Primary emotion
+        tags.append(emotion_analysis.primary_emotion.value)
+
+        # Intensity
+        tags.append(f"{emotion_analysis.intensity_level}_intensity")
+
+        # Sentiment
+        if emotion_analysis.sentiment_polarity > 0.3:
+            tags.append("positive_sentiment")
+        elif emotion_analysis.sentiment_polarity < -0.3:
+            tags.append("negative_sentiment")
+        else:
+            tags.append("neutral_sentiment")
+
+        # Artistic descriptors
+        tags.extend(emotion_analysis.artistic_descriptors[:2])
+
+        return tags

src/utils/file_utils.py

@@ -0,0 +1,149 @@
+"""
+File handling utilities for CompI project.
+"""
+
+import json
+import yaml
+from pathlib import Path
+from typing import Dict, Any, Union
+from PIL import Image
+import soundfile as sf
+import numpy as np
+
+from src.config import OUTPUTS_DIR
+
+def save_image(image: Image.Image, filename: str, subfolder: str = "images") -> Path:
+    """
+    Save a PIL Image to the outputs directory.
+    
+    Args:
+        image: PIL Image to save
+        filename: Name of the file (with extension)
+        subfolder: Subfolder within outputs directory
+        
+    Returns:
+        Path to saved file
+    """
+    output_dir = OUTPUTS_DIR / subfolder
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    file_path = output_dir / filename
+    image.save(file_path)
+    
+    return file_path
+
+def save_audio(audio_data: np.ndarray, filename: str, 
+               sample_rate: int = 22050, subfolder: str = "audio") -> Path:
+    """
+    Save audio data to the outputs directory.
+    
+    Args:
+        audio_data: Audio data as numpy array
+        filename: Name of the file (with extension)
+        sample_rate: Audio sample rate
+        subfolder: Subfolder within outputs directory
+        
+    Returns:
+        Path to saved file
+    """
+    output_dir = OUTPUTS_DIR / subfolder
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    file_path = output_dir / filename
+    sf.write(file_path, audio_data, sample_rate)
+    
+    return file_path
+
+def load_config(config_path: Union[str, Path]) -> Dict[str, Any]:
+    """
+    Load configuration from JSON or YAML file.
+    
+    Args:
+        config_path: Path to configuration file
+        
+    Returns:
+        Configuration dictionary
+    """
+    config_path = Path(config_path)
+    
+    if not config_path.exists():
+        raise FileNotFoundError(f"Configuration file not found: {config_path}")
+    
+    with open(config_path, 'r') as f:
+        if config_path.suffix.lower() in ['.yml', '.yaml']:
+            return yaml.safe_load(f)
+        elif config_path.suffix.lower() == '.json':
+            return json.load(f)
+        else:
+            raise ValueError(f"Unsupported config file format: {config_path.suffix}")
+
+def ensure_dir(path: Union[str, Path]) -> Path:
+    """
+    Ensure directory exists, create if it doesn't.
+
+    Args:
+        path: Directory path
+
+    Returns:
+        Path object
+    """
+    path = Path(path)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+def ensure_directory_exists(path: Union[str, Path]) -> Path:
+    """
+    Alias for ensure_dir for backward compatibility.
+
+    Args:
+        path: Directory path
+
+    Returns:
+        Path object
+    """
+    return ensure_dir(path)
+
+def generate_filename(prompt: str, style: str = "", mood: str = "",
+                     seed: int = 0, variation: int = 1,
+                     has_audio: bool = False, max_length: int = 100) -> str:
+    """
+    Generate a descriptive filename for generated images.
+
+    Args:
+        prompt: Text prompt used for generation
+        style: Art style
+        mood: Mood/atmosphere
+        seed: Random seed used
+        variation: Variation number
+        has_audio: Whether audio was used in generation
+        max_length: Maximum filename length
+
+    Returns:
+        Generated filename (without extension)
+    """
+    import re
+    from datetime import datetime
+
+    # Clean and truncate prompt
+    prompt_clean = re.sub(r'[^\w\s-]', '', prompt.lower())
+    prompt_slug = "_".join(prompt_clean.split()[:6])[:30]
+
+    # Clean style and mood
+    style_slug = re.sub(r'[^\w]', '', style.lower())[:10] if style else ""
+    mood_slug = re.sub(r'[^\w]', '', mood.lower())[:10] if mood else ""
+
+    # Timestamp
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+    # Audio indicator
+    audio_tag = "_audio" if has_audio else ""
+
+    # Combine all parts
+    parts = [prompt_slug, style_slug, mood_slug, timestamp, f"seed{seed}", f"v{variation}"]
+    filename = "_".join(filter(None, parts)) + audio_tag
+
+    # Truncate if too long
+    if len(filename) > max_length:
+        filename = filename[:max_length]
+
+    return filename

src/utils/image_utils.py

@@ -0,0 +1,309 @@
+"""
+Image processing utilities for CompI Phase 2.E: Style Reference/Example Image Integration
+
+This module provides utilities for:
+- Image loading from files and URLs
+- Image validation and preprocessing
+- Style analysis and feature extraction
+- Image format conversion and optimization
+"""
+
+import os
+import io
+import requests
+import hashlib
+from typing import Optional, Tuple, Dict, Any, Union, List
+from pathlib import Path
+import logging
+
+import torch
+import numpy as np
+from PIL import Image, ImageStat, ImageFilter
+import cv2
+
+from src.utils.logging_utils import setup_logger
+
+logger = setup_logger(__name__)
+
+class ImageProcessor:
+    """
+    Handles image loading, validation, and preprocessing for style reference
+    """
+    
+    def __init__(self, max_size: Tuple[int, int] = (1024, 1024)):
+        self.max_size = max_size
+        self.supported_formats = {'.jpg', '.jpeg', '.png', '.bmp', '.tiff', '.webp'}
+        
+    def load_image_from_url(
+        self, 
+        url: str, 
+        timeout: int = 10,
+        max_file_size: int = 10 * 1024 * 1024  # 10MB
+    ) -> Optional[Image.Image]:
+        """
+        Load image from URL with validation and error handling
+        
+        Args:
+            url: Image URL
+            timeout: Request timeout in seconds
+            max_file_size: Maximum file size in bytes
+            
+        Returns:
+            PIL Image or None if failed
+        """
+        try:
+            logger.info(f"Loading image from URL: {url}")
+            
+            # Validate URL format
+            if not url.startswith(('http://', 'https://')):
+                logger.error(f"Invalid URL format: {url}")
+                return None
+                
+            # Make request with headers to avoid blocking
+            headers = {
+                'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
+            }
+            
+            response = requests.get(url, timeout=timeout, headers=headers, stream=True)
+            response.raise_for_status()
+            
+            # Check content type
+            content_type = response.headers.get('content-type', '').lower()
+            if not any(img_type in content_type for img_type in ['image/', 'jpeg', 'png', 'webp']):
+                logger.error(f"Invalid content type: {content_type}")
+                return None
+                
+            # Check file size
+            content_length = response.headers.get('content-length')
+            if content_length and int(content_length) > max_file_size:
+                logger.error(f"File too large: {content_length} bytes")
+                return None
+                
+            # Load image data
+            image_data = io.BytesIO()
+            downloaded_size = 0
+            
+            for chunk in response.iter_content(chunk_size=8192):
+                downloaded_size += len(chunk)
+                if downloaded_size > max_file_size:
+                    logger.error(f"File too large during download: {downloaded_size} bytes")
+                    return None
+                image_data.write(chunk)
+                
+            image_data.seek(0)
+            
+            # Open and validate image
+            image = Image.open(image_data)
+            image = image.convert('RGB')
+            
+            logger.info(f"Successfully loaded image: {image.size}")
+            return image
+            
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request error loading image from {url}: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Error loading image from {url}: {e}")
+            return None
+            
+    def load_image_from_file(self, file_path: Union[str, Path]) -> Optional[Image.Image]:
+        """
+        Load image from local file with validation
+        
+        Args:
+            file_path: Path to image file
+            
+        Returns:
+            PIL Image or None if failed
+        """
+        try:
+            file_path = Path(file_path)
+            
+            if not file_path.exists():
+                logger.error(f"File does not exist: {file_path}")
+                return None
+                
+            if file_path.suffix.lower() not in self.supported_formats:
+                logger.error(f"Unsupported format: {file_path.suffix}")
+                return None
+                
+            image = Image.open(file_path)
+            image = image.convert('RGB')
+            
+            logger.info(f"Successfully loaded image from file: {image.size}")
+            return image
+            
+        except Exception as e:
+            logger.error(f"Error loading image from {file_path}: {e}")
+            return None
+            
+    def preprocess_image(
+        self, 
+        image: Image.Image, 
+        target_size: Optional[Tuple[int, int]] = None,
+        maintain_aspect_ratio: bool = True
+    ) -> Image.Image:
+        """
+        Preprocess image for stable diffusion
+        
+        Args:
+            image: Input PIL Image
+            target_size: Target size (width, height)
+            maintain_aspect_ratio: Whether to maintain aspect ratio
+            
+        Returns:
+            Preprocessed PIL Image
+        """
+        if target_size is None:
+            target_size = (512, 512)  # Default SD size
+            
+        try:
+            # Resize image
+            if maintain_aspect_ratio:
+                image.thumbnail(target_size, Image.Resampling.LANCZOS)
+                
+                # Create new image with target size and paste resized image
+                new_image = Image.new('RGB', target_size, (255, 255, 255))
+                paste_x = (target_size[0] - image.width) // 2
+                paste_y = (target_size[1] - image.height) // 2
+                new_image.paste(image, (paste_x, paste_y))
+                image = new_image
+            else:
+                image = image.resize(target_size, Image.Resampling.LANCZOS)
+                
+            logger.info(f"Preprocessed image to size: {image.size}")
+            return image
+            
+        except Exception as e:
+            logger.error(f"Error preprocessing image: {e}")
+            return image
+            
+    def analyze_image_properties(self, image: Image.Image) -> Dict[str, Any]:
+        """
+        Analyze image properties for style reference
+        
+        Args:
+            image: PIL Image to analyze
+            
+        Returns:
+            Dictionary of image properties
+        """
+        try:
+            # Basic properties
+            width, height = image.size
+            aspect_ratio = width / height
+            
+            # Color analysis
+            stat = ImageStat.Stat(image)
+            avg_brightness = sum(stat.mean) / len(stat.mean)
+            avg_contrast = sum(stat.stddev) / len(stat.stddev)
+            
+            # Convert to numpy for additional analysis
+            img_array = np.array(image)
+            
+            # Color distribution
+            r_mean, g_mean, b_mean = np.mean(img_array, axis=(0, 1))
+            color_variance = np.var(img_array, axis=(0, 1))
+            
+            # Edge detection for complexity
+            gray = cv2.cvtColor(img_array, cv2.COLOR_RGB2GRAY)
+            edges = cv2.Canny(gray, 50, 150)
+            edge_density = np.sum(edges > 0) / (width * height)
+            
+            properties = {
+                'dimensions': (width, height),
+                'aspect_ratio': aspect_ratio,
+                'brightness': avg_brightness,
+                'contrast': avg_contrast,
+                'color_means': (float(r_mean), float(g_mean), float(b_mean)),
+                'color_variance': color_variance.tolist(),
+                'edge_density': float(edge_density),
+                'file_size_pixels': width * height
+            }
+            
+            logger.info(f"Analyzed image properties: {properties}")
+            return properties
+            
+        except Exception as e:
+            logger.error(f"Error analyzing image properties: {e}")
+            return {}
+            
+    def generate_image_hash(self, image: Image.Image) -> str:
+        """
+        Generate hash for image deduplication
+        
+        Args:
+            image: PIL Image
+            
+        Returns:
+            MD5 hash string
+        """
+        try:
+            # Convert image to bytes
+            img_bytes = io.BytesIO()
+            image.save(img_bytes, format='PNG')
+            img_bytes = img_bytes.getvalue()
+            
+            # Generate hash
+            hash_md5 = hashlib.md5(img_bytes)
+            return hash_md5.hexdigest()
+            
+        except Exception as e:
+            logger.error(f"Error generating image hash: {e}")
+            return ""
+
+class StyleAnalyzer:
+    """
+    Analyzes style characteristics of reference images
+    """
+    
+    def __init__(self):
+        self.style_keywords = {
+            'realistic': ['photo', 'realistic', 'detailed', 'sharp'],
+            'artistic': ['painting', 'artistic', 'brushstrokes', 'canvas'],
+            'anime': ['anime', 'manga', 'cartoon', 'stylized'],
+            'abstract': ['abstract', 'geometric', 'surreal', 'conceptual'],
+            'vintage': ['vintage', 'retro', 'aged', 'classic'],
+            'modern': ['modern', 'contemporary', 'clean', 'minimal']
+        }
+        
+    def suggest_style_keywords(self, image_properties: Dict[str, Any]) -> List[str]:
+        """
+        Suggest style keywords based on image analysis
+        
+        Args:
+            image_properties: Properties from analyze_image_properties
+            
+        Returns:
+            List of suggested style keywords
+        """
+        suggestions = []
+        
+        try:
+            brightness = image_properties.get('brightness', 128)
+            contrast = image_properties.get('contrast', 50)
+            edge_density = image_properties.get('edge_density', 0.1)
+            
+            # Brightness-based suggestions
+            if brightness < 100:
+                suggestions.extend(['dark', 'moody', 'dramatic'])
+            elif brightness > 180:
+                suggestions.extend(['bright', 'light', 'airy'])
+                
+            # Contrast-based suggestions
+            if contrast > 80:
+                suggestions.extend(['high contrast', 'bold', 'striking'])
+            elif contrast < 30:
+                suggestions.extend(['soft', 'gentle', 'muted'])
+                
+            # Edge density-based suggestions
+            if edge_density > 0.2:
+                suggestions.extend(['detailed', 'complex', 'intricate'])
+            elif edge_density < 0.05:
+                suggestions.extend(['smooth', 'simple', 'minimalist'])
+                
+            return list(set(suggestions))  # Remove duplicates
+            
+        except Exception as e:
+            logger.error(f"Error suggesting style keywords: {e}")
+            return []

src/utils/logging_utils.py

@@ -0,0 +1,45 @@
+"""
+Logging utilities for CompI project.
+"""
+
+import logging
+import sys
+from pathlib import Path
+from src.config import LOG_LEVEL, LOG_FORMAT, PROJECT_ROOT
+
+def setup_logger(name: str, log_file: str = None) -> logging.Logger:
+    """
+    Set up a logger with console and optional file output.
+    
+    Args:
+        name: Logger name
+        log_file: Optional log file path
+        
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(getattr(logging, LOG_LEVEL.upper()))
+    
+    # Clear existing handlers
+    logger.handlers.clear()
+    
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(logging.INFO)
+    console_formatter = logging.Formatter(LOG_FORMAT)
+    console_handler.setFormatter(console_formatter)
+    logger.addHandler(console_handler)
+    
+    # File handler (optional)
+    if log_file:
+        log_path = PROJECT_ROOT / "logs"
+        log_path.mkdir(exist_ok=True)
+        
+        file_handler = logging.FileHandler(log_path / log_file)
+        file_handler.setLevel(logging.DEBUG)
+        file_formatter = logging.Formatter(LOG_FORMAT)
+        file_handler.setFormatter(file_formatter)
+        logger.addHandler(file_handler)
+    
+    return logger