pipeworks_mud_mapper.services.description_validator

Deterministic validator for LLM-generated room descriptions.

This module implements the hard-rule validator described in _working/description_validator.md. It enforces structural constraints without rewriting or negotiating prose, in line with the Craft of Constraint principle that authority lives outside the model.

Design goals: - Deterministic: same input yields same output. - Explainable: every failure is labeled and traceable to a rule. - Non-creative: the validator never edits or suggests replacements.

Classes

ValidationResult

Result of validating a room description.

Functions

load_validator_config()	Load validator rules from JSON config.
validate_description(text, target_words)	Validate a description against hard rules.

Module Contents

class pipeworks_mud_mapper.services.description_validator.ValidationResult

Result of validating a room description.

valid

True when no hard rule failures were detected.

Type:

bool

hard_failures

Named hard rule failures (non-negotiable in the validator).

Type:

list[str]

soft_failures

Advisory failures for future expansion (currently unused).

Type:

list[str]

metrics

Numeric metrics captured during validation (word counts, bounds).

Type:

dict

rule_hits

Tokens matched per rule, for UI staging visibility.

Type:

dict[str, list[str]]

pipeworks_mud_mapper.services.description_validator.load_validator_config()

Load validator rules from JSON config.

Returns an empty dict on missing or invalid config to keep validation stable and non-failing in the UI path.

pipeworks_mud_mapper.services.description_validator.validate_description(text, target_words)

Validate a description against hard rules.

Parameters:

• text (str) – Generated description text to validate.

• target_words (int) – Target word count from the UI. Used to compute bounds.

Returns:

Structured results for UI display and persistence.

Return type:

ValidationResult