Enterprise-grade ontology-driven framework for mining productivity intelligence, KPI standardization, Digital Twins, simulation, optimization, AI decision support, and operational analytics.
Documentation · Quick Start · Examples · Architecture · Changelog
MineProductivity turns raw mine-site events into governed KPIs, digital twins, simulations, optimized plans, and audited decisions - through one coherent, plugin-first architecture. Every performance indicator is a discoverable, versioned, self-describing object rather than a formula buried in a script.
The base install has zero third-party dependencies; every heavy backend (numpy, pandas, pyarrow, …) is opt-in.
pip install mineproductivity- 🧭 Ontology-first - a shared, explicit domain vocabulary (assets, processes, events, KPIs) precedes any code that operates on it.
- ⏳ Event-first - the system of record is an immutable event stream; all derived state (KPIs, twins, analytics) is a rebuildable projection.
- 🏷️ Metadata-first - every KPI, dataset, and model ships with machine-readable metadata (units, provenance, versioning) before it ships with logic.
- 🔌 Plugin-first - connectors, KPIs, analytics, solvers, agents, and renderers are discovered through a registry, never hard-wired into the core.
- 🧱 Clean, layered architecture - 14 packages whose inward-pointing dependency direction is mechanically enforced (both ways) by tests, not just documented.
- ✅ Enterprise quality - 2,986 tests,
mypy --strictclean across 314 files, 99% branch coverage, and public APIs stable by contract as ofv2.0.0.
- Mining companies
- Researchers
- Universities
- Consultants
- Software developers
pip install mineproductivityOptional dependency groups add capability only where you need it:
| Extra | Adds | Needed for |
|---|---|---|
analytics |
numpy, pandas, polars, duckdb |
KPI Engine execution backends, KPIResult.to_frame() |
events |
pyarrow |
Parquet/Arrow event codecs |
connectors |
openpyxl, tzdata (Windows) |
ExcelConnector, local-timezone normalization |
notebooks |
jupyter, ipykernel |
Running the learning notebooks |
dev |
the above + pytest, ruff, mypy, pre-commit |
Contributing |
pip install "mineproductivity[analytics]"Requires Python 3.12+.
Every KPI is a governed, discoverable object - look it up by its identifier and compute it:
from mineproductivity.kpis import REGISTRY
# One CAT 793F's shift: ~220 t per load, ~18 min (0.3 h) per cycle, 40 cycles.
cycles = [{"payload_t": 220.0, "operating_h": 0.3} for _ in range(40)]
tph = REGISTRY.get("PROD.TPH")().compute(cycles)
print(tph.value, tph.unit) # 733.33... t/hDiscover what the Standard Library ships:
from mineproductivity.kpis import REGISTRY
print(len(REGISTRY), "KPIs available")
for code in sorted(REGISTRY):
print(code)Want the whole platform end-to-end - one truck, one shift, one KPI, in ~50 lines? Run the five-minute tour, or read the Quick Start guide.
:material-school: MineProductivity Fundamentals — ten lessons that teach the platform from first principles, in the order the architecture is layered, using real mining problems: haul trucks, shovels, ROM stockpiles, shifts, OEE. Every lesson is a runnable script plus a full tutorial.
| Lessons | You will learn | |
|---|---|---|
| Foundation | Hello · Entities · Value objects · Events · Ontology · KPIs | Why a KPI is a governed object; append-only facts; the guardrail that stops you averaging a ratio |
| Intelligence | Analytics · Decision · Digital Twin · Visualization | Characterising a drifting fleet, explained + audited recommendations, live state as a projection |
The scripts live in examples/fundamentals/ — read them, then run them.
Work flows up a strict, inward-pointing dependency chain - lower layers never import higher ones:
core → ontology → events → kpis → analytics → decision
→ digital_twin → simulation → optimization → agents → visualization
plus three cross-cutting infrastructure packages (registry, plugins, connectors) importable by any layer.
| Tier | Packages | What they do |
|---|---|---|
| Foundation | core · ontology · events · kpis |
Primitives, the typed domain vocabulary, the event-sourced system of record, and the metadata-first KPI Engine. |
| Intelligence | analytics · decision · digital_twin · simulation · optimization · agents · visualization |
Statistical characterization, prescriptive recommendations, stateful representation, projection, prescriptive search, autonomous orchestration, and presentation. |
The interface-only extension points (solver adapters, reasoning backends, renderers, forecasting models, …) ship zero concrete implementations by design — new value arrives as plugins, evaluated against the locked specifications. See the package reference for each package's public API and extension guide.
Full documentation is published at imanojkumar.github.io/MineProductivity:
- Getting Started - installation, quick start, next steps
- Learning Suite - Fundamentals - ten lessons teaching the platform from first principles
- Tutorials - runnable, package-by-package walkthroughs
- Packages & API Reference - narrative guides and the docstring-generated symbol reference
- Architecture Handbook & ADRs - the twelve locked design specifications and the decisions behind them
- Benchmarks & Certification
Stable - v2.0.0. The architecture is complete and locked, and the public APIs are stable by contract: they will not change incompatibly without a further MAJOR release. New value ships as plugins and applications, not as changes to the locked packages. See the certification record and the CHANGELOG.
Milestone history
| Version | Milestone |
|---|---|
| v0.2.0 – v0.7.0 | Foundation Layer (core, events, ontology, registry/plugins, connectors, kpis) |
| v0.8.0 – v1.4.0 | Architecture milestones for the Intelligence tier (design specs + checklists + ADRs) |
| v1.5.0 | Analytics Engine implementation |
| v1.6.0 | Decision Intelligence implementation |
| v1.7.0 | Digital Twin implementation |
| v1.8.0 | Simulation implementation |
| v1.9.0 | Optimization implementation |
| v1.10.0 | AI Agents implementation |
| v1.11.0 | Visualization implementation |
| v2.0.0 | Enterprise certification — architecture complete & locked |
A future conformance-suite package and a CLI application are tracked as optional, post-2.0 work in the ROADMAP.
Contributions are welcome. Set up a development environment:
git clone https://github.com/imanojkumar/MineProductivity.git
cd MineProductivity
pip install -e ".[dev]"
pre-commit installSee CONTRIBUTING.md for the full workflow and CODE_OF_CONDUCT.md.
Apache License 2.0 - see LICENSE.
If you use MineProductivity in research or industry, please cite it via the Zenodo Concept DOI (which always resolves to the latest release):
Kumar, M. (2026). MineProductivity. Zenodo. https://doi.org/10.5281/zenodo.21172767
Machine-readable metadata is in CITATION.cff.