core.conversation_manager

Client conversation history management with suspend/restore support.

class ConversationManager(client, lock=None)[source]

Bases: object

Manages the underlying client’s conversation history.

Handles: - Thread-safe suspend/restore for declarative history injection - Proxy access to the client’s conversation with error handling - Message appending and conversation clearing

Parameters:

client (Any) – The AI client whose conversation history is managed.
lock (threading.Lock | None) – Optional lock for thread-safe access.

property client: Any

should_suspend(prompt, history)[source]

Determine if client history should be suspended for this call.

Suspension is needed when a history parameter is provided or the prompt contains {{...}} interpolation patterns.

Parameters:

prompt (str) – The prompt text.
history (list[str] | None) – The declarative history list.

Returns:

True if client history should be suspended.

Return type:

bool

suspend(reason='')[source]

Save and clear the client’s conversation history.

Parameters:: reason (str) – Log message reason for suspension.
Returns:: Saved history if suspended, None if client lacks methods.
Return type:: list[dict[str, Any]] | None

restore(saved)[source]

Merge new messages back into the saved client history.

Parameters:: saved (list[dict[str, Any]] | None) – Previously saved history from suspend().
Return type:: None

get_history()[source]

Get the client’s conversation history with error handling.

Return type:: list[dict[str, Any]]

set_history(history)[source]

Set the client’s conversation history with error handling.

Parameters:: history (list[dict[str, Any]])
Return type:: bool

add_message(role, content, **kwargs)[source]

Add a single message to the client’s conversation history.

Parameters:

role (str)
content (str)
kwargs (Any)

Return type:

bool

clear()[source]

Clear the client’s conversation history.

Return type:: None

Classes

class ConversationManager(client, lock=None)[source]

Bases: object

Manages the underlying client’s conversation history.

Handles: - Thread-safe suspend/restore for declarative history injection - Proxy access to the client’s conversation with error handling - Message appending and conversation clearing

Parameters:

client (Any) – The AI client whose conversation history is managed.
lock (threading.Lock | None) – Optional lock for thread-safe access.

property client: Any

should_suspend(prompt, history)[source]

Determine if client history should be suspended for this call.

Suspension is needed when a history parameter is provided or the prompt contains {{...}} interpolation patterns.

Parameters:

prompt (str) – The prompt text.
history (list[str] | None) – The declarative history list.

Returns:

True if client history should be suspended.

Return type:

bool

suspend(reason='')[source]

Save and clear the client’s conversation history.

Parameters:: reason (str) – Log message reason for suspension.
Returns:: Saved history if suspended, None if client lacks methods.
Return type:: list[dict[str, Any]] | None

restore(saved)[source]

Merge new messages back into the saved client history.

Parameters:: saved (list[dict[str, Any]] | None) – Previously saved history from suspend().
Return type:: None

get_history()[source]

Get the client’s conversation history with error handling.

Return type:: list[dict[str, Any]]

set_history(history)[source]

Set the client’s conversation history with error handling.

Parameters:: history (list[dict[str, Any]])
Return type:: bool

add_message(role, content, **kwargs)[source]

Add a single message to the client’s conversation history.

Parameters:

role (str)
content (str)
kwargs (Any)

Return type:

bool

clear()[source]

Clear the client’s conversation history.

Return type:: None