vibe.assistant.services.conversation_state_store

ConversationStateStore - manages assistant state in Flask session.

Responsibilities: - Session read/write with caching - History serialization/deserialization (Message objects <-> dicts) - Token/cost tracking - Question label and tool call ID tracking

UsageStats

Usage statistics from a provider response.

ConversationState

Typed container for assistant conversation state.

This dataclass defines all fields that are stored in the session for an assistant. Unlike a plain dict, new fields cannot be added without updating this class.

ConversationStateStore

Manages assistant conversation state in Flask session.

This class handles: - Loading state from session with defaults - Saving state with serialization - Caching to avoid repeated deserialization within a request - Token/cost tracking - Question and tool call ID tracking

__init__ 

__init__(assistant_name: str, session_getter: Callable[[], MutableMapping[str, Any]], question_definitions: dict[str, Any] | None = None) -> None

Initialize the state store.

Parameters:
  • assistant_name (str) –

    Name of the assistant (key in session['assistants'])

  • session_getter (Callable[[], MutableMapping[str, Any]]) –

    Callable that returns the Flask session dict

  • question_definitions (dict[str, Any] | None, default: None ) –

    Optional dict of predefined question definitions (used for resolving question labels)

load 

load() -> ConversationState

Load assistant state from session.

Returns:
  • ConversationState –

    ConversationState with defaults filled in for missing fields.

  • ConversationState –

    Uses caching to avoid repeated deserialization within a request.

save 

save(state: ConversationState) -> None

Save assistant state to session.

Parameters:
Raises:
  • TypeError –

    If state contains non-JSON-serializable values

  • AssertionError –

    If history contains provider-format dicts

invalidate_cache 

invalidate_cache() -> None

Explicitly invalidate the cache (e.g., after external session modifications).

update_usage 

update_usage(usage: UsageStats, sequence_number: int | None = None) -> None

Update token/cost tracking with usage stats from a response.

Parameters:
  • usage (UsageStats) –

    UsageStats from provider

  • sequence_number (int | None, default: None ) –

    Current sequence number (for TFT/TLT averaging)

append_message 

append_message(message: Message) -> None

Append a message to history.

enqueue_tool_output 

enqueue_tool_output(tool_call_id: str, output: object) -> None

Queue a tool output for submission.

Adds to both history (as ToolResult) and pending_tool_outputs (for Responses API).

clear_pending_tool_outputs 

clear_pending_tool_outputs(count: int) -> None

Remove the first count pending tool outputs (after they've been submitted).

store_question_label 

store_question_label(question_identifier: str, is_predefined: bool, question_name: str | None = None) -> None

Store question label for user display in next turn.

Parameters:
  • question_identifier (str) –

    For predefined, the question ID; for generated, the question text

  • is_predefined (bool) –

    Whether this is a predefined question

  • question_name (str | None, default: None ) –

    Unique name/field_name for this question instance

store_tool_call_id 

store_tool_call_id(field_name: str, tool_call_id: str) -> None

Store mapping from form field name to tool call ID.

get_tool_call_id 

get_tool_call_id(field_name: str) -> str | None

Get tool call ID for a form field name.

clear_question_labels 

clear_question_labels() -> None

Clear all question labels after processing.

increment_sequence_number 

increment_sequence_number() -> int

Increment sequence number and return the new value.