calminer/models/metadata.py

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum


class ResourceType(str, Enum):
    """Primary consumables and resources used in mining operations."""

    DIESEL = "diesel"
    ELECTRICITY = "electricity"
    WATER = "water"
    EXPLOSIVES = "explosives"
    REAGENTS = "reagents"
    LABOR = "labor"
    EQUIPMENT_HOURS = "equipment_hours"
    TAILINGS_CAPACITY = "tailings_capacity"


class CostBucket(str, Enum):
    """Granular cost buckets aligned with project accounting."""

    CAPITAL_INITIAL = "capital_initial"
    CAPITAL_SUSTAINING = "capital_sustaining"
    OPERATING_FIXED = "operating_fixed"
    OPERATING_VARIABLE = "operating_variable"
    MAINTENANCE = "maintenance"
    RECLAMATION = "reclamation"
    ROYALTIES = "royalties"
    GENERAL_ADMIN = "general_admin"


class StochasticVariable(str, Enum):
    """Domain variables that typically require probabilistic modelling."""

    ORE_GRADE = "ore_grade"
    RECOVERY_RATE = "recovery_rate"
    METAL_PRICE = "metal_price"
    OPERATING_COST = "operating_cost"
    CAPITAL_COST = "capital_cost"
    DISCOUNT_RATE = "discount_rate"
    THROUGHPUT = "throughput"


@dataclass(frozen=True)
class ResourceDescriptor:
    """Describes canonical metadata for a resource type."""

    unit: str
    description: str


RESOURCE_METADATA: dict[ResourceType, ResourceDescriptor] = {
    ResourceType.DIESEL: ResourceDescriptor(unit="L", description="Diesel fuel consumption"),
    ResourceType.ELECTRICITY: ResourceDescriptor(unit="kWh", description="Electrical power usage"),
    ResourceType.WATER: ResourceDescriptor(unit="m3", description="Process and dust suppression water"),
    ResourceType.EXPLOSIVES: ResourceDescriptor(unit="kg", description="Blasting agent consumption"),
    ResourceType.REAGENTS: ResourceDescriptor(unit="kg", description="Processing reagents"),
    ResourceType.LABOR: ResourceDescriptor(unit="hours", description="Direct labor hours"),
    ResourceType.EQUIPMENT_HOURS: ResourceDescriptor(unit="hours", description="Mobile equipment operating hours"),
    ResourceType.TAILINGS_CAPACITY: ResourceDescriptor(unit="m3", description="Tailings storage usage"),
}


@dataclass(frozen=True)
class CostBucketDescriptor:
    """Describes reporting label and guidance for a cost bucket."""

    label: str
    description: str


COST_BUCKET_METADATA: dict[CostBucket, CostBucketDescriptor] = {
    CostBucket.CAPITAL_INITIAL: CostBucketDescriptor(
        label="Initial Capital",
        description="Pre-production capital required to construct the mine",
    ),
    CostBucket.CAPITAL_SUSTAINING: CostBucketDescriptor(
        label="Sustaining Capital",
        description="Ongoing capital investments to maintain operations",
    ),
    CostBucket.OPERATING_FIXED: CostBucketDescriptor(
        label="Fixed Operating",
        description="Fixed operating costs independent of production rate",
    ),
    CostBucket.OPERATING_VARIABLE: CostBucketDescriptor(
        label="Variable Operating",
        description="Costs that scale with throughput or production",
    ),
    CostBucket.MAINTENANCE: CostBucketDescriptor(
        label="Maintenance",
        description="Maintenance and repair expenditures",
    ),
    CostBucket.RECLAMATION: CostBucketDescriptor(
        label="Reclamation",
        description="Mine closure and reclamation liabilities",
    ),
    CostBucket.ROYALTIES: CostBucketDescriptor(
        label="Royalties",
        description="Royalty and streaming obligations",
    ),
    CostBucket.GENERAL_ADMIN: CostBucketDescriptor(
        label="G&A",
        description="Corporate and site general and administrative costs",
    ),
}


@dataclass(frozen=True)
class StochasticVariableDescriptor:
    """Metadata describing how a stochastic variable is typically modelled."""

    unit: str
    description: str


STOCHASTIC_VARIABLE_METADATA: dict[StochasticVariable, StochasticVariableDescriptor] = {
    StochasticVariable.ORE_GRADE: StochasticVariableDescriptor(
        unit="g/t",
        description="Head grade variability across the ore body",
    ),
    StochasticVariable.RECOVERY_RATE: StochasticVariableDescriptor(
        unit="%",
        description="Metallurgical recovery uncertainty",
    ),
    StochasticVariable.METAL_PRICE: StochasticVariableDescriptor(
        unit="$/unit",
        description="Commodity price fluctuations",
    ),
    StochasticVariable.OPERATING_COST: StochasticVariableDescriptor(
        unit="$/t",
        description="Operating cost per tonne volatility",
    ),
    StochasticVariable.CAPITAL_COST: StochasticVariableDescriptor(
        unit="$",
        description="Capital cost overrun/underrun potential",
    ),
    StochasticVariable.DISCOUNT_RATE: StochasticVariableDescriptor(
        unit="%",
        description="Discount rate sensitivity",
    ),
    StochasticVariable.THROUGHPUT: StochasticVariableDescriptor(
        unit="t/d",
        description="Plant throughput variability",
    ),
}