cascade_engine

NCM Cascade Engine — Multi-turn neurochemical event sequences.

╔═══════════════════════════════════════════════════════════════════════════════╗ ║ 🌀 CASCADE ENGINE ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ Loads cascade definitions from ncm_cascades.yaml ║ ║ Checks triggers against current NCM vector + active emotions ║ ║ Advances active cascades one stage-tick per turn ║ ║ Handles interrupts (abort / pause / skip_to_stage / trigger_cascade) ║ ║ Applies synergy bonuses when cascades co-activate ║ ║ Persists state in Redis: ncm:cascades:{channel_id} ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ Called during exhale() after metabolic decay, stimulus delta ║ ║ stacking, and antagonist suppression. ║ ╚═══════════════════════════════════════════════════════════════════════════════╝

class cascade_engine.CascadeState[source]

Bases: object

Tracks active cascades, cooldowns, and history for one channel.

__init__()[source]: Initialize the instance.

to_dict()[source]

Convert to dict representation.

Returns:: Result dictionary.
Return type:: dict

classmethod from_dict(d)[source]

Construct from dict data.

Parameters:: d (dict) – The d value.
Returns:: The result.
Return type:: CascadeState

class cascade_engine.CascadeEngine(redis_client=None, variant_cache=None)[source]

Bases: object

Manages multi-turn NCM event cascades for a channel.

Parameters:: variant_cache (CueVariantCache | None)

__init__(redis_client=None, variant_cache=None)[source]

Initialize the instance.

Parameters:

redis_client – Redis connection client.
variant_cache (CueVariantCache | None) – The variant cache value.

async tick(channel_id, vector, active_emotions, delta_count=0)[source]

Execute one turn of cascade processing.

Called during exhale(). Returns combined delta vector from all active cascade stages this turn.

Parameters:

channel_id (str) – The channel being processed.
vector (Dict[str, float]) – Current NCM state vector (post-emotion-deltas).
active_emotions (Set[str]) – Emotions that fired this turn.
delta_count (int) – Number of emotion deltas applied this turn.

Returns:

Combined delta vector from cascade processing this turn.

Return type:

Dict[str, float]

async get_active_cascades(channel_id)[source]

Return currently active cascades for context injection.

Return type:: Dict[str, Dict[str, Any]]
Parameters:: channel_id (str)

async force_trigger(channel_id, cascade_id, strain_gradient=None)[source]

Manually trigger a cascade (e.g. from a tool call).

Parameters:

channel_id (str) – Target channel.
cascade_id (str) – Cascade to trigger.
strain_gradient (float | None) – Optional sativa/indica gradient (0.0-1.0) for ENDOCANNABINOID_DRIFT bipolar interpolation.

Return type:

bool