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.

PruneCompletedPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.PRUNE_COMPLETED.

session_id instance-attribute

session_id: str

The session whose tool outputs were pruned.

pruned_count instance-attribute

pruned_count: int

Number of tool output parts tombstoned in this prune pass.

pruned_tokens instance-attribute

pruned_tokens: int

Estimated tokens reclaimed by this prune pass.

LlmRetryPayload

Bases: TypedDict

Payload for :attr:MnesisEvent.LLM_RETRY.

Published on each retry attempt before the backoff sleep begins.

session_id instance-attribute

session_id: str

The session that is retrying the LLM call.

attempt instance-attribute

attempt: int

The current attempt number (1-based: first retry is attempt 1).

max_retries instance-attribute

max_retries: int

Maximum number of retries configured for this session.

error_type instance-attribute

error_type: str

Fully-qualified exception class name (e.g. "litellm.exceptions.RateLimitError").

error_message instance-attribute

error_message: str

Human-readable error message from the exception.

delay_seconds instance-attribute

delay_seconds: float

Seconds the session will sleep before the next attempt.

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.