mineproductivity.ontology

Auto-generated API reference for the Ontology package, rendered from the package's own docstrings. For the narrative overview, dependency rules, and extension guide, see Packages -> Ontology.

ontology

mineproductivity.ontology -- the typed, machine-readable model of the mining world.

Implements the ten sub-ontology families (equipment, material, location, organization, production, maintenance, cost, quality, safety, environmental) plus the cross-cutting entity-type root, relationships, reference data, and the Knowledge Graph projection contract, per docs/architecture/02_Ontology_Framework_Design_Specification.md.

ontology depends only on core -- see README.md for the full set of architectural rules this package must satisfy.

Everything documented here is part of the public API and can be imported directly from mineproductivity.ontology, e.g.::

from mineproductivity.ontology import RigidHaulTruck, Pit, Bench, Shift

CostCategory

Bases: Enum

The cost categories a :class:CostCenter can classify spend under, each mapping to a corresponding COST.* KPI namespace.

CostCenter dataclass

CostCenter(id, business_unit_id, category)

Bases: BaseEntityType

A cost center scoped to a :class:~mineproductivity.ontology.organization.business_unit.BusinessUnit.

Examples:

>>> cc = CostCenter(id="CC-FUEL-01", business_unit_id="bu-1", category=CostCategory.FUEL)
>>> cc.category
<CostCategory.FUEL: 'fuel'>

BaseEntityType dataclass

BaseEntityType(id)

Bases: BaseEntity[str], ABC

Root of every ontology entity type.

A concrete leaf (RigidHaulTruck, Pit, Shift, ...) is a frozen dataclass subclass declaring a unique code: ClassVar[str] (the stable registry key), a meta: ClassVar[EntityTypeMetadata], and whatever domain fields the type needs. Neither code nor meta is given a default at this level: a leaf type that forgets to declare one fails loudly (AttributeError) the first time either is read (e.g. by :meth:to_schema or the entity type registry), rather than silently inheriting a placeholder value.

Inherits :class:~mineproductivity.core.entity.BaseEntity's identity-based equality (two instances with the same id are equal regardless of other fields), consistent with the Cookbook's rule that entities are identity-bearing, not value-bearing.

Unlike :class:~mineproductivity.core.value_object.BaseValueObject, core.BaseEntity defines no __post_init__/validate() hook of its own (entities were not previously built on top of it by any implemented package). Since the design specification requires structural validation to be "enforced at construction" (§19), BaseEntityType adds that hook locally -- mirroring BaseValueObject's _normalize()/validate() pattern exactly -- without modifying the locked core package.

validate

validate()

Override to enforce invariants on this entity type's fields.

The default implementation does nothing (no invariants).

Raises:

Type	Description
Exception	Any exception may be raised to reject invalid state; :class:~mineproductivity.ontology.exceptions.OntologyValidationError is preferred for consistency with the rest of this package.

to_schema

to_schema()

Export this type's shape as JSON Schema -- read by dashboards, validation, and AI agents without touching source code. Cached per concrete type after the first call, since the schema is static for a given type version.

EntityTypeMetadata dataclass

EntityTypeMetadata(name, *, description='', tags=frozenset(), attributes=dict(), supported_kpis=(), parent_code=None)

Bases: BaseMetadata

Every entity type's descriptive metadata, in addition to :class:~mineproductivity.core.metadata.BaseMetadata's name/description/tags/attributes.

Mandatory per the metadata-first principle: a blank field here is a specification gap (mirrors the KPI Standard Library's completeness discipline).

EmissionFactor dataclass

EmissionFactor(id, resource_type, kg_co2e_per_unit)

Bases: BaseEntityType

A governed emission factor for one resource type (e.g. diesel, grid power), feeding CARBON.* KPIs.

Examples:

>>> factor = EmissionFactor(id="diesel-factor", resource_type="diesel", kg_co2e_per_unit=2.68)
>>> factor.kg_co2e_per_unit
2.68

MonitoringPoint dataclass

MonitoringPoint(id, mine_id, measurement_type)

Bases: BaseEntityType

An environmental monitoring point (dust, noise, water quality, ...).

LHD dataclass

LHD(id, rated_capacity, *, model='', fleet_id=None)

Bases: EquipmentType

A Load-Haul-Dump unit -- the underground counterpart to a surface loader/truck pairing, combining loading and short-haul tramming.

ArticulatedHaulTruck dataclass

ArticulatedHaulTruck(id, rated_capacity, *, model='', fuel_type='diesel', fleet_id=None)

Bases: EquipmentType

An articulated (frame-steered) haul truck, typically used underground or on poor-condition surface haul roads.

BlastholeDrill dataclass

BlastholeDrill(id, rated_capacity, *, model='', hole_diameter_mm=0.0)

Bases: EquipmentType

A blasthole drill rig, preparing a bench for blasting.

Conveyor dataclass

Conveyor(id, rated_capacity, *, length_m=0.0)

Bases: EquipmentType

A fixed conveyor segment moving material between plant stages.

Crusher dataclass

Crusher(id, rated_capacity, *, throughput_capacity_tph=0.0)

Bases: EquipmentType

A fixed or semi-mobile crusher unit.

Dozer dataclass

Dozer(id, rated_capacity, *, model='')

Bases: EquipmentType

A track dozer used for rehandling, ripping, and dump/bench housekeeping.

EquipmentType dataclass

EquipmentType(id, rated_capacity)

Bases: BaseEntityType, ABC

Abstract root for every machine in the mine.

Common behaviour (the operational state machine, availability-KPI applicability) lives here; specifics (rated capacity, cycle-level KPIs) live in leaves -- the inheritance split demonstrated in Cookbook Part I, Ch. 8.

Grader dataclass

Grader(id, rated_capacity, *, model='')

Bases: EquipmentType

A motor grader used for haul road maintenance.

HydraulicShovel dataclass

HydraulicShovel(id, rated_capacity, *, model='', fleet_id=None)

Bases: EquipmentType

A hydraulic face shovel that loads trucks.

Mill dataclass

Mill(id, rated_capacity, *, mill_type='ball')

Bases: EquipmentType

A grinding mill (SAG/ball/rod) reducing crushed ore to process feed size.

OperationalState

Bases: Enum

The four-state machine every equipment leaf type inherits.

Declared here as descriptive metadata only -- tracking which state an instance is currently in is a future digital_twin concern, derived from the event stream, never mutable state on the entity itself (design spec AD-ON-04).

RigidHaulTruck dataclass

RigidHaulTruck(id, rated_capacity, *, model='', fuel_type='diesel', fleet_id=None)

Bases: EquipmentType

A rigid-frame haul truck (e.g. CAT 793, Komatsu 930E).

WaterTruck dataclass

WaterTruck(id, rated_capacity, *, model='', tank_capacity_l=0.0)

Bases: EquipmentType

A water truck used for haul-road dust suppression.

WheelLoader dataclass

WheelLoader(id, rated_capacity, *, model='', fleet_id=None)

Bases: EquipmentType

A wheeled front-end loader, used for loading, stockpile rehandling, or as a secondary loading unit.

OntologyValidationError

OntologyValidationError(message, *, details=None)

Bases: ValidationError

A :class:~mineproductivity.ontology.entity_type.BaseEntityType instance failed structural or contextual validation.

RelationshipError

RelationshipError(message, *, details=None)

Bases: MineProductivityError

A :class:~mineproductivity.ontology.relationship.Relationship references a source_id/target_id that cannot be resolved, or declares a :class:~mineproductivity.ontology.relationship.RelationshipKind invalid for the two entity types involved.

UnknownEntityTypeError

UnknownEntityTypeError(message, *, details=None)

Bases: NotFoundError

EntityTypeRegistry.lookup(code) found no registered type for code.

GraphEdge dataclass

GraphEdge(source_id, target_id, edge_kind)

Bases: BaseValueObject

One edge in a Knowledge Graph projection -- either an ontology relationship or a KPI dependency.

GraphNode dataclass

GraphNode(node_id, node_kind, *, entity_type_code=None)

Bases: BaseValueObject

One node in a Knowledge Graph projection -- either an ontology entity or a KPI.

KnowledgeGraphProjection

Bases: ABC

The contract a future Knowledge Graph builder consumes to project this package's declared entities and relationships into nodes and edges, so "the graph can never drift from the ontology" (Cookbook Part I, Ch. 8, Architecture Insight).

Traversal (neighbors/path/search) is explicitly NOT part of this contract (design spec §4) -- it belongs to a future graph-adjacent capability that consumes this projection, not to ontology itself.

nodes abstractmethod

nodes()

Yield every node this projection contributes to the graph.

edges abstractmethod

edges()

Yield every edge this projection contributes to the graph.

Bench dataclass

Bench(id, pit_id, elevation_m)

Bases: BaseEntityType

A bench (working level) within a pit.

Examples:

>>> b7 = Bench(id="bench-7", pit_id="pit-west", elevation_m=1820.0)
>>> b7.pit_id
'pit-west'

Drive dataclass

Drive(id, level_id, *, length_m=0.0)

Bases: BaseEntityType

An underground drive (horizontal access tunnel) connecting a level to a stope or another drive.

Level dataclass

Level(id, mine_id, elevation_m)

Bases: BaseEntityType

Underground sibling of :class:~mineproductivity.ontology.location.pit.Bench: a horizontal working level within an underground mine.

Mine dataclass

Mine(id, commodity_codes, method)

Bases: BaseEntityType

The top-level mine site entity: a named operation producing one or more commodities under one mining method.

Examples:

>>> mine = Mine(id="bingham-west", commodity_codes=("copper",), method="open_pit")
>>> mine.method
'open_pit'

Pit dataclass

Pit(id, mine_id, commodity)

Bases: BaseEntityType

An open pit within a mine.

Examples:

>>> west = Pit(id="pit-west", mine_id="bingham-west", commodity="copper")
>>> west.mine_id
'bingham-west'

Route dataclass

Route(id, source_zone_id, destination_zone_id, one_way_km, effective_grade_pct)

Bases: BaseEntityType

A haul route: a source -> destination pair with a one-way distance.

Examples:

>>> route = Route(
...     id="B7N_CR1", source_zone_id="B7N", destination_zone_id="CR1",
...     one_way_km=3.2, effective_grade_pct=8.5,
... )
>>> route.one_way_km
3.2

Stope dataclass

Stope(id, level_id, *, mining_method='')

Bases: BaseEntityType

A stope: an underground void created by ore extraction.

Zone dataclass

Zone(id, mine_id, *, zone_type='general')

Bases: BaseEntityType

A named area within a mine (a dump, a stockpile, a haul-road segment, a geofenced hazard area, ...). The generic location unit other entities (:class:Route, a future :class:~mineproductivity.ontology.safety.hazard.HazardZone) attach speed limits, distances, and other spatial attributes to.

FailureMode dataclass

FailureMode(id, failure_mode_code, system)

Bases: BaseEntityType

A classified equipment failure mode (e.g. HYD-001 for a hydraulic failure), the reference taxonomy :class:~mineproductivity.events.canonical.maintenance_event.MaintenanceEvent instances point at.

Examples:

>>> mode = FailureMode(id="HYD-001", failure_mode_code="HYD-001", system="hydraulic")
>>> mode.system
'hydraulic'

MaintenanceWorkOrder dataclass

MaintenanceWorkOrder(id, equipment_id, *, failure_mode_code=None, is_planned=False)

Bases: BaseEntityType

A maintenance work order's structural shape -- identity, the equipment it targets, and whether it is planned. Scheduling logic (assignment, prioritisation, execution) is explicitly out of scope for this package (design spec §2); this entity exists purely so other packages have a stable structural reference to point at.

Commodity dataclass

Commodity(id, symbol, unit_basis)

Bases: BaseEntityType

A mineral commodity, e.g. copper, iron ore, gold.

Examples:

>>> copper = Commodity(id="copper", symbol="Cu", unit_basis="tonnes")
>>> copper.symbol
'Cu'

MaterialType

Bases: Enum

Whether a given tonne of material is ore, waste, or a processed product.

BusinessUnit dataclass

BusinessUnit(id, *, parent_business_unit_id=None)

Bases: BaseEntityType

An enterprise business unit that one or more mines roll up to -- the scope :class:~mineproductivity.ontology.cost.cost_center.CostCenter and cross-site benchmarking (Cookbook Part I, Ch. 6) are computed against.

Contractor dataclass

Contractor(id, *, service_type='')

Bases: BaseEntityType

A third-party contractor providing equipment, labour, or services.

Crew dataclass

Crew(id, mine_id)

Bases: BaseEntityType

A rostered crew (e.g. "A", "B", "C", "D") working a shift pattern.

Fleet dataclass

Fleet(id, mine_id, equipment_type_code)

Bases: BaseEntityType

A named group of equipment of one :class:~mineproductivity.ontology.equipment.equipment_type.EquipmentType.

Examples:

>>> fleet = Fleet(id="FL-NORTH", mine_id="pilbara-ridge", equipment_type_code="RIGID_HAUL_TRUCK")
>>> fleet.equipment_type_code
'RIGID_HAUL_TRUCK'

Operator dataclass

Operator(id, crew_id, licence_class)

Bases: BaseEntityType

An equipment operator, linked to cycle and delay events for operator-level KPI dimensions.

Examples:

>>> op = Operator(id="OP-001", crew_id="A", licence_class="Haul Truck")
>>> op.licence_class
'Haul Truck'

Shift dataclass

Shift(id, mine_id, pattern, start_utc, end_utc, scheduled_h)

Bases: BaseEntityType

One scheduled production shift: a UTC time window plus its scheduled-hours denominator (the authoritative basis for UTIL.PA/UTIL.UA per the KPI Engine spec's canonical time model).

Examples:

>>> from datetime import timezone
>>> shift = Shift(
...     id="A-2026-06-25", mine_id="bingham-west", pattern="2x12",
...     start_utc=datetime(2026, 6, 25, 6, tzinfo=timezone.utc),
...     end_utc=datetime(2026, 6, 25, 18, tzinfo=timezone.utc),
...     scheduled_h=12.0,
... )
>>> shift.contains(datetime(2026, 6, 25, 7, tzinfo=timezone.utc))
True

contains

contains(event_time_utc)

Half-open interval test: start_utc <= t < end_utc (the Learning & Benchmark Suite's shift-assignment rule).

ShiftCalendar dataclass

ShiftCalendar(id, mine_id, pattern, timezone)

Bases: BaseEntityType

The master shift reference table for one mine (the Learning & Benchmark Suite's shared/shift_calendar.csv): declares the pattern and timezone convention every :class:Shift instance at that mine must conform to.

ShiftPattern

Bases: Enum

Common shift patterns mines operate under.

GradeAttribute dataclass

GradeAttribute(id, commodity_code, unit)

Bases: BaseEntityType

A measurable grade/quality attribute for one commodity (e.g. "% Cu", "g/t Au").

Examples:

>>> grade = GradeAttribute(id="head-grade-cu", commodity_code="copper", unit="% Cu")
>>> grade.unit
'% Cu'

QualitySpecification dataclass

QualitySpecification(id, grade_attribute_code, *, min_value=None, max_value=None)

Bases: BaseEntityType

A governed acceptable range for one :class:GradeAttribute.

DelayCategory

Bases: Enum

The six mutually-exclusive, collectively-exhaustive delay categories, ruled canonical in Developer & Cookbook Guide Part III, "Canonical Semantics". Owned here as ontology reference data; consumed by events.DelayEvent and every UTIL/DELAY KPI.

precedence property

precedence

Lower number wins when a delay could plausibly belong to more than one category (e.g. refuelling during a breakdown).

Relationship dataclass

Relationship(source_id, kind, target_id)

Bases: BaseValueObject

A declared, typed edge between two entity ids.

Relationships are how "by pit" or "by fleet" slicing resolves: a :class:~mineproductivity.ontology.location.pit.Bench and a :class:~mineproductivity.ontology.location.pit.Pit are independent, independently serializable entities; Relationship is the explicit edge connecting them, deliberately not an object-graph pointer (see the design specification's AD-ON-02).

Examples:

>>> edge = Relationship(source_id="bench-7", kind=RelationshipKind.BELONGS_TO, target_id="pit-west")
>>> edge.kind
<RelationshipKind.BELONGS_TO: 'belongs_to'>

RelationshipKind

Bases: Enum

The five relationship kinds the ontology declares between entities.

HazardZone dataclass

HazardZone(id, zone_id, speed_limit_kmh)

Bases: BaseEntityType

A geofenced zone with a governed speed limit -- the reference a SAFE.SpeedViolationRate-style KPI resolves "violation" against.

Examples:

>>> zone = HazardZone(id="B7N_CR1", zone_id="B7N_CR1", speed_limit_kmh=45.0)
>>> zone.speed_limit_kmh
45.0

SafetyEventType

Bases: Enum

The leading safety-indicator kinds a safety event can record.

SpeedLimitMap dataclass

SpeedLimitMap(id, mine_id, *, zone_limits_kmh=dict())

Bases: BaseEntityType

A mine-wide map of zone id -> governed speed limit, the single source of truth SAFE.SpeedViolationRate and similar KPIs read to decide whether a given speed reading was a violation.

OntologyValidator

OntologyValidator(*, entity_resolver=None)

Bases: BaseValidator[BaseEntityType]

Contextual validation for a constructed :class:~mineproductivity.ontology.entity_type.BaseEntityType instance, separate from the structural field validation every leaf type already enforces on construction.

Checks two kinds of cross-entity reference by field-naming convention:

• A field named *_type_code (e.g. Fleet.equipment_type_code) is checked against this package's own entity type registry -- ontology owns that registry, so this resolution never needs external help.
• A field named *_id (e.g. Bench.pit_id) is checked against the optional, injectable entity_resolver callback -- ontology does not persist entity instances itself (design spec §4), so instance-level resolution can only happen once a caller (a future config/datasets loader) supplies one. Without a resolver, instance -level references are not checked (structural validation at construction is still always enforced regardless).

An unresolved reference is always a warning in the returned :class:~mineproductivity.core.validator.ValidationResult, never a raised exception -- Cookbook Part I, Ch. 8's rule that an orphaned reference must never silently halt ingestion of everything else.

Examples:

>>> from mineproductivity.ontology import Fleet
>>> validator = OntologyValidator()
>>> fleet = Fleet(id="FL-NORTH", mine_id="pilbara-ridge", equipment_type_code="RIGID_HAUL_TRUCK")
>>> validator.validate(fleet).is_valid
True
>>> bad_fleet = Fleet(id="FL-BAD", mine_id="pilbara-ridge", equipment_type_code="NOT_A_REAL_TYPE")
>>> validator.validate(bad_fleet).is_valid
False

register_equipment

register_equipment(cls)

Register cls into the internal entity type registry, keyed by cls.code. Applied as a decorator to every concrete leaf type across all ten sub-ontology families (register_equipment in ontology.equipment is a documented alias of this same function, for readability at equipment-specific call sites).

Raises:

Type	Description
DuplicateError	If cls.code is already registered to a different class.