tools.inject_ncm module

Inject neurochemicals into Stargazer’s Limbic System (NCM V3).

NCM INJECTION TOOL

Stimulates the Neuro-Chemical Model with chemical delta vectors. Changes persist in Redis DB12 and decay toward baseline.

SECURITY: Requires CORE_MEMORY privilege (bit 1).

async tools.inject_ncm.run(chemical_vector, reason='manual_injection', target_user_id='', ctx=None)[source]

Inject a neurochemical delta vector into the NCM, or cast user resonance.

Entry point for the inject_ncm tool. It parses a JSON map of chemical deltas and, depending on target_user_id, either stimulates Star’s own limbic shard for the current channel or writes into a per-user global resonance layer. The whole point is to let narrative drug consumption, loopcast alignment, or deliberate “resonance spells” move the bot’s emotional state in a way that persists and decays in Redis DB12.

Authorization runs first: it imports has_privilege/PRIVILEGES from tools.alter_privileges and refuses (logging a SECURITY warning) unless the caller holds CORE_MEMORY. The deltas are then validated as numeric. In resonance mode it maps standard NCM nodes to U_* shadow nodes via _NCM_TO_USER_MAP, opens a DB12 client through _get_db12_client(), and delegates to user_limbic_mirror.UserLimbicMirror.inject_resonance() (which decays after 24h). In self-injection mode it bypasses the heavy LimbicSystem machinery and does a direct read-modify-write of the db12:shard:{channel_id} key, applying each delta through a Hill-saturation curve clamped to [0.0, 3.0]. Dispatched by the tool runtime as the inject_ncm handler; no direct internal callers were found.

Parameters:

  • chemical_vector (str) – JSON object of node-to-delta numbers (full NCM node names for self-injection, or U_* nodes when targeting a user).

  • reason (str) – Free-text reason recorded with the injection. Defaults to "manual_injection".

  • target_user_id (str) – Optional Discord user ID; when set, switches to resonance mode and writes the per-user shadow layer instead of Star’s own shard.

  • ctx (ToolContext | None) – Tool execution context providing Redis, config and the calling user_id; None fails the call.

Returns:

A JSON string describing the outcome — mode of user_resonance or self_injection with the applied deltas on success, or {"success": False, "error": ...} on a privilege/parse/Redis failure.

Return type:

str