Skip to content

MineProductivity SitePack - reference plugin

A separately-installable package that proves the MineProductivity extension ecosystem end to end. It ships concrete backends for two of the framework's interface-only surfaces and registers them purely through entry points - never modifying mineproductivity itself.

Backend Interface Entry-point group Registered code(s)
HTML / PDF report renderers visualization.Renderer mineproductivity.visualization.renderers HTML.SitePack, PDF.SitePack
Dispatch fleet-allocation model optimization.MixedIntegerProgrammingModel mineproductivity.optimization MIP.SitePackDispatchAllocation
Holt linear-trend forecaster analytics.ForecastingModel mineproductivity.analytics FORECAST.SitePackHoltLinear
Moving-average / trend tools agents.Tool mineproductivity.agents.tools TOOL.SitePackMovingAverage, TOOL.SitePackTrendClassifier
Rule-based production-outlook agent agents.Agent mineproductivity.agents PLANNING.SitePackProductionOutlook

The optimization and visualization backends are Milestone 4 Batch 1; the analytics, tool, and agent backends are Batch 2. The agent is rule-based (no LLM): it composes the forecaster and both tools through the registries and is executed by the framework's own TaskExecutor.

What it demonstrates

  • Entry-point discovery - registry.EntryPointDiscovery.discover() imports the plugin's target modules; registration is the import side effect.
  • Automatic registration - backends self-register via @register_renderer / @register at import.
  • Version compatibility - the plugin declares a supported framework range (>=2.0.0,<4.0.0) and fails fast via registry.VersionCompatibility when loaded against an unsupported framework.
  • Plugin isolation - an incompatible or broken plugin raises on import and is skipped by discovery, never crashing the host.
  • Deterministic execution - the optimizer uses largest-remainder apportionment; the HTML renderer is byte-deterministic. (The PDF renderer is content-deterministic; ReportLab embeds a per-build timestamp.)

Install

pip install -e examples/plugins/sitepack          # HTML renderer + optimizer
pip install -e "examples/plugins/sitepack[pdf]"   # + PDF renderer (reportlab)

See INSTALLATION_GUIDE.md for details and AUTHORING_GUIDE.md to build your own plugin.

Package structure

examples/plugins/sitepack/
├── pyproject.toml                     # entry points, version, optional [pdf] extra
├── README.md                          # this file
├── AUTHORING_GUIDE.md
├── INSTALLATION_GUIDE.md
├── workflow_demo.py                   # runnable agent-workflow demonstration
├── mineproductivity_sitepack/
│   ├── __init__.py                    # version gate (fail-fast) + version
│   ├── _compat.py                     # supported-framework range
│   ├── visualization.py               # HtmlReportRenderer, PdfReportRenderer (Batch 1)
│   ├── optimization.py                # DispatchAllocationModel (Batch 1)
│   ├── analytics.py                   # HoltLinearForecastModel (Batch 2)
│   ├── tools.py                       # MovingAverageTool, TrendClassifierTool (Batch 2)
│   └── agents.py                      # ProductionOutlookAgent (Batch 2)
└── tests/
    ├── test_plugin.py                 # Batch 1: discovery / registration / render / solve
    └── test_batch2.py                 # Batch 2: forecast / tools / agent workflow

Agent workflow demonstration

pip install -e examples/plugins/sitepack
python examples/plugins/sitepack/workflow_demo.py

Discovers the analytics/tool/agent backends via entry points, provisions a Task, and runs it through the framework's TaskExecutor — the agent forecasts a production series, classifies its trend, and returns a deterministic recommendation with an audit trail.

Consumed by

  • The Dispatch Optimization solution (examples/enterprise/06_dispatch_optimization/) discovers the optimization backend and, when installed, produces an optimized truck-to-route allocation via the framework's OptimizationExecutor (Batch 1).
  • The Shift Performance solution (examples/enterprise/03_shift_performance/) discovers the analytics + agent backends and, when installed, produces a production-outlook (forecast + rule-based recommendation) via the framework's TaskExecutor (Batch 2).

Both integrations are additive and plugin-gated: with no framework change and no change to each solution's default (plugin-free) behaviour — every committed output stays byte-identical when the plugin is absent.