MineProductivity Public API

Authoritative catalogue of the public API as of v3.0.0. This document lists what the framework exports, how extensions plug in, and the stability guarantee attached to each surface. The binding contract on how these guarantees evolve is governance/API_STABILITY_POLICY.md.

Definition of "public": a symbol is public iff it is named in the __all__ of a package's top-level __init__.py (mineproductivity.<package>). Anything reached through a _-prefixed module (e.g. mineproductivity.agents._registry) or not in __all__ is private and carries no stability guarantee, even if importable.

1. Exported modules

The distribution mineproductivity exports 14 implemented packages with a combined 479 public symbols. The locked dependency direction is inward:

core → ontology → events → kpis → analytics → decision
     → digital_twin → simulation → optimization → agents → visualization

plus the cross-cutting infrastructure packages registry, plugins, connectors. visualization is, by design, the terminal package.

Package	Public symbols (__all__)	Role
core	38	Entities, value objects, repositories, builders, Result, BaseConfiguration
ontology	56	Domain vocabulary, schema, knowledge-graph projection
events	31	Event schema, store, bus, replay/time-travel
kpis	32	KPI metadata + standard library
registry	11	Registry framework + entry-point discovery + version compatibility
plugins	8	Plugin manifest/loader
connectors	25	Source-system integration + retry/backoff
analytics	53	Trend/baseline/benchmark/forecasting/anomaly/outlier interfaces + execution
decision	49	Rules, recommendations, explanations, audit
digital_twin	36	Twin state, snapshots, synchronization
simulation	34	Monte Carlo / DES / system-dynamics interfaces, experiments
optimization	36	Six solver-paradigm interfaces, executor, comparison, sensitivity
agents	41	Agent/Tool/Memory interfaces, policy, tasks, workflow, audit
visualization	29	Presentation/renderer interfaces, dashboards, reports, export

The top-level mineproductivity package itself exports only __version__.

Retained placeholders (not importable public API): cli and certification are chartered for future implementation (ADR-0013); they expose no public API in v3.0. Importing them yields an empty module. Seven other Phase-0 placeholder packages were removed in v3.0 - see governance/MIGRATION_GUIDE_v2_to_v3.md.

2. Registries

Each registrable extension surface exposes a module-level registry object and a lookup contract (.get(code), .list(), in). Registries store classes; callers instantiate the returned class.

Package	Registry object(s)	Notes
kpis	REGISTRY	KPI definitions
analytics	REGISTRY	Analytics models (all six categories)
decision	REGISTRY	Decision models
digital_twin	REGISTRY	Twin models
simulation	REGISTRY	Simulation models
optimization	REGISTRY	Optimization models
agents	REGISTRY, TOOLS	Agents and tools respectively
visualization	REGISTRY, RENDERERS	Visualizations and renderers respectively
connectors	CONNECTORS	Connector classes; also get_connector(code) helper

Documented naming note (stable for v3.x): the domain-model registry is named REGISTRY in every package; packages with a second registrable kind add a purpose-named registry (TOOLS, RENDERERS). connectors predates that convention and names its single registry CONNECTORS (with register_connector / get_connector). This asymmetry is intentional and frozen for the v3.x line; any alignment would be a breaking change reserved for a future major.

3. Decorators

Registration is performed by a decorator that fires at import time; discovery imports the module and the decorator is the registration side effect.

Package	Decorator(s)
kpis, analytics, decision, digital_twin, simulation, optimization	register
agents	register (agents), register_tool (tools)
visualization	register (visualizations), register_renderer (renderers)
connectors	register_connector

Each decorated class must expose a meta descriptor carrying a globally unique code (the registry key) and a version.

4. Extension points (entry-point groups)

Plugins are discovered with registry.EntryPointDiscovery().discover(registry.EntryPointSpec(group=..., target_registry=...)), which imports every entry point in group. The canonical group names are:

Extension	Entry-point group
KPI definitions	mineproductivity.kpis
Analytics models	mineproductivity.analytics
Decision models	mineproductivity.decision
Digital-twin models	mineproductivity.digital_twin
Simulation models	mineproductivity.simulation
Optimization models	mineproductivity.optimization
Agents	mineproductivity.agents
Agent tools	mineproductivity.agents.tools
Visualizations	mineproductivity.visualization
Visualization renderers	mineproductivity.visualization.renderers
Connectors	mineproductivity.connectors

Convention: the primary registry uses mineproductivity.<package>; a secondary registrable kind uses mineproductivity.<package>.<subtype>. Discovery is isolated - a plugin that raises on import (e.g. an incompatible framework version) is logged and skipped, never crashing the host.

The reference plugin examples/plugins/sitepack demonstrates five of these surfaces end to end; see its AUTHORING_GUIDE.md.

5. Stability guarantees

Governed in full by API_STABILITY_POLICY.md; summary:

Surface	Guarantee
Public symbols (in a package __all__)	Stable within a major. No incompatible change without a MAJOR bump + a deprecation cycle.
Registry objects, decorators, entry-point group names	Stable within a major (Sections 2–4).
Interface ABCs and their abstract-method signatures	Stable within a major; new optional hooks may be added in a MINOR.
Deterministic outputs of shipped models	Stable within a major (bugfixes excepted, disclosed).
_-prefixed modules / anything not in __all__	No guarantee. May change in any release.
Retained placeholders (cli, certification)	No API yet; first implementation ships in a MINOR with its own spec.

Supported Python: 3.12 and 3.13 (see governance/SUPPORTED_VERSIONS.md).