Train and Manage an Equipment Model

Equipment models move through a controlled lifecycle. Training creates a candidate for review. It does not automatically replace the criteria that currently protect an equipment record.

This guide explains the two model tracks used by Predictive Maintenance, what users can do in the application, and which lifecycle actions currently require an administrator API.

Know Which Model You Are Managing

Predictive Maintenance keeps these artifacts separate:

Model track	Purpose	Current training entry	Production authority
Equipment baseline distribution (PDM_BASELINE_DISTRIBUTION)	Describes the equipment's observed operating distribution for baseline comparison.	Predictive Maintenance > Model Console	The baseline promotion gate in the Model Console
Executable anomaly model (PDM_ANOMALY_MODEL)	Runs an anomaly-scoring artifact for a specific equipment target.	Administrator API	An ACTIVE assignment that references a verified immutable artifact

Do not treat a baseline distribution as an executable anomaly model. A successful baseline calculation does not prove that an anomaly artifact ran, and an anomaly score is not a failure probability.

Access and Permissions

Task	Entry	Required permission
View the Model Console	/pdm/model-console	mlops.model.read or system.config
View model use details	/ai-models/registry/:registryId	mlops.model.read or system.config
Train or promote a baseline	Model Console	pdm:write
Train an executable anomaly candidate	Administrator API	pdm:write
Promote or roll back an executable assignment	Administrator API	pdm:write
Review equipment findings	/pdm/anomalies and Finding Detail	pdm:read

The standard Model Usage Detail page is read-only. It shows assignment and runtime evidence, but it does not currently provide assignment promotion or rollback buttons.

Lifecycle at a Glance

SHADOW means the candidate can run for comparison without changing alerts, health scores, advisories, or findings. ACTIVE gives an assignment production authority, but production use is not confirmed until fresh successful runtime evidence appears.

Readiness explains the unmet condition instead of presenting missing evidence as a health result.

Train a Statistical Equipment Baseline

1. Open Predictive Maintenance > Model Console.
2. Find the equipment record.
3. Review the readiness result and every unmet criterion.
4. Confirm that the equipment identity, target signal, unit, operating-state history, and training window are correct.
5. Select the training action when the record is eligible and your role has pdm:write.
6. Wait for the console to refresh and confirm the new version and training time.

Readiness can have different meanings:

Result	Meaning	Next action
Eligible	The required data conditions are currently met.	Train, then review the resulting SHADOW candidate.
Missing criteria	One or more measurable requirements are not met.	Collect the missing running history or repair the required signal.
Cannot determine	The service cannot make a readiness decision.	Resolve the stated identity, data, or service problem. Do not report it as insufficient history.
Caveat	Training can proceed, but the window has a known limitation.	Record the caveat and include it in the release review.

Training the baseline creates a candidate for comparison. The existing production criteria remain in effect.

Train an Executable Anomaly Candidate

Executable anomaly-model training is currently an administrator API workflow. There is no corresponding self-service button in the standard Model Console.

Method	Endpoint	Result
POST	/api/v1/pdm/model-console/{equipmentId}/train-anomaly-model	Creates an immutable executable candidate without changing the statistical baseline or current ACTIVE path.

After the request succeeds:

1. open the model registry;
2. select the exact registry record, not only a model-type name;
3. confirm the bound equipment and target;
4. confirm the artifact is registered and verified;
5. confirm the assignment is SHADOW;
6. review SHADOW runtime evidence before making a release decision.

The API action must run in the intended tenant. Do not reuse an assignment or registry identifier copied from another tenant or environment.

Review SHADOW Behavior

Use the Model Usage Detail page to review the candidate:

• the exact equipment and target binding;
• assignment status;
• artifact kind, runtime, format, and verification status;
• training window and sample count;
• recent SHADOW execution windows;
• executed, refused, timed-out, and failed counts;
• SHADOW disagreement count and reason.

A disagreement means the SHADOW result differed from the current production path in at least one recorded comparison. It does not establish which result was correct. A candidate that produces fewer alerts is not automatically more accurate; it may also miss relevant conditions.

A trained candidate remains in SHADOW until a separate authorized promotion decision.

Use field findings, reviewed maintenance outcomes, operating context, and data-quality evidence when deciding whether the candidate is useful.

Promote Deliberately

Baseline promotion in the UI

For an eligible baseline in SHADOW, the Model Console can show the promotion action to a user with pdm:write. The backend release gate checks that the baseline can be compared against the current criteria. It does not claim that the baseline is more accurate.

If promotion is refused, follow the returned reason. Typical actions include repairing the equipment profile, training a candidate first, waiting for valid running samples, or restoring the time-series service.

Executable assignment promotion by API

Executable anomaly-model assignments use the administrator endpoint:

Method	Endpoint
POST	/api/v1/pdm/model-console/assignments/{assignmentId}/promote

Promotion changes lifecycle state atomically. After it succeeds, verify all of the following:

• the intended assignment is ACTIVE;
• the intended registry version is PRODUCTION;
• the previous equipment-level production assignment is retired;
• the artifact remains verified;
• fresh ACTIVE runtime evidence appears;
• customer-visible findings, if any, refer to the expected model provenance.

Do not describe the model as running in production when the page reports ACTIVE_AWAITING_EVIDENCE, STALE, FALLBACK, CONFLICT, or ARTIFACT_UNAVAILABLE.

Roll Back an Executable Assignment

Rollback is currently an administrator API workflow:

Method	Endpoint
POST	/api/v1/pdm/model-console/assignments/{assignmentId}/rollback

The assignmentId identifies the assignment whose lifecycle history is being rolled back. Use the identifier returned by the tenant-scoped model APIs. Do not infer it from a URL, model name, or another environment.

After rollback:

1. confirm the replacement assignment is ACTIVE;
2. confirm the rolled-back assignment and registry have the expected historical state;
3. wait for fresh runtime evidence from the restored artifact;
4. confirm the previous artifact is no longer referenced by a live assignment;
5. review customer-visible findings and alerts for continuity.

Rollback changes the model selection path. It does not delete historical assignments, lifecycle events, runtime evidence, findings, or feedback.

Understand the Main States

State	What it proves	What it does not prove
STAGING	The registry version is a candidate.	That it can affect customer results.
SHADOW	The assignment is available for non-writing comparison.	That it is the production model.
ACTIVE	The assignment has production selection authority.	That a recent execution succeeded.
PRODUCTION	The registry version is the production version for its governed scope.	That every equipment evaluation used it.
RETIRED or ROLLED_BACK	The version or assignment is historical.	That its audit evidence was deleted.

For actual execution status, use the runtime evidence on the Model Usage Detail page.

Troubleshooting

Symptom	Check
Training action is not visible	pdm:write, readiness eligibility, current assignment state, and whether this is an API-only anomaly-model workflow.
Training is refused	Equipment identity, target signal, operating-state history, window coverage, and the returned reason.
Candidate stays in SHADOW	This is the expected safe state until a human release decision; review comparison evidence and promotion prerequisites.
Promotion succeeded but the model is not shown as in production	Wait for fresh runtime evidence and inspect ACTIVE_AWAITING_EVIDENCE, stale data, fallback, or artifact verification.
Multiple live assignments are reported	Stop lifecycle changes and ask an administrator to resolve the conflict.
Rollback button cannot be found	Assignment rollback is currently an administrator API, not a standard Model Usage Detail action.
A model ran but no Finding appeared	Review data quality, persistence, fusion conditions, and Finding enablement; no Finding does not mean no execution.

Validation Checklist

• The equipment and target are correct.
• The statistical baseline and executable anomaly artifact are not confused.
• Training created a candidate rather than silently changing production.
• SHADOW evidence did not change customer-visible results.
• Promotion was performed by an authorized user after review.
• Fresh ACTIVE runtime evidence confirms actual use.
• Rollback, when used, restored the intended artifact and preserved audit history.

Related Docs

• Health Scores, Baselines, and Model Readiness
• Understand Model Use and Runtime Evidence
• Review Findings and Record Feedback
• Anomaly Review and Maintenance Advisories