Relabel Policy

Policy data table and score-to-label mapping for axis relabelling.

app/relabel_policy.py

Server-side policy table and score-to-label mapping for the Axis Descriptor Lab.

This module owns the lab’s score-to-label mapping and the canonical axis ordering used by the standalone UI. The definitions here are intentionally aligned with the current Pipe-Works mud-server policy files:

  • pipeworks_mud_server/data/worlds/pipeworks_web/policies/axes.yaml

  • pipeworks_mud_server/data/worlds/pipeworks_web/policies/thresholds.yaml

The mud server remains the runtime authority. Axis Lab keeps a checked-in lab-side copy of the current rules so the UI can perform deterministic local inspection and relabelling without keeping the older mirror-heavy file model alive.

Exports

AXIS_ORDERlist[str]

Canonical full-axis ordering, matching the mud-server axes.yaml key order for the bundled worlds.

AXIS_LABEL_ORDERdict[str, list[str]]

Canonical low-to-high ordinal label sequence for each axis, matching the mud-server ordering.values payloads.

RELABEL_POLICYdict[str, list[tuple[float, float, str]]]

Module-level constant mapping each known axis name to an ordered list of inclusive (min_score, max_score, label) tuples derived from the mud-server thresholds.yaml ranges.

apply_relabel_policy(payload) -> AxisPayload

Walk the payload’s axes, recompute labels from RELABEL_POLICY for known axes, and return a new AxisPayload with updated labels. Unknown axes are passed through unchanged. Scores are never modified.

Design notes

The policy table lives in its own module (rather than inline in a route handler) so that:

  1. Unit tests can validate the current mud-server-aligned policy in isolation without hitting the HTTP layer.

  2. The table can be imported by other modules (e.g. future CLI tools) without pulling in all of FastAPI.

  3. main.py stays a thin routing layer — it calls apply_relabel_policy(payload) and returns the result.

app.relabel_policy.resolve_axis_label(axis_name, score, fallback_label)[source]

Resolve score to the mud-server-aligned label for axis_name.

The lookup uses inclusive min <= score <= max range checks to mirror the mud server’s axis-value resolution logic. If the axis is unknown, or if the score falls outside every configured range, fallback_label is returned unchanged.

Returning the existing label for unmatched scores is intentional: the lab’s schema requires a non-empty label string, while the mud server stores label absence as None in the database layer.

Parameters:

  • axis_name (str) – Axis key to resolve.

  • score (float) – Normalised axis score in [0.0, 1.0].

  • fallback_label (str) – Existing label to preserve when no configured range matches.

Returns:

The resolved canonical label, or fallback_label when the axis or score is not covered by the configured policy.

Return type:

str

app.relabel_policy.apply_relabel_policy(payload)[source]

Recompute axis labels from the policy table and return an updated payload.

For each axis in payload, if the axis name appears in RELABEL_POLICY, the label is rewritten to the matching mud-server threshold range. Unknown axes (those not in the policy table) are passed through with their existing labels intact.

Scores are never modified — only labels change. All non-axis fields (policy_hash, seed, world_id) are preserved verbatim.

Parameters:

payload (AxisPayload) – The current axis payload with scores and (possibly stale) labels.

Returns:

A new payload instance with labels recomputed from scores.

Return type:

AxisPayload