docs/PROJECT_STRUCTURE.md

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:

# 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:

# 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.