mnesis.models.message

message

Core message and part data models for Mnesis.

FinishReason

Bases: StrEnum

Why the LLM stopped generating.

String enum so result.finish_reason == "stop" comparisons work without importing the enum.

Important — FinishReason.ERROR: when finish_reason is FinishReason.ERROR (or "error"), the LLM call failed. TurnResult.text contains an error description, not a model response. Always check finish_reason before processing text.

TextPart

Bases: BaseModel

A plain text segment of a message.

ReasoningPart

Bases: BaseModel

Chain-of-thought reasoning text (e.g. Claude extended thinking, o1 reasoning).

ToolStatus

Bases: BaseModel

Mutable lifecycle status of a tool call. Updated in-place via update_part_status().

ToolPart

Bases: BaseModel

A tool call and its result within an assistant message.

compacted_at property

compacted_at: int | None

Convenience accessor for the pruning tombstone timestamp.

is_protected property

is_protected: bool

Protected tools are never pruned by ToolOutputPruner.

CompactionMarkerPart

Bases: BaseModel

Metadata marker embedded in a compaction summary message.

Records which messages were compacted and which escalation level succeeded.

StepStartPart

Bases: BaseModel

Marker for the start of an agentic step within a turn.

StepFinishPart

Bases: BaseModel

Marker for the end of an agentic step, including token usage.

PatchPart

Bases: BaseModel

A git-format unified diff representing file changes made during a turn.

FileRefPart

Bases: BaseModel

A content-addressed reference to a large file stored outside the context window.

When the LargeFileHandler intercepts a file that exceeds the inline threshold, it stores it externally and replaces the content with this reference object. The ContextBuilder renders this as a structured [FILE: ...] block.

content_id instance-attribute

content_id: str

SHA-256 hex digest of the file content. Used as cache key.

path instance-attribute

path: str

Original file path as provided by the caller.

file_type instance-attribute

file_type: str

Detected MIME type or language identifier (e.g. 'python', 'application/json').

token_count instance-attribute

token_count: int

Estimated token count of the full file content.

exploration_summary instance-attribute

exploration_summary: str

Deterministic structural description of the file (classes, functions, keys, etc.).

TokenUsage

Bases: BaseModel

Token counts for a single LLM response or cumulative session usage.

effective_total

effective_total() -> int

Return total, computing from parts when the explicit total is zero.

MessageError

Bases: BaseModel

Structured error attached to an assistant message when the turn fails.

Message

Bases: BaseModel

A single message stored in the ImmutableStore.

Messages are append-only — the only mutable fields are token usage and finish_reason (updated after streaming completes), and part status fields (managed via update_part_status).

id instance-attribute

id: str

ULID-based sortable ID, e.g. msg_01JXYZ6K3MNPQR4STUVWXYZ01.

created_at class-attribute instance-attribute

created_at: int = Field(
    default_factory=lambda: int(time.time() * 1000)
)

Unix millisecond timestamp.

is_summary class-attribute instance-attribute

is_summary: bool = False

True if this message is a compaction summary produced by the CompactionEngine.

mode class-attribute instance-attribute

mode: str | None = None

'compaction' for summary messages, None for regular turns.

MessageWithParts

Bases: BaseModel

A message together with its ordered list of typed parts.

model_id property

model_id: str

The model that produced this message (empty string for user messages).

tokens property

tokens: TokenUsage | None

Token usage for this message (None for user messages or before streaming completes).

text_content

text_content() -> str

Concatenate text from all TextPart objects in this message.

ContextBudget

Bases: BaseModel

Token budget for assembling the context window on a single turn.

usable property

usable: int

Maximum tokens available for conversation history.

fits

fits(token_count: int) -> bool

Return True if token_count fits within the usable budget.

remaining

remaining(used: int) -> int

Return remaining tokens given how many have been used.

TurnResult

Bases: BaseModel

The result of a single MnesisSession.send() call.

Contains the assistant's text response, token usage, finish reason, and indicators for compaction and doom loop detection.

Important — finish_reason == "error": When finish_reason is "error", the LLM call failed and text contains an error description, not an LLM response. Do not treat the text as a model reply in this case. Always check finish_reason before processing text.

finish_reason instance-attribute

finish_reason: FinishReason | str

Why the LLM stopped generating.

Type is FinishReason | str: known values are the FinishReason enum members; providers may return additional string values.

• FinishReason.STOP / "stop" — natural end of response.
• FinishReason.MAX_TOKENS / "max_tokens" — output token limit reached.
• FinishReason.LENGTH / "length" — alias used by some providers.
• FinishReason.TOOL_CALLS / "tool_calls" — model requested tool execution.
• FinishReason.ERROR / "error" — the LLM call failed; text contains the error description, not a model response. Do not pass this text to the model as if it were a real reply.

cost instance-attribute

cost: float

Estimated USD cost of this turn. Always 0.0 — not yet implemented.

compaction_triggered class-attribute instance-attribute

compaction_triggered: bool = False

True if the context window after this turn crossed the soft threshold and a background compaction was scheduled. The turn does not wait for it. False when a compaction was already in flight (no second one is scheduled).

compaction_result class-attribute instance-attribute

compaction_result: CompactionResult | None = None

Result of a compaction that ran before this turn's LLM call.

Populated only when the context was over the hard threshold, so send() had to wait for compaction to finish. It is None otherwise: background (soft-threshold) compactions never block a turn, so their results arrive later via the COMPACTION_COMPLETED event instead.

CompactionResult

Bases: BaseModel

The result of a compaction run.

Records which escalation level succeeded, how many messages were compressed, the token savings achieved, and how many tool outputs were pruned.

level_used instance-attribute

level_used: int

1 = selective LLM, 2 = aggressive LLM, 3 = deterministic fallback.

compacted_message_count instance-attribute

compacted_message_count: int

Raw messages summarised by the run, cumulative across its summarisation passes.

summary_token_count instance-attribute

summary_token_count: int

Tokens of the summary content the run produced: the sum over its leaf summaries, or the resulting condensed node's tokens when condensation then merged them.

tokens_before instance-attribute

tokens_before: int

Size of the active context window before the run, on the same basis as tokens_after.

tokens_after instance-attribute

tokens_after: int

Size of the active context window after the run, including older live summaries. For sessions this is the measure the soft/hard thresholds use (system prompt included).

pruned_tool_outputs class-attribute instance-attribute

pruned_tool_outputs: int = 0

Number of tool output parts tombstoned by the ToolOutputPruner during this run.

pruned_tokens class-attribute instance-attribute

pruned_tokens: int = 0

Tokens reclaimed by pruning tool outputs during this run.

PruneResult

Bases: BaseModel

The result of a ToolOutputPruner pass.

RecordResult

Bases: BaseModel

The result of a MnesisSession.record() call.

Records the IDs of the persisted user and assistant messages so callers can reference them later (e.g. for event subscriptions or debugging).

doom_loop_detected class-attribute instance-attribute

doom_loop_detected: bool = False

True if the same tool call (name and input) has now been recorded doom_loop_threshold times consecutively.

TextDelta

Bases: BaseModel

A streamed text chunk emitted by MnesisSession.stream().

Yielded progressively as the LLM produces output. Consumers can concatenate event.text across all TextDelta events to reconstruct the full assistant response before the final :class:TurnComplete.

Attributes:

Name	Type	Description
type	Literal['text_delta']	Discriminator literal — always "text_delta".
text	str	The text fragment for this chunk.

TurnComplete

Bases: BaseModel

The final event emitted by MnesisSession.stream().

Always the last event in the stream. Carries the full :class:TurnResult so callers can inspect token usage, compaction status, and finish reason after the turn completes.

Attributes:

Name	Type	Description
type	Literal['turn_complete']	Discriminator literal — always "turn_complete".
result	TurnResult	The complete :class:TurnResult for the finished turn.