STREAMLIT_README.md

SD Roster Optimization Tool - Multi-Page Streamlit Interface

A comprehensive multi-page Streamlit web application for supply chain roster optimization using OR-Tools.

🏗️ Application Structure

🏠 Home Page

• Welcome Dashboard: Overview and navigation hub
• Global Settings: Shared data path and date configuration
• System Status: Component availability and health checks
• Quick Navigation: Direct links to main functionalities

📊 Dataset Metadata Page

Comprehensive data analysis across five detailed tabs:

📋 Data Overview Tab

• Key Metrics: Orders, quantities, products, employees, production lines
• Data Quality Analysis: Completeness scores and missing data indicators
• Data Freshness: Latest data timestamps and age indicators

📦 Demand Analysis Tab

• Demand Metrics: Total, average, max, min order sizes
• Top Products: Ranking by demand volume with visualizations
• Daily Patterns: Trend analysis and demand variability
• Distribution Analysis: Order quantity and frequency distributions

👥 Workforce Analysis Tab

• Employee Metrics: Total staff, types, distribution
• Cost Structure: Hourly rates by employee type and shift
• Productivity Analysis: Performance metrics by employee type

🏭 Production Capacity Tab

• Line Metrics: Total lines, types, maximum capacities
• Capacity Distribution: Line allocation and utilization potential
• Theoretical Analysis: Maximum capacity calculations by shift

💰 Cost Analysis Tab

• Cost Structure: Min/max/average hourly rates and ranges
• Budget Planning: Minimum and maximum cost scenarios
• Projections: Weekly and monthly cost estimates

🎯 Optimization Page

Advanced optimization interface with comprehensive results:

📊 Summary Tab

• Total optimization cost and key metrics
• Cost efficiency analysis (cost per day, cost per unit)
• Optimization parameters used

📈 Production Tab

• Production vs. demand comparison by product
• Fulfillment rate analysis with interactive charts
• Production schedule visualization

👷 Labor Tab

• Labor allocation by employee type and shift
• Required headcount analysis
• Daily and average staffing requirements

💰 Costs Tab

• Detailed cost breakdown by employee type and shift
• Cost distribution visualizations
• Priority mode analysis (when applicable)

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Run the Application

# Option 1: Using the runner script
python run_streamlit.py

# Option 2: Direct streamlit command
streamlit run Home.py

3. Access the Application

Open your browser to: http://localhost:8501

Usage Guide

Navigation Flow

1. Start at Home: Configure global settings and navigate to specific functions
2. Explore Metadata: Analyze your data across the comprehensive metadata tabs
3. Run Optimization: Configure parameters and execute optimization on the dedicated page
4. Analyze Results: Review detailed results across multiple result tabs

Page-by-Page Guide

1. Home Page: Set data paths, select date ranges, check system status
2. Dataset Metadata: Deep dive into demand, workforce, capacity, and cost analysis
3. Optimization: Configure optimization parameters, run optimization, analyze results

Technical Details

Optimization Engine

• Built on Google OR-Tools for mixed-integer programming
• Supports multiple constraint modes for realistic business scenarios
• Handles complex multi-product, multi-shift, multi-line scheduling

Data Sources

The application automatically loads data from:

• COOIS_Released_Prod_Orders.csv - Production orders and demand
• Employee data files - Staff availability and costs
• Production line configuration - Line capacities and capabilities

Configuration

Key optimization parameters can be adjusted in src/config/optimization_config.py:

• Employee types and costs
• Shift definitions and durations
• Production line capacities
• Constraint modes and business rules

Business Scenarios

Priority Mode (Recommended)

• Uses UNICEF Fixed term staff first
• Engages Humanizer staff only when fixed staff at capacity
• Reflects realistic business operations

Mandatory Mode

• Forces all fixed staff to work full hours
• More expensive but ensures full utilization
• Useful for guaranteed staffing scenarios

Demand-Driven Mode

• Purely cost-optimized scheduling
• No mandatory fixed hours
• Most cost-efficient but may underutilize staff

Troubleshooting

Common Issues

1. No Date Ranges Available: Ensure your data files are in the correct location
2. Optimization Fails: Check that demand data exists for the selected date range
3. Import Errors: Verify all dependencies are installed

Performance Tips

• Smaller date ranges optimize faster
• Reducing product count can improve solve time
• Priority mode typically solves faster than mandatory mode

File Structure

Home.py                   # Main home page (entry point)
pages/
  ├── 1_📊_Dataset_Metadata.py  # Comprehensive data analysis page
  └── 2_🎯_Optimization.py      # Optimization interface and results
run_streamlit.py          # Convenient runner script  
src/
  ├── models/optimizer_real.py  # Core optimization engine
  ├── config/optimization_config.py  # Configuration parameters
  └── etl/                # Data extraction and transformation
streamlit_app_old.py      # Backup of original single-page app

Support

For technical issues or feature requests, refer to the main project documentation or contact the development team.