cwicr-crew-optimizer

# CWICR Crew Optimizer

## Business Case

### Problem Statement
Crew planning challenges:
- Right mix of workers?
- Optimal crew size?
- Balance cost vs productivity?
- Match skills to work?

### Solution
Optimize crew composition using CWICR labor productivity data to balance cost, output, and skill requirements.

### Business Value
- **Optimal productivity** - Right-sized crews
- **Cost efficiency** - No overstaffing
- **Skill matching** - Proper worker mix
- **Schedule support** - Meet deadlines

## Technical Implementation

```python
import pandas as pd
import numpy as np
from typing import Dict, Any, List, Optional, Tuple
from dataclasses import dataclass, field
from enum import Enum
from datetime import date, timedelta


class WorkerType(Enum):
    """Types of workers."""
    FOREMAN = "foreman"
    JOURNEYMAN = "journeyman"
    APPRENTICE = "apprentice"
    LABORER = "laborer"
    OPERATOR = "operator"
    HELPER = "helper"


class Trade(Enum):
    """Construction trades."""
    CONCRETE = "concrete"
    CARPENTRY = "carpentry"
    MASONRY = "masonry"
    STEEL = "steel"
    ELECTRICAL = "electrical"
    PLUMBING = "plumbing"
    HVAC = "hvac"
    PAINTING = "painting"
    ROOFING = "roofing"
    GENERAL = "general"


@dataclass
class Worker:
    """Worker definition."""
    worker_type: WorkerType
    trade: Trade
    hourly_rate: float
    productivity_factor: float = 1.0
    overtime_multiplier: float = 1.5


@dataclass
class CrewComposition:
    """Crew composition."""
    name: str
    trade: Trade
    workers: List[Tuple[WorkerType, int]]  # (type, count)
    base_productivity: float  # Output per hour
    hourly_cost: float
    daily_output: float


@dataclass
class CrewOptimizationResult:
    """Result of crew optimization."""
    work_item: str
    quantity: float
    unit: str
    recommended_crew: CrewComposition
    alternative_crews: List[CrewComposition]
    duration_days: float
    total_labor_cost: float
    cost_per_unit: float


# Standard crew compositions
STANDARD_CREWS = {
    'concrete_small': {
        'trade': Trade.CONCRETE,
        'workers': [(WorkerType.FOREMAN, 1), (WorkerType.JOURNEYMAN, 2), (WorkerType.LABORER, 2)],
        'productivity': 1.0
    },
    'concrete_large': {
        'trade': Trade.CONCRETE,
        'workers': [(WorkerType.FOREMAN, 1), (WorkerType.JOURNEYMAN, 4), (WorkerType.LABORER, 4), (WorkerType.OPERATOR, 1)],
        'productivity': 1.8
    },
    'masonry_standard': {
        'trade': Trade.MASONRY,
        'workers': [(WorkerType.FOREMAN, 1), (WorkerType.JOURNEYMAN, 2), (WorkerType.HELPER, 2)],
        'productivity': 1.0
    },
    'carpentry_framing': {
        'trade': Trade.CARPENTRY,
        'workers': [(WorkerType.FOREMAN, 1), (WorkerType.JOURNEYMAN, 3), (WorkerType.APPRENTICE, 1)],
        'productivity': 1.0
    },
    'electrical_rough': {
        'trade': Trade.ELECTRICAL,
        'workers': [(WorkerType.FOREMAN, 1), (WorkerType.JOURNEYMAN, 2), (WorkerType.APPRENTICE, 1)],
        'productivity': 1.0
    },
    'plumbing_rough': {
        'trade': Trade.PLUMBING,
        'workers': [(WorkerType.FOREMAN, 1), (WorkerType.JOURNEYMAN, 2), (WorkerType.APPRENTICE, 1)],
        'productivity': 1.0
    }
}

# Default hourly rates by worker type
DEFAULT_RATES = {
    WorkerType.FOREMAN: 65,
    WorkerType.JOURNEYMAN: 55,
    WorkerType.APPRENTICE: 35,
    WorkerType.LABORER: 30,
    WorkerType.OPERATOR: 60,
    WorkerType.HELPER: 28
}


class CWICRCrewOptimizer:
    """Optimize crew composition using CWICR data."""

    HOURS_PER_DAY = 8

    def __init__(self,
                 cwicr_data: pd.DataFrame = None,
                 custom_rates: Dict[WorkerType, float] = None):
        self.cost_data = cwicr_data
        self.rates = custom_rates or DEFAULT_RATES
        if cwicr_data is not None:
            self._index_data()

    def _index_data(self):
        """Index cost data."""
        if 'work_item_code' in self.cost_data.columns:
            self._code_index = self.cost_data.set_index('work_item_code')
        else:
            self._code_index = None

    def get_labor_norm(self, code: str) -> Tuple[float, str]:
        """Get labor hours per unit from CWICR."""
        if self._code_index is None or code not in self._code_index.index:
            return (1.0, 'unit')

        item = self._code_index.loc[code]
        norm = float(item.get('labor_norm', item.get('labor_hours', 1)) or 1)
        unit = str(item.get('unit', 'unit'))

        return (norm, unit)

    def calculate_crew_cost(self, workers: List[Tuple[WorkerType, int]]) -> float:
        """Calculate hourly cost of crew."""
        total = 0
        for worker_type, count in workers:
            rate = self.rates.get(worker_type, 40)
            total += rate * count
        return total

    def build_crew(self,
                   name: str,
                   trade: Trade,
                   workers: List[Tuple[WorkerType, int]],
                   base_productivity: float = 1.0) -> CrewComposition:
        """Build crew composition."""

        hourly_cost = self.calculate_crew_cost(workers)
        daily_output = base_productivity * self.HOURS_PER_DAY

        return CrewComposition(
            name=name,
            trade=trade,
            workers=workers,
            base_productivity=base_productivity,
            hourly_cost=hourly_cost,
            daily_output=daily_output
        )

    def optimize_for_work(self,
                           work_item_code: str,
                           quantity: float,
                           target_days: int = None,
                           max_crew_size: int = 10) -> CrewOptimizationResult:
        """Optimize crew for specific work item."""

        labor_norm, unit = self.get_labor_norm(work_item_code)
        total_hours = quantity * labor_norm

        # Detect trade from code
        trade = self._detect_trade(work_item_code)

        # Generate crew options
        crews = []

        # Small crew