Skip to content

Tutorials

Every tutorial is backed by runnable, self-contained example scripts in the repository - read them, then run them. Each page below reuses that example set's own guide.

Running any tutorial

pip install -e ".[analytics]"   # analytics extra covers every example
python examples/<topic>/<script>.py
Each script exits 0 and prints its own output; there is nothing to configure.

Start here - Fundamentals

New to MineProductivity? Start with the Learning Suite. Ten lessons that teach the platform from first principles, in the order the architecture itself is layered, using real mining problems - haul trucks, shovels, ROM stockpiles, shifts, OEE. Each lesson is a runnable script plus a full tutorial.

# Lesson You will learn
01 Hello MineProductivity A KPI is a governed object you look up, not a formula you retype
02 Entities HT-214 is still HT-214 after it is refuelled and rebuilt
03 Value objects An ore grade has no identity - and cannot exist invalid
04 Events Append-only facts, and why last June's report still reconciles
05 Ontology Why two sites can't compare TPH without a shared vocabulary
06 KPIs The guardrail that stops you averaging a ratio (1,200 vs 1,233.3 t/h)
07 Analytics Characterise a drifting fleet without re-deriving anything
08 Decision Explained, audited recommendations from a versioned policy
09 Digital Twin Live state that is always a projection of the log
10 Visualization Show a human - without the layer knowing what a tonne is

The suite's plan and progress live in the Learning Roadmap and Learning Progress.

Package Tutorials (Milestone 2)

Deep, per-package tutorials - the full public API, integration with the layers below, and the extension point you implement. Each builds directly on the Fundamentals lesson of the same package and reuses that package's runnable example scripts.

  • 01 · Core (deep) - the full core surface: identity vs value at depth, the four extension contracts, factory/builder, Result/Maybe, and implementing BaseRepository yourself.
  • 02 · Ontology (deep) - the ten sub-ontology families and their spine: BaseEntityType, the type registry, Relationships, the knowledge-graph projection, OntologyValidator, and adding an equipment leaf with @register_equipment.
  • 03 · Events (deep) - the append-only system of record: canonical events, the EventEnvelope three-timestamp model, corrections & idempotency, replay/snapshots, confidence scoring, and defining a new event type.
  • 04 · Registry & Plugins (deep) - the extensibility subsystem: the generic Registry + @register, entry-point discovery, version gating, the PluginManifest lifecycle, activation ordering, and developing a custom plugin end to end.
  • 05 · Connectors (deep) - the vendor-neutral ingestion boundary: the FMSConnector contract, the CONNECTORS registry, resilient network ingestion (retry/auth), normalization, and implementing a connector for a new source. Completes Unit A (Foundation).
  • 06 · KPIs (deep) - opens Unit B (Intelligence): the metadata-first metric backbone — the KPIEngine over an event store, composite KPIs and the dependency graph, the 29-field governed metadata, discovery, and defining a new KPI.
  • 07 · Analytics (deep) - characterising KPI history without re-deriving it: the statistical surface, LinearTrendModel, the model-as-object families, and implementing the interface-only ForecastingModel.

  • 08 · Decision (deep) - explained, audited recommendations from a versioned Policy: rules vs thresholds, the pipeline stages, ranking/planning, real-time sessions, a strategy plugin, and the root-cause/what-if refusal.

  • 09 · Digital Twin (deep) - live state that is always a projection of the event log: _apply-only evolution, cold-start replay, live sync, snapshots, and a custom Twin plugin.

  • 10 · Simulation (deep) - hypothetical futures over a governed Scenario, seeded from a twin snapshot: Monte-Carlo experiments, scenario comparison, sensitivity sweeps, statistics delegated to analytics, and a model plugin.

  • 11 · Optimization (deep) - the best feasible plan over a governed OptimizationProblem: MIP fleet allocation, plan comparison, sensitivity, candidate search over simulation, and a solver-adapter plugin.

  • 12 · AI Agents (deep) - model-independent orchestration: governed tasks, policy-gated approval, tools composing simulation/optimization, multi-agent workflows, and a plugin agent+tool.

  • 13 · Visualization (deep) - presenting governed evidence to a human without a charting-library dependency: the PresentationModel, the one RenderingPipeline, dashboards/reports/export, and a visualization+renderer plugin.

✅ All 13 Package Tutorials are complete.

The sections below are per-package API walkthroughs - lighter capability tours of each package's API, complementing the Fundamentals path and the deep Package Tutorials above.

Foundation

  • Quick tour - the five-minute, whole-platform script.
  • Core - entities, value objects, repositories, factories/builders, validation, serialization.
  • Events - first event, replay/time-travel, corrections.
  • Ontology - equipment modelling, structural modelling, contextual validation.
  • Registry - the register → discover → lookup mechanism every plugin shares.
  • Connectors - CSV ingestion, REST with retry/auth-refresh.
  • KPIs - single-KPI execution, composite UTIL.OEE, batch summary, discovery.

Intelligence

  • Decision - audited pipelines, action prioritization, real-time sessions, plugin strategies.
  • Digital Twin - cold-start + live synchronization, discovery, snapshots, plugin twin types.
  • Simulation - snapshot-seeded Monte Carlo, scenario comparison, sensitivity sweeps.
  • Optimization - MIP fleet allocation, plan comparison, sensitivity, candidate search, plugin solvers.
  • AI Agents - single tasks, policy-gated approval, multi-agent workflows, plugin agents/tools.
  • Visualization - single-widget render, multi-source dashboards, exported reports, plugins.