mud_server.translation.profile_builder

Character profile builder for the OOC→IC translation layer.

CharacterProfileBuilder is responsible for building the flat context dictionary that is injected into the system prompt template. It fetches axis scores from the database and resolves them to their human-readable labels.

World scoping

All DB lookups use both character_name and world_id. This is non-negotiable: two characters in different worlds may share the same name, and a name-only lookup would silently return the wrong character. Any attempt to call this builder without a concrete world_id will raise a ValueError at construction time.

Axis sourcing

The builder calls database.get_character_by_name_in_world to resolve the character name to a character_id, then calls database.get_character_axis_state(character_id) which returns both axis scores and their resolved threshold labels (e.g. score 0.87 on the demeanor axis → label "proud").

Active axes filtering

Only axes listed in active_axes are included in the returned profile dict. If a character has no score for an active axis yet (e.g. the world just gained a new axis and old characters haven’t been seeded), the builder defaults to label="unknown" and score=0.0 rather than omitting the key, so the prompt template never contains an unfilled placeholder.

Attributes

logger

Classes

CharacterProfileBuilder

Builds a character profile dict suitable for system prompt rendering.

Module Contents

mud_server.translation.profile_builder.logger

class mud_server.translation.profile_builder.CharacterProfileBuilder(world_id, active_axes)[source]

Builds a character profile dict suitable for system prompt rendering.

_world_id: World that this builder is scoped to.

_active_axes: Axis names to include in the profile. An empty list means “all axes present for this character”.

Initialise the builder.

Parameters:

world_id (str) – World the builder is scoped to. Required; raises ValueError if empty so that silent world-scope omissions are caught at construction rather than producing wrong DB queries.
active_axes (list[str]) – Axis names to include in the profile.

Raises:

ValueError – If world_id is empty or blank.

build(character_name)[source]

Build a profile dict for the given character in this world.

The returned dict contains flat {axis_name}_label and {axis_name}_score keys for every axis in active_axes, plus a character_name key. These map directly to the {{key}} placeholders in the world’s ic_prompt.txt template.

Returns None in three situations (all logged at WARNING): - The character is not found in this world. - The character has no axis state at all. - An unexpected DB error occurs.

In all None cases the caller (TranslationService) treats the result as an unresolvable fallback condition and returns None from translate(), causing the engine to use the original OOC message instead.

Parameters:: character_name (str) – Name of the character to build a profile for.
Returns:: Flat profile dict on success, None on failure.
Return type:: dict[str, Any] | None