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

Size of the current context window (system prompt, live summaries and raw messages) that crossed the soft threshold. Previously a lifetime cumulative count.

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.

compacted_message_count instance-attribute

compacted_message_count: int

Messages summarised by the run, cumulative across its summarisation passes.

summary_token_count instance-attribute

summary_token_count: int

Tokens of the summary content produced: the sum over the run's leaf passes, or the condensed node's size after condensation.

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.

aborted instance-attribute

aborted: bool

True only for an abort: the abort event passed to run_compaction() / check_and_trigger() was set, or the session was closed with close(abort_compaction=True). A plain close() waits for the run instead.

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, for both send() turns and compaction LLM calls (told apart by source).

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.

source instance-attribute

source: NotRequired[str]

What is retrying: "send" (a turn's LLM call) or "compaction".

Absent on events from versions that predate this key; treat a missing value as "send".

stage instance-attribute

stage: NotRequired[str]

Compaction only: "summarisation" or "condensation".

compaction_level instance-attribute

compaction_level: NotRequired[int]

Compaction only: the escalation level (1 or 2) of the call being retried.

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 have finished, including failures (not a success count). Present for LLMMap; absent for AgenticMap.