Context

from peteos.conversation.context import Context

A context represents the chat history for a step in a session, wrapped as a mutable JSON dict. The dict is the source of truth. Messages can be appended, anchors can be added, and dynamic messages are resolved via a content map — making the context a live, evolving structure rather than a static snapshot.

Factory Methods

Context.create(system_prompt_message: SystemPromptMessage | None = None, tool_definitions_message: ToolDefinitionsMessage | None = None, parent_context: Context | None = None) -> Context

Create a new empty context. The system prompt and tool definitions messages are placed in the first slots. If parent_context is provided, the content map is inherited.

Parameter	Type	Default	Description
system_prompt_message	SystemPromptMessage | None	None	Optional system prompt.
tool_definitions_message	ToolDefinitionsMessage | None	None	Optional tool definitions.
parent_context	Context | None	None	Parent to inherit the content map from (for forks).

Context.load(path: str) -> Context

Load a context from a JSON file.

Context.load_from_dict(json_dict: dict) -> Context

Load a context from a dictionary (used during deserialization).

Instance Properties

Property	Type	Description
id	str	The context ID.
messages	list[Message]	List of messages in this context.
message_count	int	Number of messages (same as the sequence counter).
content_map	dict[str, str]	Hash → string map for dynamic message resolution.
anchor_points	list[tuple[str, int]]	Ordered list of (name, index) anchor points.
hook_index	dict[str, list[Message]]	Hook ID → messages index.
system_prompt_message	SystemPromptMessage | None	The system prompt message, or None.
tool_definitions_message	ToolDefinitionsMessage | None	The tool definitions message, or None.
raw_dict	dict	The wrapped serialized dict.

Instance Methods

append(message: Message, anchor_point: str = "messages") -> None

Insert a message at the anchor point's end-iterator position. Shifts subsequent messages and increments all anchors at or after the insertion point.

Parameter	Type	Default	Description
message	Message	—	The message to append.
anchor_point	str	"messages"	Name of the anchor point.

add_anchor(name: str, msg_index: int, after_existing: bool = True) -> None

Register a new anchor point. The msg_index is an absolute position into the messages array (0 = before all messages, len(messages) = after all messages).

Parameter	Type	Description
name	str	Anchor point name.
msg_index	int	Absolute message index.
after_existing	bool	Ordering when another anchor occupies the same position.

Raises: ValueError if the anchor name already exists.

fork_insert_sequence(system_prompt_message: SystemPromptMessage | None = None, tool_definitions_message: ToolDefinitionsMessage | None = None, start: int | None = None, end: int | None = None) -> Context

Fork this context with Python-style slice semantics on mutation counter values. Only messages created within the [start, end) range are copied into the child.

Parameter	Type	Default	Description
system_prompt_message	SystemPromptMessage | None	None	Optional new system prompt for the fork.
tool_definitions_message	ToolDefinitionsMessage | None	None	Optional new tool definitions message.
start	int | None	None	Start of mutation counter range (inclusive). None = from the first.
end	int | None	None	End of mutation counter range (exclusive). None = to the last.

Returns: A new Context with the selected messages.

rolling_sequence_window(count: int) -> Context | None

Fork including the last count non-special messages by sequence number. Returns None if the window already covers all messages.

rolling_token_window(max_tokens: int, encoding: str = "cl100k_base") -> Context | None

Fork keeping messages from the end until total tokens ≤ max_tokens. Includes special messages (system prompt, tool definitions). Returns None if no messages need to be dropped.

strip_thinking() -> Context

Fork removing all thinking content parts from every message. Empty messages are skipped.

total_token_count(encoding: str = "cl100k_base") -> int

Sum of token counts across all messages in this context.

save(session_dir: str | Path) -> None

Save the context to {YYYYMMDD}-{context_id}.json in the given session directory, where the date prefix is the context creation date.