cwicr-resource-analyzer

# CWICR Resource Analyzer

## Business Case

### Problem Statement
Construction projects require precise resource planning:
- How many labor hours are needed?
- What materials need to be procured?
- What equipment is required and for how long?

Traditional methods rely on experience-based estimates, leading to over/under allocation.

### Solution
Data-driven resource analysis using CWICR's 27,672 resources with detailed breakdowns of labor norms, material requirements, and equipment usage.

### Business Value
- **Accurate planning** - Based on validated resource norms
- **Cost optimization** - Identify resource inefficiencies
- **Procurement support** - Generate material lists
- **Labor planning** - Calculate crew requirements

## Technical Implementation

### Python 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 collections import defaultdict


class ResourceType(Enum):
    """Types of construction resources."""
    LABOR = "labor"
    MATERIAL = "material"
    EQUIPMENT = "equipment"
    SUBCONTRACT = "subcontract"


class LaborCategory(Enum):
    """Labor skill categories."""
    UNSKILLED = "unskilled"
    SEMI_SKILLED = "semi_skilled"
    SKILLED = "skilled"
    FOREMAN = "foreman"
    SUPERVISOR = "supervisor"
    SPECIALIST = "specialist"


class EquipmentCategory(Enum):
    """Equipment categories."""
    EARTHMOVING = "earthmoving"
    LIFTING = "lifting"
    CONCRETE = "concrete"
    TRANSPORT = "transport"
    COMPACTION = "compaction"
    PUMPING = "pumping"
    POWER_TOOLS = "power_tools"
    SCAFFOLDING = "scaffolding"


@dataclass
class LaborResource:
    """Represents a labor resource."""
    resource_code: str
    description: str
    category: LaborCategory
    hourly_rate: float
    skill_level: int
    productivity_factor: float = 1.0


@dataclass
class MaterialResource:
    """Represents a material resource."""
    resource_code: str
    description: str
    unit: str
    unit_price: float
    category: str
    waste_factor: float = 0.05  # 5% default waste


@dataclass
class EquipmentResource:
    """Represents an equipment resource."""
    resource_code: str
    description: str
    category: EquipmentCategory
    hourly_rate: float
    daily_rate: float
    monthly_rate: float
    fuel_consumption: float = 0.0  # liters per hour
    operator_required: bool = True


@dataclass
class ResourceRequirement:
    """Calculated resource requirement."""
    resource_code: str
    description: str
    resource_type: ResourceType
    quantity: float
    unit: str
    unit_cost: float
    total_cost: float
    duration_hours: float = 0.0


@dataclass
class ResourceSummary:
    """Summary of all resource requirements."""
    labor_hours: float
    labor_cost: float
    material_cost: float
    equipment_cost: float
    total_cost: float

    labor_by_category: Dict[str, float] = field(default_factory=dict)
    materials_list: List[Dict[str, Any]] = field(default_factory=list)
    equipment_list: List[Dict[str, Any]] = field(default_factory=list)


class CWICRResourceAnalyzer:
    """Analyze resources from CWICR database."""

    def __init__(self, cwicr_data: pd.DataFrame,
                 resources_data: Optional[pd.DataFrame] = None):
        self.work_items = cwicr_data
        self.resources = resources_data

        # Create indexes
        self._index_work_items()
        if resources_data is not None:
            self._index_resources()

    def _index_work_items(self):
        """Index work items for fast lookup."""
        if 'work_item_code' in self.work_items.columns:
            self._work_index = self.work_items.set_index('work_item_code')
        else:
            self._work_index = None

    def _index_resources(self):
        """Index resources for fast lookup."""
        if self.resources is not None and 'resource_code' in self.resources.columns:
            self._resource_index = self.resources.set_index('resource_code')
        else:
            self._resource_index = None

    def analyze_labor_requirements(self, items: List[Dict[str, Any]]) -> Dict[str, Any]:
        """Analyze labor requirements for work items."""

        total_hours = 0.0
        labor_by_category = defaultdict(float)
        labor_by_skill = defaultdict(float)
        labor_details = []

        for item in items:
            code = item.get('work_item_code', item.get('code'))
            qty = item.get('quantity', 0)

            if self._work_index is not None and code in self._work_index.index:
                work_item = self._work_index.loc[code]
                labor_norm = float(work_item.get('labor_norm', 0) or 0)
                hours = labor_norm * qty

                total_hours += hours

                # Get category if available
                category = str(work_item.get('category', 'General'))
                labor_by_category[category] += hours

                labor_details.append({
                    'work_item_code': code,
                    'description': work_item.get('description', ''),
                    'quantity': qty,
                    'labor_norm': labor_norm,
                    'total_hours': hours
                })

        return {
            'total_labor_hours': round(total_hours, 2),
            'labor_by_category': dict(labor_by_category),
            'crew_days_8hr': round(total_hours / 8, 1),
            'crew_weeks_40hr': round(total_hours / 40, 1),
            'details': labor_details
        }

    def analyze_material_requirements(self, items: List[Dict[str, Any]],
                                       include_waste: bool = True) -> Dict[str, Any]:
        """Analyze material requirements."""

        materials = defaultdict(lambda: {'quantity': 0, 'unit': '', 'cost': 0})
        total_cost = 0.0

        for item in items:
            code = item.get('work_item_code', item.get('code'))
            q