Skip to content

mnesis.events.payloads

payloads

Typed payload definitions for each MnesisEvent.

Each event published by Mnesis components carries a payload dict. This module defines a TypedDict for every event so handlers can use static type checkers and IDE auto-complete rather than guessing key names at runtime.

Usage example::

from mnesis.events.bus import EventBus, MnesisEvent
from mnesis.events.payloads import CompactionCompletedPayload

def on_compaction(event: MnesisEvent, payload: CompactionCompletedPayload) -> None:
    print(
        f"Compacted {payload['compacted_message_count']} messages "
        f"at level {payload['level_used']} "
        f"({payload['tokens_before']} → {payload['tokens_after']} tokens)"
    )

bus.subscribe(MnesisEvent.COMPACTION_COMPLETED, on_compaction)  # type: ignore[arg-type]

SessionCreatedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.SESSION_CREATED.

session_id instance-attribute 

session_id: str

The newly created session's ID.

model instance-attribute 

model: str

The LLM model string the session was created with.

SessionClosedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.SESSION_CLOSED.

session_id instance-attribute 

session_id: str

The session that was closed.

MessageCreatedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.MESSAGE_CREATED.

message_id instance-attribute 

message_id: str

The newly persisted message's ID.

role instance-attribute 

role: str

"user" or "assistant".

CompactionTriggeredPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.COMPACTION_TRIGGERED.

session_id instance-attribute 

session_id: str

The session whose compaction was triggered.

tokens instance-attribute 

tokens: int

Current cumulative token count that crossed the threshold.

CompactionCompletedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.COMPACTION_COMPLETED.

This is the model_dump() of a :class:mnesis.models.message.CompactionResult. All fields from CompactionResult are present.

summary_message_id instance-attribute 

summary_message_id: str

ID of the newly created summary message, or "" on failure.

level_used instance-attribute 

level_used: int

Escalation level: 1 = selective LLM, 2 = aggressive LLM, 3 = deterministic.

pruned_tool_outputs instance-attribute 

pruned_tool_outputs: int

Number of tool outputs tombstoned by the pruner during this run.

pruned_tokens instance-attribute 

pruned_tokens: int

Tokens reclaimed by pruning tool outputs.

CompactionFailedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.COMPACTION_FAILED.

error instance-attribute 

error: str

Human-readable error description.

DoomLoopDetectedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.DOOM_LOOP_DETECTED.

tool instance-attribute 

tool: str

Name of the tool call that was repeated past the doom-loop threshold.

MapStartedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.MAP_STARTED (operator bus only).

model is present only for :class:~mnesis.operators.LLMMap. type is present only for :class:~mnesis.operators.AgenticMap (value: "agentic").

total instance-attribute 

total: int

Total number of items to process.

model instance-attribute 

model: NotRequired[str]

LLM model string. Present for LLMMap; absent for AgenticMap.

type instance-attribute 

type: NotRequired[str]

Operator type string. Present for AgenticMap ("agentic"); absent for LLMMap.

MapItemCompletedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.MAP_ITEM_COMPLETED (operator bus only).

completed instance-attribute 

completed: int

Number of items completed so far (including this one).

total instance-attribute 

total: int

Total number of items.

success instance-attribute 

success: bool

Whether this item succeeded.

MapCompletedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.MAP_COMPLETED (operator bus only).

completed is present only for :class:~mnesis.operators.LLMMap. :class:~mnesis.operators.AgenticMap publishes only total.

total instance-attribute 

total: int

Total number of items processed.

completed instance-attribute 

completed: NotRequired[int]

Number of items that completed. Present for LLMMap; absent for AgenticMap.