tools.modulate_egregore_ncm module

MODULATE_EGREGORE_NCM – DJ the emotional state of summoned egregores.

Allows Star to inject neurochemical vectors into individual egregores, changing their emotional tone, energy level, and behavioral cadence. Like a DJ mixing the emotional atmosphere of her dollhouse.

Per-egregore NCM state is stored in Redis and included in the egregore’s context injection via _build_active_egregores().

@fire @skull THE WITCH TUNES HER DOLLS.

async tools.modulate_egregore_ncm.run(name='', vector='{}', cadence=None, reason='', ctx=None)[source]

Modulate a summoned egregore’s neurochemical/emotional state.

The sole handler for the modulate_egregore_ncm tool: Star’s “DJ booth” for adjusting an individual egregore’s emotional tone, energy, and speaking cadence. It validates that the egregore is actually summoned in the current channel, parses and clamps the requested modulation axes, stacks them onto any existing state, and persists the merged result so the egregore’s later context injection reflects the new mood.

Reads and writes Redis through ctx.redis: it loads the per-channel active-egregore set at star:egregores:{channel_key} (channel key built by _channel_key_from_ctx()) to confirm the target is present, then reads, merges, and SETs the per-egregore NCM blob at the EGREGORE_NCM_KEY pattern (star:egregore_ncm:{name}). Axis names are checked against VALID_AXES and values clamped to [MOD_MIN, MOD_MAX]; an optional cadence is validated against VALID_CADENCES. That stored state is later consumed by prompt_context.PromptContextBuilder._build_active_egregores, which reads the same star:egregore_ncm:{name} key to fold the modulation into the egregore’s prompt context. A successful modulation is logged via logger.info. Discovered via the single-tool TOOL_NAME/run format and bound by tool_loader; dispatched by the tool registry when the model calls modulate_egregore_ncm, with no direct internal callers.

Parameters:

  • name (str) – Name of the egregore to modulate; must be summoned in this channel.

  • vector (str) – JSON object string (or dict) of axis -> value modulations; values are clamped to [-1.0, 1.0] and unknown axes are warned and skipped.

  • cadence (str | None) – Optional speaking-cadence override from VALID_CADENCES.

  • reason (str) – Free-text rationale, stored with the state and echoed back.

  • ctx (ToolContext | None) – The ToolContext; redis, platform, and channel_id are used.

Returns:

An indented JSON string. On success it reports the egregore, the modulations_applied, the merged current_state and cadence, and any warnings; on failure an error (missing context/Redis/name, the egregore not being summoned, invalid vector JSON, no valid modulations, or an invalid cadence).

Return type:

str